@duro-app/ui 5.4.0 → 5.6.0

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -1,9 +1,21 @@
 import {useState} from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, userEvent, within} from 'storybook/test'
-import {BORDERS_PX, LAYERS, RADII_PX} from '@duro-app/tokens/keys'
+import {expect, userEvent, waitFor, within} from 'storybook/test'
+import {
+  BORDERS_PX,
+  FONT_SIZE_REM,
+  LAYERS,
+  RADII_PX,
+  SIZES_PX,
+  SPACING_PX,
+} from '@duro-app/tokens/keys'
+import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
 import {ButtonGroup} from './ButtonGroup'
+import type {ControlSize} from '../../shared/types'
 import {Button} from '../Button/Button'
+import {Icon} from '../Icon/Icon'
+import {Inline} from '../Inline/Inline'
+import {Menu} from '../Menu/Menu'
 import {Popover} from '../Popover/Popover'
 import {Select} from '../Select/Select'
 import {Stack} from '../Stack/Stack'
@@ -146,11 +158,11 @@ async function expectJoined(controls: Element[]) {
   }
 }
 
-function TextStyleSelects({named = false}: {named?: boolean}) {
+function TextStyleSelects({named = false, size}: {named?: boolean; size?: ControlSize}) {
   return (
     <ButtonGroup attached aria-label="Text style">
       <Select.Root name={named ? 'block' : undefined} defaultValue="normal">
-        <Select.Trigger aria-label="Block type">
+        <Select.Trigger aria-label="Block type" size={size}>
           <Select.Value />
           <Select.Icon />
         </Select.Trigger>
@@ -160,7 +172,7 @@ function TextStyleSelects({named = false}: {named?: boolean}) {
         </Select.Popup>
       </Select.Root>
       <Select.Root name={named ? 'font' : undefined} defaultValue="arial">
-        <Select.Trigger aria-label="Font">
+        <Select.Trigger aria-label="Font" size={size}>
           <Select.Value />
           <Select.Icon />
         </Select.Trigger>
@@ -170,7 +182,7 @@ function TextStyleSelects({named = false}: {named?: boolean}) {
         </Select.Popup>
       </Select.Root>
       <Select.Root name={named ? 'size' : undefined} defaultValue="15">
-        <Select.Trigger aria-label="Font size">
+        <Select.Trigger aria-label="Font size" size={size}>
           <Select.Value />
           <Select.Icon />
         </Select.Trigger>
@@ -242,25 +254,37 @@ export const AttachedFocusMiddle: Story = {
   },
 }
 
-function FormatGroup() {
+function FormatGroup({size}: {size?: ControlSize}) {
   const [pressed, setPressed] = useState<Record<string, boolean>>({u: true})
   const toggle = (key: string) => (next: boolean) => setPressed((p) => ({...p, [key]: next}))
   return (
     <ButtonGroup attached aria-label="Format">
-      <Toggle aria-label="Bold" pressed={!!pressed.b} onPressedChange={toggle('b')}>
+      <Toggle aria-label="Bold" size={size} pressed={!!pressed.b} onPressedChange={toggle('b')}>
         B
       </Toggle>
-      <Toggle aria-label="Italic" pressed={!!pressed.i} onPressedChange={toggle('i')}>
+      <Toggle aria-label="Italic" size={size} pressed={!!pressed.i} onPressedChange={toggle('i')}>
         I
       </Toggle>
-      <Toggle aria-label="Underline" pressed={!!pressed.u} onPressedChange={toggle('u')}>
+      <Toggle
+        aria-label="Underline"
+        size={size}
+        pressed={!!pressed.u}
+        onPressedChange={toggle('u')}
+      >
         U
       </Toggle>
-      <Toggle aria-label="Code" pressed={!!pressed.code} onPressedChange={toggle('code')}>
+      <Toggle
+        aria-label="Code"
+        size={size}
+        pressed={!!pressed.code}
+        onPressedChange={toggle('code')}
+      >
         {'<>'}
       </Toggle>
       <Popover.Root>
-        <Popover.Trigger aria-label="Link">↗</Popover.Trigger>
+        <Popover.Trigger aria-label="Link" size={size}>
+          ↗
+        </Popover.Trigger>
         <Popover.Popup label="Link">
           <Stack gap="sm">
             <Text>Paste a URL.</Text>
@@ -268,10 +292,10 @@ function FormatGroup() {
           </Stack>
         </Popover.Popup>
       </Popover.Root>
-      <Button variant="secondary" aria-label="Clear formatting">
+      <Button variant="secondary" size={size} aria-label="Clear formatting">
         T
       </Button>
-      <Button variant="secondary" aria-label="Highlight">
+      <Button variant="secondary" size={size} aria-label="Highlight">
         H
       </Button>
     </ButtonGroup>
@@ -372,3 +396,137 @@ export const BothPressedFocusSecond: Story = {
     await expect(drawnAt(bold, b.left + b.width / 2, ringPixels(b).bottom)).toBe(true)
   },
 }
+
+// --- Small triggers (5.6) ---
+
+/** fontSizeXs in px, from the root font size. */
+const smallFontPx = () =>
+  `${parseFloat(getComputedStyle(document.documentElement).fontSize) * FONT_SIZE_REM.fontSizeXs}px`
+
+/** [Normal | Arial | 15px] at size="small": joined like the default size. */
+export const AttachedSelectsSmall: Story = {
+  render: () => <TextStyleSelects size="small" />,
+  play: async ({canvas}) => {
+    const triggers = canvas.getAllByRole('combobox')
+    await expectJoined(triggers)
+    for (const el of triggers) {
+      await expect(getComputedStyle(el).fontSize).toBe(smallFontPx())
+    }
+  },
+}
+
+/** The mixed format group at size="small": Toggles, the Popover trigger and
+ *  the Buttons stay joined. */
+export const AttachedMixedSmall: Story = {
+  render: () => <FormatGroup size="small" />,
+  play: async ({canvas}) => {
+    const group = canvas.getByRole('group', {name: 'Format'})
+    await expectJoined(within(group).getAllByRole('button'))
+  },
+}
+
+function SmallControlsRow() {
+  return (
+    <Inline gap="sm" align="center">
+      <Toggle size="small" aria-label="Bold">
+        B
+      </Toggle>
+      <Toggle size="small" aria-label="Search">
+        <Icon name="search" size="md" />
+      </Toggle>
+      <Button size="small" variant="secondary">
+        Clear
+      </Button>
+      <Select.Root defaultValue="normal">
+        <Select.Trigger size="small" aria-label="Block type">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="normal">Normal</Select.Item>
+          <Select.Item value="h1">Heading 1</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+      <Menu.Root>
+        <Menu.Trigger size="small">Insert</Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item onClick={() => undefined}>Image</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <Popover.Root>
+        <Popover.Trigger size="small" aria-label="Text colour">
+          A
+        </Popover.Trigger>
+        <Popover.Popup label="Text colour">
+          <Text>Pick a colour.</Text>
+        </Popover.Popup>
+      </Popover.Root>
+      <Menu.Root>
+        <Menu.Trigger size="small" variant="ghost" aria-label="More">
+          <Icon name="menu" size="sm" />
+        </Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item onClick={() => undefined}>Settings</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+    </Inline>
+  )
+}
+
+/** Small Toggles (text and an 18px icon), a small Button and small Select,
+ *  Menu and Popover triggers in a plain Inline (no attached group to stretch
+ *  them): every one is controlSm tall whatever it holds, with Toggle's
+ *  padding and font. The ghost Menu trigger is the small icon-button size. */
+export const SmallTriggersRow: Story = {
+  render: () => <SmallControlsRow />,
+  play: async ({canvas}) => {
+    await withFinePointer()
+    const controls = [
+      canvas.getByRole('button', {name: 'Bold'}),
+      canvas.getByRole('button', {name: 'Search'}),
+      canvas.getByRole('button', {name: 'Clear'}),
+    ]
+    const triggers = [
+      canvas.getByRole('combobox', {name: 'Block type'}),
+      canvas.getByRole('button', {name: 'Insert'}),
+      canvas.getByRole('button', {name: 'Text colour'}),
+    ]
+    for (const el of [...controls, ...triggers]) {
+      await expect(el.offsetHeight).toBe(SIZES_PX.controlSm)
+    }
+    for (const el of triggers) {
+      const cs = getComputedStyle(el)
+      await expect(cs.paddingTop).toBe(`${SPACING_PX.xs}px`)
+      await expect(cs.paddingLeft).toBe(`${SPACING_PX.sm}px`)
+      await expect(cs.fontSize).toBe(smallFontPx())
+    }
+    const ghost = canvas.getByRole('button', {name: 'More'})
+    await expect(ghost.offsetHeight).toBe(SIZES_PX.iconButtonSm)
+    await expect(ghost.offsetWidth).toBe(SIZES_PX.iconButtonSm)
+    await expect(getComputedStyle(ghost).fontSize).toBe(smallFontPx())
+  },
+}
+
+/** The same row under a coarse pointer: Toggle and the three triggers reach
+ *  touchTarget, the ghost Menu too. Button has no touch size at any size, so the small Button stays
+ *  controlSm (the 5.5 plan's addendum). */
+export const SmallTriggersRowCoarsePointer: Story = {
+  render: () => <SmallControlsRow />,
+  play: async ({canvas}) => {
+    const touch = [
+      canvas.getByRole('button', {name: 'Bold'}),
+      canvas.getByRole('button', {name: 'Search'}),
+      canvas.getByRole('combobox', {name: 'Block type'}),
+      canvas.getByRole('button', {name: 'Insert'}),
+      canvas.getByRole('button', {name: 'Text colour'}),
+      canvas.getByRole('button', {name: 'More'}),
+    ]
+    const button = canvas.getByRole('button', {name: 'Clear'})
+    await withCoarsePointer(async () => {
+      for (const el of touch) {
+        await waitFor(() => expect(el.offsetHeight).toBe(SIZES_PX.touchTarget))
+      }
+      await expect(button.offsetHeight).toBe(SIZES_PX.controlSm)
+    })
+  },
+}

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/LinkButton/styles.css.ts

@@ -4,6 +4,7 @@ import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 export const styles = css.create({
   base: {
@@ -34,6 +35,9 @@ export const styles = css.create({
     paddingLeft: spacing.sm,
     paddingRight: spacing.sm,
     fontSize: typography.fontSizeXs,
+
+    // Matches Button: every small control is at least controlSm tall (5.6).
+    minHeight: sizes.controlSm,
   },
   primary: {
     backgroundColor: {

package/src/components/Menu/Menu.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars. The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog.',
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars; size="small" matches small Toggles and Buttons (a small ghost trigger is iconButtonSm). The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog.',
   whenToUse: [
     'Context menu or "more actions" dropdown',
     'Navigation links in a dropdown',

package/src/components/Menu/Menu.tsx

@@ -15,6 +15,7 @@ import {styles} from './styles.css'
 import {MenuContext, useMenu} from './MenuContext'
 import {useMenuRoot} from './useMenuRoot'
 import {devWarnOnce} from '../../shared/devWarnOnce'
+import type {ControlSize} from '../../shared/types'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
 import {computePopoverPosition} from '../Popover/position'
 import {usePopoverLayer} from '../Popover/PopoverLayerContext'
@@ -58,10 +59,18 @@ interface TriggerProps {
   'aria-label'?: string
   /** `ghost`: no border or fill until hover, for toolbars. Default: `default`. */
   variant?: MenuTriggerVariant
+  /** `small` matches a small Toggle or Button beside it; a small ghost trigger is `iconButtonSm`. Default: `default`. */
+  size?: ControlSize
   ref?: Ref<HTMLButtonElement>
 }
 
-function Trigger({children, 'aria-label': ariaLabel, variant = 'default', ref}: TriggerProps) {
+function Trigger({
+  children,
+  'aria-label': ariaLabel,
+  variant = 'default',
+  size = 'default',
+  ref,
+}: TriggerProps) {
   const {open, toggle, menuId, triggerId, triggerRef} = useMenu()
   const grouped = useGroupedControl<HTMLButtonElement>()
   const groupedRef = grouped.ref
@@ -99,7 +108,13 @@ function Trigger({children, 'aria-label': ariaLabel, variant = 'default', ref}:
       aria-expanded={open}
       aria-haspopup="menu"
       aria-controls={open ? menuId : undefined}
-      style={[styles.trigger, variant === 'ghost' && styles.triggerGhost, grouped.style]}
+      style={[
+        styles.trigger,
+        variant === 'ghost'
+          ? [styles.triggerGhost, size === 'small' && styles.triggerGhostSmall]
+          : size === 'small' && styles.triggerSmall,
+        grouped.style,
+      ]}
     >
       {children}
     </html.button>

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

@@ -47,6 +47,24 @@ export const styles = css.create({
     paddingRight: spacing.xs,
     borderColor: 'transparent',
   },
+  // size="small": Toggle sizeSmall's values, as longhands so they win over the
+  // trigger's own longhands. Every small control is at least controlSm tall,
+  // whatever it holds, and the touch target under a coarse pointer.
+  triggerSmall: {
+    gap: spacing.xs,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    fontSize: typography.fontSizeXs,
+    minHeight: {default: sizes.controlSm, '@media (pointer: coarse)': sizes.touchTarget},
+  },
+  // A small ghost trigger keeps the ghost's xs padding at the small icon-button size.
+  triggerGhostSmall: {
+    fontSize: typography.fontSizeXs,
+    minWidth: sizes.iconButtonSm,
+    minHeight: {default: sizes.iconButtonSm, '@media (pointer: coarse)': sizes.touchTarget},
+  },
   popup: {
     position: 'fixed',
     top: 0,

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)
+  },
+}