@duro-app/ui 5.1.0 → 5.3.0

package/src/components/ThemeProvider/Layers.stories.tsx

@@ -0,0 +1,379 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, waitFor, within} from 'storybook/test'
+import {Dialog} from '../Dialog/Dialog'
+import {Drawer} from '../Drawer/Drawer'
+import {DragDrop} from '../DragDrop/DragDrop'
+import {Popover} from '../Popover/Popover'
+import {Select} from '../Select/Select'
+import {ToastProvider, useToast} from '../Toast/ToastProvider'
+import {Button} from '../Button/Button'
+import {Stack} from '../Stack/Stack'
+import {Text} from '../Text/Text'
+
+/**
+ * What stacks above what. Dialog, Drawer, the popups and the toast region all
+ * portal into the ThemeProvider mount, so their `layers` values order them in
+ * one stacking context: a popup or a toast opened over a modal must be the
+ * topmost element where it is drawn.
+ */
+const meta: Meta = {
+  title: 'Theme/Layers',
+}
+
+export default meta
+type Story = StoryObj
+
+const page = () => within(document.body)
+
+/** True when the element drawn at `el`'s centre is `el` or inside it. */
+function onTop(el: Element): boolean {
+  const r = el.getBoundingClientRect()
+  const hit = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2)
+  return hit !== null && el.contains(hit)
+}
+
+function LinkPopover() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger>Insert link</Popover.Trigger>
+      <Popover.Popup label="Link">
+        <Stack gap="sm">
+          <Text>Paste a URL.</Text>
+          <Popover.Close>Apply</Popover.Close>
+        </Stack>
+      </Popover.Popup>
+    </Popover.Root>
+  )
+}
+
+export const PopoverInDialog: Story = {
+  render: () => (
+    <Dialog.Root>
+      <Dialog.Trigger>
+        <Button>Open editor</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Editor</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Body>
+          <LinkPopover />
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open editor'}))
+    await userEvent.click(await page().findByRole('button', {name: 'Insert link'}))
+    const popup = await page().findByRole('dialog', {name: 'Link'})
+    await waitFor(() => expect(onTop(popup)).toBe(true))
+  },
+}
+
+export const PopoverInDrawer: Story = {
+  render: () => (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button>Open details</Button>
+      </Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Header>
+          <Drawer.Title>Details</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Body>
+          <LinkPopover />
+        </Drawer.Body>
+      </Drawer.Portal>
+    </Drawer.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open details'}))
+    await userEvent.click(await page().findByRole('button', {name: 'Insert link'}))
+    const popup = await page().findByRole('dialog', {name: 'Link'})
+    await waitFor(() => expect(onTop(popup)).toBe(true))
+  },
+}
+
+function SaveButton() {
+  const {toast} = useToast()
+  return (
+    <Button onClick={() => toast({variant: 'success', message: 'Draft saved', duration: 0})}>
+      Save draft
+    </Button>
+  )
+}
+
+export const ToastOverDialog: Story = {
+  render: () => (
+    <ToastProvider>
+      <Dialog.Root>
+        <Dialog.Trigger>
+          <Button>Open draft</Button>
+        </Dialog.Trigger>
+        <Dialog.Portal size="sm">
+          <Dialog.Header>
+            <Dialog.Title>Draft</Dialog.Title>
+          </Dialog.Header>
+          <Dialog.Body>
+            <SaveButton />
+          </Dialog.Body>
+        </Dialog.Portal>
+      </Dialog.Root>
+    </ToastProvider>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open draft'}))
+    await userEvent.click(await page().findByRole('button', {name: 'Save draft'}))
+    const message = await page().findByText('Draft saved')
+    const toast = message.closest('[role="status"]') as Element
+    await waitFor(() => expect(onTop(toast)).toBe(true))
+  },
+}
+
+const ITEMS = [
+  {id: 'a', name: 'Alpha'},
+  {id: 'b', name: 'Beta'},
+]
+
+export const DragDropInDialog: Story = {
+  render: () => (
+    <Dialog.Root>
+      <Dialog.Trigger>
+        <Button>Open board</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Board</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Body>
+          <DragDrop.Root<{id: string; name: string}> onDrop={() => {}}>
+            <Stack gap="md">
+              <DragDrop.Zone id="from" label="From">
+                <Stack gap="sm">
+                  {ITEMS.map((item) => (
+                    <DragDrop.Item
+                      key={item.id}
+                      id={item.id}
+                      zone="from"
+                      label={item.name}
+                      data={item}
+                    >
+                      <Button variant="secondary">{item.name}</Button>
+                    </DragDrop.Item>
+                  ))}
+                </Stack>
+              </DragDrop.Zone>
+              <DragDrop.Zone id="to" label="To">
+                <Text>Drop here.</Text>
+              </DragDrop.Zone>
+            </Stack>
+          </DragDrop.Root>
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open board'}))
+    const alpha = await page().findByRole('button', {name: 'Alpha'})
+    const target = page().getByText('Drop here.')
+    const from = alpha.parentElement as Element
+    const a = from.getBoundingClientRect()
+    const b = target.getBoundingClientRect()
+    const init = (x: number, y: number) => ({
+      bubbles: true,
+      cancelable: true,
+      pointerId: 7,
+      pointerType: 'mouse',
+      isPrimary: true,
+      button: 0,
+      buttons: 1,
+      clientX: x,
+      clientY: y,
+    })
+    const start = {x: a.left + a.width / 2, y: a.top + a.height / 2}
+    const end = {x: b.left + b.width / 2, y: b.top + b.height / 2}
+    from.dispatchEvent(new PointerEvent('pointerdown', init(start.x, start.y)))
+    for (let i = 1; i <= 6; i++) {
+      const x = start.x + ((end.x - start.x) * i) / 6
+      const y = start.y + ((end.y - start.y) * i) / 6
+      document.dispatchEvent(new PointerEvent('pointermove', init(x, y)))
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    }
+    // Mid-drag: the ghost is the aria-hidden copy. It is click-through, so it
+    // takes hits for the duration of the check only.
+    const ghost = await waitFor(() => {
+      const found = [...document.querySelectorAll('[aria-hidden="true"]')].find(
+        (el) => el.textContent === 'Alpha' && getComputedStyle(el).position === 'fixed',
+      ) as HTMLElement | undefined
+      if (!found) throw new Error('no ghost yet')
+      return found
+    })
+    ghost.style.pointerEvents = 'auto'
+    const visible = onTop(ghost)
+    ghost.style.pointerEvents = ''
+    document.dispatchEvent(new PointerEvent('pointerup', {...init(end.x, end.y), buttons: 0}))
+    await expect(visible).toBe(true)
+  },
+}
+
+/** A Select opened inside a Popover: its listbox (mounted before the Popover
+ *  opens) and click-catcher stack above the Popover. */
+export const SelectInPopover: Story = {
+  render: () => (
+    <Popover.Root>
+      <Popover.Trigger>Style</Popover.Trigger>
+      <Popover.Popup label="Style">
+        <Select.Root defaultValue="primary">
+          <Select.Trigger aria-label="Variant">
+            <Select.Value />
+            <Select.Icon />
+          </Select.Trigger>
+          <Select.Popup>
+            <Select.Item value="primary">Primary</Select.Item>
+            <Select.Item value="secondary">Secondary</Select.Item>
+            <Select.Item value="ghost">Ghost</Select.Item>
+          </Select.Popup>
+        </Select.Root>
+      </Popover.Popup>
+    </Popover.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Style'}))
+    await userEvent.click(await page().findByRole('combobox', {name: 'Variant'}))
+    for (const name of ['Primary', 'Secondary', 'Ghost']) {
+      const option = await page().findByRole('option', {name})
+      await waitFor(() => expect(onTop(option)).toBe(true))
+    }
+  },
+}
+
+/** A Dialog opened from a button inside an open Popover: the Dialog is on
+ *  top, and the Popover does not stay drawn over it. */
+export const DialogFromPopover: Story = {
+  render: () => (
+    <Popover.Root>
+      <Popover.Trigger>Share</Popover.Trigger>
+      <Popover.Popup label="Share">
+        <Dialog.Root>
+          <Dialog.Trigger>
+            <Button>Invite people</Button>
+          </Dialog.Trigger>
+          <Dialog.Portal size="sm">
+            <Dialog.Header>
+              <Dialog.Title>Invite</Dialog.Title>
+            </Dialog.Header>
+            <Dialog.Body>
+              <Text>Send an invitation.</Text>
+            </Dialog.Body>
+          </Dialog.Portal>
+        </Dialog.Root>
+      </Popover.Popup>
+    </Popover.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Share'}))
+    await userEvent.click(await page().findByRole('button', {name: 'Invite people'}))
+    const dialog = await page().findByRole('dialog', {name: 'Invite'})
+    await waitFor(() => expect(onTop(dialog)).toBe(true))
+    // The Popover is either gone or under the modal's backdrop.
+    const popover = page().queryByRole('dialog', {name: 'Share'})
+    if (popover) await expect(onTop(popover)).toBe(false)
+  },
+}
+
+/** DragDrop inside a Dialog whose body is scrolled: the ghost stays under the
+ *  pointer and on top. */
+export const DragDropInScrolledDialog: Story = {
+  render: () => (
+    <Dialog.Root>
+      <Dialog.Trigger>
+        <Button>Open long board</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Long board</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Body>
+          <Stack gap="md">
+            {Array.from({length: 30}, (_, i) => (
+              <Text key={i}>{`Line ${i + 1}`}</Text>
+            ))}
+            <DragDrop.Root<{id: string; name: string}> onDrop={() => {}}>
+              <Stack gap="md">
+                <DragDrop.Zone id="from" label="From">
+                  <Stack gap="sm">
+                    {ITEMS.map((item) => (
+                      <DragDrop.Item
+                        key={item.id}
+                        id={item.id}
+                        zone="from"
+                        label={item.name}
+                        data={item}
+                      >
+                        <Button variant="secondary">{item.name}</Button>
+                      </DragDrop.Item>
+                    ))}
+                  </Stack>
+                </DragDrop.Zone>
+                <DragDrop.Zone id="to" label="To">
+                  <Text>Drop here.</Text>
+                </DragDrop.Zone>
+              </Stack>
+            </DragDrop.Root>
+          </Stack>
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open long board'}))
+    const alpha = await page().findByRole('button', {name: 'Alpha'})
+    alpha.scrollIntoView({block: 'center'})
+    let scrolled = 0
+    for (let el = alpha.parentElement; el; el = el.parentElement) scrolled += el.scrollTop
+    await expect(scrolled).toBeGreaterThan(0)
+    const from = alpha.parentElement as Element
+    const target = page().getByText('Drop here.')
+    const a = from.getBoundingClientRect()
+    const b = target.getBoundingClientRect()
+    const init = (x: number, y: number) => ({
+      bubbles: true,
+      cancelable: true,
+      pointerId: 7,
+      pointerType: 'mouse',
+      isPrimary: true,
+      button: 0,
+      buttons: 1,
+      clientX: x,
+      clientY: y,
+    })
+    const start = {x: a.left + a.width / 2, y: a.top + a.height / 2}
+    const end = {x: b.left + b.width / 2, y: b.top + b.height / 2}
+    from.dispatchEvent(new PointerEvent('pointerdown', init(start.x, start.y)))
+    for (let i = 1; i <= 6; i++) {
+      const x = start.x + ((end.x - start.x) * i) / 6
+      const y = start.y + ((end.y - start.y) * i) / 6
+      document.dispatchEvent(new PointerEvent('pointermove', init(x, y)))
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    }
+    const ghost = await waitFor(() => {
+      const found = [...document.querySelectorAll('[aria-hidden="true"]')].find(
+        (el) => el.textContent === 'Alpha' && getComputedStyle(el).position === 'fixed',
+      ) as HTMLElement | undefined
+      if (!found) throw new Error('no ghost yet')
+      return found
+    })
+    const g = ghost.getBoundingClientRect()
+    ghost.style.pointerEvents = 'auto'
+    const visible = onTop(ghost)
+    ghost.style.pointerEvents = ''
+    document.dispatchEvent(new PointerEvent('pointerup', {...init(end.x, end.y), buttons: 0}))
+    await expect(visible).toBe(true)
+    // Under the pointer: the ghost keeps the grab offset, so the pointer is
+    // inside it, not displaced by the scroll.
+    await expect(end.x).toBeGreaterThanOrEqual(g.left)
+    await expect(end.x).toBeLessThanOrEqual(g.right)
+    await expect(end.y).toBeGreaterThanOrEqual(g.top)
+    await expect(end.y).toBeLessThanOrEqual(g.bottom)
+  },
+}

package/src/components/ThemeProvider/ThemeProvider.stories.tsx

@@ -163,3 +163,53 @@ export const AllThemes: Story = {
     await expect(canvas.getByText('high-contrast')).toBeInTheDocument()
   },
 }
+
+const contrastStyles = css.create({
+  surface: {
+    padding: spacing.md,
+    borderRadius: radii.md,
+    backgroundColor: colors.contrastSurface,
+    color: colors.onContrastSurface,
+  },
+})
+
+/** Parse a computed `rgb(r, g, b)` / `rgba(r, g, b, a)` colour. */
+function rgbOf(value: string): [number, number, number] {
+  const parts = value.match(/\d+(\.\d+)?/g)?.map(Number) ?? []
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0]
+}
+
+/** WCAG 2.x relative luminance contrast ratio. */
+function contrastRatio(a: string, b: string): number {
+  const lum = (rgb: [number, number, number]) => {
+    const [r, g, bl] = rgb.map((c) => {
+      const s = c / 255
+      return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+    }) as [number, number, number]
+    return 0.2126 * r + 0.7152 * g + 0.0722 * bl
+  }
+  const [hi, lo] = [lum(rgbOf(a)), lum(rgbOf(b))].sort((x, y) => y - x) as [number, number]
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+// contrastSurface takes the opposite tone of the theme; its text must still
+// read at 4.5:1 or better in each one.
+export const ContrastSurfaceInEveryTheme: Story = {
+  render: () => (
+    <html.div style={sideBySideStyles.wrapper}>
+      {(['dark', 'light', 'high-contrast'] as const).map((theme) => (
+        <ThemeProvider key={theme} theme={theme}>
+          <html.div style={contrastStyles.surface}>{`Contrast surface (${theme})`}</html.div>
+        </ThemeProvider>
+      ))}
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    for (const theme of ['dark', 'light', 'high-contrast']) {
+      const el = canvas.getByText(`Contrast surface (${theme})`)
+      const style = getComputedStyle(el)
+      const ratio = contrastRatio(style.color, style.backgroundColor)
+      await expect(ratio).toBeGreaterThanOrEqual(4.5)
+    }
+  },
+}

package/src/components/ThemeProvider/ThemeProvider.tsx

@@ -3,6 +3,7 @@ import {css, html} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {lightTheme, lightShadows} from '@duro-app/tokens/themes/light.css'
 import {highContrastTheme, highContrastShadows} from '@duro-app/tokens/themes/high-contrast.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
 
 export type ThemeName = 'dark' | 'light' | 'high-contrast'
 
@@ -32,8 +33,9 @@ const styles = css.create({
     right: 0,
     bottom: 0,
     pointerEvents: 'none',
-    // Above Dialog (1001) so popups inside dialogs render on top.
-    zIndex: 1100,
+    // The stacking context the layers scale orders: Dialog, Drawer, the
+    // popups and toasts all portal in here.
+    zIndex: layers.portal,
   },
 })
 

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

@@ -6,6 +6,7 @@ import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
 import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
 
 const enter = css.keyframes({
   from: {opacity: 0, transform: 'translateY(10px)'},
@@ -28,6 +29,8 @@ export const styles = css.create({
     paddingLeft: spacing.md,
     paddingRight: spacing.md,
     pointerEvents: 'none',
+    // Above modals and popups: a toast fired while a Dialog is open shows.
+    zIndex: layers.toast,
   },
   toast: {
     pointerEvents: 'auto',

package/src/components/Toggle/Toggle.tsx

@@ -2,6 +2,8 @@ import {type ReactNode, useCallback, useLayoutEffect, useRef} from 'react'
 import {html} from 'react-strict-dom'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {useToggleGroup} from '../ToggleGroup/ToggleGroupContext'
+import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
+import {mergeRefs} from '../../shared/mergeRefs'
 import {styles} from './styles.css'
 
 export type ToggleSize = 'default' | 'small'
@@ -66,6 +68,9 @@ export function Toggle({
   )
 
   const pressed = groupPressed ?? standalonePressed
+  const grouped = useGroupedControl<HTMLButtonElement>({disabled})
+  // In a Toolbar the toolbar owns the roving tabindex, not a wrapping group.
+  const roving = wrap && value !== undefined && !grouped.onFocus
 
   const handleClick = useCallback(() => {
     if (disabled) return
@@ -78,10 +83,18 @@ export function Toggle({
 
   return (
     <html.button
-      ref={ref}
+      ref={mergeRefs(ref, grouped.ref)}
       type="button"
-      tabIndex={wrap && value !== undefined ? (group?.tabStopValue === value ? 0 : -1) : undefined}
-      onFocus={wrap && value !== undefined ? () => group?.onItemFocus(value) : undefined}
+      tabIndex={
+        grouped.onFocus
+          ? grouped.tabIndex
+          : roving
+            ? group?.tabStopValue === value
+              ? 0
+              : -1
+            : undefined
+      }
+      onFocus={grouped.onFocus ?? (roving ? () => group?.onItemFocus(value) : undefined)}
       aria-pressed={pressed}
       aria-label={ariaLabel}
       disabled={disabled}
@@ -92,8 +105,11 @@ export function Toggle({
         sizeMap[size],
         pressed ? styles.pressed : styles.unpressed,
         wrap && wrappedSizeMap[size],
-        isGrouped && !wrap && styles.grouped,
+        // In an attached ButtonGroup the group joins the borders instead.
+        isGrouped && !wrap && !grouped.attached && styles.grouped,
         disabled && styles.disabled,
+        grouped.style,
+        grouped.attached && pressed && styles.attachedPressed,
       ]}
     >
       {children}

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

@@ -75,6 +75,12 @@ export const styles = css.create({
     // Override any borderColor set by pressed state — dividers always use border token
     borderColor: colors.border,
   },
+  // Pressed, in an attached group: the accent edge is drawn inset, inside the
+  // border a neighbour's negative margin overlaps, so it shows on all four
+  // sides without a z-index (which stays for focus).
+  attachedPressed: {
+    boxShadow: `inset 0 0 0 ${borders.hairline} ${colors.accent}`,
+  },
   disabled: {
     opacity: 0.5,
     cursor: 'not-allowed',

package/src/components/ToggleGroup/ToggleGroup.tsx

@@ -6,6 +6,8 @@ import {ToggleGroupContext, type Orientation} from './ToggleGroupContext'
 import {useFieldGroupLabelling} from '../Field/FieldContext'
 import {ScrollArea} from '../ScrollArea/ScrollArea'
 import {useRovingFocus} from './useRovingFocus'
+import {useToolbar} from '../Toolbar/ToolbarContext'
+import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext'
 import {styles} from './styles.css'
 
 interface ToggleGroupProps {
@@ -72,7 +74,12 @@ export function ToggleGroup({
   )
 
   const rootRef = useRef<HTMLDivElement>(null)
-  const roving = useRovingFocus({enabled: wrap, pressed: value, rootRef})
+  // Inside a Toolbar, the toolbar's roving focus covers these toggles: one
+  // handler, never two. Inside an attached ButtonGroup, the group draws the
+  // borders and corners.
+  const inToolbar = useToolbar() !== null
+  const inAttachedGroup = useButtonGroup() !== null
+  const roving = useRovingFocus({enabled: wrap && !inToolbar, pressed: value, rootRef})
   const scrolls = wrap && maxRows !== undefined
   const pressedValue = value[0]
 
@@ -107,10 +114,15 @@ export function ToggleGroup({
   const group = (
     <html.div
       ref={rootRef}
-      role="toolbar"
-      aria-orientation={orientation}
+      role={inToolbar ? 'group' : 'toolbar'}
+      aria-orientation={inToolbar ? undefined : orientation}
       {...a11y}
-      style={[styles.root, orientation === 'vertical' && styles.vertical, wrap && styles.wrap]}
+      style={[
+        styles.root,
+        orientation === 'vertical' && styles.vertical,
+        wrap && styles.wrap,
+        inAttachedGroup && styles.inAttachedGroup,
+      ]}
     >
       {children}
     </html.div>

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

@@ -44,4 +44,11 @@ export const styles = css.create({
   vertical: {
     flexDirection: 'column',
   },
+  // In an attached ButtonGroup: no frame of its own; its toggles join the
+  // group's border like any other control.
+  inAttachedGroup: {
+    borderWidth: 0,
+    borderRadius: 0,
+    overflow: 'visible',
+  },
 })

package/src/components/Toolbar/ControlContextBoundary.tsx

@@ -0,0 +1,16 @@
+import type {ReactNode} from 'react'
+import {ButtonGroupContext} from '../ButtonGroup/ButtonGroupContext'
+import {ToolbarContext} from './ToolbarContext'
+
+/**
+ * Popups and modals stop the ButtonGroup and Toolbar contexts. A portal keeps
+ * its React parent, so without this the buttons in a Popover opened from a
+ * toolbar would come out squared and with tabindex=-1.
+ */
+export function ControlContextBoundary({children}: {children: ReactNode}) {
+  return (
+    <ButtonGroupContext.Provider value={null}>
+      <ToolbarContext.Provider value={null}>{children}</ToolbarContext.Provider>
+    </ButtonGroupContext.Provider>
+  )
+}

package/src/components/Toolbar/Toolbar.meta.ts

@@ -0,0 +1,48 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'A row of controls with one tab stop (the WAI-ARIA toolbar pattern): Tab enters at the last focused control, Left/Right move across every control inside — through attached ButtonGroups too — and Home/End jump to the ends. A Select or Menu trigger keeps its own keys, and a control whose popup is open keeps Left/Right.',
+  whenToUse: [
+    'An editor toolbar: text style, format toggles, insert menus',
+    'A dense set of related actions that should cost one Tab, not one per control',
+  ],
+  whenNotToUse: [
+    'A dialog footer or a form action row — use ButtonGroup (every button its own tab stop)',
+    'A floating bulk-selection bar — use ActionBar',
+    'A vertical toolbar holding a Select: a closed Select takes ArrowDown/ArrowUp to open, so use the horizontal orientation (a Menu is fine: its closed trigger handles no arrow key, Enter or Space opens it)',
+  ],
+  anatomy: {
+    required: ['Toolbar', 'aria-label'],
+    optional: ['ButtonGroup attached', 'Toggle', 'Button', 'Select', 'Menu', 'Popover'],
+  },
+  relatedTo: [
+    {
+      component: 'ButtonGroup',
+      kind: 'composition',
+      relationship:
+        'Place attached ButtonGroups inside a Toolbar: the group joins the controls visually, the toolbar gives them one tab stop and arrow keys',
+    },
+    {
+      component: 'ToggleGroup',
+      kind: 'composition',
+      relationship:
+        'A ToggleGroup inside a Toolbar hands its arrow keys to the toolbar (one roving handler)',
+    },
+    {
+      component: 'ActionBar',
+      kind: 'contrast',
+      relationship: 'ActionBar floats over a selection; Toolbar sits in the layout',
+    },
+  ],
+  example: `<Toolbar aria-label="Formatting">
+  <ButtonGroup attached aria-label="Text style">
+    <Toggle aria-label="Bold" pressed={bold} onPressedChange={setBold}>B</Toggle>
+    <Toggle aria-label="Italic" pressed={italic} onPressedChange={setItalic}>I</Toggle>
+  </ButtonGroup>
+  <Menu.Root>
+    <Menu.Trigger>Insert</Menu.Trigger>
+    <Menu.Popup>…</Menu.Popup>
+  </Menu.Root>
+</Toolbar>`,
+}