@duro-app/ui 5.2.0 → 5.3.0

package/src/components/Toolbar/Toolbar.stories.tsx

@@ -0,0 +1,468 @@
+import {useEffect, useRef, useState} from 'react'
+import {hydrateRoot} from 'react-dom/client'
+import {renderToString} from 'react-dom/server'
+import type {Meta, StoryObj} from '@storybook/react'
+import {html} from 'react-strict-dom'
+import {expect, userEvent, waitFor, within} from 'storybook/test'
+import {RADII_PX} from '@duro-app/tokens/keys'
+import {Toolbar} from './Toolbar'
+import {Button} from '../Button/Button'
+import {ButtonGroup} from '../ButtonGroup/ButtonGroup'
+import {Field} from '../Field/Field'
+import {Input} from '../Input/Input'
+import {Menu} from '../Menu/Menu'
+import {Popover} from '../Popover/Popover'
+import {Select} from '../Select/Select'
+import {Stack} from '../Stack/Stack'
+import {Toggle} from '../Toggle/Toggle'
+
+const meta: Meta<typeof Toolbar> = {
+  title: 'Components/Toolbar',
+  component: Toolbar,
+}
+
+export default meta
+type Story = StoryObj<typeof Toolbar>
+
+const page = () => within(document.body)
+const R = `${RADII_PX.sm}px`
+
+function TextStyle() {
+  return (
+    <ButtonGroup attached aria-label="Text style">
+      <Select.Root defaultValue="normal">
+        <Select.Trigger aria-label="Block type">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="normal">Normal</Select.Item>
+          <Select.Item value="h1">Heading 1</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+      <Select.Root defaultValue="arial">
+        <Select.Trigger aria-label="Font">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="arial">Arial</Select.Item>
+          <Select.Item value="georgia">Georgia</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+      <Select.Root defaultValue="15">
+        <Select.Trigger aria-label="Font size">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="13">13px</Select.Item>
+          <Select.Item value="15">15px</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+    </ButtonGroup>
+  )
+}
+
+function LinkPopover() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger aria-label="Link">↗</Popover.Trigger>
+      <Popover.Popup label="Link">
+        <Stack gap="sm">
+          <Field.Root>
+            <Field.Label>URL</Field.Label>
+            <Input defaultValue="https://duro.app" />
+          </Field.Root>
+          <Button size="small">Apply</Button>
+        </Stack>
+      </Popover.Popup>
+    </Popover.Root>
+  )
+}
+
+function Format() {
+  const [pressed, setPressed] = useState<Record<string, boolean>>({})
+  const toggle = (key: string) => (next: boolean) => setPressed((p) => ({...p, [key]: next}))
+  return (
+    <ButtonGroup attached aria-label="Format">
+      <Toggle aria-label="Bold" pressed={!!pressed.b} onPressedChange={toggle('b')}>
+        B
+      </Toggle>
+      <Toggle aria-label="Italic" pressed={!!pressed.i} onPressedChange={toggle('i')}>
+        I
+      </Toggle>
+      <Toggle aria-label="Underline" pressed={!!pressed.u} onPressedChange={toggle('u')}>
+        U
+      </Toggle>
+      <Toggle aria-label="Code" pressed={!!pressed.code} onPressedChange={toggle('code')}>
+        {'<>'}
+      </Toggle>
+      <LinkPopover />
+      <Button variant="secondary" aria-label="Clear formatting">
+        T
+      </Button>
+      <Popover.Root>
+        <Popover.Trigger aria-label="Highlight">H</Popover.Trigger>
+        <Popover.Popup label="Highlight">
+          <Button size="small">Purple</Button>
+        </Popover.Popup>
+      </Popover.Root>
+    </ButtonGroup>
+  )
+}
+
+function InsertMenu() {
+  return (
+    <Menu.Root>
+      <Menu.Trigger>Insert</Menu.Trigger>
+      <Menu.Popup>
+        <Menu.Item>Table</Menu.Item>
+        <Menu.Item>Image</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  )
+}
+
+function Editor() {
+  return (
+    <Toolbar aria-label="Formatting">
+      <TextStyle />
+      <Format />
+      <InsertMenu />
+    </Toolbar>
+  )
+}
+
+/** Every focusable control of the toolbar, in order: 3 + 7 + 1. */
+const CONTROLS = [
+  'Block type',
+  'Font',
+  'Font size',
+  'Bold',
+  'Italic',
+  'Underline',
+  'Code',
+  'Link',
+  'Clear formatting',
+  'Highlight',
+  'Insert',
+]
+
+function control(name: string) {
+  return page().getByRole(
+    ['Block type', 'Font', 'Font size'].includes(name) ? 'combobox' : 'button',
+    {name},
+  )
+}
+
+/** [Normal | Arial | 15px] and [B | I | U | <> | link | T | highlight], then Insert. */
+export const Default: Story = {
+  render: () => <Editor />,
+  play: async ({canvas}) => {
+    await expect(canvas.getByRole('toolbar', {name: 'Formatting'})).toBeInTheDocument()
+    // One tab stop.
+    await waitFor(() =>
+      expect(CONTROLS.map((name) => control(name).tabIndex)).toEqual(
+        CONTROLS.map((_, i) => (i === 0 ? 0 : -1)),
+      ),
+    )
+  },
+}
+
+/** Tab enters once; ArrowRight crosses the groups; End and Home reach the ends. */
+export const ArrowKeys: Story = {
+  render: () => (
+    <Stack gap="sm">
+      <Button variant="secondary">Before</Button>
+      <Editor />
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    canvas.getByRole('button', {name: 'Before'}).focus()
+    await userEvent.tab()
+    await expect(control(CONTROLS[0])).toHaveFocus()
+    for (let i = 1; i <= 8; i++) {
+      await userEvent.keyboard('{ArrowRight}')
+      await expect(control(CONTROLS[i])).toHaveFocus()
+    }
+    await userEvent.keyboard('{End}')
+    await expect(control(CONTROLS[CONTROLS.length - 1])).toHaveFocus()
+    await userEvent.keyboard('{Home}')
+    await expect(control(CONTROLS[0])).toHaveFocus()
+    await userEvent.keyboard('{ArrowLeft}')
+    await expect(control(CONTROLS[0])).toHaveFocus()
+    // Tab leaves the toolbar in one press, and Shift+Tab comes back to the
+    // control last focused.
+    await userEvent.keyboard('{End}')
+    await userEvent.tab()
+    await expect(document.activeElement?.closest('[role="toolbar"]')).toBeNull()
+    await userEvent.tab({shift: true})
+    await expect(control('Insert')).toHaveFocus()
+  },
+}
+
+/** A closed Select takes ArrowDown: it opens, and Escape closes it on its trigger. */
+export const SelectArrowDown: Story = {
+  render: () => <Editor />,
+  play: async () => {
+    const font = control('Font')
+    font.focus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(font).toHaveAttribute('aria-expanded', 'true')
+    await expect(font).toHaveFocus()
+    await expect(page().getByRole('listbox')).toBeVisible()
+    await userEvent.keyboard('{Escape}')
+    await expect(font).toHaveAttribute('aria-expanded', 'false')
+    await expect(font).toHaveFocus()
+  },
+}
+
+/** ArrowRight while a Select is open: focus stays on its trigger, the listbox stays open. */
+export const SelectOpenKeepsArrows: Story = {
+  render: () => <Editor />,
+  play: async () => {
+    const font = control('Font')
+    font.focus()
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(font).toHaveAttribute('aria-expanded', 'true')
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(font).toHaveFocus()
+    await expect(font).toHaveAttribute('aria-expanded', 'true')
+    await expect(page().getByRole('listbox')).toBeVisible()
+    await userEvent.keyboard('{Escape}')
+  },
+}
+
+/** The link Popover's contents are outside the group and the toolbar: its
+ *  Apply button is one Tab away and has all four corners round. */
+export const PopoverInsideToolbar: Story = {
+  render: () => <Editor />,
+  play: async ({userEvent}) => {
+    await userEvent.click(control('Link'))
+    const url = await page().findByRole('textbox', {name: 'URL'})
+    await waitFor(() => expect(url).toHaveFocus())
+    await userEvent.tab()
+    const apply = page().getByRole('button', {name: 'Apply'})
+    await expect(apply).toHaveFocus()
+    const cs = getComputedStyle(apply)
+    await expect([
+      cs.borderTopLeftRadius,
+      cs.borderTopRightRadius,
+      cs.borderBottomRightRadius,
+      cs.borderBottomLeftRadius,
+    ]).toEqual([R, R, R, R])
+    await expect(apply).not.toHaveAttribute('tabindex', '-1')
+  },
+}
+
+/** ArrowLeft typed in the Popover's input moves the caret, not toolbar focus. */
+export const PopoverInputKeepsArrows: Story = {
+  render: () => <Editor />,
+  play: async ({userEvent}) => {
+    await userEvent.click(control('Link'))
+    const url = (await page().findByRole('textbox', {name: 'URL'})) as HTMLInputElement
+    await waitFor(() => expect(url).toHaveFocus())
+    url.setSelectionRange(url.value.length, url.value.length)
+    const end = url.selectionStart ?? 0
+    await userEvent.keyboard('{ArrowLeft}{ArrowLeft}')
+    await expect(url).toHaveFocus()
+    await expect(url.selectionStart).toBe(end - 2)
+  },
+}
+
+/** A control that handles ArrowRight itself (preventDefault) keeps it. */
+function GreedyButton() {
+  const ref = useRef<HTMLButtonElement>(null)
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'ArrowRight') e.preventDefault()
+    }
+    el.addEventListener('keydown', onKeyDown)
+    return () => el.removeEventListener('keydown', onKeyDown)
+  }, [])
+  return (
+    <Button ref={ref} variant="secondary">
+      Stepper
+    </Button>
+  )
+}
+
+export const ControlKeepsHandledKeys: Story = {
+  render: () => (
+    <Toolbar aria-label="Playback">
+      <GreedyButton />
+      <Button variant="secondary">Next</Button>
+    </Toolbar>
+  ),
+  play: async ({canvas}) => {
+    const stepper = canvas.getByRole('button', {name: 'Stepper'})
+    stepper.focus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(stepper).toHaveFocus()
+  },
+}
+
+/** Vertical: Up/Down move. */
+export const Vertical: Story = {
+  render: () => (
+    <Toolbar aria-label="Tools" orientation="vertical">
+      <ButtonGroup attached orientation="vertical" aria-label="Draw">
+        <Button variant="secondary">Pen</Button>
+        <Button variant="secondary">Eraser</Button>
+      </ButtonGroup>
+      <Button variant="secondary">Undo</Button>
+    </Toolbar>
+  ),
+  play: async ({canvas}) => {
+    const pen = canvas.getByRole('button', {name: 'Pen'})
+    pen.focus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(canvas.getByRole('button', {name: 'Eraser'})).toHaveFocus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(canvas.getByRole('button', {name: 'Undo'})).toHaveFocus()
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(canvas.getByRole('button', {name: 'Eraser'})).toHaveFocus()
+  },
+}
+
+/**
+ * Server render: no control has registered yet, so every control in an
+ * attached group renders `middle` (square, joined) and every control is in
+ * the tab order. Hydration matches that markup exactly, then the outer
+ * corners round and the toolbar takes one tab stop.
+ */
+function SsrToolbar() {
+  return (
+    <Toolbar aria-label="Server">
+      <ButtonGroup attached aria-label="Actions">
+        <Button variant="secondary">One</Button>
+        <Button variant="secondary">Two</Button>
+        <Button variant="secondary">Three</Button>
+      </ButtonGroup>
+    </Toolbar>
+  )
+}
+
+export const ServerRender: Story = {
+  render: () => <html.div data-ssr-host="" />,
+  play: async ({canvasElement}) => {
+    const host = canvasElement.querySelector('[data-ssr-host]') as HTMLElement
+    host.innerHTML = renderToString(<SsrToolbar />)
+    const buttons = () => [...host.querySelectorAll('button')]
+    const radii = (el: Element) => {
+      const cs = getComputedStyle(el)
+      return [
+        cs.borderTopLeftRadius,
+        cs.borderTopRightRadius,
+        cs.borderBottomRightRadius,
+        cs.borderBottomLeftRadius,
+      ]
+    }
+    // Server markup: all middle, no roving tabindex yet.
+    for (const b of buttons()) {
+      await expect(radii(b)).toEqual(['0px', '0px', '0px', '0px'])
+      await expect(b.hasAttribute('tabindex')).toBe(false)
+    }
+    const errors: unknown[] = []
+    const consoleError = console.error
+    console.error = (...args: unknown[]) => {
+      errors.push(args)
+      consoleError(...args)
+    }
+    const root = hydrateRoot(host, <SsrToolbar />, {
+      onRecoverableError: (error) => errors.push(error),
+    })
+    try {
+      await waitFor(() => expect(radii(buttons()[0])).toEqual([R, '0px', '0px', R]))
+      await expect(radii(buttons()[1])).toEqual(['0px', '0px', '0px', '0px'])
+      await expect(radii(buttons()[2])).toEqual(['0px', R, R, '0px'])
+      await expect(buttons().map((b) => b.tabIndex)).toEqual([0, -1, -1])
+      await expect(errors).toEqual([])
+    } finally {
+      console.error = consoleError
+      root.unmount()
+    }
+  },
+}
+
+/** Keyed controls reordered without remounting: corners and arrow order
+ *  follow the new DOM order. */
+function Reorderable() {
+  const [names, setNames] = useState(['One', 'Two', 'Three'])
+  return (
+    <Stack gap="md">
+      <Button variant="secondary" onClick={() => setNames((n) => [...n].reverse())}>
+        Reverse
+      </Button>
+      <Toolbar aria-label="Ordered">
+        <ButtonGroup attached aria-label="Items">
+          {names.map((name) => (
+            <Button key={name} variant="secondary">
+              {name}
+            </Button>
+          ))}
+        </ButtonGroup>
+      </Toolbar>
+    </Stack>
+  )
+}
+
+export const ReorderKeyedChildren: Story = {
+  render: () => <Reorderable />,
+  play: async ({canvas}) => {
+    const one = canvas.getByRole('button', {name: 'One'})
+    await userEvent.click(canvas.getByRole('button', {name: 'Reverse'}))
+    // Same element, moved: no remount.
+    await expect(canvas.getByRole('button', {name: 'One'})).toBe(one)
+    const radii = (el: Element) => {
+      const cs = getComputedStyle(el)
+      return [
+        cs.borderTopLeftRadius,
+        cs.borderTopRightRadius,
+        cs.borderBottomRightRadius,
+        cs.borderBottomLeftRadius,
+      ]
+    }
+    const three = canvas.getByRole('button', {name: 'Three'})
+    await waitFor(() => expect(radii(three)).toEqual([R, '0px', '0px', R]))
+    await expect(radii(one)).toEqual(['0px', R, R, '0px'])
+    await expect(three.tabIndex).toBe(0)
+    three.focus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(canvas.getByRole('button', {name: 'Two'})).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(one).toHaveFocus()
+  },
+}
+
+/** Vertical, with a Menu: a closed Menu.Trigger handles no arrow key, so
+ *  ArrowDown moves on (Enter or Space opens it). Unlike a Select, a Menu can
+ *  sit in a vertical toolbar. */
+export const VerticalWithMenu: Story = {
+  render: () => (
+    <Toolbar aria-label="Tools" orientation="vertical">
+      <Menu.Root>
+        <Menu.Trigger>Insert</Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item>Table</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <Button variant="secondary">Undo</Button>
+    </Toolbar>
+  ),
+  play: async ({canvas}) => {
+    const insert = canvas.getByRole('button', {name: 'Insert'})
+    insert.focus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(insert).toHaveAttribute('aria-expanded', 'false')
+    await expect(canvas.getByRole('button', {name: 'Undo'})).toHaveFocus()
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(insert).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(insert).toHaveAttribute('aria-expanded', 'true')
+    await userEvent.keyboard('{Escape}')
+  },
+}

package/src/components/Toolbar/Toolbar.tsx

@@ -0,0 +1,113 @@
+import {type ReactNode, useCallback, useEffect, useMemo, useRef, useState} from 'react'
+import {html} from 'react-strict-dom'
+import type {Orientation} from '../../shared/types'
+import {useOrderedRegistry} from '../../shared/useOrderedRegistry'
+import {ToolbarContext, type ToolbarContextValue} from './ToolbarContext'
+import {styles} from './styles.css'
+
+export interface ToolbarProps {
+  /** Names the toolbar ("Formatting"). Required: a toolbar is a landmark-like widget. */
+  'aria-label': string
+  /**
+   * Arrow keys follow the orientation: Left/Right (default) or Up/Down. A
+   * vertical toolbar cannot hold a Select, whose closed trigger opens on
+   * ArrowDown/ArrowUp. A Menu can: its closed trigger handles no arrow key,
+   * so Up/Down move past it and Enter or Space opens it.
+   */
+  orientation?: Orientation
+  children: ReactNode
+}
+
+/**
+ * A row of controls with one tab stop (the WAI-ARIA toolbar pattern). Every
+ * Button, Toggle and Select/Menu/Popover trigger inside it, through any
+ * ButtonGroup, joins one roving tabindex: Tab enters at the last focused
+ * control, Left/Right (Up/Down when vertical) move, Home/End jump to the ends.
+ */
+export function Toolbar({
+  'aria-label': ariaLabel,
+  orientation = 'horizontal',
+  children,
+}: ToolbarProps) {
+  const rootRef = useRef<HTMLDivElement>(null)
+  const {elements, order, register} = useOrderedRegistry()
+  const [focusedId, setFocusedId] = useState<string | null>(null)
+
+  const enabled = order.filter((entry) => !entry.disabled)
+  const tabStop =
+    focusedId !== null && enabled.some((entry) => entry.id === focusedId)
+      ? focusedId
+      : (enabled[0]?.id ?? null)
+
+  const tabIndexOf = useCallback<ToolbarContextValue['tabIndexOf']>(
+    (id) => {
+      if (!order.some((entry) => entry.id === id)) return undefined
+      return id === tabStop ? 0 : -1
+    },
+    [order, tabStop],
+  )
+
+  // One listener on the document, in the bubble phase, so it runs after the
+  // controls' own handlers (React dispatches from the app root, below the
+  // document). It acts only on a key aimed at one of this toolbar's own
+  // registered controls, so keys typed in a portalled popup (a Popover's
+  // input) never move toolbar focus. A control whose popup is open
+  // (aria-expanded="true") keeps its keys, and so does one that already
+  // handled the key (defaultPrevented).
+  useEffect(() => {
+    const doc = rootRef.current?.ownerDocument
+    if (!doc) return
+    const [prev, next] =
+      orientation === 'vertical' ? ['ArrowUp', 'ArrowDown'] : ['ArrowLeft', 'ArrowRight']
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return
+      const els = order
+        .filter((entry) => !entry.disabled)
+        .map((entry) => elements.current.get(entry.id)?.el)
+        .filter((el): el is HTMLElement => el !== undefined)
+      const target = e.target as HTMLElement
+      const i = els.indexOf(target)
+      if (i < 0 || target.getAttribute('aria-expanded') === 'true') return
+      let to: HTMLElement | undefined
+      switch (e.key) {
+        case next:
+          to = els[Math.min(i + 1, els.length - 1)]
+          break
+        case prev:
+          to = els[Math.max(i - 1, 0)]
+          break
+        case 'Home':
+          to = els[0]
+          break
+        case 'End':
+          to = els[els.length - 1]
+          break
+        default:
+          return
+      }
+      e.preventDefault()
+      to?.focus()
+    }
+    doc.addEventListener('keydown', onKeyDown)
+    return () => doc.removeEventListener('keydown', onKeyDown)
+  }, [order, orientation, elements])
+
+  const ctx = useMemo<ToolbarContextValue>(
+    () => ({register, tabIndexOf, onItemFocus: setFocusedId}),
+    [register, tabIndexOf],
+  )
+
+  return (
+    <ToolbarContext.Provider value={ctx}>
+      <html.div
+        ref={rootRef}
+        role="toolbar"
+        aria-label={ariaLabel}
+        aria-orientation={orientation}
+        style={[styles.root, orientation === 'vertical' && styles.vertical]}
+      >
+        {children}
+      </html.div>
+    </ToolbarContext.Provider>
+  )
+}

package/src/components/Toolbar/ToolbarContext.ts

@@ -0,0 +1,15 @@
+import {createContext, useContext} from 'react'
+
+export interface ToolbarContextValue {
+  register: (id: string, el: HTMLElement, disabled: boolean) => () => void
+  /** 0 for the toolbar's one tab stop, -1 for the rest; undefined before
+   *  the control has registered (server render, first paint). */
+  tabIndexOf: (id: string) => 0 | -1 | undefined
+  onItemFocus: (id: string) => void
+}
+
+export const ToolbarContext = createContext<ToolbarContextValue | null>(null)
+
+export function useToolbar() {
+  return useContext(ToolbarContext)
+}

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

@@ -0,0 +1,17 @@
+import {css} from 'react-strict-dom'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+
+export const styles = css.create({
+  root: {
+    display: 'flex',
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: spacing.sm,
+  },
+  vertical: {
+    flexDirection: 'column',
+    flexWrap: 'nowrap',
+    alignItems: 'stretch',
+  },
+})

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

@@ -4,6 +4,7 @@ import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
 
 export const styles = css.create({
   root: {
@@ -12,7 +13,7 @@ export const styles = css.create({
   },
   popup: {
     position: 'absolute',
-    zIndex: 50,
+    zIndex: layers.floating,
     paddingTop: spacing.xs,
     paddingBottom: spacing.xs,
     paddingLeft: spacing.sm,

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

@@ -3,6 +3,7 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {microSpacing, 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 {layers} from '@duro-app/tokens/tokens/layers.css'
 
 export const styles = css.create({
   wrap: {
@@ -27,7 +28,7 @@ export const styles = css.create({
   head: {
     position: 'sticky',
     top: 0,
-    zIndex: 1,
+    zIndex: layers.raised,
     backgroundColor: colors.bgCard,
   },
   headRow: {

package/src/index.ts

@@ -13,7 +13,7 @@ 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 {Button, type ButtonVariant, type ButtonSize} from './components/Button/Button'
-export {ButtonGroup} from './components/ButtonGroup/ButtonGroup'
+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'
 export {Checkbox} from './components/Checkbox/Checkbox'
@@ -94,6 +94,7 @@ export {Text, type TextVariant, type TextColor} from './components/Text/Text'
 export {Toggle, type ToggleSize} from './components/Toggle/Toggle'
 export {ToggleGroup} from './components/ToggleGroup/ToggleGroup'
 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 {Switch} from './components/Switch/Switch'

package/src/shared/ModalContext.ts

@@ -0,0 +1,18 @@
+import {createContext, useContext} from 'react'
+
+/**
+ * True inside a Dialog or Drawer. A Popover reads it to pick its layer: inside
+ * a modal it must clear that modal (`layers.popover`); outside one it stays at
+ * `layers.floating`, so a modal opened later, even from inside the Popover,
+ * covers it.
+ *
+ * holds-until: a Dialog opened from a Popover that itself sits inside a Dialog
+ * still renders under that Popover (1000/1001 < 1040). It is fixed when a
+ * nested Dialog lifts its layer above its opener, or when the parent Popover
+ * closes on a nested modal opening; no consumer needs it yet.
+ */
+export const ModalContext = createContext(false)
+
+export function useInModal() {
+  return useContext(ModalContext)
+}