@duro-app/ui 5.4.0 → 5.6.0

package/src/components/Select/Select.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it).',
+    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it). Select.Trigger takes size="small" to match small Toggles and Buttons in a toolbar.',
   whenToUse: [
     'User must pick one option from a predefined list',
     'Form field for country, category, role selection',

package/src/components/Select/Select.tsx

@@ -10,6 +10,7 @@ import {usePopoverLayer} from '../Popover/PopoverLayerContext'
 import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
 import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
 import {mergeRefs} from '../../shared/mergeRefs'
+import type {ControlSize} from '../../shared/types'
 
 // --- Root ---
 interface RootProps {
@@ -38,9 +39,12 @@ function Root({name, defaultValue, value, onValueChange, initialLabels, children
 function Trigger({
   children,
   'aria-label': ariaLabel,
+  size = 'default',
 }: {
   children: ReactNode
   'aria-label'?: string
+  /** `small` matches a small Toggle or Button beside it. Default: `default`. */
+  size?: ControlSize
 }) {
   const {open, toggle, listboxId, highlightedId, triggerRef} = useSelect()
   const localRef = useRef<HTMLButtonElement>(null)
@@ -74,7 +78,7 @@ function Trigger({
       aria-activedescendant={highlightedId ?? undefined}
       aria-describedby={describedBy || undefined}
       aria-invalid={fieldCtx?.invalid || undefined}
-      style={[styles.trigger, grouped.style]}
+      style={[styles.trigger, size === 'small' && styles.triggerSmall, grouped.style]}
     >
       {children}
     </html.button>

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

@@ -37,6 +37,18 @@ export const styles = css.create({
     transitionProperty: 'border-color',
     transitionDuration: duration.fast,
   },
+  // 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},
+  },
   value: {
     color: colors.text,
   },

package/src/components/TableOfContents/TableOfContents.meta.ts

@@ -0,0 +1,41 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'The "On this page" list of a long page\'s sections: a labelled nav of in-page links (href="#id", level 2 or 3). value is the id of the section being read; that item gets aria-current="location", the nav marker bar and a heavier weight. variant="menu" puts the list behind a disclosure button (aria-expanded) for narrow screens; the disclosure state (open, defaultOpen and its change callback) exists on the menu variant only. No scroll-spy inside: the app computes value. Compound component — Root is required.',
+  whenToUse: [
+    'A long document page (docs, a runbook, an ADR) with H2/H3 sections',
+    'variant="menu" for the same list on a narrow screen, above the body',
+  ],
+  whenNotToUse: [
+    'Navigation between pages — use SideNav, Tree or Breadcrumb',
+    'Switching views of one record — use Tabs',
+    'A page with no H2/H3 — render nothing instead of an empty list',
+  ],
+  anatomy: {
+    required: ['Root', 'Item'],
+  },
+  relatedTo: [
+    {
+      component: 'Tabs',
+      kind: 'contrast',
+      relationship:
+        'Tabs swap the content in place; TableOfContents links to sections of one long page',
+    },
+    {
+      component: 'PageNav',
+      kind: 'contrast',
+      relationship: 'TableOfContents moves within the page; PageNav moves to the next page',
+    },
+  ],
+  example: `<TableOfContents.Root aria-label="On this page" label="On this page" value={activeId}>
+  <TableOfContents.Item href="#components">The components</TableOfContents.Item>
+  <TableOfContents.Item href="#wiring">Wiring</TableOfContents.Item>
+  <TableOfContents.Item href="#webhooks" level={3}>Webhooks</TableOfContents.Item>
+</TableOfContents.Root>
+
+// narrow screens
+<TableOfContents.Root aria-label="On this page" variant="menu" value={activeId}>
+  …
+</TableOfContents.Root>`,
+}

package/src/components/TableOfContents/TableOfContents.stories.tsx

@@ -0,0 +1,222 @@
+import {useState} from 'react'
+import {css, html} from 'react-strict-dom'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, waitFor} from 'storybook/test'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {TableOfContents} from './TableOfContents'
+import type {TableOfContentsVariant} from './TableOfContentsContext'
+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/TableOfContents',
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+}
+
+export default meta
+type Story = StoryObj
+
+const styles = css.create({
+  aside: {width: sizes.gridColXs},
+  phone: {width: sizes.pageXs},
+})
+
+function Sections(props: {
+  value?: string | null
+  variant?: TableOfContentsVariant
+  onNavigate?: OnNavigate
+}) {
+  return (
+    <TableOfContents.Root
+      aria-label="On this page"
+      label="On this page"
+      value={props.value}
+      variant={props.variant}
+    >
+      <TableOfContents.Item href="#components" onNavigate={props.onNavigate}>
+        The components
+      </TableOfContents.Item>
+      <TableOfContents.Item href="#wiring" onNavigate={props.onNavigate}>
+        Wiring
+      </TableOfContents.Item>
+      <TableOfContents.Item href="#webhooks" level={3} onNavigate={props.onNavigate}>
+        Webhooks
+      </TableOfContents.Item>
+      <TableOfContents.Item href="#lifecycle" onNavigate={props.onNavigate}>
+        Alert lifecycle
+      </TableOfContents.Item>
+      <TableOfContents.Item href="#next" onNavigate={props.onNavigate}>
+        Where to read next
+      </TableOfContents.Item>
+    </TableOfContents.Root>
+  )
+}
+
+export const List: Story = {
+  render: () => (
+    <html.div style={styles.aside}>
+      <Sections value="wiring" />
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByRole('navigation', {name: 'On this page'})).toBeInTheDocument()
+    const active = canvas.getByRole('link', {name: 'Wiring'})
+    await expect(active).toHaveAttribute('aria-current', 'location')
+    await expect(canvas.getByRole('link', {name: 'The components'})).not.toHaveAttribute(
+      'aria-current',
+    )
+    // not colour alone: the marker bar and a heavier weight
+    await expect(getComputedStyle(active).boxShadow).toContain('inset')
+    const other = canvas.getByRole('link', {name: 'The components'})
+    await expect(Number(getComputedStyle(active).fontWeight)).toBeGreaterThan(
+      Number(getComputedStyle(other).fontWeight),
+    )
+    // a level-3 item is indented under its H2
+    const h3 = canvas.getByRole('link', {name: 'Webhooks'})
+    await expect(parseFloat(getComputedStyle(h3).paddingLeft)).toBeGreaterThan(
+      parseFloat(getComputedStyle(other).paddingLeft),
+    )
+  },
+}
+
+export const KeyboardOrder: Story = {
+  render: () => (
+    <html.div style={styles.aside}>
+      <Sections value="components" />
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    for (const name of [
+      'The components',
+      'Wiring',
+      'Webhooks',
+      'Alert lifecycle',
+      'Where to read next',
+    ]) {
+      await userEvent.tab()
+      await expect(canvas.getByRole('link', {name})).toHaveFocus()
+    }
+  },
+}
+
+/** The app owns the scroll-spy and passes the section being read as `value`. */
+export const ControlledValue: Story = {
+  render: function Render() {
+    const [value, setValue] = useState('components')
+    return (
+      <html.div style={styles.aside}>
+        <Sections
+          value={value}
+          onNavigate={(href, event) => {
+            event.preventDefault()
+            setValue(href.slice(1))
+          }}
+        />
+      </html.div>
+    )
+  },
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('link', {name: 'Alert lifecycle'}))
+    await expect(canvas.getByRole('link', {name: 'Alert lifecycle'})).toHaveAttribute(
+      'aria-current',
+      'location',
+    )
+    await expect(canvas.getByRole('link', {name: 'The components'})).not.toHaveAttribute(
+      'aria-current',
+    )
+  },
+}
+
+export const Menu: Story = {
+  render: () => (
+    <html.div style={styles.phone}>
+      <Sections value="wiring" variant="menu" />
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('button', {name: 'On this page'})
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await expect(canvas.queryByRole('link')).toBeNull()
+
+    // opens from the keyboard; the list follows the button in the tab order
+    await userEvent.tab()
+    await expect(trigger).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    await expect(trigger).toHaveAttribute('aria-controls', canvas.getByRole('list').id)
+    await expect(canvas.getByRole('link', {name: 'Wiring'})).toHaveAttribute(
+      'aria-current',
+      'location',
+    )
+    await userEvent.tab()
+    await expect(canvas.getByRole('link', {name: 'The components'})).toHaveFocus()
+
+    // Escape closes it and gives focus back to the button
+    await userEvent.keyboard('{Escape}')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await expect(trigger).toHaveFocus()
+    await expect(canvas.queryByRole('link')).toBeNull()
+
+    // following an item closes it too
+    await userEvent.click(trigger)
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    clickLink(canvas.getByRole('link', {name: 'Webhooks'}))
+    await waitFor(() => expect(trigger).toHaveAttribute('aria-expanded', 'false'))
+
+    // a touch target: the button is at least 44px tall
+    await expect(trigger.getBoundingClientRect().height).toBeGreaterThanOrEqual(44)
+  },
+}
+
+export const ClientNavigation: StoryObj<{onNavigate: OnNavigate}> = {
+  args: {onNavigate: fn()},
+  render: (args) => (
+    <html.div style={styles.aside}>
+      <Sections value="components" onNavigate={args.onNavigate} />
+    </html.div>
+  ),
+  play: async ({args, canvas}) => {
+    const onNavigate = args.onNavigate as unknown as ReturnType<typeof fn>
+    const link = canvas.getByRole('link', {name: 'Wiring'})
+    // the part never prevents the default itself: with a handler that leaves
+    // the event alone, the browser still follows the anchor
+    await expect(clickLink(link).defaultPrevented).toBe(false)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+    await expect(onNavigate.mock.calls[0][0]).toBe('#wiring')
+    await expect(clickLink(link, {metaKey: true}).defaultPrevented).toBe(false)
+    await expect(onNavigate).toHaveBeenCalledTimes(1)
+  },
+}
+
+/**
+ * A touch screen gets 44px items in the list variant too (coarse pointer); a
+ * mouse keeps the artboard's compact rail.
+ * 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: () => (
+    <html.div style={styles.aside}>
+      <Sections value="wiring" />
+    </html.div>
+  ),
+  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/TableOfContents/TableOfContents.tsx

@@ -0,0 +1,173 @@
+import {type ReactNode, useCallback, useId, useMemo, useRef} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {useControllableValue} from '../../hooks/useControllableValue'
+import {isPlainClick, type LinkClickEvent, type OnNavigate} from '../../shared/navigate'
+import {
+  TableOfContentsContext,
+  useTableOfContents,
+  type TableOfContentsVariant,
+} from './TableOfContentsContext'
+
+/* TableOfContents — the "On this page" list of a long page's sections: a
+ * labelled `nav` of in-page links. The section being read is `value`; its item
+ * carries `aria-current="location"` and a marker bar plus a heavier weight, so
+ * colour is never the only cue. Which section is being read is the app's to
+ * work out (an IntersectionObserver over the headings): the component does no
+ * scroll-spy.
+ *
+ * `variant="menu"` is the narrow-screen form: a disclosure button (with
+ * `aria-expanded`) that shows the same list below it, and closes again when an
+ * item is followed or on Escape. */
+
+// --- Root ---
+
+/**
+ * The disclosure state (`open`, `defaultOpen`, `onOpenChange`) exists only on
+ * the menu: the list variant has no button, so it takes none of them.
+ */
+type RootProps = {
+  /** Names the landmark ("On this page"); required, from your text catalog. */
+  'aria-label': string
+  /** The id of the section being read; the Item whose href is `#<value>` is active. */
+  value?: string | null
+  /**
+   * Visible title: the caption above the list, or the menu button's text.
+   * The menu button falls back to `aria-label`; the list shows none without it.
+   */
+  label?: ReactNode
+  children: ReactNode
+} & (
+  | {
+      /** `list` (default) for a sidebar; `menu` for a narrow screen, behind a disclosure button (only `menu` takes open / defaultOpen / onOpenChange). */
+      variant?: 'list'
+      open?: never
+      defaultOpen?: never
+      onOpenChange?: never
+    }
+  | {
+      /** `list` (default) for a sidebar; `menu` for a narrow screen, behind a disclosure button (only `menu` takes open / defaultOpen / onOpenChange). */
+      variant: 'menu'
+      /** Whether the list is shown (controlled). */
+      open?: boolean
+      /** Whether the list starts shown (uncontrolled; default false). */
+      defaultOpen?: boolean
+      onOpenChange?: (open: boolean) => void
+    }
+)
+
+function Root({
+  'aria-label': ariaLabel,
+  value = null,
+  variant = 'list',
+  label,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+}: RootProps) {
+  const [open, setOpen] = useControllableValue(openProp, defaultOpen, onOpenChange)
+  const listId = useId()
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const isMenu = variant === 'menu'
+
+  const close = useCallback(() => {
+    if (isMenu && open) setOpen(false)
+  }, [isMenu, open, setOpen])
+
+  const ctx = useMemo(() => ({value, variant, close}), [value, variant, close])
+
+  const list = (
+    <html.ul id={isMenu ? listId : undefined} style={[styles.list, isMenu && styles.listMenu]}>
+      {children}
+    </html.ul>
+  )
+
+  return (
+    <TableOfContentsContext.Provider value={ctx}>
+      <html.nav
+        aria-label={ariaLabel}
+        onKeyDown={(e: {key: string}) => {
+          if (isMenu && open && e.key === 'Escape') {
+            setOpen(false)
+            triggerRef.current?.focus()
+          }
+        }}
+        style={styles.root}
+      >
+        {isMenu ? (
+          <>
+            <html.button
+              ref={triggerRef}
+              type="button"
+              aria-expanded={open}
+              aria-controls={open ? listId : undefined}
+              onClick={() => setOpen(!open)}
+              style={[styles.trigger, styles.focusable]}
+            >
+              <html.span>{label ?? ariaLabel}</html.span>
+              <html.span aria-hidden style={[styles.chevron, open && styles.chevronOpen]}>
+                ▾
+              </html.span>
+            </html.button>
+            {open ? list : null}
+          </>
+        ) : (
+          <>
+            {label != null ? <html.div style={styles.caption}>{label}</html.div> : null}
+            {list}
+          </>
+        )}
+      </html.nav>
+    </TableOfContentsContext.Provider>
+  )
+}
+
+// --- Item ---
+
+interface ItemProps {
+  /** The section's anchor, `#<heading id>`. */
+  href: string
+  /** The heading's level: 2, or 3 (indented under the 2 before it). */
+  level?: 2 | 3
+  /**
+   * Client-side navigation: called for a plain primary click (no modifier
+   * key). Call `event.preventDefault()`, then scroll or navigate yourself.
+   */
+  onNavigate?: OnNavigate
+  children: ReactNode
+}
+
+function Item({href, level = 2, onNavigate, children}: ItemProps) {
+  const {value, variant, close} = useTableOfContents()
+  const active = value != null && href === `#${value}`
+  return (
+    <html.li style={styles.item}>
+      <html.a
+        href={href}
+        aria-current={active ? 'location' : undefined}
+        onClick={(e: LinkClickEvent) => {
+          if (!isPlainClick(e)) return
+          onNavigate?.(href, e)
+          close()
+        }}
+        style={[
+          styles.link,
+          styles.focusable,
+          variant === 'menu' && styles.linkMenu,
+          level === 3 && styles.level3,
+          active && styles.linkActive,
+        ]}
+      >
+        {children}
+      </html.a>
+    </html.li>
+  )
+}
+
+export const TableOfContents = {
+  Root,
+  Item,
+}
+
+export type {TableOfContentsVariant}

package/src/components/TableOfContents/TableOfContentsContext.ts

@@ -0,0 +1,20 @@
+import {createContext, useContext} from 'react'
+
+export type TableOfContentsVariant = 'list' | 'menu'
+
+export interface TableOfContentsContextValue {
+  /** the id of the section being read (an Item is active when its href is `#<value>`) */
+  value: string | null
+  variant: TableOfContentsVariant
+  /** closes the menu variant's disclosure (no-op for the list) */
+  close: () => void
+}
+
+export const TableOfContentsContext = createContext<TableOfContentsContextValue | null>(null)
+
+export function useTableOfContents() {
+  const ctx = useContext(TableOfContentsContext)
+  if (!ctx)
+    throw new Error('TableOfContents compound components must be used within TableOfContents.Root')
+  return ctx
+}

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")',