docs: update Pagination (#1695)

* refactoring main pagination demo

* more pagination examples

* pagination styling examples

* adjust styles

* demonstrate usePagination hook, and include Theme example for styling

* remove extra backticks

* remove empty code section

Co-authored-by: Joe Buono <joebuono@amazon.com>

docs/src/pages/components/pagination/PaginationPropControls.tsx

@@ -0,0 +1,81 @@
+import {
+  Flex,
+  PaginationProps,
+  StepperField,
+  SwitchField,
+} from '@aws-amplify/ui-react';
+
+export interface PaginationPropControlsProps extends PaginationProps {
+  setCurrentPage: (
+    value: React.SetStateAction<PaginationProps['currentPage']>
+  ) => void;
+  setTotalPages: (
+    value: React.SetStateAction<PaginationProps['totalPages']>
+  ) => void;
+  setSiblingCount: (
+    value: React.SetStateAction<PaginationProps['siblingCount']>
+  ) => void;
+  setHasMorePages: (
+    value: React.SetStateAction<PaginationProps['hasMorePages']>
+  ) => void;
+  onNext: () => void;
+  onPrevious: () => void;
+  onChange: (newPageIndex: number, prevPageIndex: number) => void;
+}
+
+interface PaginationPropControlsInterface {
+  (props: PaginationPropControlsProps): JSX.Element;
+}
+
+export const PaginationPropControls: PaginationPropControlsInterface = ({
+  currentPage,
+  setCurrentPage,
+  totalPages,
+  setTotalPages,
+  siblingCount,
+  setSiblingCount,
+  hasMorePages,
+  setHasMorePages,
+}) => {
+  return (
+    <Flex direction="column">
+      <StepperField
+        label="Current Page"
+        min={1}
+        max={10}
+        step={1}
+        value={currentPage}
+        onStepChange={setCurrentPage}
+      />
+
+      <StepperField
+        label="Total Pages"
+        min={10}
+        max={20}
+        step={1}
+        value={totalPages}
+        onStepChange={setTotalPages}
+      />
+
+      <StepperField
+        label="Sibling Count"
+        min={0}
+        max={3}
+        step={1}
+        value={siblingCount}
+        onStepChange={setSiblingCount}
+      />
+
+      <SwitchField
+        label="Has More Pages"
+        defaultChecked={hasMorePages}
+        labelPosition="end"
+        onChange={(event) =>
+          setHasMorePages(
+            event.target.checked as PaginationProps['hasMorePages']
+          )
+        }
+      />
+    </Flex>
+  );
+};

docs/src/pages/components/pagination/demo.tsx

@@ -1,122 +1,41 @@
-import React, { useState, useCallback } from 'react';
+import { Pagination } from '@aws-amplify/ui-react';
+import { Demo } from '@/components/Demo';
+import { PaginationPropControls } from './PaginationPropControls';
+import { usePaginationProps } from './usePaginationProps';
 
-import { Flex, Pagination } from '@aws-amplify/ui-react';
-import { Example } from '@/components/Example';
-
-interface PaginationDemoProps {
-  isDemo?: boolean;
-  defaultCurrentPage?: number;
-  defaultTotalPages?: number;
-  defaultSiblingCount?: number;
-  defaultHasMorePages?: boolean;
-}
-export const PaginationDemo: React.FC<PaginationDemoProps> = (props) => {
-  const {
-    isDemo = true,
-    defaultCurrentPage = 1,
-    defaultTotalPages = 10,
-    defaultSiblingCount = 1,
-    defaultHasMorePages = false,
-    ...rest
-  } = props;
-
-  const [currentPage, setCurrentPage] = useState(defaultCurrentPage);
-  const [totalPages, setTotalPages] = useState(defaultTotalPages);
-  const [siblingCount, setSiblingCount] = useState(defaultSiblingCount);
-  const [hasMorePages, setHasMorePages] = useState(defaultHasMorePages);
-
-  const onNext = useCallback(() => {
-    if (currentPage < totalPages) {
-      setCurrentPage(currentPage + 1);
-    }
-  }, [currentPage, totalPages]);
+const propsToCode = (paginationProps) => {
+  return (
+    `<Pagination
+  currentPage={${paginationProps.currentPage}}
+  totalPages={${paginationProps.totalPages}}
+  siblingCount={${paginationProps.siblingCount}}` +
+    (paginationProps.hasMorePages ? `\n  hasMorePages` : '') +
+    `\n/>`
+  );
+};
 
-  const onPrev = useCallback(() => {
-    if (currentPage > 1) {
-      setCurrentPage(currentPage - 1);
-    }
-  }, [currentPage]);
+export const PaginationDemo = () => {
+  const paginationProps = usePaginationProps({
+    currentPage: 1,
+    totalPages: 10,
+    siblingCount: 1,
+    hasMorePages: false,
+  });
 
-  const onChange = useCallback((newPage, prevPage) => {
-    setCurrentPage(newPage);
-  }, []);
   return (
-    <div className="amplify-pagination-demo">
-      {isDemo ? (
-        <Flex justifyContent="center" direction="column">
-          <Flex justifyContent="center">
-            <Example>
-              <Pagination
-                currentPage={currentPage}
-                totalPages={totalPages}
-                siblingCount={siblingCount}
-                hasMorePages={hasMorePages}
-                onNext={onNext}
-                onPrevious={onPrev}
-                onChange={onChange}
-                {...rest}
-              />
-            </Example>
-          </Flex>
-          <Flex justifyContent="center" alignItems="center">
-            <label htmlFor="current-page">currentPage</label>
-            <input
-              type="text"
-              id="current-page"
-              value={currentPage}
-              placeholder="Enter current page"
-              onChange={(e) => {
-                const newCurrentPage = isNaN(Number(e.target.value))
-                  ? defaultCurrentPage
-                  : Number(e.target.value);
-                setCurrentPage(newCurrentPage);
-              }}
-            />
-          </Flex>
-          <Flex justifyContent="center" alignItems="center">
-            <label htmlFor="total-pages">totalPages</label>
-            <input
-              type="text"
-              id="total-pages"
-              value={totalPages}
-              placeholder="Enter total pages"
-              onChange={(e) => {
-                const newTotalPages = isNaN(Number(e.target.value))
-                  ? defaultTotalPages
-                  : Number(e.target.value);
-                setTotalPages(newTotalPages);
-              }}
-            />
-          </Flex>
-          <Flex justifyContent="center" alignItems="center">
-            <label htmlFor="sibling-count">siblingCount</label>
-            <input
-              type="text"
-              id="sibling-count"
-              value={siblingCount}
-              placeholder="Enter sibling count"
-              onChange={(e) => {
-                const newSiblingCount = isNaN(Number(e.target.value))
-                  ? defaultSiblingCount
-                  : Number(e.target.value);
-                setSiblingCount(newSiblingCount);
-              }}
-            />
-          </Flex>
-          <Flex justifyContent="center" alignItems="center">
-            <label htmlFor="hasMorePages">hasMorePages</label>
-            <input
-              type="checkbox"
-              id="hasMorePages"
-              checked={hasMorePages}
-              placeholder="Enter hasMorePages"
-              onChange={(e) => {
-                setHasMorePages(!hasMorePages);
-              }}
-            />
-          </Flex>
-        </Flex>
-      ) : null}
-    </div>
+    <Demo
+      code={propsToCode(paginationProps)}
+      propControls={<PaginationPropControls {...paginationProps} />}
+    >
+      <Pagination
+        currentPage={paginationProps.currentPage}
+        totalPages={paginationProps.totalPages}
+        siblingCount={paginationProps.siblingCount}
+        hasMorePages={paginationProps.hasMorePages}
+        onNext={paginationProps.onNext}
+        onPrevious={paginationProps.onPrevious}
+        onChange={paginationProps.onChange}
+      />
+    </Demo>
   );
 };

docs/src/pages/components/pagination/examples/ControlledPaginationExample.tsx

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { Pagination } from '@aws-amplify/ui-react';
+
+export const ControlledPaginationExample = () => {
+  const [currentPageIndex, setCurrentPageIndex] = React.useState(1);
+  const totalPages = 5;
+
+  const handleNextPage = () => {
+    console.log('handleNextPage');
+    setCurrentPageIndex(currentPageIndex + 1);
+  };
+
+  const handlePreviousPage = () => {
+    console.log('handlePreviousPage');
+    setCurrentPageIndex(currentPageIndex - 1);
+  };
+
+  const handleOnChange = (newPageIndex, prevPageIndex) => {
+    console.log(
+      `handleOnChange \n - newPageIndex: ${newPageIndex} \n - prevPageIndex: ${prevPageIndex}`
+    );
+    setCurrentPageIndex(newPageIndex);
+  };
+
+  return (
+    <Pagination
+      currentPage={currentPageIndex}
+      totalPages={totalPages}
+      onNext={handleNextPage}
+      onPrevious={handlePreviousPage}
+      onChange={handleOnChange}
+    />
+  );
+};

docs/src/pages/components/pagination/examples/DefaultPaginationExample.tsx

@@ -0,0 +1,7 @@
+import { Pagination, usePagination } from '@aws-amplify/ui-react';
+
+export const DefaultPaginationExample = () => {
+  const paginationProps = usePagination({ totalPages: 8 });
+
+  return <Pagination {...paginationProps} />;
+};

docs/src/pages/components/pagination/examples/PaginationHasMorePagesExample.tsx

@@ -20,24 +20,14 @@ export const PaginationHasMorePagesExample = () => {
     setCurrentPageIndex(currentPageIndex + 1);
   };
 
-  const handlePreviousPage = () => {
-    if (currentPageIndex > 1) {
-      setCurrentPageIndex(currentPageIndex - 1);
-    }
-  };
-
-  const handleOnChange = (pageIndex) => {
-    setCurrentPageIndex(pageIndex);
-  };
-
   return (
     <Pagination
       currentPage={currentPageIndex}
       totalPages={pageTokens.length}
       hasMorePages={hasMorePages}
       onNext={handleNextPage}
-      onPrevious={handlePreviousPage}
-      onChange={handleOnChange}
+      onPrevious={() => setCurrentPageIndex(currentPageIndex - 1)}
+      onChange={(pageIndex) => setCurrentPageIndex(pageIndex)}
     />
   );
 };

docs/src/pages/components/pagination/examples/PaginationSiblingCountExample.tsx

@@ -0,0 +1,11 @@
+import { Pagination, usePagination } from '@aws-amplify/ui-react';
+
+export const PaginationSiblingCountExample = () => {
+  const paginationProps = usePagination({
+    totalPages: 11,
+    currentPage: 5,
+    siblingCount: 2,
+  });
+
+  return <Pagination {...paginationProps} />;
+};

docs/src/pages/components/pagination/examples/PaginationStylingExample.tsx

@@ -0,0 +1,11 @@
+import { Pagination, usePagination } from '@aws-amplify/ui-react';
+
+export const PaginationStylingExample = ({
+  className,
+  totalPages,
+  ...rest
+}) => {
+  const paginationProps = usePagination({ totalPages });
+
+  return <Pagination className={className} {...paginationProps} {...rest} />;
+};

docs/src/pages/components/pagination/examples/PaginationThemeExample.tsx

@@ -0,0 +1,34 @@
+import {
+  AmplifyProvider,
+  Pagination,
+  usePagination,
+} from '@aws-amplify/ui-react';
+
+const theme = {
+  name: 'pagination-theme',
+  tokens: {
+    components: {
+      pagination: {
+        current: {
+          backgroundColor: { value: 'rebeccapurple' },
+        },
+        button: {
+          hover: {
+            backgroundColor: { value: '{colors.neutral.40.value}' },
+            color: { value: '{colors.white.value}' },
+          },
+        },
+      },
+    },
+  },
+};
+
+export const PaginationThemeExample = () => {
+  const paginationProps = usePagination({ totalPages: 6 });
+
+  return (
+    <AmplifyProvider theme={theme}>
+      <Pagination {...paginationProps} />
+    </AmplifyProvider>
+  );
+};

docs/src/pages/components/pagination/examples/index.ts

@@ -1 +1,6 @@
+export { ControlledPaginationExample } from './ControlledPaginationExample';
+export { DefaultPaginationExample } from './DefaultPaginationExample';
+export { PaginationStylingExample } from './PaginationStylingExample';
 export { PaginationHasMorePagesExample } from './PaginationHasMorePagesExample';
+export { PaginationSiblingCountExample } from './PaginationSiblingCountExample';
+export { PaginationThemeExample } from './PaginationThemeExample';