@duro-app/ui 5.4.0 → 5.5.0

package/src/components/PageNav/PageNav.tsx

@@ -0,0 +1,93 @@
+import {createContext, type ReactNode, useContext} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {linkClickHandler, type OnNavigate} from '../../shared/navigate'
+
+/* PageNav — the previous and next pages in reading order, at the foot of a
+ * page: a labelled `nav` holding up to two link cards. Each card shows a small
+ * direction label ("Previous", from your text catalog) over the page title.
+ * Prev holds the left slot and Next the right one even when the other is
+ * missing, so Next stays right-aligned on the last-but-one page too; on a
+ * narrow container (below the `xs` breakpoint) the two stack.
+ *
+ * Not `Pagination` (numbered result pages, in `@duro-app/ui/table`). */
+
+// Prev and Next place themselves in Root's two-column grid.
+const PageNavContext = createContext(false)
+
+function usePageNav() {
+  if (!useContext(PageNavContext))
+    throw new Error('PageNav compound components must be used within PageNav.Root')
+}
+
+// --- Root ---
+
+interface RootProps {
+  /** Names the landmark ("Pages"); required, from your text catalog. */
+  'aria-label': string
+  /** A `PageNav.Prev` and/or a `PageNav.Next`. */
+  children: ReactNode
+}
+
+function Root({'aria-label': ariaLabel, children}: RootProps) {
+  return (
+    <PageNavContext.Provider value={true}>
+      <html.nav aria-label={ariaLabel} style={styles.root}>
+        <html.div style={styles.grid}>{children}</html.div>
+      </html.nav>
+    </PageNavContext.Provider>
+  )
+}
+
+// --- Prev / Next ---
+
+interface LinkProps {
+  href: string
+  /** The page's title. */
+  title: ReactNode
+  /** The direction label above the title ("Previous", "Next"), from your text catalog. */
+  label: ReactNode
+  /**
+   * Client-side navigation: called for a plain primary click (no modifier
+   * key). Call `event.preventDefault()`, then your router's navigate.
+   */
+  onNavigate?: OnNavigate
+}
+
+function Prev({href, title, label, onNavigate}: LinkProps) {
+  usePageNav()
+  return (
+    <html.a
+      href={href}
+      onClick={linkClickHandler(href, onNavigate)}
+      style={[styles.card, styles.prev]}
+    >
+      <html.span style={styles.label}>
+        <html.span aria-hidden>←</html.span> {label}
+      </html.span>
+      <html.span style={styles.title}>{title}</html.span>
+    </html.a>
+  )
+}
+
+function Next({href, title, label, onNavigate}: LinkProps) {
+  usePageNav()
+  return (
+    <html.a
+      href={href}
+      onClick={linkClickHandler(href, onNavigate)}
+      style={[styles.card, styles.next]}
+    >
+      <html.span style={styles.label}>
+        {label} <html.span aria-hidden>→</html.span>
+      </html.span>
+      <html.span style={styles.title}>{title}</html.span>
+    </html.a>
+  )
+}
+
+export const PageNav = {
+  Root,
+  Prev,
+  Next,
+}

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

@@ -0,0 +1,100 @@
+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 {breakpoints} from '@duro-app/tokens/tokens/breakpoints.css'
+import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+
+// Below this container width the two cards stack (Mobile.dc.html); above it
+// they sit side by side, each in its own half (Reader.dc.html).
+const STACK_BP = breakpoints.xs
+const STACKED = `@container (max-width: ${STACK_BP})`
+
+// The picked docs browser (docs/mockups/docs-nav/Reader.dc.html and
+// Mobile.dc.html, `.pn .card`): two interactive cards, a small muted
+// direction label over the title, Next aligned right.
+export const styles = css.create({
+  // hosts the container query: a container cannot query itself
+  root: {
+    containerType: 'inline-size',
+    minWidth: 0,
+  },
+  grid: {
+    display: 'grid',
+    gridTemplateColumns: {
+      default: 'minmax(0, 1fr) minmax(0, 1fr)',
+      [STACKED]: 'minmax(0, 1fr)',
+    },
+    gap: spacing.md,
+  },
+  card: {
+    display: 'flex',
+    flexDirection: 'column',
+    padding: spacing.md,
+    fontFamily: typography.fontFamily,
+    color: colors.text,
+    textDecorationLine: 'none',
+    backgroundColor: {
+      default: colors.bgCard,
+      ':hover': colors.bgCardHover,
+    },
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+    borderRadius: radii.md,
+    cursor: 'pointer',
+    transitionProperty: 'background-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,
+    },
+  },
+  // each side keeps its slot: Next stays in the right half without a Prev
+  prev: {
+    gridColumn: {
+      default: '1',
+      [STACKED]: 'auto',
+    },
+    gridRow: {
+      default: '1',
+      [STACKED]: 'auto',
+    },
+  },
+  next: {
+    gridColumn: {
+      default: '2',
+      [STACKED]: 'auto',
+    },
+    gridRow: {
+      default: '1',
+      [STACKED]: 'auto',
+    },
+    textAlign: {
+      default: 'right',
+      [STACKED]: 'left',
+    },
+  },
+  label: {
+    fontSize: typography.fontSizeXs,
+    color: colors.textMuted,
+  },
+  title: {
+    fontSize: typography.fontSizeSm,
+    overflowWrap: 'anywhere',
+  },
+})

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