@ceed/ads 1.23.3 → 1.23.4

package/dist/components/navigation/Pagination.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-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.
+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.
 
 ```tsx
 <Stack spacing={4}>
@@ -44,28 +46,11 @@ function DataList() {
 }
 ```
 
-## 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>
-```
+## Features
 
 ### Sizes
 
-Pagination supports three sizes for different layouts.
+Pagination is available in three sizes -- `sm`, `md`, and `lg` -- for both the standard and compact variants.
 
 ```tsx
 <Stack spacing={4}>
@@ -84,9 +69,9 @@ Pagination supports three sizes for different layouts.
 </Stack>
 ```
 
-### Pages
+### Page Positions
 
-Navigation through different page positions.
+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.
 
 ```tsx
 <Stack spacing={4}>
@@ -123,25 +108,25 @@ Navigation through different page positions.
 </Stack>
 ```
 
-### Uncontrolled
+### Uncontrolled Mode
 
-Component manages its own page state.
+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.
 
 ```tsx
 <Pagination {...args} />
 ```
 
-### Controlled
+### Controlled Mode
 
-Parent component controls the page state.
+In controlled mode the parent component owns the page state via `paginationModel` and updates it through `onPageChange`. This gives full control over navigation behavior.
 
 ```tsx
 <Pagination {...args} paginationModel={paginationModel} onPageChange={handlePageChange} />
 ```
 
-### Change Row Count
+### Dynamic Row Count
 
-Pagination automatically adjusts when total items change.
+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.
 
 ```tsx
 <Stack gap={2}>
@@ -153,40 +138,23 @@ Pagination automatically adjusts when total items change.
 </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, fetchData }) {
+function DataTable({ columns }) {
   const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(25);
+  const [pageSize] = useState(25);
   const { data, totalCount, isLoading } = useFetchData(page, pageSize);
 
   return (
     <Box>
       <Table columns={columns} data={data} loading={isLoading} />
-      <Stack direction="row" justifyContent="space-between" mt={2}>
+      <Stack direction="row" justifyContent="space-between" alignItems="center" 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}
@@ -199,14 +167,13 @@ function DataTable({ columns, fetchData }) {
 }
 ```
 
-### Search Results
+### Search Results with Compact Variant
 
 ```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]);
@@ -217,7 +184,7 @@ function SearchResults({ query }) {
       <ResultList results={results} />
       <Pagination
         rowCount={totalCount}
-        defaultPaginationModel={{ page: 1, pageSize: 10 }}
+        paginationModel={{ page, pageSize: 10 }}
         onPageChange={setPage}
         variant="compact"
       />
@@ -226,322 +193,64 @@ function SearchResults({ query }) {
 }
 ```
 
-### Gallery with Pagination
+### URL-Synchronized Pagination
 
 ```tsx
-function Gallery({ images }) {
-  const pageSize = 12;
-  const [currentPage, setCurrentPage] = useState(1);
-
-  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
+function URLPaginatedList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const page = parseInt(searchParams.get('page') || '1', 10);
 
-```tsx
-function ResponsivePagination({ rowCount, page, onPageChange }) {
-  const isMobile = useMediaQuery('(max-width: 600px)');
+  const handlePageChange = (newPage: number) => {
+    setSearchParams({ page: String(newPage) });
+  };
 
   return (
     <Pagination
-      rowCount={rowCount}
-      paginationModel={{ page, pageSize: 10 }}
-      onPageChange={onPageChange}
-      variant={isMobile ? 'compact' : 'standard'}
-      size={isMobile ? 'sm' : 'md'}
+      rowCount={totalCount}
+      paginationModel={{ page, pageSize: 25 }}
+      onPageChange={handlePageChange}
     />
   );
 }
 ```
 
-## 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
 
-### ✅ Do
-
-1. **Show context**: Display total items and current range
+- **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.
 
 ```tsx
-// ✅ Good: Show pagination context
+// Good
 <Stack direction="row" justifyContent="space-between">
-  <Typography>Showing 1-25 of 250 items</Typography>
-  <Pagination rowCount={250} />
+  <Typography>Showing 1--25 of 250 items</Typography>
+  <Pagination rowCount={250} paginationModel={{ page: 1, pageSize: 25 }} onPageChange={setPage} />
 </Stack>
 ```
 
-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
+- **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.
 
 ```tsx
 useEffect(() => {
   setPage(1);
-}, [filters]);
+}, [filters, searchQuery]);
 ```
 
-### ❌ Don't
-
-1. **Don't use for very small datasets**: Pagination adds complexity
+- **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.
 
 ```tsx
-// ❌ Bad: Pagination for 5 items
-<Pagination rowCount={5} />
+// Bad -- pagination for 5 items
+<Pagination rowCount={5} paginationModel={{ page: 1, pageSize: 10 }} onPageChange={setPage} />
 
-// ✅ Good: Just show all items
+// Good -- just render the list
 <ItemList items={items} />
 ```
 
-2. **Don't hide the page count**: Users need to know how many pages exist
-
-3. **Don't use inconsistent page sizes**: Keep pageSize consistent in session
-
-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);
+- **Handle loading states.** Disable pagination controls while data is being fetched to prevent race conditions from rapid page switches.
 
-  const handlePageChange = (newPage) => {
-    setSearchParams({ page: String(newPage) });
-  };
+- **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.
 
-  return (
-    <Pagination
-      rowCount={totalCount}
-      paginationModel={{ page, pageSize: 25 }}
-      onPageChange={handlePageChange}
-    />
-  );
-}
-```
+## Accessibility
 
-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.
+- **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.