@duro-app/ui 5.4.0 → 5.5.0

package/dist/shared/navigate.d.ts

@@ -0,0 +1,25 @@
+/** The part of a click event a link part reads and hands to `onNavigate`. */
+export interface LinkClickEvent {
+    readonly button: number;
+    readonly metaKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly defaultPrevented: boolean;
+    preventDefault(): void;
+}
+/**
+ * Called for a plain primary click on a link part. Call
+ * `event.preventDefault()`, then your router's navigate; leave the event alone
+ * to let the browser follow the link.
+ */
+export type OnNavigate = (href: string, event: LinkClickEvent) => void;
+/** A primary-button click with no modifier key, not already prevented. */
+export declare function isPlainClick(event: LinkClickEvent): boolean;
+/**
+ * The `onClick` of a link part: hands a plain click on a link with no
+ * `target` to `onNavigate`, and does nothing otherwise, so the browser default
+ * runs. Undefined when there is no `onNavigate` (no handler at all).
+ */
+export declare function linkClickHandler(href: string, onNavigate: OnNavigate | undefined, target?: string | null): ((event: LinkClickEvent) => void) | undefined;
+//# sourceMappingURL=navigate.d.ts.map

package/dist/shared/navigate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../../src/shared/navigate.ts"],"names":[],"mappings":"AAgBA,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,cAAc,IAAI,IAAI,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;AAEtE,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,CAAC,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC,GAAG,SAAS,CAM/C"}

package/dist/table.js

@@ -1,4 +1,4 @@
-import { M as F, l as xt, R as rt, H as kt, m as pt, n as bt, o as ft, p as mt, j as ht, q as yt, r as St, t as Tt } from "./Table-Cm5cCnZD.js";
+import { M as F, m as xt, R as rt, H as kt, n as pt, o as bt, p as ft, q as mt, k as ht, t as yt, r as St, v as Tt } from "./Table-DYN-bp0e.js";
 import { jsx as u, jsxs as q } from "react/jsx-runtime";
 import { c as H, m as p, d as b } from "./compiler-runtime-B2IcI8_O.js";
 import { flexRender as E, useReactTable as it, getPaginationRowModel as Ct, getFilteredRowModel as vt, getSortedRowModel as at, getCoreRowModel as st } from "@tanstack/react-table";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^5.4.0"
+    "@duro-app/tokens": "^5.5.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Breadcrumb/Breadcrumb.meta.ts

@@ -0,0 +1,37 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Where the current page sits in the hierarchy: a labelled nav landmark with an ordered list of links, outermost first. An Item is either a link (href, optional onNavigate) or the current page (current: text with aria-current="page"), never both — the types refuse the mix. The › separators are aria-hidden. Links take href and an optional onNavigate(href, event) for a client router (plain clicks only). Compound component — Root is required.',
+  whenToUse: [
+    'A page deep in a hierarchy — docs › section › page, admin › collection › record',
+    'A detail page whose way back to its collection should be one click',
+  ],
+  whenNotToUse: [
+    'The previous and next pages in reading order — use PageNav',
+    'The sections of the page being read — use TableOfContents',
+    'Primary app navigation — use SideNav',
+  ],
+  anatomy: {
+    required: ['Root', 'Item'],
+  },
+  relatedTo: [
+    {
+      component: 'PageNav',
+      kind: 'contrast',
+      relationship: 'Breadcrumb goes up the hierarchy; PageNav goes along the reading order',
+    },
+    {
+      component: 'admin-detail-page',
+      kind: 'composition',
+      relationship: 'The admin-detail-page recipe heads the record with a Breadcrumb',
+    },
+  ],
+  example: `<Breadcrumb.Root aria-label="Breadcrumb">
+  <Breadcrumb.Item href="/docs" onNavigate={go}>Docs</Breadcrumb.Item>
+  <Breadcrumb.Item href="/docs/architecture" onNavigate={go}>Architecture</Breadcrumb.Item>
+  <Breadcrumb.Item current>AI-ops platform</Breadcrumb.Item>
+</Breadcrumb.Root>
+
+// go = (href, event) => { event.preventDefault(); navigate(href) }`,
+}

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -0,0 +1,110 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, waitFor} from 'storybook/test'
+import {Breadcrumb} from './Breadcrumb'
+import {clickLink} from '../../docs/clickLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import type {OnNavigate} from '../../shared/navigate'
+
+const meta: Meta = {
+  title: 'Components/Breadcrumb',
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+}
+
+export default meta
+type Story = StoryObj
+
+function Trail({onNavigate}: {onNavigate?: OnNavigate}) {
+  return (
+    <Breadcrumb.Root aria-label="Breadcrumb">
+      <Breadcrumb.Item href="#docs" onNavigate={onNavigate}>
+        Docs
+      </Breadcrumb.Item>
+      <Breadcrumb.Item href="#architecture" onNavigate={onNavigate}>
+        Architecture
+      </Breadcrumb.Item>
+      <Breadcrumb.Item current>AI-ops platform</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  )
+}
+
+export const Default: Story = {
+  render: () => <Trail />,
+  play: async ({canvas}) => {
+    const nav = canvas.getByRole('navigation', {name: 'Breadcrumb'})
+    await expect(nav).toBeInTheDocument()
+    // the list holds the three items only: the separators are aria-hidden
+    await expect(canvas.getAllByRole('listitem')).toHaveLength(3)
+    await expect(canvas.getAllByRole('link').map((a) => a.textContent)).toEqual([
+      'Docs',
+      'Architecture',
+    ])
+    // the current page is text, not a link, and says so
+    const current = canvas.getByText('AI-ops platform')
+    await expect(current).toHaveAttribute('aria-current', 'page')
+    await expect(current.closest('a')).toBeNull()
+  },
+}
+
+export const KeyboardOrder: Story = {
+  render: () => <Trail />,
+  play: async ({canvas, userEvent}) => {
+    await userEvent.tab()
+    await expect(canvas.getByRole('link', {name: 'Docs'})).toHaveFocus()
+    await userEvent.tab()
+    await expect(canvas.getByRole('link', {name: 'Architecture'})).toHaveFocus()
+    // the current page is not a tab stop
+    await userEvent.tab()
+    await expect(canvas.getByRole('link', {name: 'Architecture'})).not.toHaveFocus()
+  },
+}
+
+export const ClientNavigation: StoryObj<{onNavigate: OnNavigate}> = {
+  args: {onNavigate: fn()},
+  render: (args) => <Trail onNavigate={args.onNavigate} />,
+  play: async ({args, canvas}) => {
+    const onNavigate = args.onNavigate as unknown as ReturnType<typeof fn>
+    onNavigate.mockImplementation((_href: string, event: {preventDefault(): void}) =>
+      event.preventDefault(),
+    )
+    const link = canvas.getByRole('link', {name: 'Architecture'})
+
+    // a plain click goes to the router, which prevents the default
+    await expect(clickLink(link).defaultPrevented).toBe(true)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+    await expect(onNavigate.mock.calls[0][0]).toBe('#architecture')
+
+    // a modified or non-primary click keeps the browser default
+    for (const init of [{metaKey: true}, {ctrlKey: true}, {shiftKey: true}, {button: 1}]) {
+      await expect(clickLink(link, init).defaultPrevented).toBe(false)
+    }
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+  },
+}
+
+/**
+ * A touch screen gets 44px links (coarse pointer); a mouse keeps the
+ * artboard's text-height row.
+ * It drives Chrome's touch emulation through Vitest's CDP session, so it runs
+ * as a test and stays out of the dev sidebar (there is no Vitest there).
+ */
+export const TouchTargets: Story = {
+  tags: ['!dev', '!autodocs'],
+  render: () => <Trail />,
+  play: async ({canvas}) => {
+    await withFinePointer()
+    const links = () => canvas.getAllByRole('link')
+    for (const link of links()) {
+      await expect(link.getBoundingClientRect().height).toBeLessThan(SIZES_PX.touchTarget)
+    }
+    await withCoarsePointer(async () => {
+      for (const link of links()) {
+        await waitFor(() =>
+          expect(link.getBoundingClientRect().height).toBeGreaterThanOrEqual(SIZES_PX.touchTarget),
+        )
+      }
+    })
+  },
+}

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,95 @@
+import {Children, createContext, Fragment, isValidElement, type ReactNode, useContext} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {linkClickHandler, type OnNavigate} from '../../shared/navigate'
+
+/* Breadcrumb — where the current page sits in the site's hierarchy: a
+ * labelled `nav` holding an ordered list of links, the last one the current
+ * page (`aria-current="page"`, shown as text). The separators between items
+ * are decorative (`aria-hidden`), so a screen reader hears the list alone. */
+
+// Items render list items: outside Root's list they would be invalid markup.
+const BreadcrumbContext = createContext(false)
+
+function useBreadcrumb() {
+  if (!useContext(BreadcrumbContext))
+    throw new Error('Breadcrumb compound components must be used within Breadcrumb.Root')
+}
+
+// --- Root ---
+
+interface RootProps {
+  /** Names the landmark ("Breadcrumb"); required, from your text catalog. */
+  'aria-label': string
+  /** `Breadcrumb.Item`s, outermost first. */
+  children: ReactNode
+}
+
+function Root({'aria-label': ariaLabel, children}: RootProps) {
+  const items = Children.toArray(children).filter(isValidElement)
+  return (
+    <BreadcrumbContext.Provider value={true}>
+      <html.nav aria-label={ariaLabel} style={styles.root}>
+        <html.ol style={styles.list}>
+          {items.map((item, i) => (
+            <Fragment key={item.key ?? i}>
+              {i > 0 ? (
+                <html.li aria-hidden style={styles.separator}>
+                  ›
+                </html.li>
+              ) : null}
+              {item}
+            </Fragment>
+          ))}
+        </html.ol>
+      </html.nav>
+    </BreadcrumbContext.Provider>
+  )
+}
+
+// --- Item ---
+
+/**
+ * A link to an ancestor page, or the current page. The two are exclusive: the
+ * current page has no `href` (it is text) and a link is never `current`.
+ */
+type ItemProps = {children: ReactNode} & (
+  | {
+      /** Where the item links to. */
+      href: string
+      /**
+       * Client-side navigation: called for a plain primary click (no modifier
+       * key). Call `event.preventDefault()`, then your router's navigate.
+       */
+      onNavigate?: OnNavigate
+      current?: never
+    }
+  | {
+      /** The page the user is on: rendered as text with `aria-current="page"`. */
+      current: true
+      href?: never
+      onNavigate?: never
+    }
+)
+
+function Item({href, current, onNavigate, children}: ItemProps) {
+  useBreadcrumb()
+  return (
+    <html.li style={styles.item}>
+      {current ? (
+        <html.span aria-current="page" style={styles.current}>
+          {children}
+        </html.span>
+      ) : (
+        <html.a href={href} onClick={linkClickHandler(href, onNavigate)} style={styles.link}>
+          {children}
+        </html.a>
+      )}
+    </html.li>
+  )
+}
+
+export const Breadcrumb = {
+  Root,
+  Item,
+}

package/src/components/Breadcrumb/styles.css.ts

@@ -0,0 +1,76 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+
+// The picked docs browser (docs/mockups/docs-nav/Reader.dc.html, `.crumbs`):
+// small muted text, accent links, a `›` between items, the current page plain.
+export const styles = css.create({
+  root: {
+    minWidth: 0,
+  },
+  list: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: spacing.xs,
+    margin: 0,
+    padding: 0,
+    listStyleType: 'none',
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.textMuted,
+  },
+  item: {
+    display: 'inline-flex',
+    minWidth: 0,
+  },
+  separator: {
+    display: 'inline-flex',
+    color: colors.textMuted,
+    userSelect: 'none',
+  },
+  // On a touch screen (coarse pointer, as Toggle does) each link is a
+  // touch target; a mouse keeps the artboard's text-height row.
+  link: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    minHeight: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
+    color: {
+      default: colors.accent,
+      ':hover': colors.accentHover,
+    },
+    textDecorationLine: {
+      default: 'none',
+      ':hover': 'underline',
+    },
+    borderRadius: radii.xs,
+    transitionProperty: 'color',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+    outlineWidth: {
+      default: 0,
+      ':focus-visible': borders.focusRing,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':focus-visible': 'solid',
+    },
+    outlineColor: {
+      default: 'transparent',
+      ':focus-visible': colors.accent,
+    },
+    outlineOffset: {
+      default: 0,
+      ':focus-visible': borders.focusOffset,
+    },
+  },
+  // the artboard keeps the current page in the list's muted colour; it is
+  // told apart by not being a link (and by aria-current for assistive tech)
+  current: {
+    color: 'inherit',
+  },
+})

package/src/components/Inline/Inline.meta.ts

@@ -5,11 +5,12 @@ export const meta: ComponentMeta = {
   whenToUse: [
     'Toolbar or button group that must stay on one row',
     'Horizontal alignment of a known, small number of items',
-    'Icon + text pairs, breadcrumbs, action rows',
+    'Icon + text pairs, action rows',
   ],
   whenNotToUse: [
     'Items that should wrap to the next line — use Cluster',
     'Vertical stacking — use Stack',
+    'A breadcrumb trail — use Breadcrumb (a nav landmark with aria-current)',
   ],
   relatedTo: [
     {

package/src/components/LinkButton/LinkButton.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Button-styled hyperlink. Renders an <a> tag, not a <button>. Use for navigation, not actions.',
+    'Button-styled hyperlink. Renders an <a> tag, not a <button>. Use for navigation, not actions. onNavigate(href, event) hands a plain primary click to a client router (the app calls event.preventDefault(), then navigates); modified clicks keep the browser default.',
   whenToUse: [
     'Navigation that should look like a button (e.g., "Get started", "View all")',
     'Links to external pages with button styling',

package/src/components/LinkButton/LinkButton.stories.tsx

@@ -1,7 +1,10 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
+import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {LinkButton} from './LinkButton'
+import {clickLink} from '../../docs/clickLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+import type {OnNavigate} from '../../shared/navigate'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof LinkButton> = {
@@ -90,3 +93,41 @@ export const AllVariants: Story = {
     await expect(links.length).toBe(4)
   },
 }
+
+/**
+ * Client-side navigation: `onNavigate` gets a plain primary click (the app
+ * calls `event.preventDefault()`, then its router's navigate); a modified
+ * click, or a link with `target`, keeps the browser default.
+ */
+export const ClientNavigation: StoryObj<{onNavigate: OnNavigate}> = {
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  args: {onNavigate: fn()},
+  render: (args) => (
+    <>
+      <LinkButton href="#billing" onNavigate={args.onNavigate}>
+        Get started
+      </LinkButton>{' '}
+      <LinkButton href="#help" target="_blank" onNavigate={args.onNavigate}>
+        Help
+      </LinkButton>
+    </>
+  ),
+  play: async ({args, canvas}) => {
+    const onNavigate = args.onNavigate as unknown as ReturnType<typeof fn>
+    onNavigate.mockImplementation((_href: string, event: {preventDefault(): void}) =>
+      event.preventDefault(),
+    )
+    const link = canvas.getByRole('link', {name: 'Get started'})
+    await expect(clickLink(link).defaultPrevented).toBe(true)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+    await expect(onNavigate.mock.calls[0][0]).toBe('#billing')
+    for (const init of [{metaKey: true}, {ctrlKey: true}, {shiftKey: true}, {altKey: true}]) {
+      await expect(clickLink(link, init).defaultPrevented).toBe(false)
+    }
+    // a target opens where it says, not through the router
+    const help = canvas.getByRole('link', {name: 'Help'})
+    await expect(clickLink(help).defaultPrevented).toBe(false)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+  },
+}

package/src/components/LinkButton/LinkButton.tsx

@@ -1,6 +1,7 @@
 import type {ReactNode} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
+import {linkClickHandler, type OnNavigate} from '../../shared/navigate'
 
 export type LinkButtonVariant = 'primary' | 'secondary'
 export type LinkButtonSize = 'default' | 'small'
@@ -12,6 +13,12 @@ interface LinkButtonProps {
   fullWidth?: boolean
   target?: '_blank' | '_self'
   rel?: string
+  /**
+   * Client-side navigation: called for a plain primary click (no modifier
+   * key, no `target`); the browser default runs for every other click. Call
+   * `event.preventDefault()`, then your router's navigate.
+   */
+  onNavigate?: OnNavigate
   children: ReactNode
 }
 
@@ -27,6 +34,7 @@ export function LinkButton({
   fullWidth = false,
   target,
   rel,
+  onNavigate,
   children,
 }: LinkButtonProps) {
   return (
@@ -34,6 +42,7 @@ export function LinkButton({
       href={href}
       target={target}
       rel={rel}
+      onClick={linkClickHandler(href, onNavigate, target)}
       style={[styles.base, sizeMap[size], styles[variant], fullWidth && styles.fullWidth]}
     >
       {children}

package/src/components/PageNav/PageNav.meta.ts

@@ -0,0 +1,35 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'The previous and next pages in reading order, at the foot of a page: a labelled nav with up to two link cards (a direction label over the page title, both from props). A missing side keeps its slot, so Next stays right-aligned; the cards stack below the xs container width. Links take href and an optional onNavigate(href, event) (plain clicks only). Compound component — Root is required.',
+  whenToUse: [
+    'Docs or a guide read in order — the foot of each page',
+    'A sequence of steps where each step is its own page',
+  ],
+  whenNotToUse: [
+    'Numbered result pages of a table — use Pagination from @duro-app/ui/table',
+    'Going up the hierarchy — use Breadcrumb',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Prev', 'Next'],
+  },
+  relatedTo: [
+    {
+      component: 'Breadcrumb',
+      kind: 'contrast',
+      relationship: 'PageNav goes along the reading order; Breadcrumb goes up the hierarchy',
+    },
+    {
+      component: 'Card',
+      kind: 'contrast',
+      relationship:
+        'PageNav draws its own link cards; do not wrap a Card in a link to fake a prev/next pair',
+    },
+  ],
+  example: `<PageNav.Root aria-label="Pages">
+  <PageNav.Prev href="/docs/architecture/clusters" label="Previous" title="Clusters and bootstrap" onNavigate={go} />
+  <PageNav.Next href="/docs/architecture/secrets" label="Next" title="Secrets and Vault" onNavigate={go} />
+</PageNav.Root>`,
+}

package/src/components/PageNav/PageNav.stories.tsx

@@ -0,0 +1,146 @@
+import {css, html} from 'react-strict-dom'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn} from 'storybook/test'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {PageNav} from './PageNav'
+import {clickLink} from '../../docs/clickLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+import type {OnNavigate} from '../../shared/navigate'
+
+const meta: Meta = {
+  title: 'Components/PageNav',
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+}
+
+export default meta
+type Story = StoryObj
+
+const styles = css.create({
+  column: {width: sizes.panelLg},
+  narrow: {width: sizes.panelSm},
+})
+
+function Pages(props: {prev?: boolean; next?: boolean; onNavigate?: OnNavigate}) {
+  const {prev = true, next = true, onNavigate} = props
+  return (
+    <PageNav.Root aria-label="Pages">
+      {prev ? (
+        <PageNav.Prev
+          href="#clusters"
+          label="Previous"
+          title="Clusters and bootstrap"
+          onNavigate={onNavigate}
+        />
+      ) : null}
+      {next ? (
+        <PageNav.Next
+          href="#secrets"
+          label="Next"
+          title="Secrets and Vault"
+          onNavigate={onNavigate}
+        />
+      ) : null}
+    </PageNav.Root>
+  )
+}
+
+export const Default: Story = {
+  render: () => (
+    <html.div style={styles.column}>
+      <Pages />
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await expect(canvas.getByRole('navigation', {name: 'Pages'})).toBeInTheDocument()
+    // the arrows are decorative: the name is the label and the title
+    const prev = canvas.getByRole('link', {name: 'Previous Clusters and bootstrap'})
+    const next = canvas.getByRole('link', {name: 'Next Secrets and Vault'})
+    // side by side, Next on the right
+    await expect(next.getBoundingClientRect().left).toBeGreaterThan(
+      prev.getBoundingClientRect().right,
+    )
+    await userEvent.tab()
+    await expect(prev).toHaveFocus()
+    await userEvent.tab()
+    await expect(next).toHaveFocus()
+  },
+}
+
+/** The first page of a section: no Prev, and Next keeps the right half. */
+export const OnlyNext: Story = {
+  render: () => (
+    <html.div style={styles.column}>
+      <Pages prev={false} />
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const nav = canvas.getByRole('navigation', {name: 'Pages'})
+    const next = canvas.getByRole('link', {name: 'Next Secrets and Vault'})
+    const navBox = nav.getBoundingClientRect()
+    const nextBox = next.getBoundingClientRect()
+    await expect(nextBox.left).toBeGreaterThan(navBox.left + navBox.width / 3)
+    await expect(Math.round(nextBox.right)).toBe(Math.round(navBox.right))
+    await expect(getComputedStyle(next).textAlign).toBe('right')
+  },
+}
+
+/** The last page of a section: no Next, and Prev keeps the left half. */
+export const OnlyPrev: Story = {
+  render: () => (
+    <html.div style={styles.column}>
+      <Pages next={false} />
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const navBox = canvas.getByRole('navigation', {name: 'Pages'}).getBoundingClientRect()
+    const prevBox = canvas
+      .getByRole('link', {name: 'Previous Clusters and bootstrap'})
+      .getBoundingClientRect()
+    await expect(canvas.getAllByRole('link')).toHaveLength(1)
+    await expect(canvas.queryByRole('link', {name: /Next/})).toBeNull()
+    await expect(Math.round(prevBox.left)).toBe(Math.round(navBox.left))
+    await expect(prevBox.right).toBeLessThan(navBox.left + navBox.width / 2)
+  },
+}
+
+/** Below the xs container width the cards stack, Prev first. */
+export const Stacked: Story = {
+  render: () => (
+    <html.div style={styles.narrow}>
+      <Pages />
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const prev = canvas.getByRole('link', {name: 'Previous Clusters and bootstrap'})
+    const next = canvas.getByRole('link', {name: 'Next Secrets and Vault'})
+    await expect(next.getBoundingClientRect().top).toBeGreaterThanOrEqual(
+      prev.getBoundingClientRect().bottom,
+    )
+    await expect(Math.round(next.getBoundingClientRect().left)).toBe(
+      Math.round(prev.getBoundingClientRect().left),
+    )
+  },
+}
+
+export const ClientNavigation: StoryObj<{onNavigate: OnNavigate}> = {
+  args: {onNavigate: fn()},
+  render: (args) => (
+    <html.div style={styles.column}>
+      <Pages onNavigate={args.onNavigate} />
+    </html.div>
+  ),
+  play: async ({args, canvas}) => {
+    const onNavigate = args.onNavigate as unknown as ReturnType<typeof fn>
+    onNavigate.mockImplementation((_href: string, event: {preventDefault(): void}) =>
+      event.preventDefault(),
+    )
+    const next = canvas.getByRole('link', {name: 'Next Secrets and Vault'})
+    await expect(clickLink(next).defaultPrevented).toBe(true)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+    await expect(onNavigate.mock.calls[0][0]).toBe('#secrets')
+    await expect(clickLink(next, {metaKey: true}).defaultPrevented).toBe(false)
+    await expect(clickLink(next, {altKey: true}).defaultPrevented).toBe(false)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+  },
+}