@duro-app/ui 5.1.0 → 5.2.0

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

@@ -1,7 +1,13 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn, spyOn} from 'storybook/test'
+import {expect, fn, spyOn, waitFor, within} from 'storybook/test'
+import {css, html} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {Menu} from './Menu'
 import {Button} from '../Button/Button'
+import {Dialog} from '../Dialog/Dialog'
+import {Icon} from '../Icon/Icon'
 
 const meta: Meta = {
   title: 'Components/Menu',
@@ -65,11 +71,11 @@ export const OpenClose: Story = {
 
     await userEvent.click(trigger)
     await expect(trigger).toHaveAttribute('aria-expanded', 'true')
-    const items = canvas.getAllByRole('menuitem')
+    const items = page().getAllByRole('menuitem')
     await expect(items.length).toBe(3)
 
     await userEvent.keyboard('{Escape}')
-    await expect(canvas.queryByRole('menu')).not.toBeInTheDocument()
+    await waitFor(() => expect(page().queryByRole('menu')).not.toBeInTheDocument())
   },
 }
 
@@ -103,7 +109,7 @@ export const KeyboardNavigation: Story = {
   play: async ({canvas, userEvent}) => {
     const trigger = canvas.getByRole('button', {name: /Navigate/})
     await userEvent.click(trigger)
-    await expect(canvas.getByRole('menu')).toBeInTheDocument()
+    await expect(page().getByRole('menu')).toBeInTheDocument()
   },
 }
 
@@ -137,7 +143,7 @@ export const WithLinks: Story = {
   play: async ({canvas, userEvent}) => {
     await userEvent.click(canvas.getByRole('button', {name: /Account/}))
 
-    const items = canvas.getAllByRole('menuitem')
+    const items = page().getAllByRole('menuitem')
     await expect(items.length).toBe(3)
 
     // Link items should be anchor elements with href
@@ -160,11 +166,11 @@ export const WithSeparator: Story = {
   ),
   play: async ({canvas, userEvent}) => {
     await userEvent.click(canvas.getByRole('button', {name: /History/}))
-    const menu = canvas.getByRole('menu')
-    const separator = canvas.getByRole('separator')
+    const menu = page().getByRole('menu')
+    const separator = page().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')
+    const items = page().getAllByRole('menuitem')
     await expect(items.length).toBe(3)
     await userEvent.keyboard('{ArrowDown}')
     await userEvent.keyboard('{ArrowDown}')
@@ -196,3 +202,278 @@ export const NestedControlWarns: Story = {
     )
   },
 }
+
+// The popup is portalled into the ThemeProvider mount: query the document.
+const page = () => within(document.body)
+
+const storyStyles = css.create({
+  scroller: {
+    height: sizes.panelSm,
+    overflow: 'auto',
+    borderWidth: 0,
+  },
+  toolbar: {
+    position: 'sticky',
+    top: 0,
+    overflow: 'auto',
+    display: 'flex',
+    gap: spacing.sm,
+    padding: spacing.sm,
+    backgroundColor: colors.bgCard,
+  },
+  filler: {
+    height: sizes.pageMd,
+  },
+  editor: {
+    minHeight: sizes.editorMinH,
+    padding: spacing.sm,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+  },
+})
+
+// react-strict-dom has no contentEditable prop; a rich-text editor sets it.
+const makeEditable = (el: HTMLElement | null) => el?.setAttribute('contenteditable', 'true')
+
+const THIRTY = Array.from({length: 30}, (_, i) => `Action ${i + 1}`)
+
+// A sticky, overflow:auto toolbar used to clip the popup; portalled, it is
+// placed in the viewport and scrolls inside its own max height.
+export const InStickyOverflowToolbar: Story = {
+  render: () => (
+    <html.div style={storyStyles.scroller}>
+      <html.div style={storyStyles.toolbar}>
+        <Menu.Root>
+          <Menu.Trigger>Insert</Menu.Trigger>
+          <Menu.Popup>
+            {THIRTY.map((label) => (
+              <Menu.Item key={label}>{label}</Menu.Item>
+            ))}
+          </Menu.Popup>
+        </Menu.Root>
+      </html.div>
+      <html.div style={storyStyles.filler} />
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Insert'}))
+    const menu = await page().findByRole('menu', {name: 'Insert'})
+    const box = menu.getBoundingClientRect()
+    await expect(box.top).toBeGreaterThanOrEqual(0)
+    await expect(box.left).toBeGreaterThanOrEqual(0)
+    await expect(box.bottom).toBeLessThanOrEqual(window.innerHeight)
+    await expect(box.right).toBeLessThanOrEqual(window.innerWidth)
+    await expect(menu.scrollHeight).toBeGreaterThan(menu.clientHeight)
+    await expect(page().getAllByRole('menuitem')).toHaveLength(30)
+    // The last item scrolls into view when it is highlighted.
+    await userEvent.keyboard('{End}')
+    const last = page().getByRole('menuitem', {name: 'Action 30'})
+    const lastBox = last.getBoundingClientRect()
+    await expect(lastBox.bottom).toBeLessThanOrEqual(menu.getBoundingClientRect().bottom + 1)
+  },
+}
+
+// APG menu button: focus moves to the menu, and the menu's
+// aria-activedescendant names the highlighted item.
+export const FocusAndActiveDescendant: Story = {
+  render: () => (
+    <Menu.Root>
+      <Menu.Trigger>Edit</Menu.Trigger>
+      <Menu.Popup>
+        <Menu.Item>Cut</Menu.Item>
+        <Menu.Item>Copy</Menu.Item>
+        <Menu.Item>Paste</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('button', {name: 'Edit'})
+    await userEvent.click(trigger)
+    const menu = await page().findByRole('menu', {name: 'Edit'})
+    await waitFor(() => expect(document.activeElement).toBe(menu))
+    await userEvent.keyboard('{ArrowDown}')
+    const copy = page().getByRole('menuitem', {name: 'Copy'})
+    await expect(document.activeElement).toBe(menu)
+    await expect(menu).toHaveAttribute('aria-activedescendant', copy.id)
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(page().queryByRole('menu')).not.toBeInTheDocument())
+    await expect(trigger).toHaveFocus()
+  },
+}
+
+// One Escape closes the innermost layer only: the Menu, not its Dialog.
+const onMenuOpenChange = fn()
+const onDialogOpenChange = fn()
+
+export const EscapeInsideDialog: Story = {
+  beforeEach: () => {
+    onMenuOpenChange.mockClear()
+    onDialogOpenChange.mockClear()
+  },
+  render: () => (
+    <Dialog.Root defaultOpen onOpenChange={onDialogOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Header>
+          <Dialog.Title>Format</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Body>
+          <Menu.Root onOpenChange={onMenuOpenChange}>
+            <Menu.Trigger>Align</Menu.Trigger>
+            <Menu.Popup>
+              <Menu.Item>Left</Menu.Item>
+              <Menu.Item>Center</Menu.Item>
+            </Menu.Popup>
+          </Menu.Root>
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({userEvent}) => {
+    await userEvent.click(page().getByRole('button', {name: 'Align'}))
+    await page().findByRole('menu', {name: 'Align'})
+    await expect(onMenuOpenChange).toHaveBeenCalledWith(true)
+    // The popup stacks above the dialog: its item is what a press hits.
+    const center = page().getByRole('menuitem', {name: 'Center'})
+    const box = center.getBoundingClientRect()
+    await expect(
+      document.elementFromPoint(box.left + box.width / 2, box.top + box.height / 2),
+    ).toBe(center)
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(page().queryByRole('menu')).not.toBeInTheDocument())
+    // The Escape closes the menu once: onOpenChange(true) on open, then
+    // exactly one onOpenChange(false).
+    await expect(onMenuOpenChange.mock.calls.filter(([open]) => open === false)).toHaveLength(1)
+    await expect(onMenuOpenChange).toHaveBeenLastCalledWith(false)
+    await expect(onDialogOpenChange).toHaveBeenCalledTimes(0)
+    await expect(page().getByRole('dialog', {name: 'Format'})).toBeInTheDocument()
+  },
+}
+
+// The keydown handler sits on the menu, never on document: typing in an
+// editor while the menu is open reaches the editor.
+export const TypingElsewhereIsNotIntercepted: Story = {
+  render: () => (
+    <html.div>
+      <Menu.Root>
+        <Menu.Trigger>Blocks</Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item>Heading</Menu.Item>
+          <Menu.Item>Quote</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <html.div ref={makeEditable} role="textbox" aria-label="Editor" style={storyStyles.editor} />
+    </html.div>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Blocks'}))
+    await page().findByRole('menu', {name: 'Blocks'})
+    const editor = canvas.getByRole('textbox', {name: 'Editor'})
+    editor.focus()
+    await userEvent.keyboard('a b{ArrowDown}c')
+    await expect(editor).toHaveTextContent('a bc')
+    await expect(page().getByRole('menu', {name: 'Blocks'})).not.toHaveAttribute(
+      'aria-activedescendant',
+      page().getByRole('menuitem', {name: 'Quote'}).id,
+    )
+  },
+}
+
+// A toolbar icon trigger: ghost variant, named by aria-label, ref forwarded.
+export const GhostIconTrigger: Story = {
+  render: () => (
+    <Menu.Root>
+      <Menu.Trigger variant="ghost" aria-label="More actions">
+        <Icon name="menu" size="sm" />
+      </Menu.Trigger>
+      <Menu.Popup align="end">
+        <Menu.Item>Rename</Menu.Item>
+        <Menu.Item>Delete</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('button', {name: 'More actions'})
+    await userEvent.click(trigger)
+    await expect(await page().findByRole('menu', {name: 'More actions'})).toBeVisible()
+  },
+}
+
+const onRename = fn()
+
+// Enter activates the highlighted item exactly once.
+export const EnterActivatesOnce: Story = {
+  beforeEach: () => {
+    onRename.mockClear()
+  },
+  render: () => (
+    <Menu.Root>
+      <Menu.Trigger>File</Menu.Trigger>
+      <Menu.Popup>
+        <Menu.Item onClick={onRename}>Rename</Menu.Item>
+        <Menu.Item>Delete</Menu.Item>
+      </Menu.Popup>
+    </Menu.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'File'}))
+    await page().findByRole('menu', {name: 'File'})
+    await userEvent.keyboard('{Enter}')
+    await waitFor(() => expect(page().queryByRole('menu')).not.toBeInTheDocument())
+    await expect(onRename).toHaveBeenCalledTimes(1)
+  },
+}
+
+// Tab from a menu portalled out of a Dialog closes it and continues from the
+// trigger, so focus lands on the next control in the dialog. Under the Vitest
+// browser runner a real keyboard (Playwright) presses Tab; the simulated
+// keydown below is what the Storybook UI can run.
+export const TabInsideDialog: Story = {
+  render: () => (
+    <Dialog.Root defaultOpen>
+      <Dialog.Portal>
+        <Dialog.Header>
+          <Dialog.Title>Insert</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Body>
+          <Menu.Root>
+            <Menu.Trigger>Block</Menu.Trigger>
+            <Menu.Popup>
+              <Menu.Item>Quote</Menu.Item>
+            </Menu.Popup>
+          </Menu.Root>
+          <Button variant="secondary">After</Button>
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({userEvent}) => {
+    const trigger = page().getByRole('button', {name: 'Block'})
+    await userEvent.click(trigger)
+    const menu = await page().findByRole('menu', {name: 'Block'})
+    menu.dispatchEvent(new KeyboardEvent('keydown', {key: 'Tab', bubbles: true}))
+    await waitFor(() => expect(page().queryByRole('menu')).not.toBeInTheDocument())
+    await expect(trigger).toHaveFocus()
+
+    const keyboard = await realKeyboard()
+    if (!keyboard) return
+    await userEvent.click(trigger)
+    await page().findByRole('menu', {name: 'Block'})
+    await keyboard('{Tab}')
+    await waitFor(() => expect(page().queryByRole('menu')).not.toBeInTheDocument())
+    await expect(page().getByRole('button', {name: 'After'})).toHaveFocus()
+  },
+}
+
+/**
+ * The Vitest browser runner's keyboard, which drives the browser itself
+ * (Playwright) so Tab moves focus the way a person's would. Outside that
+ * runner (the Storybook UI) the module throws on import, and there is none.
+ */
+async function realKeyboard(): Promise<((keys: string) => Promise<void>) | null> {
+  try {
+    const {userEvent} = await import('vitest/browser')
+    return (keys) => userEvent.keyboard(keys)
+  } catch {
+    return null
+  }
+}

package/src/components/Menu/Menu.tsx

@@ -1,17 +1,37 @@
-import {type ReactNode, useRef, useId, useEffect} from 'react'
+import {
+  type ReactNode,
+  type Ref,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react'
+import {createPortal} from 'react-dom'
 import {html} from 'react-strict-dom'
+import {SPACING_PX} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
 import {MenuContext, useMenu} from './MenuContext'
 import {useMenuRoot} from './useMenuRoot'
 import {devWarnOnce} from '../../shared/devWarnOnce'
+import {usePortalMount} from '../ThemeProvider/ThemeProvider'
+import {computePopoverPosition} from '../Popover/position'
+import {usePopoverLayer} from '../Popover/PopoverLayerContext'
 
 // --- Root ---
 interface RootProps {
   children: ReactNode
+  /** Controlled open state. */
+  open?: boolean
+  /** Initial open state (uncontrolled). */
+  defaultOpen?: boolean
+  /** Called when the menu opens or closes. */
+  onOpenChange?: (open: boolean) => void
 }
 
-function Root({children}: RootProps) {
-  const {ctx, rootRef} = useMenuRoot()
+function Root({children, open, defaultOpen, onOpenChange}: RootProps) {
+  const {ctx, rootRef} = useMenuRoot({open, defaultOpen, onOpenChange})
 
   return (
     <MenuContext.Provider value={ctx}>
@@ -28,35 +48,51 @@ function Root({children}: RootProps) {
 // Its children are the label (text, an Icon) — never a Button or other control.
 const NESTED_CONTROL = 'button, a[href], input, select, textarea, [role="button"]'
 
-function Trigger({children}: {children: ReactNode}) {
-  const {open, toggle, menuId, triggerRef} = useMenu()
-  const localRef = useRef<HTMLButtonElement>(null)
+export type MenuTriggerVariant = 'default' | 'ghost'
 
-  // Sync local ref to context triggerRef
-  useEffect(() => {
-    triggerRef.current = localRef.current
-  })
+interface TriggerProps {
+  children: ReactNode
+  /** Accessible name — required when the label is an icon only. */
+  'aria-label'?: string
+  /** `ghost`: no border or fill until hover, for toolbars. Default: `default`. */
+  variant?: MenuTriggerVariant
+  ref?: Ref<HTMLButtonElement>
+}
+
+function Trigger({children, 'aria-label': ariaLabel, variant = 'default', ref}: TriggerProps) {
+  const {open, toggle, menuId, triggerId, triggerRef} = useMenu()
+
+  const setRef = useCallback(
+    (el: HTMLButtonElement | null) => {
+      triggerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) ref.current = el
+    },
+    [ref, triggerRef],
+  )
 
   // TypeScript can't stop a <Button> child; the DOM can tell.
   useEffect(() => {
-    if (localRef.current?.querySelector(NESTED_CONTROL)) {
+    if (triggerRef.current?.querySelector(NESTED_CONTROL)) {
       devWarnOnce(
         'Menu',
         'trigger-nested-control',
         'Menu.Trigger is itself the button — give it the label (text, an Icon), not a Button, link or other control. A control inside a <button> is invalid HTML: it breaks hydration and hands assistive tech a button inside a button.',
       )
     }
-  }, [])
+  }, [triggerRef])
 
   return (
     <html.button
-      ref={localRef}
+      ref={setRef}
+      id={triggerId}
       type="button"
       onClick={toggle}
+      aria-label={ariaLabel}
       aria-expanded={open}
       aria-haspopup="menu"
       aria-controls={open ? menuId : undefined}
-      style={styles.trigger}
+      style={[styles.trigger, variant === 'ghost' && styles.triggerGhost]}
     >
       {children}
     </html.button>
@@ -69,23 +105,58 @@ interface PopupProps {
   align?: 'start' | 'end'
 }
 
+// Portalled into the ThemeProvider mount and placed against the trigger, so a
+// sticky or overflow-clipped toolbar never cuts it off. Capped at
+// `sizes.listMaxH`; longer menus scroll.
 function Popup({children, align = 'start'}: PopupProps) {
-  const {open, close, menuId, highlightedId} = useMenu()
+  const {open, menuId, triggerId, highlightedId, triggerRef, popupRef} = useMenu()
+  const [coords, setCoords] = useState({top: 0, left: 0})
+  const mount = usePortalMount()
+  // Inside a Popover, a press on this portalled popup is not an outside press.
+  usePopoverLayer(popupRef, {active: open})
+
+  useLayoutEffect(() => {
+    if (!open) return
+    const update = () => {
+      const popup = popupRef.current
+      const rect = triggerRef.current?.getBoundingClientRect()
+      if (!popup || !rect) return
+      const next = computePopoverPosition({
+        anchor: {top: rect.top, left: rect.left, width: rect.width, height: rect.height},
+        popup: {width: popup.offsetWidth, height: popup.offsetHeight},
+        viewport: {width: window.innerWidth, height: window.innerHeight},
+        side: 'bottom',
+        align,
+        offset: SPACING_PX.xs,
+      })
+      setCoords((prev) =>
+        prev.top === next.top && prev.left === next.left ? prev : {top: next.top, left: next.left},
+      )
+    }
+    update()
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    return () => {
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [open, align, popupRef, triggerRef])
 
-  if (!open) return null
+  if (!open || typeof document === 'undefined') return null
 
-  return (
-    <>
-      <html.div style={styles.backdrop} onClick={close} />
-      <html.div
-        id={menuId}
-        role="menu"
-        aria-activedescendant={highlightedId ?? undefined}
-        style={[styles.popup, align === 'end' && styles.popupEnd]}
-      >
-        {children}
-      </html.div>
-    </>
+  return createPortal(
+    <html.div
+      ref={popupRef}
+      id={menuId}
+      role="menu"
+      tabIndex={-1}
+      aria-labelledby={triggerId}
+      aria-activedescendant={highlightedId ?? undefined}
+      style={[styles.popup, styles.popupPosition(coords.top, coords.left)]}
+    >
+      {children}
+    </html.div>,
+    mount ?? document.body,
   )
 }
 
@@ -149,7 +220,7 @@ function LinkItem({href, children}: LinkItemProps) {
       ref={ref}
       id={id}
       href={href}
-      onClick={close}
+      onClick={() => close()}
       role="menuitem"
       onPointerEnter={() => setHighlightedId(id)}
       style={[styles.item, styles.linkItem, isHighlighted && styles.itemHighlighted]}

package/src/components/Menu/MenuContext.ts

@@ -3,12 +3,15 @@ import {createContext, useContext} from 'react'
 export interface MenuContextValue {
   open: boolean
   toggle: () => void
+  /** Close the menu and put focus back on the trigger. */
   close: () => void
   menuId: string
+  triggerId: string
   highlightedId: string | null
   setHighlightedId: (id: string | null) => void
   registerItem: (id: string, element: HTMLElement) => () => void
   triggerRef: React.RefObject<HTMLButtonElement | null>
+  popupRef: React.RefObject<HTMLDivElement | null>
 }
 
 export const MenuContext = createContext<MenuContextValue | null>(null)

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

@@ -35,19 +35,21 @@ export const styles = css.create({
     transitionProperty: 'background-color, border-color',
     transitionDuration: duration.fast,
   },
-  backdrop: {
-    position: 'fixed',
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: 0,
-    zIndex: 49,
+  // Toolbar trigger: no border or fill until hover, at least icon-button size.
+  triggerGhost: {
+    justifyContent: 'center',
+    minWidth: sizes.iconButton,
+    minHeight: sizes.iconButton,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.xs,
+    paddingRight: spacing.xs,
+    borderColor: 'transparent',
   },
   popup: {
-    position: 'absolute',
-    top: '100%',
+    position: 'fixed',
+    top: 0,
     left: 0,
-    marginTop: spacing.xs,
     backgroundColor: colors.bgCard,
     borderWidth: borders.hairline,
     borderStyle: 'solid',
@@ -57,12 +59,20 @@ export const styles = css.create({
     paddingTop: spacing.xs,
     paddingBottom: spacing.xs,
     minWidth: sizes.popupMinW,
-    zIndex: 50,
-  },
-  popupEnd: {
-    left: 'auto',
-    right: 0,
+    maxHeight: sizes.listMaxH,
+    overflowY: 'auto',
+    // Above Dialog/Drawer (1000/1001), like Select and Combobox: they portal
+    // into the same mount, so a menu opened inside a dialog must out-rank it.
+    zIndex: 1050,
+    // The portal layer is pointer-events: none so clicks fall through it;
+    // the popup takes them back.
+    pointerEvents: 'auto',
+    outlineStyle: 'none',
   },
+  popupPosition: (top: number, left: number) => ({
+    top,
+    left,
+  }),
   item: {
     display: 'flex',
     alignItems: 'center',
@@ -79,8 +89,14 @@ export const styles = css.create({
     transitionProperty: 'background-color',
     transitionDuration: duration.fast,
   },
+  // The fill is the highlight; the transparent outline is what forced-colors
+  // mode paints, where fills are dropped.
   itemHighlighted: {
     backgroundColor: colors.bgCardHover,
+    outlineStyle: 'solid',
+    outlineWidth: borders.focusRing,
+    outlineColor: 'transparent',
+    outlineOffset: `calc(-1 * ${borders.focusRing})`,
   },
   separator: {
     height: 0,