@duro-app/ui 5.7.0 → 5.8.1

package/src/components/Grid/Grid.stories.tsx

@@ -1,13 +1,18 @@
+import {useRef} from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
+import {expect, waitFor} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Grid} from './Grid'
 import {Stack} from '../Stack/Stack'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
-import {SIZES_PX, SPACING_KEYS} from '@duro-app/tokens/keys'
+import {SIZES_PX, SPACING_KEYS, type SpacingToken} from '@duro-app/tokens/keys'
+import {breakpointsPx} from '@duro-app/tokens/tokens/breakpoints.css'
 import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 import {useContainerQuery} from '../../hooks/useContainerQuery'
+import {useContainerBelow} from '../../hooks/useContainerBelow'
+import {Aside} from '../Aside/Aside'
+import {onThemeSurface} from '../../docs/themedSurface'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
 
@@ -25,7 +30,7 @@ const meta: Meta<typeof Grid> = {
       description: 'A count, or weights such as [1, 2] for a one-third / two-thirds split',
     },
     minColumnWidth: {control: 'text'},
-    layout: {control: 'select', options: [undefined, 'split', 'split-wide']},
+    layout: {control: 'select', options: [undefined, 'split', 'split-wide', 'content-aside']},
   },
 }
 
@@ -261,3 +266,197 @@ const trackStyles = css.create({
     backgroundColor: colors.bgCard,
   },
 })
+
+// --- content-aside --------------------------------------------------------
+
+const asideStyles = css.create({
+  // pageLg (1200px) and pageSm (600px): either side of md (768px)
+  wide: {width: sizes.pageLg},
+  narrow: {width: sizes.pageSm},
+  cell: {
+    padding: spacing.sm,
+    borderWidth: borders.hairline,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+  },
+  // An outline, not a border: the frame's edge without taking its width.
+  frame: (width: number) => ({
+    width,
+    outlineWidth: borders.hairline,
+    outlineStyle: 'dashed',
+    outlineColor: colors.border,
+  }),
+})
+
+// Each page's Grid ref, for the play functions to compare with the DOM.
+const gridRefs = new Map<string, {current: HTMLDivElement | null}>()
+
+/** Reports, beside the grid, what `useContainerBelow` sees on the Grid's ref. */
+function ReadingPage({name, gap = 'xl'}: {name: string; gap?: SpacingToken}) {
+  const ref = useRef<HTMLDivElement | null>(null)
+  gridRefs.set(name, ref)
+  const below = useContainerBelow(ref, 'md')
+  return (
+    <html.div role="group" aria-label={name}>
+      <Grid ref={ref} layout="content-aside" gap={gap}>
+        <html.div role="region" aria-label={`${name} content`} style={asideStyles.cell}>
+          {below ? 'below md' : 'md or wider'}
+        </html.div>
+        <Aside aria-label={`${name} outline`}>
+          <html.div style={asideStyles.cell}>On this page</html.div>
+        </Aside>
+      </Grid>
+    </html.div>
+  )
+}
+
+interface ContentAsideArgs {
+  /** The gap between the reading column and the Aside. */
+  gap: SpacingToken
+  /** The frame's width in px: the container the Grid measures. */
+  width: number
+}
+
+/**
+ * A reading column beside an Aside (asideW); one column below md (768px),
+ * measured on the Grid's own container. Drag `width` across 768 to see it
+ * collapse: the column reports what `useContainerBelow` sees.
+ */
+export const ContentAside: StoryObj<ContentAsideArgs> = {
+  args: {gap: 'xl', width: SIZES_PX.pageLg},
+  argTypes: {
+    gap: {control: 'select', options: [...SPACING_KEYS]},
+    width: {control: {type: 'range', min: 320, max: 1440, step: 8}},
+  },
+  parameters: {a11y: {test: 'error'}, controls: {include: ['gap', 'width']}},
+  decorators: [onThemeSurface],
+  render: ({gap, width}) => (
+    <html.div style={asideStyles.frame(width)}>
+      <ReadingPage name="Page" gap={gap} />
+    </html.div>
+  ),
+}
+
+/** ContentAside's checks, kept off the visible story so a Control change cannot fail them. */
+export const ContentAsideChecks: StoryObj<ContentAsideArgs> = {
+  ...ContentAside,
+  tags: ['!dev', '!autodocs'],
+  play: async ({args, canvas}) => {
+    const content = canvas.getByRole('region', {name: 'Page content'})
+    const aside = canvas.getByRole('complementary', {name: 'Page outline'})
+    if (args.width >= breakpointsPx.md) {
+      await expect(aside.getBoundingClientRect().width).toBe(SIZES_PX.asideW)
+      await expect(aside.getBoundingClientRect().left).toBeGreaterThan(
+        content.getBoundingClientRect().right,
+      )
+    } else {
+      await expect(aside.getBoundingClientRect().top).toBeGreaterThanOrEqual(
+        content.getBoundingClientRect().bottom,
+      )
+    }
+  },
+}
+
+/** ContentAside's checks below md (pageSm, 600px): the Aside stacks under the column. */
+export const ContentAsideStackedChecks: StoryObj<ContentAsideArgs> = {
+  ...ContentAsideChecks,
+  args: {...ContentAsideChecks.args, width: SIZES_PX.pageSm},
+}
+
+/** A wide page and a narrow one, side by side: beside, then stacked. */
+export const ContentAsideWideAndNarrow: Story = {
+  tags: ['!dev', '!autodocs'],
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: () => (
+    <Stack gap="lg">
+      <html.div style={asideStyles.wide}>
+        <ReadingPage name="Wide" />
+      </html.div>
+      <html.div style={asideStyles.narrow}>
+        <ReadingPage name="Narrow" />
+      </html.div>
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    const wideContent = canvas.getByRole('region', {name: 'Wide content'})
+    const wideAside = canvas.getByRole('complementary', {name: 'Wide outline'})
+    await expect(wideAside.getBoundingClientRect().width).toBe(SIZES_PX.asideW)
+    await expect(wideAside.getBoundingClientRect().left).toBeGreaterThan(
+      wideContent.getBoundingClientRect().right,
+    )
+    const narrowContent = canvas.getByRole('region', {name: 'Narrow content'})
+    const narrowAside = canvas.getByRole('complementary', {name: 'Narrow outline'})
+    await expect(narrowAside.getBoundingClientRect().top).toBeGreaterThanOrEqual(
+      narrowContent.getBoundingClientRect().bottom,
+    )
+  },
+}
+
+/**
+ * The collapse and `useContainerBelow` follow the Grid's container, not the
+ * window: in a 1440px viewport the 600px page stacks and reports "below md",
+ * the 1200px one does not. The forwarded ref is the container the query
+ * measures. Sizes the browser through Vitest, so it runs as a test only.
+ */
+export const ContentAsideFollowsItsContainer: Story = {
+  tags: ['!dev', '!autodocs'],
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+  render: () => (
+    <Stack gap="lg">
+      <html.div style={asideStyles.wide}>
+        <ReadingPage name="Wide" />
+      </html.div>
+      <html.div style={asideStyles.narrow}>
+        <ReadingPage name="Narrow" />
+      </html.div>
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    const {page} = await import('vitest/browser')
+    const before = {width: window.innerWidth, height: window.innerHeight}
+    await page.viewport(1440, 900)
+    try {
+      await waitFor(() => expect(window.innerWidth).toBe(1440))
+      const narrow = canvas.getByRole('group', {name: 'Narrow'})
+      const wide = canvas.getByRole('group', {name: 'Wide'})
+      // the ref resolves to the container element the query measures
+      const narrowContainer = narrow.firstElementChild as HTMLElement
+      await expect(gridRefs.get('Narrow')?.current).toBe(narrowContainer)
+      await expect(gridRefs.get('Wide')?.current).toBe(wide.firstElementChild)
+      await expect(getComputedStyle(narrowContainer).containerType).toBe('inline-size')
+      await expect(narrowContainer.getBoundingClientRect().width).toBe(SIZES_PX.pageSm)
+      await waitFor(() =>
+        expect(canvas.getByRole('region', {name: 'Narrow content'})).toHaveTextContent('below md'),
+      )
+      await expect(canvas.getByRole('region', {name: 'Wide content'})).toHaveTextContent(
+        'md or wider',
+      )
+      // and the CSS collapse agrees with it
+      const narrowAside = canvas.getByRole('complementary', {name: 'Narrow outline'})
+      await expect(narrowAside.getBoundingClientRect().width).toBe(SIZES_PX.pageSm)
+      const wideAside = canvas.getByRole('complementary', {name: 'Wide outline'})
+      await expect(wideAside.getBoundingClientRect().width).toBe(SIZES_PX.asideW)
+    } finally {
+      await page.viewport(before.width, before.height)
+    }
+  },
+}
+
+const plainGrid: {current: HTMLDivElement | null} = {current: null}
+
+/** `ref` reaches the grid element itself when there is no named layout. */
+export const RefWithoutLayout: Story = {
+  render: () => (
+    <Grid ref={plainGrid} columns={2} gap="sm">
+      <Cell>One</Cell>
+      <Cell>Two</Cell>
+    </Grid>
+  ),
+  play: async ({canvas}) => {
+    const grid = canvas.getByText('One').parentElement as HTMLElement
+    await expect(getComputedStyle(grid).display).toBe('grid')
+    await expect(plainGrid.current).toBe(grid)
+  },
+}

package/src/components/Grid/Grid.tsx

@@ -1,4 +1,4 @@
-import {Children, type ReactNode} from 'react'
+import {Children, type ReactNode, type Ref} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {isNative} from '../../platform'
@@ -6,7 +6,7 @@ import {cellBasis, cellPosition, columnWeights, gridTemplate, type GridColumns}
 import type {SpacingToken} from '@duro-app/tokens/keys'
 import {resolveLength, resolveTrack, type GridTrack, type Length} from '../../shared/length'
 
-export type GridLayout = 'split' | 'split-wide'
+export type GridLayout = 'split' | 'split-wide' | 'content-aside'
 
 interface GridProps {
   gap?: SpacingToken
@@ -25,7 +25,9 @@ interface GridProps {
    * column on the width of its OWN container — `split` below `sm` (640px),
    * `split-wide` below `md` (768px) — so a split nested inside another
    * split, or beside an open DetailPanel, collapses when it runs out of room
-   * rather than when the window does. Wins over `columns` / `minColumnWidth`.
+   * rather than when the window does. `content-aside` is a reading column
+   * beside an `Aside` (`asideW`, 320px), one column below `md`. Wins over
+   * `columns` / `minColumnWidth`.
    */
   layout?: GridLayout
   /**
@@ -37,6 +39,13 @@ interface GridProps {
    * wins over it.
    */
   tracks?: readonly GridTrack[]
+  /**
+   * The Grid's outer element: with a `layout`, the wrapper its container
+   * query measures (hand it to `useContainerBelow` to follow the same
+   * collapse); otherwise the grid itself. Web only: on native the ref is not
+   * attached.
+   */
+  ref?: Ref<HTMLDivElement>
   children: ReactNode
 }
 
@@ -65,6 +74,7 @@ const columnsMap = {
 const layoutMap = {
   split: styles.split,
   'split-wide': styles.splitWide,
+  'content-aside': styles.contentAside,
 } as const satisfies Record<GridLayout, unknown>
 
 // On native the named layouts are their weights; there is no media query to
@@ -72,6 +82,7 @@ const layoutMap = {
 const layoutWeights = {
   split: [1, 2],
   'split-wide': [1, 3],
+  'content-aside': [2, 1],
 } as const satisfies Record<GridLayout, readonly number[]>
 
 const cellGapLeftMap = {
@@ -96,7 +107,15 @@ const cellGapTopMap = {
   xxxl: styles.cellGapTopXxxl,
 } as const satisfies Record<SpacingToken, unknown>
 
-export function Grid({gap = 'md', columns, minColumnWidth, layout, tracks, children}: GridProps) {
+export function Grid({
+  gap = 'md',
+  columns,
+  minColumnWidth,
+  layout,
+  tracks,
+  ref,
+  children,
+}: GridProps) {
   const hasTracks = tracks !== undefined && tracks.length > 0
   if (isNative) {
     return (
@@ -122,10 +141,20 @@ export function Grid({gap = 'md', columns, minColumnWidth, layout, tracks, child
             ? styles.template(gridTemplate(columnWeights(columns) ?? [1]))
             : undefined
 
-  const grid = <html.div style={[styles.base, gapMap[gap], columnStyle]}>{children}</html.div>
+  const grid = (
+    <html.div ref={layout ? undefined : ref} style={[styles.base, gapMap[gap], columnStyle]}>
+      {children}
+    </html.div>
+  )
   // A named layout answers its container query from a wrapper: an element
   // cannot query its own size.
-  return layout ? <html.div style={styles.splitContainer}>{grid}</html.div> : grid
+  return layout ? (
+    <html.div ref={ref} style={styles.splitContainer}>
+      {grid}
+    </html.div>
+  ) : (
+    grid
+  )
 }
 
 /**

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

@@ -12,6 +12,7 @@ import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 // has. defineConsts strings, inlined into the @container text at build time.
 const SPLIT_WIDE_BP = breakpoints.md // 280px rail + real content
 const SPLIT_BP = breakpoints.sm // 240px list + ≥ 384px detail
+const CONTENT_ASIDE_BP = breakpoints.md // reading column + 320px aside
 
 export const styles = css.create({
   base: {
@@ -50,6 +51,16 @@ export const styles = css.create({
       [`@container (min-width: ${SPLIT_WIDE_BP})`]: `minmax(${sizes.gridColMd}, 1fr) minmax(0, 3fr)`,
     },
   },
+  // A reading column beside an Aside (table of contents, related links): the
+  // aside keeps its asideW track, the content takes the rest and may shrink
+  // (minmax(0, …) so a wide code block scrolls instead of widening the
+  // grid); one column below md.
+  contentAside: {
+    gridTemplateColumns: {
+      default: 'minmax(0, 1fr)',
+      [`@container (min-width: ${CONTENT_ASIDE_BP})`]: `minmax(0, 1fr) ${sizes.asideW}`,
+    },
+  },
   // Weighted columns: `[1, 2]` → `1fr 2fr` (see columns.ts).
   template: (tracks: string) => ({
     gridTemplateColumns: tracks,

package/src/components/Heading/Heading.stories.tsx

@@ -0,0 +1,51 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {Heading} from './Heading'
+import {Stack} from '../Stack/Stack'
+import {TextLink} from '../TextLink/TextLink'
+import {onThemeSurface} from '../../docs/themedSurface'
+
+const meta: Meta = {
+  title: 'Components/Heading',
+  parameters: {a11y: {test: 'error'}},
+  decorators: [onThemeSurface],
+}
+
+export default meta
+type Story = StoryObj
+
+export const Levels: Story = {
+  render: () => (
+    <Stack gap="sm">
+      <Heading level={1}>Page title</Heading>
+      <Heading level={2}>Section</Heading>
+      <Heading level={3}>Subsection</Heading>
+      <Heading level={4} color="muted">
+        Group
+      </Heading>
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByRole('heading', {level: 1, name: 'Page title'})).toBeInTheDocument()
+    await expect(canvas.getByRole('heading', {level: 4, name: 'Group'})).toBeInTheDocument()
+  },
+}
+
+/** `id` makes a heading the target of an in-page link (a table of contents)
+ *  or of `aria-labelledby`. */
+export const WithId: Story = {
+  render: () => (
+    <Stack gap="sm">
+      <TextLink href="#install">Install</TextLink>
+      <Heading level={2} id="install">
+        Install
+      </Heading>
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    const heading = canvas.getByRole('heading', {level: 2, name: 'Install'})
+    await expect(heading).toHaveAttribute('id', 'install')
+    await expect(document.getElementById('install')).toBe(heading)
+    await expect(canvas.getByRole('link', {name: 'Install'})).toHaveAttribute('href', '#install')
+  },
+}

package/src/components/Heading/Heading.tsx

@@ -17,6 +17,8 @@ interface HeadingProps {
   variant?: HeadingVariant
   color?: 'default' | 'muted' | 'accent'
   align?: 'start' | 'center' | 'end'
+  /** The heading's id: an in-page link's target (`href="#id"`), an `aria-labelledby` reference. */
+  id?: string
   children: ReactNode
 }
 
@@ -35,14 +37,43 @@ const alignMap = {
   end: styles.alignEnd,
 } as const
 
-export function Heading({level, variant, color = 'default', align, children}: HeadingProps) {
+export function Heading({level, variant, color = 'default', align, id, children}: HeadingProps) {
   const resolvedVariant = variant ?? defaultVariantMap[level]
   const style = [typePresets[resolvedVariant], styles[color], align && alignMap[align]]
 
-  if (level === 1) return <html.h1 style={style}>{children}</html.h1>
-  if (level === 2) return <html.h2 style={style}>{children}</html.h2>
-  if (level === 3) return <html.h3 style={style}>{children}</html.h3>
-  if (level === 4) return <html.h4 style={style}>{children}</html.h4>
-  if (level === 5) return <html.h5 style={style}>{children}</html.h5>
-  return <html.h6 style={style}>{children}</html.h6>
+  if (level === 1)
+    return (
+      <html.h1 id={id} style={style}>
+        {children}
+      </html.h1>
+    )
+  if (level === 2)
+    return (
+      <html.h2 id={id} style={style}>
+        {children}
+      </html.h2>
+    )
+  if (level === 3)
+    return (
+      <html.h3 id={id} style={style}>
+        {children}
+      </html.h3>
+    )
+  if (level === 4)
+    return (
+      <html.h4 id={id} style={style}>
+        {children}
+      </html.h4>
+    )
+  if (level === 5)
+    return (
+      <html.h5 id={id} style={style}>
+        {children}
+      </html.h5>
+    )
+  return (
+    <html.h6 id={id} style={style}>
+      {children}
+    </html.h6>
+  )
 }

package/src/components/LinkButton/LinkButton.stories.tsx

@@ -1,11 +1,13 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn} from 'storybook/test'
+import {expect, fn, waitFor} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {LinkButton} from './LinkButton'
 import {clickLink} from '../../docs/clickLink'
 import {onThemeSurface} from '../../docs/themedSurface'
 import type {OnNavigate} from '../../shared/navigate'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
 
 const meta: Meta<typeof LinkButton> = {
   title: 'Components/LinkButton',
@@ -131,3 +133,41 @@ export const ClientNavigation: StoryObj<{onNavigate: OnNavigate}> = {
     await expect(onNavigate).toHaveBeenCalledTimes(1)
   },
 }
+
+/**
+ * A touch screen gets 44px links, default and small alike (5.6, as Button);
+ * a mouse keeps the compact control.
+ * 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>
+      <LinkButton href="#a">Open runbook</LinkButton>
+      <LinkButton href="#b" size="small">
+        Edit
+      </LinkButton>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const links = () => [
+      canvas.getByRole('link', {name: 'Open runbook'}),
+      canvas.getByRole('link', {name: 'Edit'}),
+    ]
+    await withFinePointer()
+    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),
+        )
+        await expect(link.getBoundingClientRect().width).toBeGreaterThanOrEqual(
+          SIZES_PX.touchTarget,
+        )
+      }
+    })
+  },
+}

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

@@ -22,12 +22,15 @@ export const styles = css.create({
     transitionProperty: 'background-color, border-color, color',
     transitionDuration: duration.fast,
     transitionTimingFunction: easing.standard,
+    // Matches Button: the 44px target under a coarse pointer (5.6).
+    minWidth: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
   },
   sizeDefault: {
     paddingTop: spacing.sm,
     paddingBottom: spacing.sm,
     paddingLeft: spacing.md,
     paddingRight: spacing.md,
+    minHeight: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
   },
   sizeSmall: {
     paddingTop: spacing.xs,
@@ -36,8 +39,9 @@ export const styles = css.create({
     paddingRight: spacing.sm,
     fontSize: typography.fontSizeXs,
 
-    // Matches Button: every small control is at least controlSm tall (5.6).
-    minHeight: sizes.controlSm,
+    // Matches Button: every small control is at least controlSm tall, and
+    // the touch target under a coarse pointer (5.6).
+    minHeight: {default: sizes.controlSm, '@media (pointer: coarse)': sizes.touchTarget},
   },
   primary: {
     backgroundColor: {

package/src/components/LiveRegion/LiveRegion.meta.ts

@@ -0,0 +1,29 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Tells assistive tech about a change that has no focus move: a polite (role="status") or assertive (role="alert") region. Always mounted — render it empty and change its content to announce; visuallyHidden keeps it off screen.',
+  whenToUse: [
+    'Confirming an action that leaves focus where it is ("Link copied", "Saved")',
+    'A result that arrives later ("12 results", "Answer ready")',
+    'An error the person must hear now — politeness="assertive"',
+  ],
+  whenNotToUse: [
+    'A message that also needs to be seen and dismissed — use Toast (it announces itself)',
+    'An inline field error — use Field.Error',
+  ],
+  relatedTo: [
+    {
+      component: 'VisuallyHidden',
+      kind: 'contrast',
+      relationship:
+        'VisuallyHidden hides static text; LiveRegion visuallyHidden announces changing text',
+    },
+    {
+      component: 'CodeBlock',
+      kind: 'composition',
+      relationship: 'CodeBlock announces "copied" through a LiveRegion',
+    },
+  ],
+  example: `<LiveRegion visuallyHidden>{copied ? 'Link copied' : ''}</LiveRegion>`,
+}