feat: add Pagination component

AGENT.md

@@ -49,6 +49,7 @@ import "cyberui-2045/styles.css";
 | `Carousel` | Image carousel. |
 | `Steps` | Multi-step progress indicator. |
 | `DropdownMenu` | Dropdown/context menu anchored to a trigger element. Arrow-key navigation, `danger` item styling, click-outside/Escape dismissal. |
+| `Pagination` | Page control for lists/tables. Controlled `currentPage`/`totalPages`, compact ellipsis collapsing for large page counts, Previous/Next controls. |
 | `GradientText` | Text with cyberpunk gradient effects. |
 | `SectionTitle` | Title with decorative gradient line. |
 | `Timeline` | Vertical event history display. |

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`Pagination`** component — a cyberpunk-styled page control for list/table views with more results than fit on one page. Always controlled via `currentPage`/`onPageChange`. Defaults to `compact` ellipsis-collapsing (`siblingCount`/`boundaryCount` tunable) so large page counts collapse distant pages behind an ellipsis, keeping boundary pages and a window around the current page visible; `compact={false}` renders every page. `showPrevNext` toggles Previous/Next controls, `variant` (`primary`/`secondary`/`accent`) reuses Button/Badge's palette for the active-page highlight and hover glow, and `size` supports responsive values (new `RESPONSIVE_SIZE_MAPS.pagination` entry). Page/Previous/Next controls are native `<button>`s in normal tab order with `aria-current="page"` on the active page; `Home`/`End` jump to the first/last page from anywhere inside the control.
 - **`DropdownMenu`** component — a cyberpunk-styled dropdown/context menu anchored to a trigger element, for row actions and context menus attached to a button. Reuses `TabNavigation`'s dropdown anchor+menu pattern internally (click-outside close, viewport-aware alignment, staged open/close transition). `trigger` accepts either a single React element (cloned with the required `onClick`/`aria-*` wiring) or a render prop for full control. `items` takes `{ label, icon?, onClick?, disabled?, danger? }` entries, with `danger` reusing `Button`'s destructive-action styling. Supports controlled (`open`/`onOpenChange`) or uncontrolled usage, `align` (`start`/`end`, auto-flips on overflow), and a responsive `size` (new `RESPONSIVE_SIZE_MAPS.dropdownMenu` entry). Full keyboard support: `ArrowDown`/`ArrowUp` on the trigger opens the menu focused on the first/last item; inside the menu, `ArrowDown`/`ArrowUp` move focus via roving tabindex (wrapping, skipping disabled items), `Home`/`End` jump to the first/last item, `Enter`/`Space` activates the focused item, and `Escape` closes the menu and returns focus to the trigger.
 
 ## [2.5.0] - 2026-07-23

CLAUDE.md

@@ -34,7 +34,7 @@ npm test              # All tests (unit + Storybook/Playwright)
 | Layout | Card, Modal, Divider, Accordion |
 | Feedback | Notification, Badge, Skeleton, Tooltip |
 | Progress | CircularProgress, SegmentedProgress, LinearProgress |
-| Navigation | TabNavigation, Carousel, Steps, DropdownMenu |
+| Navigation | TabNavigation, Carousel, Steps, DropdownMenu, Pagination |
 | Typography | GradientText, SectionTitle |
 | Display | Timeline |
 | Media | Image, Avatar |

README.md

@@ -65,6 +65,7 @@ function App() {
 | Carousel | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-carousel--docs) |
 | Steps | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-steps--docs) |
 | DropdownMenu | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-dropdownmenu--docs) |
+| Pagination | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-pagination--docs) |
 | GradientText | Typography | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-gradienttext--docs) |
 | SectionTitle | Typography | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-sectiontitle--docs) |
 | Timeline | Display | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-timeline--docs) |

bin/usage-content.js

@@ -53,6 +53,7 @@ Paths below are relative to \`node_modules/cyberui-2045/\`.
 | Carousel | Navigation | \`dist/components/Carousel.d.ts\` |
 | Steps | Navigation | \`dist/components/Steps.d.ts\` |
 | DropdownMenu | Navigation | \`dist/components/DropdownMenu.d.ts\` |
+| Pagination | Navigation | \`dist/components/Pagination.d.ts\` |
 | GradientText | Typography | \`dist/components/GradientText.d.ts\` |
 | SectionTitle | Typography | \`dist/components/SectionTitle.d.ts\` |
 | Timeline | Display | \`dist/components/Timeline.d.ts\` |

public/component-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "packageVersion": "2.5.0",
-  "generatedAt": "2026-07-26T06:11:37.769Z",
+  "generatedAt": "2026-08-02T06:15:31.179Z",
   "categoryOrder": [
     "Forms",
     "Layout",
@@ -1526,7 +1526,7 @@
           "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ((triggerProps: DropdownMenuTriggerProps) => ReactElement<...>)",
           "required": true,
           "default": null,
-          "description": "The trigger that opens the menu. Pass a single React element (e.g. a\n`Button`) to have it cloned with the required `onClick`/`aria-*`\nwiring, or a render prop for full control over how those props are\napplied.\n@example // Element trigger\n<DropdownMenu trigger={<Button variant=\"secondary\">Actions</Button>} items={items} />\n@example // Render-prop trigger\n<DropdownMenu\n  trigger={(triggerProps) => <button {...triggerProps}>Actions</button>}\n  items={items}\n/>"
+          "description": "The trigger that opens the menu. Pass a single React element (e.g. a\n`Button`) to have it cloned with the required `onClick`/`aria-*`\nwiring, or a render prop for full control over how those props are\napplied. If the element already has its own `onClick`/`onKeyDown`,\nthey're called first, before the dropdown's own handling runs.\n@example // Element trigger\n<DropdownMenu trigger={<Button variant=\"secondary\">Actions</Button>} items={items} />\n@example // Render-prop trigger\n<DropdownMenu\n  trigger={(triggerProps) => <button {...triggerProps}>Actions</button>}\n  items={items}\n/>"
         },
         {
           "name": "align",
@@ -1593,6 +1593,102 @@
         }
       ]
     },
+    {
+      "name": "Pagination",
+      "category": "Navigation",
+      "sourceFile": "src/components/Pagination.tsx",
+      "displayName": "Pagination",
+      "description": "A cyberpunk-styled page control for list/table views with more results\nthan fit on one page. Always controlled via `currentPage`/`onPageChange`,\nwith a compact ellipsis-collapsing mode for large page counts.",
+      "docSummary": "Page control for lists/tables. Controlled `currentPage`/`totalPages`, compact ellipsis collapsing for large page counts, Previous/Next controls.",
+      "storybookPath": "components-pagination--docs",
+      "manifestOverride": false,
+      "props": [
+        {
+          "name": "currentPage",
+          "type": "number",
+          "required": true,
+          "default": null,
+          "description": "Current active page, 1-based. Pagination is always controlled by this value."
+        },
+        {
+          "name": "totalPages",
+          "type": "number",
+          "required": true,
+          "default": null,
+          "description": "Total number of pages available."
+        },
+        {
+          "name": "onPageChange",
+          "type": "(page: number) => void",
+          "required": true,
+          "default": null,
+          "description": "Fired with the newly selected page number when the user clicks a page, Previous/Next, or uses Home/End."
+        },
+        {
+          "name": "compact",
+          "type": "boolean | undefined",
+          "required": false,
+          "default": true,
+          "description": "Collapses distant page numbers behind an ellipsis for large page counts,\nalways keeping `boundaryCount` pages at each edge and `siblingCount`\npages around `currentPage` visible. When `false`, every page renders."
+        },
+        {
+          "name": "siblingCount",
+          "type": "number | undefined",
+          "required": false,
+          "default": 1,
+          "description": "Number of page buttons shown on each side of `currentPage` when `compact` is true."
+        },
+        {
+          "name": "boundaryCount",
+          "type": "number | undefined",
+          "required": false,
+          "default": 1,
+          "description": "Number of page buttons always shown at the start and end when `compact` is true."
+        },
+        {
+          "name": "showPrevNext",
+          "type": "boolean | undefined",
+          "required": false,
+          "default": true,
+          "description": "Whether to render Previous/Next controls alongside the page numbers."
+        },
+        {
+          "name": "variant",
+          "type": "\"primary\" | \"secondary\" | \"accent\" | undefined",
+          "required": false,
+          "default": "primary",
+          "description": "Visual style for the active page and hover glow, matching Button/Badge's variant vocabulary."
+        },
+        {
+          "name": "size",
+          "type": "ResponsiveValue<\"sm\" | \"md\" | \"lg\"> | undefined",
+          "required": false,
+          "default": "md",
+          "description": "Size of each page control. Can be a static value or a responsive object."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean | undefined",
+          "required": false,
+          "default": false,
+          "description": "Disables every control in the group — no page can be selected."
+        },
+        {
+          "name": "ariaLabel",
+          "type": "string | undefined",
+          "required": false,
+          "default": "Pagination",
+          "description": "Accessible label for the containing `<nav>` landmark."
+        },
+        {
+          "name": "className",
+          "type": "string | undefined",
+          "required": false,
+          "default": "",
+          "description": "Additional CSS classes for the outer `<nav>`."
+        }
+      ]
+    },
     {
       "name": "GradientText",
       "category": "Typography",

public/llms.txt

@@ -16,12 +16,12 @@ npm install cyberui-2045
 ```
 
 <!-- cyberui-2045:manifest:start -->
-## Components (27)
+## Components (28)
 - Forms: `Button`, `Input`, `Toggle`, `Select`, `Checkbox`, `FormField`, `RadioGroup`
 - Layout: `Card`, `Modal`, `Divider`, `Accordion`
 - Feedback: `Notification`, `Badge`, `Skeleton`, `Tooltip`
 - Progress: `CircularProgress`, `SegmentedProgress`, `LinearProgress`
-- Navigation: `TabNavigation`, `Carousel`, `Steps`, `DropdownMenu`
+- Navigation: `TabNavigation`, `Carousel`, `Steps`, `DropdownMenu`, `Pagination`
 - Typography: `GradientText`, `SectionTitle`
 - Display: `Timeline`
 - Media: `Image`, `Avatar`

scripts/generate-manifest.js

@@ -25,7 +25,7 @@ const CATEGORY_MAP = {
   Card: 'Layout', Modal: 'Layout', Divider: 'Layout', Accordion: 'Layout',
   Notification: 'Feedback', Badge: 'Feedback', Skeleton: 'Feedback', Tooltip: 'Feedback',
   CircularProgress: 'Progress', LinearProgress: 'Progress', SegmentedProgress: 'Progress',
-  TabNavigation: 'Navigation', Carousel: 'Navigation', Steps: 'Navigation', DropdownMenu: 'Navigation',
+  TabNavigation: 'Navigation', Carousel: 'Navigation', Steps: 'Navigation', DropdownMenu: 'Navigation', Pagination: 'Navigation',
   GradientText: 'Typography', SectionTitle: 'Typography',
   Timeline: 'Display',
   Image: 'Media', Avatar: 'Media',
@@ -63,6 +63,7 @@ const DOC_SUMMARIES = {
   Avatar: 'Circular profile image with glitch-style initials fallback and an `online`/`offline`/`away` status dot.',
   RadioGroup: 'Neon-styled radio group for mutually-exclusive selection. Arrow-key navigation via roving tabindex.',
   DropdownMenu: 'Dropdown/context menu anchored to a trigger element. Arrow-key navigation, `danger` item styling, click-outside/Escape dismissal.',
+  Pagination: 'Page control for lists/tables. Controlled `currentPage`/`totalPages`, compact ellipsis collapsing for large page counts, Previous/Next controls.',
 };
 
 // SegmentedProgress exports `type SegmentedProgressProps = RadialProps | BlockProps`,