@duro-app/ui 5.4.0 → 5.6.0

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/Toggle/Toggle.tsx

@@ -4,9 +4,10 @@ import {useControllableValue} from '../../hooks/useControllableValue'
 import {useToggleGroup} from '../ToggleGroup/ToggleGroupContext'
 import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
 import {mergeRefs} from '../../shared/mergeRefs'
+import type {ControlSize} from '../../shared/types'
 import {styles} from './styles.css'
 
-export type ToggleSize = 'default' | 'small'
+export type ToggleSize = ControlSize
 
 interface ToggleProps {
   /** Controlled pressed state (standalone usage). */

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

@@ -37,6 +37,8 @@ export const styles = css.create({
     fontSize: typography.fontSizeXs,
     borderRadius: radii.sm,
     gap: spacing.xs,
+    // Every small control is at least controlSm tall, whatever it holds (5.6).
+    minHeight: {default: sizes.controlSm, '@media (pointer: coarse)': sizes.touchTarget},
   },
   // wrapped toggles: a fixed block size per size, the touch target under a
   // coarse pointer. ToggleGroup's maxRows arithmetic reads the same tokens.

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,7 +12,9 @@ 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 type {ControlSize} from './shared/types'
 export {ButtonGroup, type ButtonGroupProps} from './components/ButtonGroup/ButtonGroup'
 export {Callout, type CalloutVariant} from './components/Callout/Callout'
 export {Card, type CardVariant, type CardSize} from './components/Card/Card'
@@ -44,6 +46,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 +79,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'
@@ -97,6 +104,7 @@ export {Tooltip} from './components/Tooltip/Tooltip'
 export {Toolbar, type ToolbarProps} from './components/Toolbar/Toolbar'
 export {Popover} from './components/Popover/Popover'
 export type {PopoverHandle} from './components/Popover/Popover'
+export {useInModal} from './shared/ModalContext'
 export {Switch} from './components/Switch/Switch'
 
 // Layout primitives
@@ -107,6 +115,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'
 

package/src/shared/ModalContext.ts

@@ -13,6 +13,13 @@ import {createContext, useContext} from 'react'
  */
 export const ModalContext = createContext(false)
 
-export function useInModal() {
+/**
+ * True inside a Dialog or Drawer, false outside. A floating surface that is not
+ * a Duro Popover picks its layer with it, the way a Popover does:
+ * `useInModal() ? layers.popover : layers.floating`, and for one that must
+ * cover another floating surface (a link editor over a format bar)
+ * `useInModal() ? layers.popoverRaised : layers.floatingRaised`.
+ */
+export function useInModal(): boolean {
   return useContext(ModalContext)
 }

package/src/shared/exports.typecheck.ts

@@ -0,0 +1,16 @@
+// Compile-only checks that 5.6's additions are on the package root, where a
+// consumer imports them. `pnpm typecheck` fails if one is dropped from
+// index.ts or changes shape. Never imported at runtime.
+
+import type {ButtonSize, ControlSize, ToggleSize, useInModal} from '../index'
+
+type Same<T, U> = [T] extends [U] ? ([U] extends [T] ? true : false) : false
+
+// A floating surface that is not a Popover picks its layer with it.
+export const useInModalIsBoolean: Same<ReturnType<typeof useInModal>, boolean> = true
+export const useInModalTakesNothing: Same<Parameters<typeof useInModal>, []> = true
+
+// The shared size, and the two sizes that alias it.
+export const controlSizes: Same<ControlSize, 'default' | 'small'> = true
+export const buttonSizeIsControlSize: Same<ButtonSize, ControlSize> = true
+export const toggleSizeIsControlSize: Same<ToggleSize, ControlSize> = true

package/src/shared/linkParts.typecheck.tsx

@@ -0,0 +1,47 @@
+// Compile-only fixtures for the exclusive prop sets of the docs-nav parts.
+// `pnpm typecheck` fails if an illegal combination becomes assignable, or a
+// legal one stops being. Never imported at runtime.
+
+import type {Breadcrumb} from '../components/Breadcrumb/Breadcrumb'
+import type {TableOfContents} from '../components/TableOfContents/TableOfContents'
+import type {OnNavigate} from './navigate'
+
+/** `true` when every member of T is assignable to U. */
+type Assignable<T, U> = [T] extends [U] ? true : false
+
+/** The props a function component takes. */
+type PropsOf<C> = C extends (props: infer P) => unknown ? P : never
+
+type CrumbProps = PropsOf<typeof Breadcrumb.Item>
+type TocRootProps = PropsOf<typeof TableOfContents.Root>
+type Children = {children: string}
+
+// Breadcrumb.Item: a link, or the current page — never both, never neither.
+export const crumbLink: Assignable<{href: string} & Children, CrumbProps> = true
+export const crumbLinkNavigate: Assignable<
+  {href: string; onNavigate: OnNavigate} & Children,
+  CrumbProps
+> = true
+export const crumbCurrent: Assignable<{current: true} & Children, CrumbProps> = true
+export const crumbCurrentWithHref: Assignable<
+  {current: true; href: string} & Children,
+  CrumbProps
+> = false
+export const crumbCurrentWithNavigate: Assignable<
+  {current: true; onNavigate: OnNavigate} & Children,
+  CrumbProps
+> = false
+export const crumbNeither: Assignable<Children, CrumbProps> = false
+
+// TableOfContents.Root: the disclosure props belong to the menu variant only.
+type TocBase = {'aria-label': string} & Children
+export const tocList: Assignable<TocBase, TocRootProps> = true
+export const tocMenuOpen: Assignable<
+  {variant: 'menu'; open: boolean; onOpenChange: (open: boolean) => void} & TocBase,
+  TocRootProps
+> = true
+export const tocListOpen: Assignable<{open: boolean} & TocBase, TocRootProps> = false
+export const tocListDefaultOpen: Assignable<
+  {variant: 'list'; defaultOpen: boolean} & TocBase,
+  TocRootProps
+> = false