docs(style): update style guide for component naming

docs/style.md

@@ -390,11 +390,6 @@ made before an official release.
 For experimental or unstable code, we use the `unstable_` prefix. For example:
 
 ```js
-// An unstable component
-function unstable_Pagination(props) {
-  // ...
-}
-
 // An unstable method
 function unstable_layout() {
   // ...
@@ -404,6 +399,16 @@ function unstable_layout() {
 const unstable_meta = {
   // ...
 };
+
+// An unstable component will retain its name, specifically for things like
+// the rules of hooks plugin which depend on the correct casing of the name
+function Pagination(props) {
+  // ...
+}
+
+// However, when we export the component we will export it with the `unstable_`
+// prefix. (Similar to React.unstable_Suspense, React.unstable_Profiler)
+export { default as unstable_Pagination } from './components/Pagination';
 ```
 
 For teams using these features, they will need to import the functionality by
@@ -416,28 +421,6 @@ import { unstable_Pagination as Pagination } from 'carbon-components-react';
 This code should be treated as experimental and will break between release
 versions for the package that it is being imported from.
 
-<table>
-<thead><tr><th>Unpreferred</th><th>Preferred</th></tr></thead>
-<tbody>
-<tr><td>
-
-```jsx
-function Unstable_MyComponent() {
-  // ...
-}
-```
-
-</td><td>
-
-```jsx
-function unstable_MyComponent() {
-  // ...
-}
-```
-
-</td></tr>
-</tbody></table>
-
 ## Sass
 
 ### Guidelines

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -6451,7 +6451,7 @@ Map {
       },
     },
   },
-  "PageSelector" => Object {
+  "unstable_PageSelector" => Object {
     "defaultProps": Object {
       "className": null,
       "id": 1,
@@ -6487,7 +6487,7 @@ Map {
       },
     },
   },
-  "Unstable_Pagination" => Object {
+  "unstable_Pagination" => Object {
     "defaultProps": Object {
       "backwardText": "Previous page",
       "children": undefined,

packages/react/src/__tests__/index-test.js

@@ -90,7 +90,6 @@ describe('Carbon Components React', () => {
         "OrderedList",
         "OverflowMenu",
         "OverflowMenuItem",
-        "PageSelector",
         "Pagination",
         "PaginationNav",
         "PaginationSkeleton",
@@ -192,7 +191,8 @@ describe('Carbon Components React', () => {
         "TooltipDefinition",
         "TooltipIcon",
         "UnorderedList",
-        "Unstable_Pagination",
+        "unstable_PageSelector",
+        "unstable_Pagination",
       ]
     `);
   });

packages/react/src/components/Pagination/Unstable_Pagination/Pagination-story.js → packages/react/src/components/Pagination/experimental/Pagination-story.js

@@ -15,9 +15,10 @@ import {
   text,
   withKnobs,
 } from '@storybook/addon-knobs';
-
-import Unstable_Pagination from './Pagination';
-import PageSelector from './PageSelector';
+import {
+  unstable_PageSelector as PageSelector,
+  unstable_Pagination as Pagination,
+} from '../../../';
 
 const props = () => ({
   disabled: boolean('Disable backward/forward buttons (disabled)', false),
@@ -38,13 +39,13 @@ const props = () => ({
   onChange: action('onChange'),
 });
 
-storiesOf('UNSTABLE Pagination', module)
+storiesOf('unstable_Pagination', module)
   .addDecorator(withKnobs)
   .addDecorator((story) => <div style={{ width: '800px' }}>{story()}</div>)
   .add(
     'with a page selector',
     () => (
-      <Unstable_Pagination
+      <Pagination
         {...props()}
         totalItems={350}
         pageSizes={array('Choices of `pageSize` (pageSizes)', [10, 20, 30])}>
@@ -56,26 +57,26 @@ storiesOf('UNSTABLE Pagination', module)
             totalPages={totalPages}
           />
         )}
-      </Unstable_Pagination>
+      </Pagination>
     ),
     {
       info: {
-        propTables: [Unstable_Pagination, PageSelector],
+        propTables: [Pagination, PageSelector],
         text: `
             🚨 This component is *experimental* and may change. 🚨
-            \`Unstable_Pagination\` accepts a render prop \`children\`.
+            \`Pagination\` accepts a render prop \`children\`.
             This example wraps the \`children\` (\`PageSelector\`) in a function, allowing it to pass information back to the parent component.
             \`\`\`jsx
-            {/** 
-              * Provide \`totalItems\` to \`Unstable_Pagination\` when using the \`PageSelector\` child.
-              * \`Unstable_Pagination\` uses \`totalItems\` to calculate \`totalPages\`.
+            {/**
+              * Provide \`totalItems\` to \`Pagination\` when using the \`PageSelector\` child.
+              * \`Pagination\` uses \`totalItems\` to calculate \`totalPages\`.
               * And then, \`PageSelector\` uses the calculated \`totalPages\` to accurately display page options.
               */}
-            <Unstable_Pagination
+            <Pagination
               totalItems={350}
               pageSizes={[10, 15, 20, 25]}
             >
-              {/** 
+              {/**
                 * Below, \`children\` is a render prop, wrapped in a function.
                 * - \`currentPage\` is used to display the current page.
                 * - \`onSetPage\` is used to update the current page state in the parent component.
@@ -89,20 +90,20 @@ storiesOf('UNSTABLE Pagination', module)
                   totalPages={totalPages}
                 />
               )}
-            </Unstable_Pagination>
+            </Pagination>
             \`\`\`
           `,
       },
     }
   )
   .add(
     'with no sizer, child input, or child selector',
-    () => <Unstable_Pagination {...props()} totalItems={350} />,
+    () => <Pagination {...props()} totalItems={350} />,
     {
       info: {
         text: `
           🚨 This component is *experimental* and may change. 🚨
-          Without \`children\`, \`Unstable_Pagination\` renders without a page selector. 
+          Without \`children\`, \`Pagination\` renders without a page selector.
         `,
       },
     }

packages/react/src/components/Pagination/Unstable_Pagination/Pagination.js → packages/react/src/components/Pagination/experimental/Pagination.js

@@ -16,7 +16,7 @@ import SelectItem from '../../SelectItem';
 
 const { prefix } = settings;
 
-function Unstable_Pagination({
+function Pagination({
   backwardText,
   children,
   className,
@@ -166,26 +166,7 @@ function Unstable_Pagination({
   );
 }
 
-Unstable_Pagination.defaultProps = {
-  backwardText: 'Previous page',
-  className: null,
-  children: undefined,
-  disabled: false,
-  forwardText: 'Next page',
-  id: 1,
-  itemsPerPageText: 'Items per page:',
-  itemRangeText: (min, max, total) => `${min}–${max} of ${total} items`,
-  itemText: (min, max) => `${min}–${max} items`,
-  initialPage: 1,
-  pageRangeText: (current, total) => `${current} of ${total} pages`,
-  pageSize: 10,
-  pageSizes: undefined,
-  pageText: (page) => `page ${page}`,
-  pagesUnknown: false,
-  totalItems: undefined,
-};
-
-Unstable_Pagination.propTypes = {
+Pagination.propTypes = {
   /**
    * The description for the backward icon.
    */
@@ -270,4 +251,23 @@ Unstable_Pagination.propTypes = {
   totalItems: PropTypes.number,
 };
 
-export default Unstable_Pagination;
+Pagination.defaultProps = {
+  backwardText: 'Previous page',
+  className: null,
+  children: undefined,
+  disabled: false,
+  forwardText: 'Next page',
+  id: 1,
+  itemsPerPageText: 'Items per page:',
+  itemRangeText: (min, max, total) => `${min}–${max} of ${total} items`,
+  itemText: (min, max) => `${min}–${max} items`,
+  initialPage: 1,
+  pageRangeText: (current, total) => `${current} of ${total} pages`,
+  pageSize: 10,
+  pageSizes: undefined,
+  pageText: (page) => `page ${page}`,
+  pagesUnknown: false,
+  totalItems: undefined,
+};
+
+export default Pagination;

packages/react/src/components/Pagination/Unstable_Pagination/index.js → packages/react/src/components/Pagination/experimental/index.js

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export Unstable_Pagination from './Pagination';
+export Pagination from './Pagination';
 export PageSelector from './PageSelector';

packages/react/src/index.js

@@ -169,6 +169,6 @@ export * from './components/UIShell';
 
 // experimental
 export {
-  PageSelector,
-  Unstable_Pagination,
-} from './components/Pagination/Unstable_Pagination';
+  PageSelector as unstable_PageSelector,
+  Pagination as unstable_Pagination,
+} from './components/Pagination/experimental';