@duro-app/ui 5.1.0 → 5.3.0

package/src/components/Menu/useMenuRoot.ts

@@ -1,48 +1,93 @@
-import {useState, useCallback, useRef, useId, useEffect} from 'react'
+import {useState, useCallback, useRef, useId, useEffect, useLayoutEffect} from 'react'
 import type {MenuContextValue} from './MenuContext'
+import {isOutsidePress} from '../Popover/outside'
 
-export function useMenuRoot() {
-  const [open, setOpen] = useState(false)
+export interface MenuRootOptions {
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+/**
+ * The menu-button pattern (WAI-ARIA APG): on open, focus moves to the
+ * `role="menu"` popup, which carries `aria-activedescendant`; arrows move the
+ * highlight; Escape closes and focus returns to the trigger. The keydown
+ * handler sits on the popup itself, never on `document`, so keys typed
+ * elsewhere (an editor) are never intercepted, and Escape stops there so an
+ * enclosing Popover or Dialog stays open.
+ */
+export function useMenuRoot({open: openProp, defaultOpen = false, onOpenChange}: MenuRootOptions) {
+  const [inner, setInner] = useState(defaultOpen)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : inner
   const [highlightedId, setHighlightedId] = useState<string | null>(null)
+  // Read by the keydown handler, so activating an item is not a side effect
+  // inside a state updater (React may run updaters twice).
+  const highlightedRef = useRef(highlightedId)
+  useLayoutEffect(() => {
+    highlightedRef.current = highlightedId
+  }, [highlightedId])
   const menuId = useId()
+  const triggerId = useId()
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const popupRef = useRef<HTMLDivElement | null>(null)
   const itemsRef = useRef(new Map<string, HTMLElement>())
   const orderRef = useRef<string[]>([])
-  const needsInitialHighlightRef = useRef(false)
+  const openRef = useRef(open)
+  openRef.current = open
+  const onOpenChangeRef = useRef(onOpenChange)
+  onOpenChangeRef.current = onOpenChange
 
-  const close = useCallback(() => {
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (next === openRef.current) return
+      if (!controlled) setInner(next)
+      onOpenChangeRef.current?.(next)
+    },
+    [controlled],
+  )
+
+  // Closes and leaves focus where it is (a press elsewhere put it there).
+  const dismiss = useCallback(() => {
+    if (!openRef.current) return
     setOpen(false)
     setHighlightedId(null)
-    needsInitialHighlightRef.current = false
+  }, [setOpen])
+
+  // Closes and puts focus back on the trigger.
+  const close = useCallback(() => {
+    if (!openRef.current) return
+    dismiss()
     triggerRef.current?.focus()
-  }, [])
+  }, [dismiss])
 
   const toggle = useCallback(() => {
-    setOpen((prev) => {
-      if (!prev) {
-        needsInitialHighlightRef.current = true
-      } else {
-        setHighlightedId(null)
-        needsInitialHighlightRef.current = false
-      }
-      return !prev
-    })
-  }, [])
+    if (openRef.current) close()
+    else setOpen(true)
+  }, [close, setOpen])
 
-  // Highlight the first item after items register on open.
-  // Child effects (item registration) run before this parent effect,
-  // so orderRef is populated by the time this runs.
+  // On open: focus the menu and highlight the first item. Child effects (item
+  // registration) run before this parent effect, so orderRef is populated.
+  const wasOpenRef = useRef(false)
   useEffect(() => {
-    if (open && needsInitialHighlightRef.current) {
-      needsInitialHighlightRef.current = false
-      const order = orderRef.current
-      if (order.length > 0) {
-        setHighlightedId(order[0])
-      }
+    if (open && !wasOpenRef.current) {
+      popupRef.current?.focus({preventScroll: true})
+      const first = orderRef.current[0]
+      if (first) setHighlightedId(first)
+    } else if (!open && wasOpenRef.current) {
+      setHighlightedId(null)
     }
+    wasOpenRef.current = open
   }, [open])
 
+  // Keep the highlighted item in view when the popup scrolls.
+  useEffect(() => {
+    if (!highlightedId) return
+    const el = itemsRef.current.get(highlightedId)
+    el?.scrollIntoView?.({block: 'nearest'})
+  }, [highlightedId])
+
   const registerItem = useCallback((id: string, element: HTMLElement) => {
     itemsRef.current.set(id, element)
     const map = itemsRef.current
@@ -60,12 +105,24 @@ export function useMenuRoot() {
     }
   }, [])
 
-  // Native keydown for full KeyboardEvent access (preventDefault)
+  // Native keydown on the popup element, for full KeyboardEvent access.
   useEffect(() => {
-    const root = rootRef.current
-    if (!root || !open) return
+    const popup = popupRef.current
+    if (!popup || !open) return
 
     function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        e.stopPropagation()
+        close()
+        return
+      }
+      if (e.key === 'Tab') {
+        // Back on the trigger before the browser moves focus, so Tab and
+        // Shift+Tab continue from where the menu was opened.
+        close()
+        return
+      }
       const order = orderRef.current
       if (order.length === 0) return
 
@@ -99,41 +156,41 @@ export function useMenuRoot() {
         case 'Enter':
         case ' ': {
           e.preventDefault()
-          const items = itemsRef.current
-          setHighlightedId((prev) => {
-            if (prev) {
-              const el = items.get(prev)
-              el?.click()
-            }
-            return prev
-          })
-          break
-        }
-        case 'Escape': {
-          e.preventDefault()
-          close()
-          break
-        }
-        case 'Tab': {
-          close()
+          const current = highlightedRef.current
+          if (current) itemsRef.current.get(current)?.click()
           break
         }
       }
     }
 
-    root.addEventListener('keydown', handleKeyDown)
-    return () => root.removeEventListener('keydown', handleKeyDown)
+    popup.addEventListener('keydown', handleKeyDown)
+    return () => popup.removeEventListener('keydown', handleKeyDown)
   }, [open, close])
 
+  // A press outside the trigger and the popup closes the menu, and leaves
+  // focus where the press put it.
+  useEffect(() => {
+    if (!open) return
+    function onPointerDown(e: PointerEvent) {
+      if (isOutsidePress(e.target as Node | null, [popupRef.current, triggerRef.current])) {
+        dismiss()
+      }
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => document.removeEventListener('pointerdown', onPointerDown, true)
+  }, [open, dismiss])
+
   const ctx: MenuContextValue = {
     open,
     toggle,
     close,
     menuId,
+    triggerId,
     highlightedId,
     setHighlightedId,
     registerItem,
     triggerRef,
+    popupRef,
   }
 
   return {ctx, rootRef}

package/src/components/Popover/Popover.tsx

@@ -19,6 +19,10 @@ import {styles} from './styles.css'
 import {computePopoverPosition, type PopoverAlign, type PopoverSide} from './position'
 import {isOutsidePress} from './outside'
 import {PopoverLayerContext, type PopoverLayerContextValue} from './PopoverLayerContext'
+import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
+import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
+import {mergeRefs} from '../../shared/mergeRefs'
+import {useInModal} from '../../shared/ModalContext'
 
 // --- Context ---
 
@@ -193,18 +197,30 @@ function Root({
 // --- Trigger ---
 // Trigger IS the button (like Menu.Trigger): give it a label, not a Button.
 
-function Trigger({children}: {children: ReactNode}) {
+interface TriggerProps {
+  children: ReactNode
+  /** Accessible name: required when the label is an icon only. */
+  'aria-label'?: string
+  /** The trigger <button>, e.g. to measure it or return focus to it. */
+  ref?: Ref<HTMLButtonElement>
+}
+
+function Trigger({children, 'aria-label': ariaLabel, ref}: TriggerProps) {
   const {open, setOpen, popoverId, triggerRef} = usePopover('Trigger')
+  const grouped = useGroupedControl<HTMLButtonElement>()
 
   return (
     <html.button
-      ref={triggerRef}
+      ref={mergeRefs(triggerRef, grouped.ref, ref)}
+      tabIndex={grouped.tabIndex}
+      onFocus={grouped.onFocus}
       type="button"
       onClick={() => setOpen(!open)}
+      aria-label={ariaLabel}
       aria-haspopup="dialog"
       aria-expanded={open}
       aria-controls={open ? popoverId : undefined}
-      style={styles.trigger}
+      style={[styles.trigger, grouped.style]}
     >
       {children}
     </html.button>
@@ -226,6 +242,7 @@ function Popup({children, label}: PopupProps) {
   // Inside ThemeProvider's portal layer, like Select/Dialog/Drawer: theme
   // tokens cascade into the popup and it stacks above dialogs.
   const mount = usePortalMount()
+  const inModal = useInModal()
 
   // Measure before paint on open; re-measure on scroll/resize (capture phase
   // catches any scrolling ancestor) and when Root.reposition() is called.
@@ -271,9 +288,13 @@ function Popup({children, label}: PopupProps) {
       role="dialog"
       aria-label={label}
       tabIndex={-1}
-      style={[styles.popup, styles.popupPosition(coords.top, coords.left)]}
+      style={[
+        styles.popup,
+        inModal && styles.popupInModal,
+        styles.popupPosition(coords.top, coords.left),
+      ]}
     >
-      {children}
+      <ControlContextBoundary>{children}</ControlContextBoundary>
     </html.div>,
     mount ?? document.body,
   )

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

@@ -5,6 +5,7 @@ import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {duration} from '@duro-app/tokens/tokens/motion.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
 
 export const styles = css.create({
   trigger: {
@@ -30,6 +31,11 @@ export const styles = css.create({
     transitionProperty: 'background-color, border-color',
     transitionDuration: duration.fast,
   },
+  // Inside a Dialog or Drawer: above that modal (same portal mount), below a
+  // Select or Menu opened from inside the Popover.
+  popupInModal: {
+    zIndex: layers.popover,
+  },
   popup: {
     position: 'fixed',
     top: 0,
@@ -45,7 +51,9 @@ export const styles = css.create({
     fontFamily: typography.fontFamily,
     fontSize: typography.fontSizeSm,
     color: colors.text,
-    zIndex: 50,
+    // Outside a modal: floating chrome, so a Dialog or Drawer opened later
+    // (even from inside this Popover) covers it.
+    zIndex: layers.floating,
     // The portal layer is pointer-events: none so clicks fall through it;
     // the popup takes them back.
     pointerEvents: 'auto',

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

@@ -3,6 +3,7 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {microSpacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
 import {sizes} from '@duro-app/tokens/tokens/sizes.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
 
 export const styles = css.create({
   root: {
@@ -23,7 +24,7 @@ export const styles = css.create({
   },
   scrollbar: {
     position: 'absolute',
-    zIndex: 1,
+    zIndex: layers.raised,
     display: 'flex',
     touchAction: 'none',
     userSelect: 'none',

package/src/components/Select/Select.stories.tsx

@@ -1,5 +1,5 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, fn, screen} from 'storybook/test'
+import {expect, screen} from 'storybook/test'
 import {Dialog} from '../Dialog/Dialog'
 import {Select} from './Select'
 
@@ -194,3 +194,22 @@ export const InsideDialog: Story = {
     await expect(listbox.closest('[role="dialog"]')).toBeNull()
   },
 }
+
+/** Closed, the trigger opens on ArrowDown or ArrowUp, on the selected option (5.3). */
+export const ArrowKeysOpen: Story = {
+  render: Default.render,
+  play: async ({canvas, userEvent}) => {
+    const trigger = canvas.getByRole('combobox')
+    trigger.focus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    await expect(trigger).toHaveFocus()
+    const selected = screen.getByRole('option', {name: 'English'})
+    await expect(trigger).toHaveAttribute('aria-activedescendant', selected.id)
+    await userEvent.keyboard('{Escape}')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    await userEvent.keyboard('{Escape}')
+  },
+}

package/src/components/Select/Select.tsx

@@ -7,6 +7,9 @@ import {useSelectRoot} from './useSelectRoot'
 import {useFieldContext} from '../Field/FieldContext'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
 import {usePopoverLayer} from '../Popover/PopoverLayerContext'
+import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
+import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
+import {mergeRefs} from '../../shared/mergeRefs'
 
 // --- Root ---
 interface RootProps {
@@ -41,6 +44,7 @@ function Trigger({
 }) {
   const {open, toggle, listboxId, highlightedId, triggerRef} = useSelect()
   const localRef = useRef<HTMLButtonElement>(null)
+  const grouped = useGroupedControl<HTMLButtonElement>()
   // Inside a <Field.Root>, adopt its controlId so <Field.Label for={controlId}>
   // labels the trigger (a labelable <button>) — no manual aria-label needed; and
   // surface the field's description/error + invalid state, mirroring <Input>.
@@ -56,7 +60,9 @@ function Trigger({
 
   return (
     <html.button
-      ref={localRef}
+      ref={mergeRefs(localRef, grouped.ref)}
+      tabIndex={grouped.tabIndex}
+      onFocus={grouped.onFocus}
       id={fieldCtx?.controlId}
       type="button"
       role={'combobox' as 'listbox'}
@@ -68,7 +74,7 @@ function Trigger({
       aria-activedescendant={highlightedId ?? undefined}
       aria-describedby={describedBy || undefined}
       aria-invalid={fieldCtx?.invalid || undefined}
-      style={styles.trigger}
+      style={[styles.trigger, grouped.style]}
     >
       {children}
     </html.button>
@@ -161,7 +167,7 @@ function Popup({children}: {children: ReactNode}) {
           coords && styles.popupPosition(coords.top, coords.left, coords.width),
         ]}
       >
-        {children}
+        <ControlContextBoundary>{children}</ControlContextBoundary>
       </html.div>
     </>
   )

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

@@ -6,6 +6,7 @@ import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {duration} 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'
 
 export const styles = css.create({
   root: {
@@ -55,7 +56,7 @@ export const styles = css.create({
     bottom: 0,
     // Above Dialog/Drawer (1000/1001): they portal into the same mount, so a
     // popup opened from inside a dialog must out-rank the dialog itself.
-    zIndex: 1049,
+    zIndex: layers.popupBackdrop,
     // The portal mount is pointer-events: none, so re-enable here to catch
     // outside clicks that close the popup.
     pointerEvents: 'auto',
@@ -76,7 +77,7 @@ export const styles = css.create({
     minWidth: sizes.labelMinW,
     maxHeight: sizes.listMaxH,
     overflowY: 'auto',
-    zIndex: 1050,
+    zIndex: layers.popup,
     // Re-enable pointer events: the portal mount is pointer-events: none.
     pointerEvents: 'auto',
   },

package/src/components/Select/useSelectRoot.ts

@@ -80,6 +80,23 @@ export function useSelectRoot({
     }
   }, [])
 
+  // Closed: ArrowDown/ArrowUp on the trigger open the listbox (the APG
+  // select-only combobox), on the selected option or the first. In a Toolbar
+  // this is why a closed Select keeps those keys; Left/Right still move on.
+  useEffect(() => {
+    const root = rootRef.current
+    if (!root || open) return
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.target !== triggerRef.current) return
+      if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return
+      if (e.altKey || e.ctrlKey || e.metaKey) return
+      e.preventDefault()
+      toggle()
+    }
+    root.addEventListener('keydown', handleKeyDown)
+    return () => root.removeEventListener('keydown', handleKeyDown)
+  }, [open, toggle])
+
   // Native keydown for full KeyboardEvent access (preventDefault)
   useEffect(() => {
     const root = rootRef.current

package/src/components/TextLink/TextLink.meta.ts

@@ -0,0 +1,33 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Inline hyperlink for running text and standalone text links ("View all", "Edit profile"). Always underlined, so colour is never the only cue: default is accent text with an accent underline; subtle keeps the surrounding text colour with a muted underline and turns accent on hover. target="_blank" defaults rel to noopener noreferrer.',
+  whenToUse: [
+    'A link inside a sentence or paragraph',
+    'A standalone text link under a list or card ("View all requests")',
+    'A quiet link in dense UI (variant="subtle")',
+  ],
+  whenNotToUse: [
+    'A link that should look like a button — use LinkButton',
+    'An action that does not navigate — use Button (variant="link" for a text-styled action)',
+    'A link inside a dropdown — use Menu.LinkItem',
+  ],
+  relatedTo: [
+    {
+      component: 'LinkButton',
+      kind: 'contrast',
+      relationship:
+        'LinkButton is a hyperlink styled as a button; TextLink is a hyperlink styled as text',
+    },
+    {
+      component: 'Button',
+      kind: 'contrast',
+      relationship: 'Button runs an action; TextLink navigates',
+    },
+  ],
+  example: `<Text>
+  Read the <TextLink href="/docs/migrate">migration guide</TextLink> before you change seats, or{' '}
+  <TextLink href="/plans" variant="subtle">compare plans</TextLink> first.
+</Text>`,
+}

package/src/components/TextLink/TextLink.stories.tsx

@@ -0,0 +1,63 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {TextLink} from './TextLink'
+import {Text} from '../Text/Text'
+import {Inline} from '../Inline/Inline'
+
+const meta: Meta<typeof TextLink> = {
+  title: 'Components/TextLink',
+  component: TextLink,
+  args: {href: '#guide', children: 'migration guide'},
+}
+
+export default meta
+type Story = StoryObj<typeof TextLink>
+
+export const InRunningText: Story = {
+  render: () => (
+    <Text>
+      Your workspace moved to the new plan. Read the{' '}
+      <TextLink href="#guide">migration guide</TextLink> before you change seats, or{' '}
+      <TextLink href="#plans" variant="subtle">
+        compare plans
+      </TextLink>{' '}
+      first.
+    </Text>
+  ),
+  play: async ({canvas}) => {
+    for (const name of ['migration guide', 'compare plans']) {
+      const link = canvas.getByRole('link', {name})
+      // Underlined in both variants: colour is never the only cue.
+      await expect(getComputedStyle(link).textDecorationLine).toContain('underline')
+    }
+  },
+}
+
+export const Standalone: Story = {
+  render: () => (
+    <Inline gap="lg">
+      <TextLink href="#all">View all requests</TextLink>
+      <TextLink href="#profile" variant="subtle">
+        Edit profile
+      </TextLink>
+      <TextLink href="https://example.com/docs" target="_blank">
+        Documentation
+      </TextLink>
+    </Inline>
+  ),
+  play: async ({canvas}) => {
+    const external = canvas.getByRole('link', {name: 'Documentation'})
+    await expect(external).toHaveAttribute('target', '_blank')
+    await expect(external).toHaveAttribute('rel', 'noopener noreferrer')
+  },
+}
+
+export const KeyboardFocus: Story = {
+  render: () => <TextLink href="#billing">Billing settings</TextLink>,
+  play: async ({canvas, userEvent}) => {
+    await userEvent.tab()
+    const link = canvas.getByRole('link', {name: 'Billing settings'})
+    await expect(link).toHaveFocus()
+    await expect(getComputedStyle(link).outlineStyle).toBe('solid')
+  },
+}

package/src/components/TextLink/TextLink.tsx

@@ -0,0 +1,46 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+
+export type TextLinkVariant = 'default' | 'subtle'
+
+interface TextLinkProps {
+  href: string
+  /** `_blank` opens a new tab; `rel` then defaults to `noopener noreferrer`. */
+  target?: '_blank' | '_self'
+  rel?: string
+  /**
+   * `default`: accent text with an accent underline. `subtle`: the
+   * surrounding text colour with a muted underline, accent on hover. Both
+   * stay underlined, so colour is never the only cue in running text.
+   */
+  variant?: TextLinkVariant
+  /** Accessible name, when the visible text alone does not say where it goes. */
+  'aria-label'?: string
+  children: ReactNode
+}
+
+/**
+ * An inline hyperlink in running text or a standalone "View all" link. For a
+ * link that looks like a button, use LinkButton.
+ */
+export function TextLink({
+  href,
+  target,
+  rel,
+  variant = 'default',
+  'aria-label': ariaLabel,
+  children,
+}: TextLinkProps) {
+  return (
+    <html.a
+      href={href}
+      target={target}
+      rel={rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)}
+      aria-label={ariaLabel}
+      style={[styles.base, styles[variant]]}
+    >
+      {children}
+    </html.a>
+  )
+}

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

@@ -0,0 +1,58 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {radii} from '@duro-app/tokens/tokens/spacing.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+
+// Direction "Underlined" (docs/mockups/text-link/Underlined.dc.html): the
+// underline is always there, so colour is never the only cue (WCAG F73).
+export const styles = css.create({
+  base: {
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    lineHeight: 'inherit',
+    cursor: 'pointer',
+    textDecorationLine: 'underline',
+    textDecorationStyle: 'solid',
+    borderRadius: radii.xs,
+    transitionProperty: 'color, text-decoration-color',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: easing.standard,
+    outlineWidth: {
+      default: 0,
+      ':focus-visible': borders.focusRing,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':focus-visible': 'solid',
+    },
+    outlineColor: {
+      default: 'transparent',
+      ':focus-visible': colors.accent,
+    },
+    outlineOffset: {
+      default: 0,
+      ':focus-visible': borders.focusOffset,
+    },
+  },
+  default: {
+    color: {
+      default: colors.accent,
+      ':hover': colors.accentHover,
+    },
+    textDecorationColor: {
+      default: colors.accent,
+      ':hover': colors.accentHover,
+    },
+  },
+  subtle: {
+    color: {
+      default: 'inherit',
+      ':hover': colors.accent,
+    },
+    textDecorationColor: {
+      default: colors.textMuted,
+      ':hover': colors.accent,
+    },
+  },
+})