[@react-ui] Add initialSelectedPage to Pagination Component

packages/libs/react-ui/src/components/Pagination/Pagination.stories.tsx

@@ -1,7 +1,6 @@
 import { SystemIcon } from '@components/Icon';
 import { IPaginationProps, Pagination } from '@components/Pagination';
 import { Stack } from '@components/Stack';
-import { Heading } from '@components/Typography';
 import type { Meta, StoryObj } from '@storybook/react';
 import React from 'react';
 
@@ -14,11 +13,36 @@ const meta: Meta<
   } & IPaginationProps
 > = {
   title: 'Components/Pagination',
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'This is a navigation component that is used to visually represent and provide interaction elements for pagination. I provides previous and next buttons as well as a subset of the available pages closest to the selected page.<br><br><i>This component has a controlled and uncontrolled state. When a currentPage is not provided, the component will track state internally.</i>',
+      },
+    },
+  },
   argTypes: {
     label: {
       control: {
         type: 'text',
       },
+      description:
+        'Text that is passed to the Nav element as an aria-label for accessibility.',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    currentPage: {
+      control: {
+        type: 'number',
+        min: 1,
+        max: 20,
+        step: 1,
+      },
+      description: 'Current page number. Used when component is controlled.',
+      table: {
+        type: { summary: 'number' },
+      },
     },
     totalPages: {
       control: {
@@ -27,6 +51,10 @@ const meta: Meta<
         max: 20,
         step: 2,
       },
+      description: 'Total number of pages.',
+      table: {
+        type: { summary: 'number' },
+      },
     },
     visiblePageLimit: {
       control: {
@@ -35,6 +63,23 @@ const meta: Meta<
         max: 7,
         step: 1,
       },
+      description:
+        'Number of pages that are visible and can be directly selected.',
+      table: {
+        type: { summary: 'number' },
+      },
+    },
+    initialSelectedPage: {
+      control: {
+        type: 'number',
+        min: 1,
+        max: 20,
+        step: 1,
+      },
+      description: 'The default selected page before any interaction.',
+      table: {
+        type: { summary: 'number' },
+      },
     },
   },
 };
@@ -50,22 +95,28 @@ type Story = StoryObj<IPaginationProps>;
 
 export const Controlled: Story = {
   args: {
-    label: 'Label',
+    label: 'Pagination',
     totalPages: 10,
     visiblePageLimit: 3,
+    initialSelectedPage: 2,
+    currentPage: 2,
   },
-  render: ({ totalPages, label, visiblePageLimit }) => {
-    const [page, setPage] = React.useState(1);
-
+  render: ({
+    totalPages,
+    label,
+    visiblePageLimit,
+    initialSelectedPage,
+    currentPage,
+  }) => {
     return (
       <Stack direction="column" gap="$4">
-        <Heading as="h6">Controlled Page State: {page}</Heading>
         <Pagination
           totalPages={totalPages}
-          currentPage={page}
+          currentPage={currentPage}
           label={label}
           visiblePageLimit={visiblePageLimit}
-          onPageChange={setPage}
+          initialSelectedPage={initialSelectedPage}
+          onPageChange={() => console.log('Updating Page')}
         />
       </Stack>
     );
@@ -77,13 +128,15 @@ export const Uncontrolled: Story = {
     label: 'Label',
     totalPages: 10,
     visiblePageLimit: 3,
+    initialSelectedPage: 2,
   },
-  render: ({ totalPages, label, visiblePageLimit }) => {
+  render: ({ totalPages, label, visiblePageLimit, initialSelectedPage }) => {
     return (
       <Pagination
         totalPages={totalPages}
         label={label}
         visiblePageLimit={visiblePageLimit}
+        initialSelectedPage={initialSelectedPage}
         onPageChange={() => console.log('Updating Page')}
       />
     );

packages/libs/react-ui/src/components/Pagination/Pagination.tsx

@@ -12,6 +12,7 @@ export interface IPaginationProps {
   currentPage?: number;
   label: string;
   visiblePageLimit?: number;
+  initialSelectedPage?: number;
   onPageChange: (page: number) => void;
 }
 
@@ -20,9 +21,17 @@ export const Pagination: FC<IPaginationProps> = ({
   currentPage,
   label,
   visiblePageLimit = 3,
+  initialSelectedPage,
   onPageChange,
 }) => {
-  const [_page, setPage] = useState(1);
+  const validInitialSelectedPage =
+    initialSelectedPage &&
+    initialSelectedPage <= totalPages &&
+    initialSelectedPage > 0;
+
+  const [_page, setPage] = useState(
+    validInitialSelectedPage ? initialSelectedPage : 1,
+  );
   const page = currentPage || _page;
   const pages = paginate({
     page,
@@ -32,7 +41,7 @@ export const Pagination: FC<IPaginationProps> = ({
   const enablePrevious = page > 1;
   const enableNext = page < totalPages;
 
-  const onClick = (page: number) => {
+  const onClick = (page: number): void => {
     setPage(page);
     onPageChange(page);
   };
@@ -49,12 +58,14 @@ export const Pagination: FC<IPaginationProps> = ({
           />
         </li>
         {pages.map((pageNum) => (
-          <PageNum
-            key={pageNum}
-            number={pageNum}
-            current={pageNum === page}
-            onClick={() => onClick(pageNum)}
-          />
+          <li key={pageNum}>
+            <PageNum
+              key={pageNum}
+              number={pageNum}
+              current={pageNum === page}
+              onClick={() => onClick(pageNum)}
+            />
+          </li>
         ))}
         <li>
           <PageNav