@duro-app/ui 5.0.0 → 5.2.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/StatusIcon/StatusIcon.stories.tsx

@@ -1,10 +1,10 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {StatusIcon} from './StatusIcon'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 const meta: Meta<typeof StatusIcon> = {
   title: 'Components/StatusIcon',
@@ -52,7 +52,7 @@ export const CustomSize: Story = {
 const gridStyles = css.create({
   grid: {
     display: 'grid',
-    gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))',
+    gridTemplateColumns: `repeat(auto-fill, minmax(${sizes.gridColSm}, 1fr))`,
     gap: spacing.lg,
   },
   cell: {display: 'flex', flexDirection: 'column', alignItems: 'center', gap: spacing.sm},

package/src/components/Table/Table.stories.tsx

@@ -1293,3 +1293,42 @@ export const CardsBelowMobileBreakpoint: Story = {
     await expect(getComputedStyle(ownerLabel).display).toBe('block')
   },
 }
+
+// A column width can carry a size token inside a track function: resolveTrack
+// turns `minmax(gridColSm, 1fr)` into `minmax(var(--…), 1fr)` (ADR-0027).
+export const TokenColumnWidths: Story = {
+  name: 'Token column widths',
+  render: () => (
+    <html.div style={respStyles.scrollDense}>
+      <Table.Root>
+        <Table.Header>
+          <Table.Row>
+            <Table.HeaderCell width="minmax(gridColSm, 1fr)">Name</Table.HeaderCell>
+            <Table.HeaderCell width="fit-content(labelMinW)">Owner</Table.HeaderCell>
+            <Table.HeaderCell width="iconButton">Act</Table.HeaderCell>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>SMTP submission service account</Table.Cell>
+            <Table.Cell>{LONG_EMAIL}</Table.Cell>
+            <Table.Cell>x</Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table.Root>
+    </html.div>
+  ),
+  play: async ({canvasElement}) => {
+    await waitFor(() =>
+      expect(canvasElement.querySelectorAll('[role="columnheader"]')).toHaveLength(3),
+    )
+    const headers = [...canvasElement.querySelectorAll('[role="columnheader"]')]
+    const [name, owner, act] = headers.map((h) => h.getBoundingClientRect().width)
+    // minmax(gridColSm, 1fr): at least 240px and takes the slack.
+    await expect(name).toBeGreaterThanOrEqual(240)
+    // fit-content(labelMinW): capped at 120px even with a long email inside.
+    await expect(owner).toBeLessThanOrEqual(120.5)
+    // iconButton: exactly 32px.
+    await expect(Math.abs(act! - 32)).toBeLessThanOrEqual(0.5)
+  },
+}

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

package/src/components/ThemeProvider/ThemeProvider.stories.tsx

@@ -163,3 +163,53 @@ export const AllThemes: Story = {
     await expect(canvas.getByText('high-contrast')).toBeInTheDocument()
   },
 }
+
+const contrastStyles = css.create({
+  surface: {
+    padding: spacing.md,
+    borderRadius: radii.md,
+    backgroundColor: colors.contrastSurface,
+    color: colors.onContrastSurface,
+  },
+})
+
+/** Parse a computed `rgb(r, g, b)` / `rgba(r, g, b, a)` colour. */
+function rgbOf(value: string): [number, number, number] {
+  const parts = value.match(/\d+(\.\d+)?/g)?.map(Number) ?? []
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0]
+}
+
+/** WCAG 2.x relative luminance contrast ratio. */
+function contrastRatio(a: string, b: string): number {
+  const lum = (rgb: [number, number, number]) => {
+    const [r, g, bl] = rgb.map((c) => {
+      const s = c / 255
+      return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+    }) as [number, number, number]
+    return 0.2126 * r + 0.7152 * g + 0.0722 * bl
+  }
+  const [hi, lo] = [lum(rgbOf(a)), lum(rgbOf(b))].sort((x, y) => y - x) as [number, number]
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+// contrastSurface takes the opposite tone of the theme; its text must still
+// read at 4.5:1 or better in each one.
+export const ContrastSurfaceInEveryTheme: Story = {
+  render: () => (
+    <html.div style={sideBySideStyles.wrapper}>
+      {(['dark', 'light', 'high-contrast'] as const).map((theme) => (
+        <ThemeProvider key={theme} theme={theme}>
+          <html.div style={contrastStyles.surface}>{`Contrast surface (${theme})`}</html.div>
+        </ThemeProvider>
+      ))}
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    for (const theme of ['dark', 'light', 'high-contrast']) {
+      const el = canvas.getByText(`Contrast surface (${theme})`)
+      const style = getComputedStyle(el)
+      const ratio = contrastRatio(style.color, style.backgroundColor)
+      await expect(ratio).toBeGreaterThanOrEqual(4.5)
+    }
+  },
+}

package/src/components/VisuallyHidden/VisuallyHidden.meta.ts

@@ -0,0 +1,19 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Text for assistive tech only: kept in the accessibility tree, clipped off screen. Gives words to an icon-only control or a visual-only cue.',
+  whenToUse: [
+    'A label for an icon inside a control that has no aria-label prop',
+    'Spelling out what a colour or icon shows (a status dot, "(opens in a new tab)")',
+    'A heading that structures a page for screen readers without a visible title',
+  ],
+  whenNotToUse: [
+    'Naming a control that takes aria-label — pass aria-label instead',
+    'Hiding content from everyone — render nothing, or use display: none',
+  ],
+  example: `<Button variant="secondary">
+  <Icon name="search" size="sm" />
+  <VisuallyHidden>Search</VisuallyHidden>
+</Button>`,
+}

package/src/components/VisuallyHidden/VisuallyHidden.stories.tsx

@@ -0,0 +1,30 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {expect} from 'storybook/test'
+import {VisuallyHidden} from './VisuallyHidden'
+import {Button} from '../Button/Button'
+import {Icon} from '../Icon/Icon'
+
+const meta: Meta<typeof VisuallyHidden> = {
+  title: 'Components/VisuallyHidden',
+  component: VisuallyHidden,
+}
+
+export default meta
+type Story = StoryObj<typeof VisuallyHidden>
+
+export const NamesAnIconButton: Story = {
+  render: () => (
+    <Button variant="secondary">
+      <Icon name="search" size="sm" />
+      <VisuallyHidden>Search</VisuallyHidden>
+    </Button>
+  ),
+  play: async ({canvas}) => {
+    const button = canvas.getByRole('button', {name: 'Search'})
+    await expect(button).toBeInTheDocument()
+    const text = canvas.getByText('Search')
+    const box = text.getBoundingClientRect()
+    await expect(box.width).toBeLessThanOrEqual(1)
+    await expect(box.height).toBeLessThanOrEqual(1)
+  },
+}

package/src/components/VisuallyHidden/VisuallyHidden.tsx

@@ -0,0 +1,22 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {visuallyHidden} from '../../styles/visually-hidden.css'
+
+interface VisuallyHiddenProps {
+  children: ReactNode
+  /** For aria-describedby / aria-labelledby to point at. */
+  id?: string
+}
+
+/**
+ * Text for assistive tech only: in the accessibility tree, not on screen. Use
+ * it to give an icon-only control or a visual-only cue words — a status a
+ * colour shows, "(opens in a new tab)" after a link.
+ */
+export function VisuallyHidden({children, id}: VisuallyHiddenProps) {
+  return (
+    <html.span id={id} style={[visuallyHidden.base, visuallyHidden.text]}>
+      {children}
+    </html.span>
+  )
+}