@duro-app/ui 4.1.0 → 4.3.0

package/dist/table.js

@@ -1,4 +1,4 @@
-import { M as F, s as xt, R as rt, H as kt, a as pt, B as bt, c as mt, C as ft, b as ht, d as yt } from "./Table-Bj5u2Q-k.js";
+import { M as F, s as xt, R as rt, H as kt, a as pt, B as bt, c as mt, C as ft, b as ht, d as yt } from "./Table-JTgcR_Fh.js";
 import { jsx as u, jsxs as B } from "react/jsx-runtime";
 import { c as H, m as p, d as b } from "./compiler-runtime-B2IcI8_O.js";
 import { flexRender as E, useReactTable as it, getPaginationRowModel as St, getFilteredRowModel as Tt, getSortedRowModel as at, getCoreRowModel as st } from "@tanstack/react-table";

package/package.json

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

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

@@ -23,6 +23,12 @@ export const meta: ComponentMeta = {
       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,10 +8,14 @@ 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'],
+    optional: ['LinkItem', 'Separator'],
   },
   relatedTo: [
     {
@@ -31,6 +35,7 @@ export const meta: ComponentMeta = {
   <Menu.Popup>
     <Menu.Item onClick={() => console.log('edit')}>Edit</Menu.Item>
     <Menu.Item onClick={() => console.log('duplicate')}>Duplicate</Menu.Item>
+    <Menu.Separator />
     <Menu.LinkItem href="/settings">Settings</Menu.LinkItem>
   </Menu.Popup>
 </Menu.Root>`,

package/src/components/Menu/Menu.stories.tsx

@@ -146,6 +146,32 @@ export const WithLinks: Story = {
   },
 }
 
+export const WithSeparator: Story = {
+  render: () => (
+    <Menu.Root>
+      <Menu.Trigger>History</Menu.Trigger>
+      <Menu.Popup>
+        <Menu.Item>Added SCADA to Operations</Menu.Item>
+        <Menu.Item>Renamed 2 capabilities</Menu.Item>
+        <Menu.Separator />
+        <Menu.Item>See full history</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: /History/}))
+    const menu = canvas.getByRole('menu')
+    const separator = canvas.getByRole('separator')
+    await expect(separator).toHaveAttribute('aria-orientation', 'horizontal')
+    // The separator is not an item: three items, and arrows pass over it.
+    const items = canvas.getAllByRole('menuitem')
+    await expect(items.length).toBe(3)
+    await userEvent.keyboard('{ArrowDown}')
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(menu).toHaveAttribute('aria-activedescendant', items[2].id)
+  },
+}
+
 // Misuse on purpose, so it runs as a test but stays out of the sidebar:
 // Menu.Trigger is the button, and a Button inside it earns a dev warning.
 export const NestedControlWarns: Story = {

package/src/components/Menu/Menu.tsx

@@ -159,10 +159,19 @@ function LinkItem({href, children}: LinkItemProps) {
   )
 }
 
+// --- Separator ---
+// A rule between groups of items. role="separator" is a valid child of a
+// menu (WAI-ARIA menu pattern), and it is never registered as an item, so
+// arrow keys and the active descendant pass over it.
+function Separator() {
+  return <html.div role="separator" aria-orientation="horizontal" style={styles.separator} />
+}
+
 export const Menu = {
   Root,
   Trigger,
   Popup,
   Item,
   LinkItem,
+  Separator,
 }

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

@@ -80,6 +80,14 @@ export const styles = css.create({
   itemHighlighted: {
     backgroundColor: colors.bgCardHover,
   },
+  separator: {
+    height: 0,
+    marginTop: spacing.xs,
+    marginBottom: spacing.xs,
+    borderTopWidth: 1,
+    borderTopStyle: 'solid',
+    borderTopColor: colors.border,
+  },
   linkItem: {
     textDecoration: 'none',
     color: {

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()
+  },
+}