@duro-app/ui 5.3.0 → 5.5.0

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

@@ -0,0 +1,147 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {microSpacing, radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {typeScale, 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: the list is Reader.dc.html's `.toc` / `.tocitem`
+// (a hairline rail, the active item marked by the nav marker bar), the menu is
+// Mobile.dc.html's `.mtoc` (docs/mockups/docs-nav/).
+export const styles = css.create({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: 0,
+    fontFamily: typography.fontFamily,
+  },
+  caption: {
+    marginBottom: spacing.sm,
+    fontSize: typography.fontSizeXs,
+    fontWeight: typography.fontWeightMedium,
+    letterSpacing: typeScale.letterSpacingWide,
+    textTransform: 'uppercase',
+    color: colors.textMuted,
+  },
+  list: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacing.xs,
+    margin: 0,
+    padding: 0,
+    listStyleType: 'none',
+    borderLeftWidth: borders.hairline,
+    borderLeftStyle: 'solid',
+    borderLeftColor: colors.border,
+  },
+  // the menu's list opens below its button, as a panel
+  listMenu: {
+    gap: 0,
+    marginTop: spacing.xs,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.sm,
+    backgroundColor: colors.bgCard,
+  },
+  item: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  // On a touch screen (coarse pointer, as Toggle does) each item is a touch
+  // target; a mouse keeps the artboard's compact rail.
+  link: {
+    display: {default: 'block', '@media (pointer: coarse)': 'flex'},
+    alignItems: {default: null, '@media (pointer: coarse)': 'center'},
+    minHeight: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
+    paddingTop: microSpacing.px2,
+    paddingBottom: microSpacing.px2,
+    paddingLeft: spacing.ms,
+    paddingRight: spacing.ms,
+    fontSize: typography.fontSizeSm,
+    fontWeight: typography.fontWeightNormal,
+    textDecorationLine: 'none',
+    color: {
+      default: colors.textMuted,
+      ':hover': colors.text,
+    },
+    cursor: 'pointer',
+    transitionProperty: 'color',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  // a touch target per item when the menu is the narrow-screen form
+  linkMenu: {
+    display: 'flex',
+    alignItems: 'center',
+    minHeight: sizes.touchTarget,
+  },
+  level3: {
+    paddingLeft: `calc(${spacing.ms} + ${spacing.md})`,
+  },
+  // not colour alone: the marker bar and a heavier weight
+  linkActive: {
+    color: colors.text,
+    fontWeight: typography.fontWeightMedium,
+    boxShadow: `inset ${sizes.navMarkerW} 0 0 ${colors.accent}`,
+  },
+  trigger: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: spacing.sm,
+    width: '100%',
+    minHeight: sizes.touchTarget,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.ms,
+    paddingRight: spacing.ms,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+    color: colors.text,
+    textAlign: 'left',
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.sm,
+    cursor: 'pointer',
+    transitionProperty: 'background-color',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  // the keyboard ring, inset so a neighbour or the panel edge never clips it
+  focusable: {
+    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': `calc(-1 * ${borders.focusOffset})`,
+    },
+  },
+  chevron: {
+    color: colors.textMuted,
+    transitionProperty: 'transform',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+  },
+  chevronOpen: {
+    transform: 'rotate(180deg)',
+  },
+})

package/src/components/TextLink/TextLink.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Inline hyperlink for running text and standalone text links ("View all", "Edit profile"). Always underlined, so colour is never the only cue: default is accent text with an accent underline; subtle keeps the surrounding text colour with a muted underline and turns accent on hover. target="_blank" defaults rel to noopener noreferrer.',
+    'Inline hyperlink for running text and standalone text links ("View all", "Edit profile"). Always underlined, so colour is never the only cue: default is accent text with an accent underline; subtle keeps the surrounding text colour with a muted underline and turns accent on hover. target="_blank" defaults rel to noopener noreferrer. 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: [
     'A link inside a sentence or paragraph',
     'A standalone text link under a list or card ("View all requests")',

package/src/components/TextLink/TextLink.stories.tsx

@@ -1,6 +1,9 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
+import {expect, fn} from 'storybook/test'
 import {TextLink} from './TextLink'
+import {clickLink} from '../../docs/clickLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+import type {OnNavigate} from '../../shared/navigate'
 import {Text} from '../Text/Text'
 import {Inline} from '../Inline/Inline'
 
@@ -61,3 +64,41 @@ export const KeyboardFocus: Story = {
     await expect(getComputedStyle(link).outlineStyle).toBe('solid')
   },
 }
+
+/**
+ * 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) => (
+    <>
+      <TextLink href="#billing" onNavigate={args.onNavigate}>
+        Billing settings
+      </TextLink>{' '}
+      <TextLink href="#help" target="_blank" onNavigate={args.onNavigate}>
+        Help
+      </TextLink>
+    </>
+  ),
+  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: 'Billing settings'})
+    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/TextLink/TextLink.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 TextLinkVariant = 'default' | 'subtle'
 
@@ -17,6 +18,12 @@ interface TextLinkProps {
   variant?: TextLinkVariant
   /** Accessible name, when the visible text alone does not say where it goes. */
   'aria-label'?: 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
 }
 
@@ -30,6 +37,7 @@ export function TextLink({
   rel,
   variant = 'default',
   'aria-label': ariaLabel,
+  onNavigate,
   children,
 }: TextLinkProps) {
   return (
@@ -38,6 +46,7 @@ export function TextLink({
       target={target}
       rel={rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)}
       aria-label={ariaLabel}
+      onClick={linkClickHandler(href, onNavigate, target)}
       style={[styles.base, styles[variant]]}
     >
       {children}

package/src/components/Tree/Tree.meta.ts

@@ -2,10 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. Compound component — Root is required.',
+    'Hierarchy of items with single selection and expandable branches (the WAI-ARIA tree pattern): one tab stop, arrow keys, Home/End, typeahead. An Item with href renders its row as a real link (cmd-click opens a tab) outside the tab order; Enter/Space follows it, through onNavigate(href, event) when given. Compound component — Root is required.',
   whenToUse: [
     'Browsing data that nests to any depth — a file tree, zones › services › capabilities, namespace › resource',
     'Picking one node of a hierarchy to show its details beside the tree',
+    'A docs tree of sections and pages, each Item with href (and onNavigate for a client router)',
   ],
   whenNotToUse: [
     'Site or app navigation — use SideNav (a rail advertises destinations; a tree browses data)',

package/src/components/Tree/Tree.stories.tsx

@@ -1,8 +1,11 @@
 import {useState} from 'react'
 import {html} from 'react-strict-dom'
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
+import {expect, fn} from 'storybook/test'
 import {Tree} from './Tree'
+import {clickLink} from '../../docs/clickLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+import type {OnNavigate} from '../../shared/navigate'
 
 const meta: Meta = {
   title: 'Components/Tree',
@@ -149,3 +152,92 @@ export const Controlled: Story = {
     await expect(canvas.getByLabelText('Selected')).toHaveTextContent('finance')
   },
 }
+
+function DocsTree(props: {onNavigate?: OnNavigate; defaultValue?: string}) {
+  const {onNavigate} = props
+  return (
+    <Tree.Root
+      aria-label="Docs"
+      defaultExpanded={['architecture', 'operations']}
+      defaultValue={props.defaultValue}
+    >
+      <Tree.Item value="start" label="Start here" href="#start" onNavigate={onNavigate} />
+      <Tree.Item value="architecture" label="Architecture" meta="4">
+        <Tree.Item
+          value="clusters"
+          label="Clusters and bootstrap"
+          href="#clusters"
+          onNavigate={onNavigate}
+        />
+        <Tree.Item value="ai-ops" label="AI-ops platform" href="#ai-ops" onNavigate={onNavigate} />
+        <Tree.Item
+          value="secrets"
+          label="Secrets and Vault"
+          href="#secrets"
+          onNavigate={onNavigate}
+        />
+      </Tree.Item>
+      <Tree.Item value="operations" label="Operations" meta="31">
+        <Tree.Item value="runbooks" label="Runbooks" href="#runbooks" onNavigate={onNavigate} />
+      </Tree.Item>
+    </Tree.Root>
+  )
+}
+
+/**
+ * Items with `href`: each row is a real link (cmd-click opens a tab, "Copy
+ * link" works) that stays out of the tab order, so the tree keeps one tab stop
+ * and its keyboard. Enter follows the link through `onNavigate`.
+ */
+export const WithLinks: StoryObj<{onNavigate: OnNavigate}> = {
+  parameters: {
+    a11y: {
+      test: 'error',
+      // holds-until: https://github.com/fredericrous/duro-design-system/issues/79
+      // — the selected row's accent on bgCardHover is 6.76:1, under AAA's
+      // 7:1 (AA passes). Re-enable this rule when that pair reaches 7:1.
+      options: {rules: {'color-contrast-enhanced': {enabled: false}}},
+    },
+  },
+  decorators: [onThemeSurface],
+  args: {onNavigate: fn()},
+  render: (args) => <DocsTree onNavigate={args.onNavigate} defaultValue="ai-ops" />,
+  play: async ({args, canvas, userEvent}) => {
+    const onNavigate = args.onNavigate as unknown as ReturnType<typeof fn>
+    onNavigate.mockImplementation((_href: string, event: {preventDefault(): void}) =>
+      event.preventDefault(),
+    )
+    const item = (name: RegExp) => canvas.getByRole('treeitem', {name})
+
+    // a real link, outside the tab order
+    const link = canvas.getByRole('link', {name: /Clusters and bootstrap/})
+    await expect(link).toHaveAttribute('href', '#clusters')
+    await expect(link).toHaveAttribute('tabindex', '-1')
+
+    // one tab stop (the selection), and the arrow keys still move focus
+    await userEvent.tab()
+    await expect(item(/AI-ops platform/)).toHaveFocus()
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(item(/Clusters and bootstrap/)).toHaveFocus()
+    await userEvent.keyboard('{ArrowDown}{ArrowDown}')
+    await expect(item(/Secrets and Vault/)).toHaveFocus()
+    await userEvent.keyboard('{Home}')
+    await expect(item(/Start here/)).toHaveFocus()
+
+    // Enter follows the link: onNavigate, then the item is selected
+    await userEvent.keyboard('{End}{ArrowUp}{ArrowUp}{Enter}')
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+    await expect(onNavigate.mock.calls[0][0]).toBe('#secrets')
+    await expect(item(/Secrets and Vault/)).toHaveAttribute('aria-selected', 'true')
+
+    // a plain click goes to the router; a meta-click keeps the browser
+    // default and does not select
+    await expect(clickLink(link).defaultPrevented).toBe(true)
+    await expect(onNavigate).toHaveBeenCalledTimes(2)
+    await expect(onNavigate.mock.calls[1][0]).toBe('#clusters')
+    const runbooks = canvas.getByRole('link', {name: /Runbooks/})
+    await expect(clickLink(runbooks, {metaKey: true}).defaultPrevented).toBe(false)
+    await expect(onNavigate).toHaveBeenCalledTimes(2)
+    await expect(item(/Runbooks/)).toHaveAttribute('aria-selected', 'false')
+  },
+}

package/src/components/Tree/Tree.tsx

@@ -12,13 +12,19 @@ import {
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {TreeContext, TreeLevelContext, useTree} from './TreeContext'
+import {isPlainClick, type LinkClickEvent, type OnNavigate} from '../../shared/navigate'
 
 /* Tree — a hierarchy of items (the WAI-ARIA tree pattern): single selection,
  * expandable branches, one tab stop (roving tabindex), and the keyboard of a
  * file explorer — ↑/↓ move between visible items, → opens a branch then goes
  * to its first child, ← closes it then goes to the parent, Home/End, Enter
  * or Space select, and typing jumps to the next item whose label starts with
- * the typed letters. */
+ * the typed letters.
+ *
+ * An item with `href` renders its row as a real link (cmd-click opens a tab,
+ * "Copy link" works) that stays out of the tab order: the treeitem keeps the
+ * single tab stop and the keyboard above, and Enter or Space on it follows
+ * the link, through `onNavigate` when given. */
 
 // --- Root ---
 
@@ -144,10 +150,15 @@ function Root({
           focusItem(list[list.length - 1])
           return
         case 'Enter':
-        case ' ':
+        case ' ': {
           e.preventDefault()
-          onSelect(val)
+          // an item with href: follow its link (the click selects it and
+          // runs onNavigate, or the browser navigates)
+          const link = current.querySelector<HTMLElement>(':scope > [data-tree-link]')
+          if (link) link.click()
+          else onSelect(val)
           return
+        }
       }
       // typeahead: a printable character, no modifier
       if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
@@ -237,9 +248,20 @@ interface ItemProps {
   children?: ReactNode
   /** trailing content on the row (a count, a status) */
   meta?: ReactNode
+  /**
+   * Makes the row a link to this URL. A plain click (or Enter / Space)
+   * selects the item and calls `onNavigate`; a modified click keeps the
+   * browser default (new tab, new window) and does not select.
+   */
+  href?: string
+  /**
+   * Client-side navigation for `href`: called for a plain primary click. Call
+   * `event.preventDefault()`, then your router's navigate.
+   */
+  onNavigate?: OnNavigate
 }
 
-function Item({value, label, textValue, children, meta}: ItemProps) {
+function Item({value, label, textValue, children, meta, href, onNavigate}: ItemProps) {
   const {selectedValue, onSelect, isExpanded, toggle, focusValue, keyboardFocus} = useTree()
   const level = useContext(TreeLevelContext)
   const hasChildren = Children.count(children) > 0
@@ -249,6 +271,32 @@ function Item({value, label, textValue, children, meta}: ItemProps) {
   // named by its own label only: a branch's content includes its children,
   // and a name computed from content would read the whole subtree
   const labelId = useId()
+  const rowStyles = [
+    styles.indent(level),
+    selected && styles.rowSelected,
+    keyboardFocus && focusValue === value && styles.rowFocused,
+  ]
+  const rowContent = (
+    <>
+      <html.span
+        aria-hidden
+        onClick={(e: {stopPropagation: () => void; preventDefault: () => void}) => {
+          if (!hasChildren) return
+          // the chevron only toggles: it never selects, nor follows a link
+          e.stopPropagation()
+          e.preventDefault()
+          toggle(value)
+        }}
+        style={[styles.chevron, open && styles.chevronOpen, !hasChildren && styles.chevronLeaf]}
+      >
+        ▸
+      </html.span>
+      <html.span id={labelId} style={styles.label}>
+        {label}
+      </html.span>
+      {meta != null ? <html.span style={styles.meta}>{meta}</html.span> : null}
+    </>
+  )
 
   return (
     <html.li
@@ -262,31 +310,25 @@ function Item({value, label, textValue, children, meta}: ItemProps) {
       data-tree-text={text}
       style={styles.item}
     >
-      <html.div
-        onClick={() => onSelect(value)}
-        style={[
-          styles.row,
-          styles.indent(level),
-          selected && styles.rowSelected,
-          keyboardFocus && focusValue === value && styles.rowFocused,
-        ]}
-      >
-        <html.span
-          aria-hidden
-          onClick={(e: {stopPropagation: () => void}) => {
-            if (!hasChildren) return
-            e.stopPropagation()
-            toggle(value)
+      {href !== undefined ? (
+        <html.a
+          href={href}
+          tabIndex={-1}
+          data-tree-link=""
+          onClick={(e: LinkClickEvent) => {
+            if (!isPlainClick(e)) return
+            onSelect(value)
+            onNavigate?.(href, e)
           }}
-          style={[styles.chevron, open && styles.chevronOpen, !hasChildren && styles.chevronLeaf]}
+          style={[styles.row, styles.rowLink, ...rowStyles]}
         >
-          ▸
-        </html.span>
-        <html.span id={labelId} style={styles.label}>
-          {label}
-        </html.span>
-        {meta != null ? <html.span style={styles.meta}>{meta}</html.span> : null}
-      </html.div>
+          {rowContent}
+        </html.a>
+      ) : (
+        <html.div onClick={() => onSelect(value)} style={[styles.row, ...rowStyles]}>
+          {rowContent}
+        </html.div>
+      )}
       {open ? (
         <TreeLevelContext.Provider value={level + 1}>
           <html.ul role="group" style={styles.group}>

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

@@ -50,6 +50,12 @@ export const styles = css.create({
     transitionDuration: duration.fast,
     transitionTimingFunction: easing.standard,
   },
+  // the row of an item with href: a real link that looks like the others
+  rowLink: {
+    textDecorationLine: 'none',
+    outlineWidth: 0,
+    outlineStyle: 'none',
+  },
   // one indent step per level below the top
   indent: (level: number) => ({
     paddingLeft: `calc(${spacing.sm} + ${Math.max(0, level - 1)} * ${spacing.lg})`,

package/src/docs/clickLink.ts

@@ -0,0 +1,24 @@
+/* Story helper for the onNavigate contract (shared/navigate.ts): dispatches a
+ * click on a link and reports whether anything before the window — the link
+ * part, or the onNavigate it called — prevented the default. The window
+ * listener then prevents it itself, so a story never navigates the frame or
+ * opens a tab, whatever modifier the click carries. */
+export function clickLink(
+  link: Element,
+  init: Pick<MouseEventInit, 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey' | 'button'> = {},
+): {defaultPrevented: boolean} {
+  let defaultPrevented = false
+  const onClick = (event: MouseEvent) => {
+    defaultPrevented = event.defaultPrevented
+    event.preventDefault()
+  }
+  window.addEventListener('click', onClick)
+  try {
+    link.dispatchEvent(
+      new MouseEvent('click', {bubbles: true, cancelable: true, button: 0, ...init}),
+    )
+  } finally {
+    window.removeEventListener('click', onClick)
+  }
+  return {defaultPrevented}
+}

package/src/docs/coarsePointer.ts

@@ -0,0 +1,42 @@
+import {expect, waitFor} from 'storybook/test'
+
+/**
+ * `vitest/browser` throws when imported outside Vitest, so it is loaded on
+ * call (as Menu's stories do): the stories still render in a dev Storybook.
+ * `CDPSession` is empty until the provider's typings load; `send` exists at runtime.
+ */
+const cdpSend = async (method: string, params: object) => {
+  const {cdp} = await import('vitest/browser')
+  return (cdp() as unknown as {send: (method: string, params: object) => Promise<unknown>}).send(
+    method,
+    params,
+  )
+}
+
+/**
+ * Runs `check` with Chrome's touch emulation on, so `(pointer: coarse)` matches
+ * (as DrawerScroll's CoarsePointerRows does), then turns it off again so the
+ * stories after this one see a mouse.
+ */
+export async function withCoarsePointer(check: () => Promise<void>) {
+  await cdpSend('Emulation.setTouchEmulationEnabled', {enabled: true, maxTouchPoints: 1})
+  try {
+    await waitFor(() => expect(matchMedia('(pointer: coarse)').matches).toBe(true))
+    await check()
+  } finally {
+    await cdpSend('Emulation.setTouchEmulationEnabled', {enabled: false})
+    await waitFor(() => expect(matchMedia('(pointer: coarse)').matches).toBe(false))
+  }
+}
+
+/**
+ * Turns touch emulation off and waits for a mouse. A story that measures the
+ * fine-pointer layout calls it first: the browser is shared by every story
+ * file, and one that times out mid-emulation (DrawerScroll's, under load)
+ * leaves `(pointer: coarse)` on for whatever runs next.
+ * holds-until: #81 (DrawerScroll turns emulation off in a `finally`).
+ */
+export async function withFinePointer() {
+  await cdpSend('Emulation.setTouchEmulationEnabled', {enabled: false})
+  await waitFor(() => expect(matchMedia('(pointer: coarse)').matches).toBe(false))
+}

package/src/docs/themedSurface.tsx

@@ -0,0 +1,23 @@
+import type {Decorator} from '@storybook/react'
+import {css, html} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+
+const styles = css.create({
+  surface: {
+    padding: spacing.md,
+    backgroundColor: colors.bg,
+    color: colors.text,
+  },
+})
+
+/**
+ * Paints the theme's page background behind a story. The vitest browser frame
+ * has a white page whatever the theme, so axe would measure the dark theme's
+ * text against white; on this surface `color-contrast` checks the real pair.
+ */
+export const onThemeSurface: Decorator = (Story) => (
+  <html.div style={styles.surface}>
+    <Story />
+  </html.div>
+)

package/src/index.ts

@@ -12,6 +12,7 @@ export {ActionBarProvider} from './components/ActionBar/ActionBarProvider'
 export {Alert, type AlertVariant} from './components/Alert/Alert'
 export {Icon, type IconName} from './components/Icon'
 export {Badge, type BadgeVariant, type BadgeSize} from './components/Badge/Badge'
+export {Breadcrumb} from './components/Breadcrumb/Breadcrumb'
 export {Button, type ButtonVariant, type ButtonSize} from './components/Button/Button'
 export {ButtonGroup, type ButtonGroupProps} from './components/ButtonGroup/ButtonGroup'
 export {Callout, type CalloutVariant} from './components/Callout/Callout'
@@ -44,6 +45,7 @@ export {
   type LinkButtonSize,
 } from './components/LinkButton/LinkButton'
 export {Menu} from './components/Menu/Menu'
+export {PageNav} from './components/PageNav/PageNav'
 export {Panel} from './components/Panel/Panel'
 export {RadioGroup} from './components/RadioGroup/RadioGroup'
 export {ScrollArea} from './components/ScrollArea/ScrollArea'
@@ -76,6 +78,10 @@ export {TagGroup} from './components/TagGroup/TagGroup'
 // stays optional for apps that never render a data table. Importing Table
 // from there gives the same object with those attached.
 export {Table, type TableVariant, type TableSize} from './components/Table/Table'
+export {
+  TableOfContents,
+  type TableOfContentsVariant,
+} from './components/TableOfContents/TableOfContents'
 export {Tabs} from './components/Tabs/Tabs'
 export {Tree} from './components/Tree/Tree'
 export {Textarea, type TextareaVariant} from './components/Textarea/Textarea'
@@ -107,6 +113,9 @@ export {Grid} from './components/Grid/Grid'
 export type {GridTrack} from './shared/length'
 export {PageShell, type PageShellMaxWidth, type PageShellPadding} from './components/PageShell'
 
+// Router-agnostic links: the onNavigate contract every link part shares
+export type {LinkClickEvent, OnNavigate} from './shared/navigate'
+
 // Hooks
 export {useContainerQuery, type ContainerSize} from './hooks/useContainerQuery'