@ceed/ads 1.20.0 → 1.20.1-next.1

package/dist/components/navigation/Pagination.md

@@ -2,6 +2,8 @@
 
 ## 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.
+
 ```tsx
 <Stack spacing={4}>
   <Stack spacing={1}>
@@ -23,4 +25,523 @@
 
 ```tsx
 import { Pagination } from '@ceed/ads';
+
+function DataList() {
+  const [page, setPage] = useState(1);
+  const pageSize = 10;
+  const totalItems = 250;
+
+  return (
+    <>
+      <ItemList items={items} page={page} pageSize={pageSize} />
+      <Pagination
+        rowCount={totalItems}
+        paginationModel={{ page, pageSize }}
+        onPageChange={setPage}
+      />
+    </>
+  );
+}
+```
+
+## 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 supports three sizes for different layouts.
+
+```tsx
+<Stack spacing={4}>
+  <Stack spacing={2}>
+    <div>Standard</div>
+    <Pagination {...args} variant="standard" size="sm" />
+    <Pagination {...args} variant="standard" size="md" />
+    <Pagination {...args} variant="standard" size="lg" />
+  </Stack>
+  <Stack spacing={2}>
+    <div>Compact</div>
+    <Pagination {...args} variant="compact" size="sm" />
+    <Pagination {...args} variant="compact" size="md" />
+    <Pagination {...args} variant="compact" size="lg" />
+  </Stack>
+</Stack>
+```
+
+### Pages
+
+Navigation through different page positions.
+
+```tsx
+<Stack spacing={4}>
+  <Stack spacing={2}>
+    <div>Standard</div>
+    <Pagination {...args} variant="standard" defaultPaginationModel={{
+      page: 1,
+      pageSize: 1
+    }} />
+    <Pagination {...args} variant="standard" defaultPaginationModel={{
+      page: 10,
+      pageSize: 1
+    }} />
+    <Pagination {...args} variant="standard" defaultPaginationModel={{
+      page: 20,
+      pageSize: 1
+    }} />
+  </Stack>
+  <Stack spacing={2}>
+    <div>Compact</div>
+    <Pagination {...args} variant="compact" defaultPaginationModel={{
+      page: 1,
+      pageSize: 1
+    }} />
+    <Pagination {...args} variant="compact" defaultPaginationModel={{
+      page: 10,
+      pageSize: 1
+    }} />
+    <Pagination {...args} variant="compact" defaultPaginationModel={{
+      page: 20,
+      pageSize: 1
+    }} />
+  </Stack>
+</Stack>
+```
+
+### Uncontrolled
+
+Component manages its own page state.
+
+```tsx
+<Pagination {...args} />
 ```
+
+### Controlled
+
+Parent component controls the page state.
+
+```tsx
+<Pagination {...args} paginationModel={paginationModel} onPageChange={handlePageChange} />
+```
+
+### Change Row Count
+
+Pagination automatically adjusts when total items change.
+
+```tsx
+<Stack gap={2}>
+  <Pagination {...args} rowCount={rowCount} />
+  <Stack direction="row" gap={2}>
+    <Button onClick={() => setRowCount(rowCount - 1)}>Decrease Row count</Button>
+    <Button onClick={() => setRowCount(rowCount + 1)}>Increase Row count</Button>
+  </Stack>
+</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 }) {
+  const [page, setPage] = useState(1);
+  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" mt={2}>
+        <Typography level="body-sm">
+          Showing {(page - 1) * pageSize + 1} - {Math.min(page * pageSize, totalCount)} of {totalCount}
+        </Typography>
+        <Pagination
+          rowCount={totalCount}
+          paginationModel={{ page, pageSize }}
+          onPageChange={setPage}
+        />
+      </Stack>
+    </Box>
+  );
+}
+```
+
+### 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]);
+
+  return (
+    <Stack spacing={2}>
+      <Typography level="body-sm">{totalCount} results for "{query}"</Typography>
+      <ResultList results={results} />
+      <Pagination
+        rowCount={totalCount}
+        defaultPaginationModel={{ page: 1, pageSize: 10 }}
+        onPageChange={setPage}
+        variant="compact"
+      />
+    </Stack>
+  );
+}
+```
+
+### Gallery with 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
+
+```tsx
+function ResponsivePagination({ rowCount, page, onPageChange }) {
+  const isMobile = useMediaQuery('(max-width: 600px)');
+
+  return (
+    <Pagination
+      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
+
+### ✅ Do
+
+1. **Show context**: Display total items and current range
+
+```tsx
+// ✅ Good: Show pagination context
+<Stack direction="row" justifyContent="space-between">
+  <Typography>Showing 1-25 of 250 items</Typography>
+  <Pagination rowCount={250} />
+</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
+
+```tsx
+useEffect(() => {
+  setPage(1);
+}, [filters]);
+```
+
+### ❌ Don't
+
+1. **Don't use for very small datasets**: Pagination adds complexity
+
+```tsx
+// ❌ Bad: Pagination for 5 items
+<Pagination rowCount={5} />
+
+// ✅ Good: Just show all items
+<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);
+
+  const handlePageChange = (newPage) => {
+    setSearchParams({ page: String(newPage) });
+  };
+
+  return (
+    <Pagination
+      rowCount={totalCount}
+      paginationModel={{ page, pageSize: 25 }}
+      onPageChange={handlePageChange}
+    />
+  );
+}
+```
+
+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.