@pnx-mixtape/mxds 0.0.29 → 0.1.0-rc.0

package/src/Component/Navigation/README.md

@@ -1,26 +1,282 @@
 # Navigation
 
-### How to use
+A list of links rendered as a `<nav>` with an accessible label. Ships in two React flavours (`Navigation` for flat lists, `Dropdown` for two-level hover/tap menus) and a Twig template that covers four navigation types: `collapsible`, `dropdown`, `mega`, and `footer`. Used inside `Header`, `Footer`, and `UtilityList`.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/Navigation/navigation.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/Navigation/navigation.css";
+```
 
-**Twig**
+This bundle imports four partials:
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+- `_navigation.css` — base `.mx-nav` + `.mx-nav--inline`
+- `_navigation-collapsible.css` — vertical, click-to-expand (mobile / sidebar)
+- `_navigation-dropdown.css` — horizontal with hover flyouts
+- `_navigation-mega.css` — 3-level mega-menu extension of dropdown
 
-- Eg: `{% extends '@mixtape/Component/Navigation/navigation.twig' %}`
+To use the interactive flavours, also import the Web Component JS:
 
-Alternatively copy/paste the file for more control.
+```js
+import "@pnx-mixtape/mxds/src/Component/Navigation/Elements/Navigation"
+```
 
-**JS Custom Element**
+---
 
-Custom Elements are self defined, simply import the desired feature.
-These do not use the Shadow DOM and are not typical Web Components.
-External CSS applies.
-No Polyfills or frameworks are required.
+## `NavigationItem` type
 
-- Sticky import: `import '@pnx-mixtape/mxds/src/Component/Navigation/Elements/Navigation';` and be sure to include `<mx-navigation>` around the menu.
+Both React components and the Header/Footer layouts consume the same recursive item shape, defined in `Navigation.tsx`:
 
-See twig files for all HTML examples.
+```ts
+interface NavigationItem {
+  id: string
+  to: string
+  title: string
+  className?: string
+  items?: NavigationItem[] // nested children (Dropdown only)
+}
+```
+
+---
+
+## React — `Navigation` (flat list)
+
+A single-level `<nav><ul>` with no interactive behaviour. Use for footer link groups, utility lists, or any simple list-of-links navigation.
+
+```tsx
+import { Navigation } from "@pnx-mixtape/mxds/src/react"
+
+<Navigation
+  title="Footer links"
+  items={[
+    { id: "1", title: "Home", to: "/" },
+    { id: "2", title: "About", to: "/about" },
+    { id: "3", title: "Contact", to: "/contact" },
+  ]}
+/>
+
+// Horizontal layout
+<Navigation
+  title="Utility"
+  inline
+  items={[
+    { id: "1", title: "Login", to: "/login" },
+    { id: "2", title: "Search", to: "/search" },
+  ]}
+/>
+```
+
+**`Navigation` props:**
+
+| Prop        | Type               | Default | Description                                                       |
+| ----------- | ------------------ | ------- | ----------------------------------------------------------------- |
+| `title`     | `string`           | —       | Required. Used as `aria-label` on the `<nav>` element             |
+| `items`     | `NavigationItem[]` | —       | Flat list of links (nested `items` are ignored by this component) |
+| `inline`    | `boolean`          | `false` | Lays the list out horizontally (`mx-nav--inline`)                 |
+| `className` | `string`           | —       | Extra class on the `<nav>`                                        |
+
+Any additional props are spread onto the `<nav>` element.
+
+---
+
+## React — `Dropdown` (two-level hover/tap menu)
+
+A two-level nav where top-level items with child `items` expose a chevron toggle button. On desktop (above `mediaQuery`) sub-menus open on hover; below the breakpoint the toggle becomes click-to-expand.
+
+```tsx
+import { Dropdown } from "@pnx-mixtape/mxds/react"
+
+<Dropdown
+  title="Primary navigation"
+  items={[
+    {
+      id: "1",
+      title: "Services",
+      to: "/services",
+      items: [
+        { id: "1.1", title: "Design", to: "/services/design" },
+        { id: "1.2", title: "Development", to: "/services/dev" },
+      ],
+    },
+    { id: "2", title: "About", to: "/about" },
+    { id: "3", title: "Contact", to: "/contact" },
+  ]}
+/>
+
+// Custom mobile breakpoint
+<Dropdown
+  title="Primary navigation"
+  mediaQuery="(max-width: 960px)"
+  items={items}
+/>
+```
+
+**`Dropdown` props:**
+
+| Prop         | Type               | Default                | Description                                                               |
+| ------------ | ------------------ | ---------------------- | ------------------------------------------------------------------------- |
+| `title`      | `string`           | —                      | Required. Used as `aria-label` on the `<nav>`                             |
+| `items`      | `NavigationItem[]` | —                      | Top-level items; each may contain a single level of `items`               |
+| `mediaQuery` | `string`           | `"(max-width: 720px)"` | Viewport at or below which the menu switches to click-to-expand behaviour |
+| `className`  | `string`           | —                      | Extra class on the `<nav>`                                                |
+
+Behind the scenes, each top-level item with children is rendered by `DropdownLevel`, which manages its own open state with react-stately's `useDisclosureState` and listens for keyboard keys (`Escape`/`ArrowUp` close, `ArrowDown`/`Enter`/`Space` open).
+
+---
+
+## HTML — minimal markup
+
+### Flat
+
+```html
+<nav class="mx-nav" aria-label="Footer links">
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+### Inline (horizontal)
+
+```html
+<nav class="mx-nav mx-nav--inline" aria-label="Utility">
+  <ul>
+    <li><a href="/login">Login</a></li>
+    <li><a href="/search">Search</a></li>
+  </ul>
+</nav>
+```
+
+### Dropdown (wrapped in `<mx-nav>` Web Component)
+
+```html
+<mx-nav flyout>
+  <nav class="mx-nav mx-nav--dropdown" aria-label="Primary navigation" id="main-nav">
+    <ul class="mx-nav__level-1">
+      <li class="mx-nav__has-subnav">
+        <a href="/services">Services</a>
+        <button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only" type="button">
+          Sub-navigation
+        </button>
+        <ul class="mx-nav__level-2" inert>
+          <li><a href="/services/design">Design</a></li>
+          <li><a href="/services/dev">Development</a></li>
+        </ul>
+      </li>
+      <li><a href="/about">About</a></li>
+    </ul>
+  </nav>
+</mx-nav>
+```
+
+The `<mx-nav>` Web Component wires up keyboard navigation, hover flyouts (when the `flyout` attribute is set), edge detection (when `edgeCheck` is set), and `inert`/`aria-expanded` toggling on sub-menus.
+
+**`<mx-nav>` attributes:**
+
+| Attribute   | Description                                                          |
+| ----------- | -------------------------------------------------------------------- |
+| `flyout`    | Opens sub-menus on hover at or above `mq`                            |
+| `edgeCheck` | Adds `mx-nav--reverse` to sub-menus that would overflow the viewport |
+| `mq`        | Media query for hover behaviour (default: `"(min-width: 720px)"`)    |
+
+---
+
+## Twig
+
+Two templates are provided. `navigation.twig` is a thin wrapper that sets modifiers from a `type` prop, then extends `menu.twig` for the actual markup.
+
+```twig
+{% include '@mixtape/Component/Navigation/navigation.twig' with {
+  type: 'dropdown',
+  title: 'Primary navigation',
+  id: 'main-nav',
+  items: navigation_items,
+} %}
+```
+
+**`navigation.twig` props:**
+
+| Prop    | Type                                                | Description                                                       |
+| ------- | --------------------------------------------------- | ----------------------------------------------------------------- |
+| `type`  | `'collapsible' \| 'dropdown' \| 'mega' \| 'footer'` | Selects a preset set of modifiers and behaviour (see table below) |
+| `title` | `string`                                            | `aria-label` for the `<nav>`                                      |
+| `id`    | `string`                                            | `id` on the `<nav>` — used by the Header toggle for ARIA wiring   |
+| `items` | `MenuItem[]`                                        | Recursive tree of menu items (see shape below)                    |
+
+**Type → behaviour map (from `navigation.twig`):**
+
+| `type`        | Modifier classes                    | Wrapped in `<mx-nav>` | Extra attrs               |
+| ------------- | ----------------------------------- | --------------------- | ------------------------- |
+| `collapsible` | `mx-nav--collapsible`               | yes                   | —                         |
+| `dropdown`    | `mx-nav--dropdown`                  | yes                   | `flyout`                  |
+| `mega`        | `mx-nav--dropdown mx-nav--mega-nav` | yes                   | `edgeCheck`               |
+| `footer`      | `mx-nav--footer`                    | no                    | sub-lists are not `inert` |
+
+**`MenuItem` shape** (consumed by `menu.twig`):
+
+| Prop           | Type         | Description                                                                             |
+| -------------- | ------------ | --------------------------------------------------------------------------------------- |
+| `link.href`    | `string`     | If empty, the title renders as plain text                                               |
+| `link.title`   | `string`     | Visible label                                                                           |
+| `link.current` | `boolean`    | Adds `aria-current="page"`                                                              |
+| `items`        | `MenuItem[]` | Optional children — adds `mx-nav__has-subnav` on the `<li>` and renders a toggle button |
+
+---
+
+## Modifiers
+
+| Class                                         | Applied by                                 | Visual intent                                                                                                |
+| --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `mx-nav`                                      | Always                                     | Base styles — vertical flex list, no bullets, inherits current text colour                                   |
+| `mx-nav--inline`                              | React `inline` prop / utility              | Horizontal wrap with `--nav-gap` between items                                                               |
+| `mx-nav--collapsible`                         | Twig `type: 'collapsible'`                 | Vertical sidebar/mobile menu, click to expand, divider lines between items, highlights `aria-current="page"` |
+| `mx-nav--dropdown`                            | React `Dropdown` / Twig `type: 'dropdown'` | Horizontal top level, absolute-positioned level-2 panels                                                     |
+| `mx-nav--mega-nav`                            | Twig `type: 'mega'`                        | Extends `--dropdown` for a third level positioned to the side of level 2                                     |
+| `mx-nav--footer`                              | Twig `type: 'footer'`                      | Used by Footer layout; sub-lists stay visible (not `inert`)                                                  |
+| `mx-nav--reverse`                             | `<mx-nav edgeCheck>` JS                    | Flips sub-menu alignment when it would overflow the viewport                                                 |
+| `mx-nav--open`                                | `<mx-nav>` JS                              | Added to `<li>` while its sub-menu is open                                                                   |
+| `mx-nav__level-1` / `__level-2` / `__level-3` | Structural                                 | Sub-list nesting level                                                                                       |
+| `mx-nav__has-subnav`                          | Structural                                 | Applied to any `<li>` that contains a child `<ul>`                                                           |
+| `mx-nav__toggle`                              | Structural                                 | The chevron button that opens a sub-menu                                                                     |
+| `mx-nav__separator`                           | Authoring                                  | Adds a divider line above a dropdown `<li>`                                                                  |
+
+---
+
+## Accessibility
+
+- The outer `<nav>` receives an `aria-label` from the `title` prop — always provide a meaningful label so screen-reader users can distinguish multiple navs on a page (e.g. "Primary navigation", "Footer links").
+- Sub-menu toggle buttons expose `aria-expanded` (true/false) and `aria-controls` pointing to the `id` of their `<ul>`.
+- Sub-lists that are closed use the `inert` attribute — removing them from the tab order and from assistive tech — so no additional ARIA is needed on the list itself.
+- The `<mx-nav>` Web Component attaches keyboard handling via the shared `Keyboard` utility: arrow keys move between links, `Escape` closes open sub-menus.
+- `DropdownLevel` (React) handles these keys on the toggle button itself: `Escape`/`ArrowUp` close; `ArrowDown`/`Enter`/`Space` open.
+- The chevron button uses `mx-icon--only` — its accessible name comes from the text "Sub-navigation" inside the button. Never rely on the chevron rotation alone to convey state.
+- Current-page items should carry `aria-current="page"`; collapsible navigation styles this with a bold weight and an accent background.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-nav {
+  --nav-font-size: var(--font-size);
+  --nav-gap: var(--spacing-s); /* inline nav gap */
+  --nav-underline: none; /* link underline default */
+  --nav-active-underline: underline; /* link underline on hover */
+  --nav-active-background: var(--colour-background-alt); /* current-page bg */
+  --nav-active-foreground: inherit;
+  --nav-expanded-background: var(--colour-background-alt); /* open dropdown bg */
+  --nav-expanded-foreground: inherit;
+  --dropdown-width: 270px; /* level-2 panel width */
+  --item-spacing: var(--spacing-xxs); /* padding on each link */
+  --toggle-gap: var(--spacing-l); /* space reserved for chevron */
+  --toggle-top: 12px; /* chevron vertical offset */
+  --toggle-foreground: var(--colour-foreground);
+  --line-width: 1px; /* divider between collapsible items */
+  --line-colour: var(--colour-border);
+}
+```
+
+---
+
+→ Used in context: `mockups/HomePage.stories.ts:6`

package/src/Component/Navigation/__snapshots__/Navigation.stories.ts.snap

@@ -92,7 +92,7 @@ exports[`Dropdown 1`] = `
             What we do
           </a>
                           <button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only" aria-expanded="false" aria-controls="unique-0">Sub-navigation</button>
-              <ul class="mx-nav__level-2" inert="" id="unique-0" aria-labelledby="unique-1">
+              <ul class="mx-nav__level-2" id="unique-0" aria-labelledby="unique-1" inert="">
           <li>
                   <a href="#">
             Events

package/src/Component/Navigation/_navigation.css

@@ -4,7 +4,7 @@
 
 @layer design-system.atoms {
   .mx-nav {
-    --link-colour: currentcolor;
+    --colour-link: var(--link-colour, currentcolor);
 
     &:where(:not(:has(ul))),
     ul {

package/src/Component/Pagination/Components/PaginationContext.tsx

@@ -10,6 +10,7 @@ import {
   useEffect,
 } from "react"
 import useUrlParams from "../../../Utility/Hooks/useUrlParams"
+import { validators } from "../../../Utility/utilities"
 
 type PaginationContextValues = {
   total: number
@@ -113,19 +114,34 @@ const PaginationProvider = ({
   useEffect(() => {
     if (onLoad.current) return
     // check url for page query.
-    const queryPage = parseInt(searchParams?.get("page")) || 1
-    if (queryPage && queryPage !== currentPage) onClick(queryPage)
+    const pageParam = searchParams?.get("page") ?? "1"
+
+    // Validate page parameter is a valid integer
+    if (!validators.integer(pageParam, 1, lastPage)) {
+      if (process.env.NODE_ENV !== "production")
+        // oxlint-disable-next-line no-console
+        console.warn(`Invalid page parameter: ${pageParam}, using page 1`)
+
+      if (onClick && currentPage !== 1) {
+        onClick(1)
+      }
+      return
+    }
+
+    const queryPage = parseInt(pageParam, 10)
+    if (onClick && queryPage !== currentPage) onClick(queryPage)
+
     return () => {
       // Only use effect on initial load.
       onLoad.current = true
     }
-  }, [currentPage, onClick, searchParams])
+  }, [currentPage, onClick, searchParams, lastPage])
 
   // On page change, set URL ?page=x
   useEffect(() => {
     if (previousPage.current === currentPage) return
     // scroll to the start.
-    scrollRef.current?.scrollIntoView()
+    scrollRef?.current?.scrollIntoView()
     // add page query to URL when page changes.
     let paramString = ""
     if (currentPage !== 1) {

package/src/Component/Pagination/Components/PaginationItem.figma.ts

@@ -0,0 +1,30 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=66-259
+// source=src/Component/Pagination/Components/PaginationItem.tsx
+// component=PaginationItem
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const as = instance.getEnum("As", {
+  Item: "item",
+  Ellipsis: "ellipsis",
+  Previous: "previous",
+  Next: "next",
+})
+const active = instance.getEnum("Active", { Off: false, On: true })
+const disabled = instance.getEnum("Disabled", { Off: false, On: true })
+
+const asProp = as !== "item" ? ` as="${as}"` : ""
+const numberProp =
+  as === "item" || as === "previous" || as === "next" ? ` number={${active ? 1 : 2}}` : ""
+const activeProp = active ? " active" : ""
+const disabledProp = disabled ? " disabled" : ""
+
+export default {
+  example: figma.code`<PaginationItem${asProp}${numberProp}${activeProp}${disabledProp} />`,
+  imports: ['import { PaginationItem } from "@pnx-mixtape/mxds/react"'],
+  id: "pagination-item",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Pagination/Components/PaginationItem.tsx

@@ -13,32 +13,36 @@ const PaginationItem = ({
   number,
   active = false,
   disabled = false,
-}: PaginationItemProps): JSX.Element => (
-  <li
-    className={classNames(`mx-pagination__${as}`)}
-    aria-current={active ? "step" : null}
-    aria-hidden={disabled ? "true" : null}
-  >
-    {as === "ellipsis" && <>...</>}
-    {as === "item" && (
-      <>
-        {active && <>{number}</>}
-        {!active && (
-          <button type="button" data-page={number}>
-            {number}
-          </button>
-        )}
-      </>
-    )}
-    {(as === "next" || as === "previous") && (
-      <button type="button" disabled={disabled} data-page={number}>
-        {as === "previous" && (
-          <span className={classNames("mx-icon", "mx-icon--arrow-left")}></span>
-        )}
-        <span>{as}</span>
-        {as === "next" && <span className={classNames("mx-icon", "mx-icon--arrow-right")}></span>}
-      </button>
-    )}
-  </li>
-)
+}: PaginationItemProps): JSX.Element => {
+  // previous/next live outside the page list, so they are not list items.
+  const Tag = as === "previous" || as === "next" ? "div" : "li"
+  return (
+    <Tag
+      className={classNames(`mx-pagination__${as}`)}
+      aria-current={active ? "page" : null}
+      aria-hidden={disabled ? "true" : null}
+    >
+      {as === "ellipsis" && <>...</>}
+      {as === "item" && (
+        <>
+          {active && <>{number}</>}
+          {!active && (
+            <button type="button" data-page={number}>
+              {number}
+            </button>
+          )}
+        </>
+      )}
+      {(as === "next" || as === "previous") && (
+        <button type="button" disabled={disabled} data-page={number}>
+          {as === "previous" && (
+            <span className={classNames("mx-icon", "mx-icon--arrow-left")}></span>
+          )}
+          <span>{as}</span>
+          {as === "next" && <span className={classNames("mx-icon", "mx-icon--arrow-right")}></span>}
+        </button>
+      )}
+    </Tag>
+  )
+}
 export default PaginationItem

package/src/Component/Pagination/Pagination.figma.ts

@@ -0,0 +1,24 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=66-327
+// source=src/Component/Pagination/Pagination.tsx
+// component=Pagination
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+// `Position` (First/Middle/Last) is a Figma-only representative state — Pagination
+// itself takes no props at all, everything comes from a required PaginationProvider
+// ancestor. Pick total/resultsPerPage/currentPage values that reproduce each shown
+// state (10 total pages, at page 1 / 5 / 10 respectively).
+const position = instance.getEnum("Position", { First: "first", Middle: "middle", Last: "last" })
+const currentPage = position === "first" ? 1 : position === "last" ? 10 : 5
+
+export default {
+  example: figma.code`<PaginationProvider total={100} resultsPerPage={10} currentPage={${currentPage}}>
+  <Pagination />
+</PaginationProvider>`,
+  imports: ['import { Pagination, PaginationProvider } from "@pnx-mixtape/mxds/react"'],
+  id: "pagination",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Pagination/Pagination.stories.ts

@@ -1,16 +1,23 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect } from "storybook/test"
 import Component from "./pagination.twig"
 import PaginationItem from "./pagination-item.twig"
 import Link from "../../Atom/Link/link.twig"
 import Icon from "../../Atom/Icon/icon.twig"
 import "./pagination.css"
-import { Pagination as PaginationType } from "@pnx-mixtape/ids-shape"
+import { Pagination as IdsPagination } from "@pnx-mixtape/ids-shape"
 import { Icons } from "../../enums"
+import { modes } from "../../../.storybook/modes"
+
+// local widening until `label` lands in @pnx-mixtape/ids-shape, and `pages` is
+// a concatenated string of pre-rendered PaginationItem markup rather than an array
+type PaginationType = Omit<IdsPagination, "pages"> & { label?: string; pages?: string }
 
 const meta: Meta<PaginationType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
+    label: "Page 2 of 10",
     previous: Link({
       href: "#",
       title: "Previous",
@@ -54,9 +61,17 @@ const meta: Meta<PaginationType> = {
           title: "10",
         }),
       }),
-    ],
+    ].join(""),
   },
   argTypes: {
+    label: {
+      description:
+        "Page count label (e.g. `Page 2 of 10`) shown instead of the numbered list in narrow containers.",
+      control: "text",
+      table: {
+        type: { summary: "string" },
+      },
+    },
     previous: {
       description: `[Link](/?path=/docs/atom-link--docs) component with the \`${Icons.ARROW_LEFT}\` [Icon](/?path=/docs/atom-icon--docs).`,
       control: "text",
@@ -73,14 +88,22 @@ const meta: Meta<PaginationType> = {
     },
     pages: {
       description:
-        "List of `PaginationItem` objects, with either a [Link](/?path=/docs/atom-link--docs) components where `current` is used for the active page, or `ellipsis=true`.",
+        "A concatenated string of `PaginationItem` markup, with either a [Link](/?path=/docs/atom-link--docs) components where `current` is used for the active page, or `ellipsis=true`.",
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "PaginationItem[]" },
+        type: { summary: "string" },
+      },
+    },
+  },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
       },
     },
   },
@@ -89,4 +112,19 @@ const meta: Meta<PaginationType> = {
 export default meta
 type Story = StoryObj<PaginationType>
 
-export const Pagination: Story = {}
+// This variant is static markup with no client-side JS (unlike the React
+// version) - real navigation is expected to reload the page, so there's no
+// click/keyboard interaction to test here, just the ARIA structure.
+export const Pagination: Story = {
+  play: async ({ canvas, step }) => {
+    await step("Current page is marked with aria-current", async () => {
+      await expect(canvas.getByRole("link", { name: "2" })).toHaveAttribute("aria-current", "page")
+      await expect(canvas.getByRole("link", { name: "1" })).not.toHaveAttribute("aria-current")
+    })
+
+    await step("Previous/next links are present", async () => {
+      await expect(canvas.getByRole("link", { name: /Previous/ })).toBeInTheDocument()
+      await expect(canvas.getByRole("link", { name: /Next/ })).toBeInTheDocument()
+    })
+  },
+}

package/src/Component/Pagination/Pagination.stories.tsx

@@ -1,4 +1,6 @@
+import { useState } from "react"
 import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect } from "storybook/test"
 import Component from "./Components/PaginationContext"
 import PaginationComponent from "./Pagination"
 import "./pagination.css"
@@ -19,9 +21,63 @@ const meta: Meta<typeof Component> = {
     total: 100,
     currentPage: 1,
     resultsPerPage: 10,
-    children: <PaginationComponent />,
+  },
+  // `currentPage` is a fully controlled prop - stand in for what a real app
+  // would do and own the current-page state, feeding it back in via `onClick`.
+  render: args => {
+    const [currentPage, setCurrentPage] = useState(args.currentPage)
+
+    return (
+      <Component
+        {...args}
+        currentPage={currentPage}
+        onClick={setCurrentPage}
+        onMouseOver={() => {}}
+      >
+        <PaginationComponent />
+      </Component>
+    )
   },
 }
 
 export default meta
-export const Pagination: StoryObj<typeof meta> = {}
+export const Pagination: StoryObj<typeof meta> = {
+  play: async ({ canvas, userEvent, step }) => {
+    // The previous button's wrapper is `aria-hidden` while disabled (at page
+    // 1), so it isn't queryable by role until a later page is reached.
+    const next = canvas.getByRole("button", { name: "next" })
+    const label = canvas.getByText(/^Page \d+ of 10$/)
+
+    await step("Starts on page 1, previous hidden while disabled", async () => {
+      await expect(label).toHaveTextContent("Page 1 of 10")
+      await expect(canvas.queryByRole("button", { name: "previous" })).not.toBeInTheDocument()
+      await expect(next).not.toBeDisabled()
+    })
+
+    await step("Clicking a page number navigates", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "2" }))
+      await expect(label).toHaveTextContent("Page 2 of 10")
+      await expect(canvas.getByRole("button", { name: "previous" })).toBeInTheDocument()
+    })
+
+    await step("Next/previous buttons navigate", async () => {
+      await userEvent.click(next)
+      await expect(label).toHaveTextContent("Page 3 of 10")
+      await userEvent.click(canvas.getByRole("button", { name: "previous" }))
+      await expect(label).toHaveTextContent("Page 2 of 10")
+    })
+
+    await step("Enter on a focused page button also navigates", async () => {
+      const page4 = canvas.getByRole("button", { name: "4" })
+      page4.focus()
+      await userEvent.keyboard("{Enter}")
+      await expect(label).toHaveTextContent("Page 4 of 10")
+    })
+
+    await step("Reset: back to page 1, previous hides again", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: "1" }))
+      await expect(label).toHaveTextContent("Page 1 of 10")
+      await expect(canvas.queryByRole("button", { name: "previous" })).not.toBeInTheDocument()
+    })
+  },
+}