docs: enhance Contribution Guide and Migration Guide (#883)

* docs: update `v1 to v2 migration guide` to include component updates * docs: update section title in the migration guide * docs: update routes for Contribution Guide and Migration Guide * docs: move Contribution Guide and Migration Guide to top-level pages * docs: correct corss-page links * docs: update icons for the side navigation menu items
trendmicro-frontend · Jul 4, 2024 · 7baee21 · 7baee21
1 parent 474fe55
commit 7baee21
Show file tree

Hide file tree

Showing 12 changed files with 158 additions and 50 deletions.
diff --git a/packages/react-docs/config/sidebar-routes.js b/packages/react-docs/config/sidebar-routes.js
@@ -8,8 +8,10 @@ import {
   ColorIcon,
   FileImageOIcon,
   HookIcon,
-  ListOpenIcon,
+  MigrateSuccessIcon,
+  RocketIcon,
   SVGIcon,
+  UserTeamIcon,
   WidgetsIcon,
   WorkspaceIcon,
 } from '@tonic-ui/react-icons';
@@ -25,7 +27,7 @@ export const routes = [
   {
     title: 'Getting Started',
     icon: (props) => (
-      <ListOpenIcon size="4x" {...props} />
+      <RocketIcon size="4x" {...props} />
     ),
     routes: [
       { title: 'Installation', path: 'getting-started/installation' },
@@ -37,22 +39,36 @@ export const routes = [
       { title: 'The sx prop', path: 'getting-started/the-sx-prop' },
       { title: 'Security', path: 'getting-started/security' },
       { title: 'Tonic UI Versions', path: 'getting-started/versions' },
-      { title: 'CONTRIBUTING', heading: true },
-      { title: 'Contributing', path: 'getting-started/contributing' },
-      { title: 'React Documentation Site', path: 'getting-started/contributing/react-documentation-site' },
+    ],
+  },
+  {
+    title: 'Contribution Guide',
+    icon: (props) => (
+      <UserTeamIcon size="4x" {...props} />
+    ),
+    routes: [
+      { title: 'Overview', path: 'contribution-guide' },
+      { title: 'React Documentation Site', path: 'contribution-guide/react-documentation-site' },
       {
         title: <Flex columnGap="2x">React Components <sub>PART 1</sub></Flex>,
-        path: 'getting-started/contributing/react-components-part-1',
+        path: 'contribution-guide/react-components-part-1',
       },
       {
         title: <Flex columnGap="2x">React Components <sub>PART 2</sub></Flex>,
-        path: 'getting-started/contributing/react-components-part-2',
+        path: 'contribution-guide/react-components-part-2',
       },
-      { title: 'React Icons', path: 'getting-started/contributing/react-icons' },
-      { title: 'Publishing', path: 'getting-started/contributing/publishing' },
-      { title: 'MIGRATION', heading: true },
-      { title: 'Migration From v1 to v2', path: 'getting-started/migration-v1-to-v2' },
-      { title: 'Migration From v0 to v1', path: 'getting-started/migration-v0-to-v1' },
+      { title: 'React Icons', path: 'contribution-guide/react-icons' },
+      { title: 'Publishing', path: 'contribution-guide/publishing' },
+    ],
+  },
+  {
+    title: 'Migration Guide',
+    icon: (props) => (
+      <MigrateSuccessIcon size="4x" {...props} />
+    ),
+    routes: [
+      { title: 'Migrating from v1 to v2', path: 'migration-guide/migrating-from-v1-to-v2' },
+      { title: 'Migrating from v0 to v1', path: 'migration-guide/migrating-from-v0-to-v1' },
     ],
   },
   {

diff --git a/packages/react-docs/pages/components/icon/index.page.mdx b/packages/react-docs/pages/components/icon/index.page.mdx
@@ -12,7 +12,7 @@ import {
 
 > <TextLabel><Flex alignItems="center" columnGap="2x" mb="1x"><AlertIcon /> IMPORTANT NOTICE</Flex></TextLabel>
 >
-> All built-in icons were removed in v2. See the [migration guide](../getting-started/migration-v1-to-v2#icons) while upgrading from v0 or v1. If you are looking for the pre-defined Tonic icon components, visit the [React Icons](../icons) page.
+> All built-in icons were removed in v2. See the [migration guide](../migration-guide/migrating-from-v1-to-v2#icons) while upgrading from v0 or v1. If you are looking for the pre-defined Tonic icon components, visit the [React Icons](../icons) page.
 
 ## Import
 

diff --git a/...tting-started/contributing/index.page.mdx → ...s/pages/contribution-guide/index.page.mdx b/...tting-started/contributing/index.page.mdx → ...s/pages/contribution-guide/index.page.mdx
@@ -1,4 +1,4 @@
-# Contributing
+# Contribution Guide
 
 Thank you for your interest in contributing to Tonic UI!
 

diff --git a/...-started/contributing/publishing.page.mdx → ...es/contribution-guide/publishing.page.mdx b/...-started/contributing/publishing.page.mdx → ...es/contribution-guide/publishing.page.mdx
@@ -1,4 +1,4 @@
-import BorderedBox from '../../../components/BorderedBox';
+import BorderedBox from '../../components/BorderedBox';
 
 # Publishing
 

diff --git a/...buting/react-components-part-1-example.js → ...-guide/react-components-part-1-example.js b/...buting/react-components-part-1-example.js → ...-guide/react-components-part-1-example.js
diff --git a/...ributing/react-components-part-1.page.mdx → ...on-guide/react-components-part-1.page.mdx b/...ributing/react-components-part-1.page.mdx → ...on-guide/react-components-part-1.page.mdx
@@ -1,11 +1,11 @@
-import BorderedBox from '../../../components/BorderedBox';
-import Code from '../../components/code/index.page.mdx'
+import BorderedBox from '../../components/BorderedBox';
+import Code from '../components/code/index.page.mdx'
 
 # Contributing to React Components <sup>PART 1</sup>
 
 ## Workflow
 
-This example will walk you through the process of creating a [Code](../../components/code) component. This component serves as a straightforward example to help you understand the entire development and documentation flow.
+This example will walk you through the process of creating a [Code](../components/code) component. This component serves as a straightforward example to help you understand the entire development and documentation flow.
 
 {render('./react-components-part-1-example')}
 
@@ -184,7 +184,7 @@ Include the new documentation page in `packages/react-docs/config/sidebar-routes
 
 #### Step 3: API structure
 
-Refer to the existing [Code component documentation](../../components/code) or visit the [GitHub repository](https://github.com/trendmicro-frontend/tonic-ui/blob/v2/packages/react-docs/pages/components/code) for details.
+Refer to the existing [Code component documentation](../components/code) for details.
 
 <BorderedBox>
   <Code />

diff --git a/...ributing/react-components-part-2.page.mdx → ...on-guide/react-components-part-2.page.mdx b/...ributing/react-components-part-2.page.mdx → ...on-guide/react-components-part-2.page.mdx
@@ -204,9 +204,9 @@ The `variant` prop offers various styles tailored to specific component needs. H
 
 Variant | Description | Used In
 :--- | :---------- | :------
-`solid`    | The background and the border are filled with the same color.   | [Alert](../../components/alert), [Badge](../../components/badge), [Divider](../../components/divider), [Tag](../../components/tag)
-`filled`   | The background and the border are filled with different colors. | [Input](../../components/input), [InputControl](../../components/input-control), [Select](../../components/select), [Tabs](../../components/tabs), [SearchInput](../../components/search-input), [Textarea](../../components/textarea)
-`flush`    | Only the bottom bordered is rendered. | [Input](../../components/input), [InputControl](../../components/input-control), [SearchInput](../../components/search-input)
-`outline`  | Only the border is filled.                                      | [Alert](../../components/alert), [Input](../../components/input), [InputControl](../../components/input-control), [SearchInput](../../components/search-input), [Select](../../components/select), [Table](../../components/table), [Tag](../../components/tag), [Textarea](../../components/textarea)
-`unstyled` | No style is applied.                                            | [Input](../../components/input), [InputControl](../../components/input-control), [SearchInput](../../components/search-input), [Select](../../components/select), [Tabs](../../components/tabs), [Textarea](../../components/textarea)
-`default`  | The component's default style.                                  | [Button](../../components/button), [Table](../../components/table), [Tabs](../../components/tabs)
+`solid`    | The background and the border are filled with the same color.   | [Alert](../components/alert), [Badge](../components/badge), [Divider](../components/divider), [Tag](../components/tag)
+`filled`   | The background and the border are filled with different colors. | [Input](../components/input), [InputControl](../components/input-control), [Select](../components/select), [Tabs](../components/tabs), [SearchInput](../components/search-input), [Textarea](../components/textarea)
+`flush`    | Only the bottom bordered is rendered. | [Input](../components/input), [InputControl](../components/input-control), [SearchInput](../components/search-input)
+`outline`  | Only the border is filled.                                      | [Alert](../components/alert), [Input](../components/input), [InputControl](../components/input-control), [SearchInput](../components/search-input), [Select](../components/select), [Table](../components/table), [Tag](../components/tag), [Textarea](../components/textarea)
+`unstyled` | No style is applied.                                            | [Input](../components/input), [InputControl](../components/input-control), [SearchInput](../components/search-input), [Select](../components/select), [Tabs](../components/tabs), [Textarea](../components/textarea)
+`default`  | The component's default style.                                  | [Button](../components/button), [Table](../components/table), [Tabs](../components/tabs)
diff --git a/...ibuting/react-documentation-site.page.mdx → ...n-guide/react-documentation-site.page.mdx b/...ibuting/react-documentation-site.page.mdx → ...n-guide/react-documentation-site.page.mdx
@@ -11,14 +11,14 @@ Name | Description
 404.page.js | Handles the 404 error page, displayed when a route is not found.
 _app.page.js | A custom `App` component that controls the page initialization and creates a shared layout between page changes.
 _document.page.js | A custom `Document` component that allows you to modify the initial HTML document structure. You can configure the `<html>` and `<body>` tags, set up meta tags, or add scripts and styles necessary for server-side rendering.
-[getting-started/](../../getting-started) | Contains the getting started guide for Tonic UI.
-[patterns/](../../patterns) | Contains documentation on design patterns and best practices for Tonic UI.
-[components/](../../components) | Contains documentation for Tonic UI React components: `@tonic-ui/react`
-[hooks/](../../hooks) | Contains documentation for Tonic UI React Hooks: `@tonic-ui/react-hooks`
-[icons/](../../icons) | Contains documentation for Tonic UI React Icons: `@tonic-ui/react-icons`
-[styled-system/](../../styled-system) | Contains documentation for Tonic UI Styled System: `@tonic-ui/styled-system`
-[theme/](../../theme) | Contains documentation for Tonic UI theme: `@tonic-ui/theme`
-[playground/](../../playground) | Demonstrates how to create interactive applications with Tonic UI.
+[getting-started/](../getting-started/usage) | Contains the getting started guide for Tonic UI.
+[patterns/](../patterns) | Contains documentation on design patterns and best practices for Tonic UI.
+[components/](../components) | Contains documentation for Tonic UI React components: `@tonic-ui/react`
+[hooks/](../hooks) | Contains documentation for Tonic UI React Hooks: `@tonic-ui/react-hooks`
+[icons/](../icons) | Contains documentation for Tonic UI React Icons: `@tonic-ui/react-icons`
+[styled-system/](../styled-system) | Contains documentation for Tonic UI Styled System: `@tonic-ui/styled-system`
+[theme/](../theme) | Contains documentation for Tonic UI theme: `@tonic-ui/theme`
+[playground/](../playground) | Demonstrates how to create interactive applications with Tonic UI.
 
 > Tip: Page extensions should be either `.page.js` or `.page.mdx`; otherwise, they will be treated as non-page files. If you need to use other page extensions, you can configure them in `next.config.js`.
 

diff --git a/...started/contributing/react-icons.page.mdx → ...s/contribution-guide/react-icons.page.mdx b/...started/contributing/react-icons.page.mdx → ...s/contribution-guide/react-icons.page.mdx
@@ -41,7 +41,7 @@ After generating the icons, it is important to verify that the new icons are cor
 yarn dev
 ```
 
-2. Open your browser and navigate to the documentation site (usually `http://localhost:3000`). Browse through the [React Icons](../../icons) page to ensure they are displaying correctly.
+2. Open your browser and navigate to the documentation site (usually `http://localhost:3000`). Browse through the [React Icons](../icons) page to ensure they are displaying correctly.
 
 ## Submitting Your Contribution
 

diff --git a/packages/react-docs/pages/getting-started/icons/index.page.mdx b/packages/react-docs/pages/getting-started/icons/index.page.mdx
@@ -4,4 +4,4 @@
 
 * Explore a variety of pre-defined icons with [React Icons](../icons).
 * Discover how to create custom SVG icons using [SVGIcon](../icons/svg-icon).
-* Learn about migrating icon components when upgrading from v1 to v2 [here](../getting-started/migration-v1-to-v2#icons).
+* Learn about migrating icon components when upgrading from v1 to v2 [here](../migration-guide/migrating-from-v1-to-v2#icons).
diff --git a/...started/migration-v0-to-v1/index.page.mdx → ...on-guide/migrating-from-v0-to-v1.page.mdx b/...started/migration-v0-to-v1/index.page.mdx → ...on-guide/migrating-from-v0-to-v1.page.mdx
@@ -1,4 +1,4 @@
-# Migration From v0 to v1
+# Migrating From v0 to v1
 
 ⚠️ This guide outlines the necessary steps to migrate from Tonic UI v0 to v1. Please review the breaking changes and assess the compatibility with your current setup before proceeding with the upgrade.
 

diff --git a/...started/migration-v1-to-v2/index.page.mdx → ...on-guide/migrating-from-v1-to-v2.page.mdx b/...started/migration-v1-to-v2/index.page.mdx → ...on-guide/migrating-from-v1-to-v2.page.mdx
@@ -8,13 +8,15 @@ import {
   AlertIcon,
 } from '@tonic-ui/react-icons';
 
-# Migration From v1 to v2
+# Migrating From v1 to v2
 
 ⚠️ This guide outlines the necessary steps to migrate from Tonic UI v1 to v2. Please review the breaking changes and assess the compatibility with your current setup before proceeding with the upgrade.
 
-## Color Style
+## Major Updates and Breaking Changes
 
-### What's changed
+This section highlights the major updates and breaking changes in Tonic UI v2.
+
+### Color Style
 
 > <TextLabel><Flex alignItems="center" columnGap="2x" mb="2x"><AlertIcon /> DEPRECATION NOTICE</Flex></TextLabel>
 > The following keys in the color style are deprecated and will be removed in the next major release. Please update your code with the [recommended configuration](#recommended-configuration) to avoid encountering breaking changes in the future.
@@ -122,8 +124,6 @@ const App = (props) => (
 export default App;
 ```
 
-### Recommended configuration
-
 Here is the recommended configuration for utilizing the `risk` and `severity` colors. Please note that some old keys, such as `severity.safe` and `severity.unknown`, are no longer available here. You may need to adjust your code accordingly.
 
 ```js
@@ -167,7 +167,7 @@ const customColorStyle = {
 };
 ```
 
-## Date Pickers
+### Date Pickers
 
 The [Calendar](../components/date-pickers/calendar) and [DatePicker](../components/date-pickers/date-picker) components have been moved from `@tonic-ui/react-lab` to `@tonic-ui/react`. You can import them as follows:
 
@@ -178,15 +178,15 @@ import {
 } from '@tonic-ui/react';
 ```
 
-## Icons
+### Icons
 
 In Tonic UI v2, icon components must be imported separately from the `@tonic-ui/react-icons` package. Here are two migration options to ensure a smooth transition:
 
-### Option 1: Recommended approach
+#### Option 1: Recommended approach
 
 This method is the recommended approach, although requiring the most code changes. A codemod is provided to automate this process.
 
-#### Step 1: Update dependencies
+##### Step 1: Update dependencies
 
 Ensure your `package.json` file includes the latest versions of Tonic UI packages:
 
@@ -197,7 +197,7 @@ Ensure your `package.json` file includes the latest versions of Tonic UI package
 }
 ```
 
-#### Step 2: Update import location for icon components
+##### Step 2: Update import location for icon components
 
 Update the import locations for icon components within Tonic UI v2.
 
@@ -254,7 +254,7 @@ For TypeScript files:
 npx @tonic-ui/codemod@latest react/v2.0.0/import-react-icons . --extensions=ts,tsx --parser=tsx --verbose=2
 ```
 
-#### Step 3: Remove unnecessary icons and dependencies
+##### Step 3: Remove unnecessary icons and dependencies
 
 After updating the icon imports, remove the unnecessary `@trendmicro/tmicon` dependency from your project if it was used.
 
@@ -266,11 +266,11 @@ After updating the icon imports, remove the unnecessary `@trendmicro/tmicon` dep
   }
 ```
 
-### Option 2: Backward compatible approach
+#### Option 2: Backward compatible approach
 
 This method provides backward compatibility with minimal code changes, but it disables bundle-size optimization.
 
-#### Step 1: Update dependencies
+##### Step 1: Update dependencies
 
 Ensure your `package.json` file includes the necessary Tonic UI packages:
 
@@ -282,7 +282,7 @@ Ensure your `package.json` file includes the necessary Tonic UI packages:
   }
 ```
 
-#### Step 2: Import SVG icons and generate icons for the theme
+##### Step 2: Import SVG icons and generate icons for the theme
 
 Manually generate icons and pass them to the theme to ensure your app displays icons properly after the upgrade.
 
@@ -319,3 +319,95 @@ export default () => (
   </TonicProvider>
 );
 ```
+
+## Component Modifications
+
+This section lists the changes and deprecations for various components in Tonic UI v2.
+
+> <TextLabel><Flex alignItems="center" columnGap="2x" mb="2x"><AlertIcon /> DEPRECATION NOTICE</Flex></TextLabel>
+> The following components are marked as deprecated and will be removed in the next major release. Please update your code accordingly:
+* `AccordionCollapse` is deprecated. Use `AccordionContent` instead.
+* `TableHeaderRow` is deprecated. Use `TableRow` instead.
+* `TableHeaderCell` is deprecated. Use `TableCell` instead.
+* `ToastProvider` is deprecated. Use `ToastManager` instead.
+* `useToast` is deprecated. Use `useToastManager` instead.
+
+### `Alert`
+* Removed `isCloseButtonVisible` prop
+
+### `Badge`
+* Removed `dotSize`, `isHidden`, `offset`, and `variantColor` props
+
+### `Box`
+* Removed CSS `fill` and `stroke` properties for SVG elements
+
+### `Checkbox`
+The `ref` prop now targets the outermost element. To retrieve the checked status of the input, rename `ref` to `inputRef`.
+```diff
+- <Checkbox ref={checkboxRef} />
++ <Checkbox inputRef={checkboxRef} />
+```
+
+### `CheckboxGroup`
+* Changed `onChange(value, event)` to `onChange(value)`
+
+### `InputBase`
+* Removed `isInvalid` prop
+
+### `Pagination`
+* Removed `ellipsisLabel`, `firstButton`, `lastButton`, `prevButton`, and `nextButton` props
+* Changed `onChange(event, value)` to `onChange(value)`
+
+### `Popover`
+* Removed `arrowAt`, `distance`, `hideArrow`, and `skidding` props
+* Removed `PopperArrowComponent` and `PopperArrowProps` props from `PopoverContent`
+
+### `Popper`
+* Removed `container` prop
+
+### `Portal`
+* Removed `container`, `isDisabled`, and `onRender` props
+
+### `Radio`
+The `ref` prop now targets the outermost element. To retrieve the checked status of the input, rename `ref` to `inputRef`.
+```diff
+- <Radio ref={radioRef} />
++ <Radio inputRef={radioRef} />
+```
+
+### `Spinner`
+* Removed `color`, `strokeWidth`, and `speed` props
+
+### `Scrollbar`
+* Removed `disabled`, `minThumbSize`, `visibility`, `renderView`, `renderHorizontalTrack`, `renderHorizontalThumb`, `renderVerticalTrack`, `renderVerticalThumb`, and `thumbSize` props
+
+### `Switch`
+The `ref` prop now targets the outermost element. To retrieve the checked status of the input, rename `ref` to `inputRef`.
+```diff
+- <Switch ref={switchRef} />
++ <Switch inputRef={switchRef} />
+```
+
+### `Tabs`
+* Removed `activateOnKeyPress`, `isFitted`, `isManual` props
+
+### `Table`
+* Removed `isHoverable` prop
+
+### `Tag`
+* Removed `isCloseButtonVisible`, `isInvalid`, and `variantColor` props
+
+### `Toast`
+* Removed `isCloseButtonVisible` prop.
+
+### `ToastManager`
+* Removed `container` prop
+
+### `Tooltip`
+* Removed `PopperArrowComponent`, `PopperArrowProps`, `arrowAt`, `hideArrow`, `hideDelay`, `showDelay`, and `closeOnMouseDown` props
+
+### `TooltipContent`
+* Removed `PopperArrowComponent` and `PopperArrowProps` props
+
+### `useMenu`
+* Removed `openMenu` and `closeMenu` props from the Menu context provider. Use `onOpen` and `onClose` props with the `useMenu` hook instead.