@duro-app/ui 4.2.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^4.2.0"
+    "@duro-app/tokens": "^4.4.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/ActionBar/ActionBar.meta.ts

@@ -7,6 +7,7 @@ export const meta: ComponentMeta = {
     'Bulk actions on table selections (delete, revoke, export)',
     'Multi-select workflows where actions apply to all selected items',
     'Selection-scoped verbs on a canvas/editor surface (set `bottomOffset` to clear any bottom chrome such as zoom controls)',
+    'A docked side panel (DetailPanel) is open: pass its width as `insetInlineEnd` so the bar centres beside it, not under it (follows the writing direction: the left edge in right-to-left)',
   ],
   whenNotToUse: [
     'Single-item actions that have an inline home — use inline buttons or a Menu',
@@ -18,6 +19,12 @@ export const meta: ComponentMeta = {
       kind: 'composition',
       relationship: 'Common pattern: Table checkboxes + ActionBar for bulk ops',
     },
+    {
+      component: 'DetailPanel',
+      kind: 'composition',
+      relationship:
+        "With a DetailPanel docked at the end edge, pass the panel's width as insetInlineEnd",
+    },
   ],
   example: `<ActionBar selectedItemCount={selected.size} onClearSelection={() => setSelected(new Set())}>
   <Button variant="danger" size="small" onClick={handleDelete}>Delete</Button>

package/src/components/ActionBar/ActionBar.stories.tsx

@@ -1,6 +1,6 @@
 import {useState} from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn, userEvent, within} from 'storybook/test'
+import {expect, fn, within} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {ActionBar} from './ActionBar'
 import {Button} from '../Button/Button'
@@ -155,8 +155,7 @@ export const Default: Story = {
       onClearSelection={args.onClearSelection as () => void}
     />
   ),
-  play: async ({canvasElement}) => {
-    const canvas = within(canvasElement)
+  play: async () => {
     // The ActionBar is portalled to document.body, so query from there
     const toolbar = document.querySelector('[role="toolbar"]')
     await expect(toolbar).toBeInTheDocument()
@@ -310,3 +309,96 @@ export const AllVariants: Story = {
     </html.div>
   ),
 }
+
+// A panel docked at the window's end edge, standing in for an open DetailPanel.
+const docked = css.create({
+  panel: {
+    position: 'fixed',
+    top: 0,
+    bottom: 0,
+    insetInlineEnd: 0,
+    width: 360,
+    borderInlineStartWidth: 1,
+    borderInlineStartStyle: 'solid',
+  },
+})
+
+// Real buttons: they don't shrink below their labels, so together they are
+// wider than the free area beside the panel.
+const WIDE_ACTIONS = [
+  'Duplicate',
+  'Move to section',
+  'Copy style',
+  'Paste style',
+  'Group',
+  'Ungroup',
+  'Bring forward',
+  'Send backward',
+  'Delete',
+]
+
+const barRect = () =>
+  (document.querySelector('[role="toolbar"]') as Element).getBoundingClientRect()
+const panelRect = () =>
+  (document.querySelector('[data-testid="docked-panel"]') as Element).getBoundingClientRect()
+
+export const NoInset: Story = {
+  render: () => (
+    <ActionBar selectedItemCount={2} onClearSelection={() => {}}>
+      <Button variant="secondary" size="small">
+        Delete
+      </Button>
+    </ActionBar>
+  ),
+  play: async () => {
+    const bar = barRect()
+    const centre = document.documentElement.clientWidth / 2
+    // Today's placement: centred on the window.
+    await expect(Math.abs(bar.left + bar.width / 2 - centre)).toBeLessThanOrEqual(1)
+  },
+}
+
+export const DockedPanel: Story = {
+  render: () => (
+    <>
+      <html.div style={docked.panel} data-testid="docked-panel" />
+      <ActionBar selectedItemCount={2} insetInlineEnd={360} onClearSelection={() => {}}>
+        <Button variant="secondary" size="small">
+          Delete
+        </Button>
+      </ActionBar>
+    </>
+  ),
+  play: async () => {
+    const bar = barRect()
+    const panel = panelRect()
+    // Clear of the panel, and centred in what is left of the window.
+    await expect(bar.right).toBeLessThanOrEqual(panel.left - 24)
+    await expect(Math.abs(bar.left + bar.width / 2 - panel.left / 2)).toBeLessThanOrEqual(1)
+  },
+}
+
+export const DockedPanelWideBar: Story = {
+  render: () => (
+    <>
+      <html.div style={docked.panel} data-testid="docked-panel" />
+      <ActionBar selectedItemCount={2} insetInlineEnd={360} onClearSelection={() => {}}>
+        {WIDE_ACTIONS.map((a) => (
+          <Button key={a} variant="secondary" size="small">
+            {a}
+          </Button>
+        ))}
+      </ActionBar>
+    </>
+  ),
+  play: async () => {
+    // A bar wider than the free area still keeps 24px clear of the panel,
+    // and so does what it holds: the actions scroll, they don't spill.
+    const limit = panelRect().left - 24
+    await expect(barRect().right).toBeLessThanOrEqual(limit)
+    const last = await within(document.body).findByRole('button', {name: 'Delete'})
+    const actions = last.parentElement!
+    await expect(actions.getBoundingClientRect().right).toBeLessThanOrEqual(limit)
+    await expect(actions.scrollWidth).toBeGreaterThan(actions.clientWidth)
+  },
+}

package/src/components/ActionBar/ActionBar.tsx

@@ -22,6 +22,13 @@ export interface ActionBarProps {
    * height. Defaults to the spacing.lg token.
    */
   bottomOffset?: SpacingToken | number
+  /**
+   * Width in px of chrome docked at the window's inline-end edge (right in
+   * left-to-right, left in right-to-left), such as an open DetailPanel: the
+   * bar centres in what is left and keeps 24px clear of it. 0 or omitted
+   * centres on the window.
+   */
+  insetInlineEnd?: number
   /** Action buttons to display. */
   children: ReactNode
 }
@@ -33,6 +40,7 @@ function ActionBarContent({
   onClearSelection,
   dismissible = true,
   bottomOffset,
+  insetInlineEnd = 0,
   children,
 }: ActionBarProps) {
   const countStr = selectedItemCount === 'all' ? 'All' : `${selectedItemCount}`
@@ -44,6 +52,7 @@ function ActionBarContent({
       aria-label={label}
       style={[
         styles.overlay,
+        insetInlineEnd > 0 ? styles.inset(insetInlineEnd) : styles.centered,
         bottomOffset != null &&
           styles.overlayOffset(
             typeof bottomOffset === 'number' ? bottomOffset : SPACING_PX[bottomOffset],
@@ -55,7 +64,9 @@ function ActionBarContent({
         {label}
       </html.span>
       <html.div style={[styles.separator, isEmphasized && styles.separatorEmphasized]} />
-      <html.div style={styles.actions}>{children}</html.div>
+      <html.div style={[styles.actions, insetInlineEnd > 0 && styles.actionsScroll]}>
+        {children}
+      </html.div>
       {dismissible && (
         <html.button
           type="button"

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

@@ -9,8 +9,6 @@ export const styles = css.create({
   overlay: {
     position: 'fixed',
     bottom: spacing.lg,
-    left: '50%',
-    transform: 'translateX(-50%)',
     display: 'flex',
     flexDirection: 'row',
     alignItems: 'center',
@@ -26,8 +24,25 @@ export const styles = css.create({
     borderRadius: radii.md,
     boxShadow: shadows.lg,
     zIndex: 50,
+  },
+  // Centred on the window: the default, with nothing docked at its edge.
+  centered: {
+    left: '50%',
+    transform: 'translateX(-50%)',
     maxWidth: 'calc(100vw - 48px)',
   },
+  // Centred in the window minus chrome docked at the inline-end edge (a
+  // DetailPanel). Both insets and auto margins centre a fixed box of
+  // fit-content width in what is left, measured on the containing block
+  // (the window without a classic scrollbar), not on 100vw.
+  inset: (end: number) => ({
+    insetInlineStart: 0,
+    insetInlineEnd: end,
+    marginInlineStart: 'auto',
+    marginInlineEnd: 'auto',
+    width: 'fit-content',
+    maxWidth: `calc(100% - ${end}px - 48px)`,
+  }),
   overlayOffset: (bottom: number) => ({
     bottom,
   }),
@@ -51,6 +66,23 @@ export const styles = css.create({
     alignItems: 'center',
     gap: spacing.sm,
   },
+  // Beside a docked panel the room is narrower: more actions than fit scroll
+  // instead of spilling past the bar. A scroll box clips vertically too, so
+  // the row gets room on every side for the buttons' focus rings, taken back
+  // by its margin so the bar keeps its size.
+  actionsScroll: {
+    minWidth: 0,
+    overflowX: 'auto',
+    overflowY: 'hidden',
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.xs,
+    paddingRight: spacing.xs,
+    marginTop: `calc(-1 * ${spacing.xs})`,
+    marginBottom: `calc(-1 * ${spacing.xs})`,
+    marginLeft: `calc(-1 * ${spacing.xs})`,
+    marginRight: `calc(-1 * ${spacing.xs})`,
+  },
   closeButton: {
     display: 'inline-flex',
     alignItems: 'center',

package/src/components/DetailPanel/DetailPanel.meta.ts

@@ -18,11 +18,23 @@ export const meta: ComponentMeta = {
     optional: ['Title', 'Footer', 'Close'],
   },
   relatedTo: [
+    {
+      component: 'ActionBar',
+      kind: 'composition',
+      relationship:
+        "An ActionBar shown while the panel is open takes the panel's width as insetInlineEnd",
+    },
     {
       component: 'Drawer',
       kind: 'contrast',
       relationship: 'Drawer is modal with backdrop; DetailPanel is non-modal and in-flow',
     },
+    {
+      component: 'Popover',
+      kind: 'contrast',
+      relationship:
+        'Popover is a small anchored overlay for a few controls; DetailPanel is an in-flow panel for long editing',
+    },
     {
       component: 'Table',
       kind: 'composition',

package/src/components/Dialog/Dialog.meta.ts

@@ -30,6 +30,12 @@ export const meta: ComponentMeta = {
       kind: 'contrast',
       relationship: 'DetailPanel is non-modal and in-flow; Dialog is modal with backdrop',
     },
+    {
+      component: 'Popover',
+      kind: 'contrast',
+      relationship:
+        'Popover is a small non-modal card anchored to an element; Dialog is a modal decision',
+    },
   ],
   example: `<Dialog.Root open={open} onOpenChange={setOpen}>
   <Dialog.Trigger>

package/src/components/Drawer/Drawer.meta.ts

@@ -30,6 +30,12 @@ export const meta: ComponentMeta = {
       kind: 'contrast',
       relationship: 'DetailPanel is non-modal and in-flow; Drawer is modal with backdrop',
     },
+    {
+      component: 'Popover',
+      kind: 'contrast',
+      relationship:
+        'Popover is a small card anchored to an element; Drawer takes its place at phone width',
+    },
   ],
   example: `<Drawer.Root anchor="right" open={open} onOpenChange={setOpen}>
   <Drawer.Trigger>

package/src/components/Menu/Menu.meta.ts

@@ -8,7 +8,11 @@ export const meta: ComponentMeta = {
     'Navigation links in a dropdown',
     'Overflow menu for toolbar actions',
   ],
-  whenNotToUse: ['Picking a value — use Select', 'Primary navigation — use SideNav or Tabs'],
+  whenNotToUse: [
+    'Picking a value — use Select',
+    'Primary navigation — use SideNav or Tabs',
+    'A small form tied to the trigger — use Popover',
+  ],
   anatomy: {
     required: ['Root', 'Trigger', 'Popup', 'Item'],
     optional: ['LinkItem', 'Separator'],

package/src/components/Popover/Popover.meta.ts

@@ -0,0 +1,69 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves.',
+  whenToUse: [
+    'A small form or controls tied to one element that stay open while you work in them',
+    'Anchoring to a spot that is not a button (a canvas point, a text selection) with a virtual anchor',
+  ],
+  whenNotToUse: [
+    'A list of actions — use Menu',
+    'Hover-only text — use Tooltip',
+    'A blocking decision — use Dialog or ConfirmDialog',
+    'A long editor, or one that follows the selection — use DetailPanel',
+    'Phone width — use Drawer',
+  ],
+  anatomy: {
+    required: ['Root', 'Popup'],
+    optional: ['Trigger', 'Close'],
+  },
+  relatedTo: [
+    {
+      component: 'Menu',
+      kind: 'contrast',
+      relationship: 'Menu opens a list of actions; Popover holds small forms and controls',
+    },
+    {
+      component: 'Tooltip',
+      kind: 'contrast',
+      relationship:
+        'Tooltip shows hover-only text; Popover holds interactive content and stays open',
+    },
+    {
+      component: 'Dialog',
+      kind: 'contrast',
+      relationship: 'Dialog is modal and blocks the page; Popover is non-modal and anchored',
+    },
+    {
+      component: 'DetailPanel',
+      kind: 'contrast',
+      relationship:
+        'DetailPanel is an in-flow panel for long editing; Popover is a small anchored overlay',
+    },
+    {
+      component: 'Drawer',
+      kind: 'contrast',
+      relationship:
+        'Drawer is the modal edge panel for phone width; Popover is anchored and non-modal',
+    },
+    {
+      component: 'Field',
+      kind: 'composition',
+      relationship: 'Place Field.Root with its control inside Popover.Popup for a labelled field',
+    },
+  ],
+  example: `const ref = useRef<PopoverHandle>(null)
+const anchor = () => new DOMRect(point.x, point.y, 0, 0)
+
+<Popover.Root ref={ref} open={open} onOpenChange={setOpen} anchor={anchor} side="bottom" align="start">
+  <Popover.Popup label="Edit label">
+    <Field.Root>
+      <Field.Label>Label</Field.Label>
+      <Input value={label} onChange={(e) => setLabel(e.target.value)} />
+    </Field.Root>
+    <Popover.Close>Done</Popover.Close>
+  </Popover.Popup>
+</Popover.Root>
+// after the anchor moves: ref.current?.reposition()`,
+}

package/src/components/Popover/Popover.stories.tsx

@@ -0,0 +1,250 @@
+import {useRef, useState} from 'react'
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect, fn, waitFor, within} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {Popover, type PopoverHandle} from './Popover'
+import {Button} from '../Button/Button'
+import {Field} from '../Field/Field'
+import {Input} from '../Input/Input'
+import {Select} from '../Select/Select'
+import {Stack} from '../Stack/Stack'
+
+const meta: Meta = {
+  title: 'Components/Popover',
+}
+
+export default meta
+type Story = StoryObj
+
+// The popup is portalled out of the story's canvas, so query the document.
+const page = () => within(document.body)
+
+const styles = css.create({
+  stage: {
+    position: 'relative',
+    height: 320,
+    borderWidth: 1,
+    borderStyle: 'dashed',
+    borderColor: colors.border,
+    padding: spacing.md,
+  },
+  spot: {
+    position: 'absolute',
+    top: 120,
+    left: 160,
+    width: 120,
+    padding: spacing.sm,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.accent,
+  },
+  shifted: {
+    transform: 'translateX(120px)',
+  },
+})
+
+export const Default: Story = {
+  render: () => (
+    <Popover.Root>
+      <Popover.Trigger>Rename</Popover.Trigger>
+      <Popover.Popup label="Rename">
+        <Stack gap="sm">
+          <Field.Root>
+            <Field.Label>Label</Field.Label>
+            <Input defaultValue="Get started" />
+          </Field.Root>
+          <Popover.Close>Done</Popover.Close>
+        </Stack>
+      </Popover.Popup>
+    </Popover.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('button', {name: 'Rename'})
+    await userEvent.click(trigger)
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    const dialog = page().getByRole('dialog', {name: 'Rename'})
+    await expect(dialog).toBeVisible()
+    // Focus moves to the first field.
+    await waitFor(() => expect(page().getByRole('textbox', {name: 'Label'})).toHaveFocus())
+
+    await userEvent.keyboard('{Escape}')
+    await expect(page().queryByRole('dialog')).not.toBeInTheDocument()
+    // ...and comes back to the trigger.
+    await waitFor(() => expect(trigger).toHaveFocus())
+  },
+}
+
+export const CloseButton: Story = {
+  render: Default.render,
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('button', {name: 'Rename'})
+    await userEvent.click(trigger)
+    await userEvent.click(page().getByRole('button', {name: 'Done'}))
+    await expect(page().queryByRole('dialog')).not.toBeInTheDocument()
+    await waitFor(() => expect(trigger).toHaveFocus())
+  },
+}
+
+function WithIgnored({onOpenChange}: {onOpenChange: (open: boolean) => void}) {
+  const ignored = useRef<HTMLButtonElement | null>(null)
+  return (
+    <Stack gap="md">
+      <Popover.Root onOpenChange={onOpenChange} ignore={[() => ignored.current]}>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Popup label="Item">
+          <Popover.Close>Close</Popover.Close>
+        </Popover.Popup>
+      </Popover.Root>
+      <html.button ref={ignored} type="button">
+        Grip (ignored)
+      </html.button>
+      <html.button type="button">Elsewhere</html.button>
+    </Stack>
+  )
+}
+
+export const OutsidePress: Story = {
+  render: () => <WithIgnored onOpenChange={fn()} />,
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open'}))
+    await expect(page().getByRole('dialog', {name: 'Item'})).toBeVisible()
+
+    // A press on an ignored element keeps it open.
+    await userEvent.click(canvas.getByRole('button', {name: 'Grip (ignored)'}))
+    await expect(page().getByRole('dialog', {name: 'Item'})).toBeVisible()
+
+    // A press anywhere else closes it.
+    await userEvent.click(canvas.getByRole('button', {name: 'Elsewhere'}))
+    await expect(page().queryByRole('dialog')).not.toBeInTheDocument()
+  },
+}
+
+export const NestedSelectOwnsEscape: 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">
+              <Select.ItemText>Primary</Select.ItemText>
+            </Select.Item>
+            <Select.Item value="secondary">
+              <Select.ItemText>Secondary</Select.ItemText>
+            </Select.Item>
+          </Select.Popup>
+        </Select.Root>
+      </Popover.Popup>
+    </Popover.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Style'}))
+    const variant = page().getByRole('combobox', {name: 'Variant'})
+    await userEvent.click(variant)
+    await expect(variant).toHaveAttribute('aria-expanded', 'true')
+
+    // The first Esc closes only the Select...
+    await userEvent.keyboard('{Escape}')
+    await expect(variant).toHaveAttribute('aria-expanded', 'false')
+    await expect(page().getByRole('dialog', {name: 'Style'})).toBeVisible()
+
+    // ...the second closes the popover.
+    await userEvent.keyboard('{Escape}')
+    await expect(page().queryByRole('dialog')).not.toBeInTheDocument()
+  },
+}
+
+function VirtualAnchorDemo() {
+  const spot = useRef<HTMLDivElement | null>(null)
+  const handle = useRef<PopoverHandle | null>(null)
+  const [open, setOpen] = useState(false)
+  const [shifted, setShifted] = useState(false)
+  return (
+    <Stack gap="sm">
+      <Button onClick={() => setOpen(true)}>Edit the spot</Button>
+      <html.div style={styles.stage}>
+        <html.div ref={spot} style={[styles.spot, shifted && styles.shifted]}>
+          Spot
+        </html.div>
+      </html.div>
+      <Popover.Root
+        ref={handle}
+        open={open}
+        onOpenChange={setOpen}
+        anchor={() => spot.current!.getBoundingClientRect()}
+      >
+        <Popover.Popup label="Spot">
+          <Stack gap="sm">
+            <Button
+              variant="secondary"
+              onClick={() => {
+                setShifted((s) => !s)
+                // The anchor moved without a scroll or resize: re-measure.
+                requestAnimationFrame(() => handle.current?.reposition())
+              }}
+            >
+              Move the spot
+            </Button>
+            <Popover.Close>Done</Popover.Close>
+          </Stack>
+        </Popover.Popup>
+      </Popover.Root>
+    </Stack>
+  )
+}
+
+export const VirtualAnchor: Story = {
+  render: () => <VirtualAnchorDemo />,
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Edit the spot'}))
+    const dialog = page().getByRole('dialog', {name: 'Spot'})
+    const spot = canvas.getByText('Spot')
+    await waitFor(() =>
+      expect(dialog.getBoundingClientRect().left).toBeCloseTo(spot.getBoundingClientRect().left, 0),
+    )
+    // Below the spot (side bottom).
+    await expect(dialog.getBoundingClientRect().top).toBeGreaterThanOrEqual(
+      spot.getBoundingClientRect().bottom,
+    )
+
+    const before = spot.getBoundingClientRect().left
+    await userEvent.click(page().getByRole('button', {name: 'Move the spot'}))
+    await waitFor(() => expect(spot.getBoundingClientRect().left).toBeGreaterThan(before))
+    await waitFor(() =>
+      expect(dialog.getBoundingClientRect().left).toBeCloseTo(spot.getBoundingClientRect().left, 0),
+    )
+  },
+}
+
+function DisclosureDemo() {
+  const [expanded, setExpanded] = useState(true)
+  return (
+    <Popover.Root>
+      <Popover.Trigger>Details</Popover.Trigger>
+      <Popover.Popup label="Details">
+        <html.button type="button" aria-expanded={expanded} onClick={() => setExpanded((e) => !e)}>
+          More
+        </html.button>
+      </Popover.Popup>
+    </Popover.Root>
+  )
+}
+
+export const DisclosureDoesNotOwnEscape: Story = {
+  render: () => <DisclosureDemo />,
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Details'}))
+    const more = page().getByRole('button', {name: 'More'})
+    await waitFor(() => expect(more).toHaveFocus())
+    await expect(more).toHaveAttribute('aria-expanded', 'true')
+    // An expanded disclosure opens no popup of its own: Esc closes the popover.
+    await userEvent.keyboard('{Escape}')
+    await expect(page().queryByRole('dialog')).not.toBeInTheDocument()
+  },
+}