@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/navigation/Pagination.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-The Pagination component enables users to navigate through large datasets or content collections that are divided into discrete pages. It provides controls for moving forward and backward, jumping to specific pages, and understanding the current position within the total set.
-
-Pagination ships in two variants -- **standard** (clickable page numbers) and **compact** (dropdown selector) -- making it suitable for different screen sizes and layout constraints. It supports both controlled and uncontrolled usage patterns to integrate smoothly with any state management approach.
+Pagination allows users to navigate through large datasets or content collections by dividing them into discrete pages. It provides intuitive controls for moving between pages, jumping to specific pages, and understanding the current position within the total dataset. Pagination comes in two variants: standard (page numbers) and compact (dropdown selector), making it suitable for different space constraints and use cases.
 
 ```tsx
 <Stack spacing={4}>
@@ -46,11 +44,28 @@ function DataList() {
 }
 ```
 
-## Features
+## Examples
+
+### Playground
+
+Both standard and compact variants displayed together.
+
+```tsx
+<Stack spacing={4}>
+  <Stack spacing={1}>
+    <div>Standard</div>
+    <Pagination {...args} variant="standard" />
+  </Stack>
+  <Stack spacing={1}>
+    <div>Compact</div>
+    <Pagination {...args} variant="compact" />
+  </Stack>
+</Stack>
+```
 
 ### Sizes
 
-Pagination is available in three sizes -- `sm`, `md`, and `lg` -- for both the standard and compact variants.
+Pagination supports three sizes for different layouts.
 
 ```tsx
 <Stack spacing={4}>
@@ -69,9 +84,9 @@ Pagination is available in three sizes -- `sm`, `md`, and `lg` -- for both the s
 </Stack>
 ```
 
-### Page Positions
+### Pages
 
-The component correctly handles the visual presentation when the user is at the beginning, middle, or end of the page range, adjusting ellipsis buttons and disabled states accordingly.
+Navigation through different page positions.
 
 ```tsx
 <Stack spacing={4}>
@@ -108,25 +123,25 @@ The component correctly handles the visual presentation when the user is at the
 </Stack>
 ```
 
-### Uncontrolled Mode
+### Uncontrolled
 
-In uncontrolled mode the component manages its own page state internally. Pass `defaultPaginationModel` to set the initial state and use `onPageChange` to react to changes.
+Component manages its own page state.
 
 ```tsx
 <Pagination {...args} />
 ```
 
-### Controlled Mode
+### Controlled
 
-In controlled mode the parent component owns the page state via `paginationModel` and updates it through `onPageChange`. This gives full control over navigation behavior.
+Parent component controls the page state.
 
 ```tsx
 <Pagination {...args} paginationModel={paginationModel} onPageChange={handlePageChange} />
 ```
 
-### Dynamic Row Count
+### Change Row Count
 
-Pagination automatically adjusts when the total number of items changes. If the current page exceeds the new page count, the component clamps to the last available page.
+Pagination automatically adjusts when total items change.
 
 ```tsx
 <Stack gap={2}>
@@ -138,23 +153,40 @@ Pagination automatically adjusts when the total number of items changes. If the
 </Stack>
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Data tables**: Navigate through paginated table data
+- **Search results**: Browse through multiple pages of results
+- **Content listings**: Articles, products, or any list content
+- **Admin panels**: Managing records across multiple pages
+- **API data**: When server returns paginated responses
+
+### ❌ When Not to Use
+
+- **Infinite scroll**: When content loads continuously on scroll
+- **Small datasets**: Less than 20 items don't need pagination
+- **Single content**: Individual articles or detail views
+- **Sequential flows**: Use Stepper for multi-step processes
+- **Real-time data**: Frequently updating data may shift pages unpredictably
+
 ## Common Use Cases
 
 ### Data Table Pagination
 
 ```tsx
-function DataTable({ columns }) {
+function DataTable({ columns, fetchData }) {
   const [page, setPage] = useState(1);
-  const [pageSize] = useState(25);
+  const [pageSize, setPageSize] = useState(25);
   const { data, totalCount, isLoading } = useFetchData(page, pageSize);
 
   return (
     <Box>
       <Table columns={columns} data={data} loading={isLoading} />
-      <Stack direction="row" justifyContent="space-between" alignItems="center" mt={2}>
+      <Stack direction="row" justifyContent="space-between" mt={2}>
         <Typography level="body-sm">
-          Showing {(page - 1) * pageSize + 1}--{Math.min(page * pageSize, totalCount)} of{' '}
-          {totalCount}
+          Showing {(page - 1) * pageSize + 1} - {Math.min(page * pageSize, totalCount)} of {totalCount}
         </Typography>
         <Pagination
           rowCount={totalCount}
@@ -167,13 +199,14 @@ function DataTable({ columns }) {
 }
 ```
 
-### Search Results with Compact Variant
+### Search Results
 
 ```tsx
 function SearchResults({ query }) {
   const [page, setPage] = useState(1);
   const { results, totalCount } = useSearch(query, page);
 
+  // Reset to page 1 when query changes
   useEffect(() => {
     setPage(1);
   }, [query]);
@@ -184,7 +217,7 @@ function SearchResults({ query }) {
       <ResultList results={results} />
       <Pagination
         rowCount={totalCount}
-        paginationModel={{ page, pageSize: 10 }}
+        defaultPaginationModel={{ page: 1, pageSize: 10 }}
         onPageChange={setPage}
         variant="compact"
       />
@@ -193,64 +226,322 @@ function SearchResults({ query }) {
 }
 ```
 
-### URL-Synchronized Pagination
+### Gallery with Pagination
 
 ```tsx
-function URLPaginatedList() {
-  const [searchParams, setSearchParams] = useSearchParams();
-  const page = parseInt(searchParams.get('page') || '1', 10);
+function Gallery({ images }) {
+  const pageSize = 12;
+  const [currentPage, setCurrentPage] = useState(1);
 
-  const handlePageChange = (newPage: number) => {
-    setSearchParams({ page: String(newPage) });
-  };
+  const paginatedImages = useMemo(() => {
+    const start = (currentPage - 1) * pageSize;
+    return images.slice(start, start + pageSize);
+  }, [images, currentPage, pageSize]);
+
+  return (
+    <Box>
+      <Grid container spacing={2}>
+        {paginatedImages.map((image) => (
+          <Grid key={image.id} xs={4}>
+            <ImageCard image={image} />
+          </Grid>
+        ))}
+      </Grid>
+      <Box display="flex" justifyContent="center" mt={3}>
+        <Pagination
+          rowCount={images.length}
+          paginationModel={{ page: currentPage, pageSize }}
+          onPageChange={setCurrentPage}
+        />
+      </Box>
+    </Box>
+  );
+}
+```
+
+### API Pagination
+
+```tsx
+function APIList() {
+  const [paginationModel, setPaginationModel] = useState({
+    page: 1,
+    pageSize: 20,
+  });
+
+  const { data } = useQuery({
+    queryKey: ['items', paginationModel],
+    queryFn: () => fetchItems({
+      page: paginationModel.page,
+      limit: paginationModel.pageSize,
+    }),
+  });
+
+  return (
+    <Box>
+      <ItemList items={data?.items || []} />
+      <Pagination
+        rowCount={data?.totalCount || 0}
+        paginationModel={paginationModel}
+        onPageChange={(newPage) =>
+          setPaginationModel((prev) => ({ ...prev, page: newPage }))
+        }
+      />
+    </Box>
+  );
+}
+```
+
+### Compact Pagination for Mobile
+
+```tsx
+function ResponsivePagination({ rowCount, page, onPageChange }) {
+  const isMobile = useMediaQuery('(max-width: 600px)');
 
   return (
     <Pagination
-      rowCount={totalCount}
-      paginationModel={{ page, pageSize: 25 }}
-      onPageChange={handlePageChange}
+      rowCount={rowCount}
+      paginationModel={{ page, pageSize: 10 }}
+      onPageChange={onPageChange}
+      variant={isMobile ? 'compact' : 'standard'}
+      size={isMobile ? 'sm' : 'md'}
     />
   );
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                     | Type                                 | Default                     | Description                  |
+| ------------------------ | ------------------------------------ | --------------------------- | ---------------------------- |
+| `rowCount`               | `number`                             | -                           | Total number of items        |
+| `paginationModel`        | `{ page: number; pageSize: number }` | -                           | Controlled pagination state  |
+| `defaultPaginationModel` | `{ page: number; pageSize: number }` | `{ page: 1, pageSize: 25 }` | Default state (uncontrolled) |
+| `onPageChange`           | `(newPage: number) => void`          | -                           | Callback when page changes   |
+| `variant`                | `'standard' \| 'compact'`            | `'standard'`                | Pagination style             |
+| `size`                   | `'sm' \| 'md' \| 'lg'`               | `'md'`                      | Component size               |
+
+### Variant Comparison
+
+| Feature              | Standard     | Compact             |
+| -------------------- | ------------ | ------------------- |
+| Page numbers visible | Yes          | No                  |
+| Quick page jump      | Click number | Dropdown select     |
+| Space required       | More         | Less                |
+| Best for             | Desktop      | Mobile/tight spaces |
+
+### Controlled vs Uncontrolled
+
+```tsx
+// Uncontrolled - component manages state
+<Pagination
+  rowCount={100}
+  defaultPaginationModel={{ page: 1, pageSize: 10 }}
+  onPageChange={(page) => console.log('Page:', page)}
+/>
+
+// Controlled - you manage state
+const [page, setPage] = useState(1);
+<Pagination
+  rowCount={100}
+  paginationModel={{ page, pageSize: 10 }}
+  onPageChange={setPage}
+/>
+```
+
+### Page Calculation
+
+The component automatically calculates total pages:
+
+```tsx
+// With 95 items and pageSize of 10:
+// totalPages = Math.ceil(95 / 10) = 10 pages
+
+<Pagination
+  rowCount={95}
+  paginationModel={{ page: 1, pageSize: 10 }}
+  onPageChange={handleChange}
+/>
+```
+
+## Accessibility
+
+Pagination includes built-in accessibility features:
+
+### ARIA Attributes
+
+- Current page marked with `aria-current="page"`
+- Navigation buttons have descriptive `aria-label` attributes
+- Disabled buttons properly marked with `disabled`
+
+### Keyboard Navigation
+
+- **Tab**: Move through pagination controls
+- **Enter/Space**: Activate focused button
+- **Arrow Keys**: Navigate within the compact dropdown
+
+### Screen Reader Support
+
+```tsx
+// Buttons announce their purpose
+<button aria-label="Previous page">←</button>
+<button aria-label="Next page">→</button>
+<button aria-label="More previous pages">...</button>
+<button aria-current="page">5</button>  // "Page 5, current"
+```
+
+### Status Announcements
+
+Consider adding live region for page changes:
+
+```tsx
+function PaginatedList() {
+  const [page, setPage] = useState(1);
+
+  return (
+    <>
+      <div aria-live="polite" className="sr-only">
+        Page {page} of {totalPages}
+      </div>
+      <Pagination onPageChange={setPage} />
+    </>
+  );
+}
+```
+
 ## Best Practices
 
-- **Always show context.** Display the total item count and current range (for example "Showing 1--25 of 250") alongside the pagination controls so users understand the scope of the data.
+### ✅ Do
+
+1. **Show context**: Display total items and current range
 
 ```tsx
-// Good
+// ✅ Good: Show pagination context
 <Stack direction="row" justifyContent="space-between">
-  <Typography>Showing 1--25 of 250 items</Typography>
-  <Pagination rowCount={250} paginationModel={{ page: 1, pageSize: 25 }} onPageChange={setPage} />
+  <Typography>Showing 1-25 of 250 items</Typography>
+  <Pagination rowCount={250} />
 </Stack>
 ```
 
-- **Reset to page 1 when filters change.** When the user applies a new filter or search query, always reset the page to 1 to avoid showing an empty or out-of-range page.
+2. **Start from page 1**: Users expect 1-based pagination
+
+```tsx
+// ✅ Good: 1-based pagination
+defaultPaginationModel={{ page: 1, pageSize: 25 }}
+```
+
+3. **Handle empty states**: Show appropriate UI when there's no data
+
+```tsx
+{totalCount > 0 ? (
+  <Pagination rowCount={totalCount} />
+) : (
+  <Typography>No results found</Typography>
+)}
+```
+
+4. **Reset on filter changes**: Return to page 1 when filters change
 
 ```tsx
 useEffect(() => {
   setPage(1);
-}, [filters, searchQuery]);
+}, [filters]);
 ```
 
-- **Do not paginate very small datasets.** If the total number of items fits comfortably on a single screen, display all items directly instead of adding pagination overhead.
+### ❌ Don't
+
+1. **Don't use for very small datasets**: Pagination adds complexity
 
 ```tsx
-// Bad -- pagination for 5 items
-<Pagination rowCount={5} paginationModel={{ page: 1, pageSize: 10 }} onPageChange={setPage} />
+// ❌ Bad: Pagination for 5 items
+<Pagination rowCount={5} />
 
-// Good -- just render the list
+// ✅ Good: Just show all items
 <ItemList items={items} />
 ```
 
-- **Handle loading states.** Disable pagination controls while data is being fetched to prevent race conditions from rapid page switches.
+2. **Don't hide the page count**: Users need to know how many pages exist
 
-- **Use the compact variant on small screens.** The standard variant with page numbers can overflow on narrow viewports. Switch to `variant="compact"` or reduce the `size` prop for responsive layouts.
+3. **Don't use inconsistent page sizes**: Keep pageSize consistent in session
 
-## Accessibility
+4. **Don't forget loading states**: Show loading while fetching page data
+
+```tsx
+// ✅ Good: Handle loading
+<Pagination disabled={isLoading} />
+```
+
+## Performance Considerations
+
+### Server-Side Pagination
+
+For large datasets, paginate on the server:
+
+```tsx
+function ServerPaginatedList() {
+  const [page, setPage] = useState(1);
+  const pageSize = 25;
+
+  const { data, isLoading } = useQuery({
+    queryKey: ['items', page, pageSize],
+    queryFn: () => api.getItems({ page, pageSize }),
+    keepPreviousData: true, // Keep old data while loading
+  });
+
+  return (
+    <>
+      <ItemList items={data?.items} loading={isLoading} />
+      <Pagination
+        rowCount={data?.totalCount || 0}
+        paginationModel={{ page, pageSize }}
+        onPageChange={setPage}
+      />
+    </>
+  );
+}
+```
+
+### Memoize Handlers
+
+When used in complex components, memoize the change handler:
+
+```tsx
+const handlePageChange = useCallback((newPage) => {
+  setPage(newPage);
+}, []);
+```
+
+### Virtualization Alternative
+
+For very large datasets, consider virtualization instead of pagination:
+
+```tsx
+// Instead of pagination for 10,000+ items:
+<VirtualizedList items={items} itemHeight={50} />
+```
+
+### URL Sync
+
+For shareable pagination state, sync with URL:
+
+```tsx
+function URLPaginatedList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const page = parseInt(searchParams.get('page') || '1', 10);
+
+  const handlePageChange = (newPage) => {
+    setSearchParams({ page: String(newPage) });
+  };
+
+  return (
+    <Pagination
+      rowCount={totalCount}
+      paginationModel={{ page, pageSize: 25 }}
+      onPageChange={handlePageChange}
+    />
+  );
+}
+```
 
-- **ARIA attributes**: The current page button is marked with `aria-current="page"`. Previous and next buttons carry descriptive `aria-label` values such as "Previous page" and "Next page".
-- **Keyboard navigation**: All pagination buttons are focusable with `Tab` and activated with `Enter` or `Space`. In the compact variant, arrow keys navigate the dropdown options.
-- **Disabled states**: When the user is on the first or last page, the corresponding navigation button is properly disabled and announced as such to assistive technologies.
-- **Live region consideration**: For dynamic content updates, consider wrapping a status message in an `aria-live="polite"` region to announce the current page to screen reader users.
+Pagination is essential for managing large datasets in admin interfaces. Choose between standard and compact variants based on available space and user needs, ensuring a smooth navigation experience through your data.