@duro-app/ui 4.3.0 → 4.5.0

package/src/components/Toggle/Toggle.tsx

@@ -1,4 +1,4 @@
-import {type ReactNode, useCallback} from 'react'
+import {type ReactNode, useCallback, useLayoutEffect, useRef} from 'react'
 import {html} from 'react-strict-dom'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {useToggleGroup} from '../ToggleGroup/ToggleGroupContext'
@@ -23,6 +23,11 @@ interface ToggleProps {
   children: ReactNode
 }
 
+const wrappedSizeMap = {
+  default: styles.wrappedDefault,
+  small: styles.wrappedSmall,
+} as const
+
 const sizeMap = {
   default: styles.sizeDefault,
   small: styles.sizeSmall,
@@ -46,6 +51,14 @@ export function Toggle({
   const disabled = disabledProp || (group?.disabled ?? false)
   const size = group?.size ?? sizeProp
 
+  const wrap = group?.wrap ?? false
+  const ref = useRef<HTMLButtonElement>(null)
+  const register = group?.register
+  useLayoutEffect(() => {
+    if (!wrap || !register || value === undefined || !ref.current) return
+    return register(value, ref.current)
+  }, [wrap, register, value])
+
   const [standalonePressed, setStandalonePressed] = useControllableValue(
     controlledPressed,
     defaultPressed,
@@ -65,7 +78,10 @@ export function Toggle({
 
   return (
     <html.button
+      ref={ref}
       type="button"
+      tabIndex={wrap && value !== undefined ? (group?.tabStopValue === value ? 0 : -1) : undefined}
+      onFocus={wrap && value !== undefined ? () => group?.onItemFocus(value) : undefined}
       aria-pressed={pressed}
       aria-label={ariaLabel}
       disabled={disabled}
@@ -75,7 +91,8 @@ export function Toggle({
         styles.base,
         sizeMap[size],
         pressed ? styles.pressed : styles.unpressed,
-        isGrouped && styles.grouped,
+        wrap && wrappedSizeMap[size],
+        isGrouped && !wrap && styles.grouped,
         disabled && styles.disabled,
       ]}
     >

package/src/components/Toggle/rowHeight.ts

@@ -0,0 +1,12 @@
+/**
+ * The fixed block size of a Toggle in a wrapping group, per size, and under a
+ * coarse pointer. One source for ToggleGroup's `maxRows` arithmetic and the
+ * stories that measure it.
+ *
+ * holds-until: StyleX can import a constant into a static style. Toggle's
+ * `styles.css.ts` must repeat these numbers in its `wrapped*` heights. The
+ * ToggleGroup stories (small, default) and the Drawer coarse-pointer story
+ * measure a rendered toggle against this module to ±0.5px, so a drift in
+ * either file fails a test rather than a layout.
+ */
+export const ROW_HEIGHT = {small: 28, default: 39, coarse: 44} as const

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

@@ -21,6 +21,8 @@ export const styles = css.create({
     outlineStyle: 'solid',
     outlineColor: colors.accent,
     outlineOffset: 2,
+    minWidth: {default: null, '@media (pointer: coarse)': 44},
+    minHeight: {default: null, '@media (pointer: coarse)': 44},
   },
   sizeDefault: {
     padding: `${spacing.sm} ${spacing.md}`,
@@ -34,6 +36,16 @@ export const styles = css.create({
     borderRadius: radii.sm,
     gap: spacing.xs,
   },
+  // wrapped toggles: a fixed block size per size, 44px under a coarse pointer.
+  // Must equal ROW_HEIGHT in ./rowHeight (StyleX cannot import it here).
+  wrappedDefault: {
+    boxSizing: 'border-box',
+    height: {default: 39, '@media (pointer: coarse)': 44},
+  },
+  wrappedSmall: {
+    boxSizing: 'border-box',
+    height: {default: 28, '@media (pointer: coarse)': 44},
+  },
   unpressed: {
     backgroundColor: {
       default: 'transparent',

package/src/components/ToggleGroup/ToggleGroup.meta.ts

@@ -6,10 +6,11 @@ export const meta: ComponentMeta = {
   whenToUse: [
     'Visible option set where user picks one or more (view mode, filter categories)',
     'Segmented control pattern',
+    'A visible grid of icon choices: wrap + maxRows (rows scroll past maxRows, one tab stop with arrow keys, 44px touch targets)',
   ],
   whenNotToUse: [
     'Dropdown selection — use Select',
-    'Many options (5+) — use Select for space efficiency',
+    'Many text options (5+) — use Select for space efficiency; does not apply to icon-only choices, which keep options visible and open no layer',
     'Form checkboxes — use Checkbox group in Fieldset',
   ],
   relatedTo: [
@@ -30,5 +31,14 @@ export const meta: ComponentMeta = {
   <Toggle value="list">List view</Toggle>
   <Toggle value="grid">Grid view</Toggle>
   <Toggle value="board">Board view</Toggle>
+</ToggleGroup>
+
+// Icon choices: wraps onto rows, scrolls past three, one tab stop
+<ToggleGroup wrap maxRows={3} size="small" value={[icon]} onValueChange={(v) => v[0] && setIcon(v[0])} aria-label="Icon">
+  {names.map((name) => (
+    <Toggle key={name} value={name} aria-label={name}>
+      <Icon name={name} size="sm" />
+    </Toggle>
+  ))}
 </ToggleGroup>`,
 }

package/src/components/ToggleGroup/ToggleGroup.stories.tsx

@@ -3,6 +3,8 @@ import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {ToggleGroup} from './ToggleGroup'
 import {Toggle} from '../Toggle/Toggle'
+import {Icon, type IconName} from '../Icon'
+import {ROW_HEIGHT} from '../Toggle/rowHeight'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta<typeof ToggleGroup> = {
@@ -158,3 +160,157 @@ export const AllVariants: Story = {
     await expect(groups.length).toBe(4)
   },
 }
+
+const ICON_NAMES: IconName[] = [
+  'x-circle',
+  'check-circle',
+  'check-done',
+  'clock',
+  'forbidden',
+  'info-circle',
+  'alert-triangle',
+  'shield',
+  'lock',
+  'key',
+  'map',
+  'layers',
+  'repeat',
+  'database',
+  'shield-check',
+  'route',
+  'git-branch',
+  'menu',
+  'pin',
+  'server',
+  'hard-drive',
+  'box',
+  'image',
+  'tag',
+  'pie-chart',
+  'users',
+  'user-plus',
+  'mail',
+  'file-text',
+  'plug',
+  'search',
+  'mic',
+  'sun',
+  'moon',
+  'monitor',
+  'contrast',
+  'info-circle-filled',
+  'alert-triangle-filled',
+  'check-circle-filled',
+  'x-circle-filled',
+  'shield-filled',
+  'lock-filled',
+]
+
+const iconStyles = css.create({
+  frame: {width: 320},
+})
+
+function IconChoices({
+  names,
+  pressed,
+  size = 'small',
+}: {
+  names: IconName[]
+  pressed: string
+  size?: 'small' | 'default'
+}) {
+  return (
+    <html.div style={iconStyles.frame}>
+      <ToggleGroup wrap maxRows={3} size={size} defaultValue={[pressed]} aria-label="Icon">
+        {names.map((name) => (
+          <Toggle key={name} value={name} aria-label={name}>
+            <Icon name={name} size="sm" />
+          </Toggle>
+        ))}
+      </ToggleGroup>
+    </html.div>
+  )
+}
+
+export const IconChoicesStory: Story = {
+  name: 'Icon choices',
+  render: () => <IconChoices names={ICON_NAMES} pressed={ICON_NAMES[39]} />,
+  play: async ({canvas, canvasElement}) => {
+    const scrollTopBefore = document.scrollingElement?.scrollTop
+    await expect(ICON_NAMES.length).toBe(42)
+    const viewport = canvasElement.querySelector<HTMLElement>('[data-duro-scroll]')!
+    await expect(Math.abs(viewport.clientHeight - 118)).toBeLessThanOrEqual(2)
+
+    const pressed = canvas.getByRole('button', {name: ICON_NAMES[39]})
+    const other = canvas.getByRole('button', {name: ICON_NAMES[0]})
+    await expect(pressed).toHaveAttribute('aria-pressed', 'true')
+    for (const el of [pressed, other]) {
+      const cs = getComputedStyle(el)
+      await expect(cs.borderTopWidth).toBe('1px')
+      await expect(cs.borderRightWidth).toBe('1px')
+      await expect(cs.borderBottomWidth).toBe('1px')
+      await expect(cs.borderLeftWidth).toBe('1px')
+      // radii.sm
+      await expect(cs.borderTopLeftRadius).toBe('8px')
+    }
+
+    // the pressed toggle is visible inside the viewport
+    const v = viewport.getBoundingClientRect()
+    const p = pressed.getBoundingClientRect()
+    await expect(p.top).toBeGreaterThanOrEqual(v.top - 1)
+    await expect(p.bottom).toBeLessThanOrEqual(v.bottom + 1)
+    await expect(document.scrollingElement?.scrollTop).toBe(scrollTopBefore)
+  },
+}
+
+export const FiveIcons: Story = {
+  name: 'Five icons',
+  render: () => <IconChoices names={ICON_NAMES.slice(0, 5)} pressed={ICON_NAMES[0]} />,
+  play: async ({canvas}) => {
+    const group = canvas.getByRole('toolbar')
+    await expect(group.getBoundingClientRect().height).toBe(ROW_HEIGHT.small)
+    // exact: Toggle's styles repeat ROW_HEIGHT, and a drift must fail here
+    const toggle = canvas.getAllByRole('button')[0].getBoundingClientRect()
+    await expect(Math.abs(toggle.height - ROW_HEIGHT.small)).toBeLessThanOrEqual(0.5)
+  },
+}
+
+export const KeyboardRoving: Story = {
+  render: () => <IconChoices names={ICON_NAMES} pressed={ICON_NAMES[3]} />,
+  play: async ({canvas, userEvent}) => {
+    const btn = (i: number) => canvas.getByRole('button', {name: ICON_NAMES[i]})
+    await userEvent.tab()
+    await expect(btn(3)).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(btn(4)).toHaveFocus()
+    await userEvent.keyboard('{ArrowLeft}{ArrowLeft}')
+    await expect(btn(2)).toHaveFocus()
+    // Down moves to the next row, Up back
+    const top = btn(2).getBoundingClientRect().top
+    await userEvent.keyboard('{ArrowDown}')
+    const active = document.activeElement as HTMLElement
+    await expect(active.getBoundingClientRect().top).toBeGreaterThan(top + 20)
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(btn(2)).toHaveFocus()
+    await userEvent.keyboard('{End}')
+    await expect(btn(41)).toHaveFocus()
+    await userEvent.keyboard('{Home}')
+    await expect(btn(0)).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(btn(0)).toHaveAttribute('aria-pressed', 'true')
+    // a second tab leaves the group
+    await userEvent.tab()
+    await expect(canvas.getAllByRole('button')).not.toContain(document.activeElement)
+  },
+}
+
+export const DefaultSizeRows: Story = {
+  name: 'Default size rows',
+  render: () => (
+    <IconChoices names={ICON_NAMES.slice(0, 5)} pressed={ICON_NAMES[0]} size="default" />
+  ),
+  play: async ({canvas}) => {
+    const toggle = canvas.getAllByRole('button')[0].getBoundingClientRect()
+    await expect(Math.abs(toggle.height - ROW_HEIGHT.default)).toBeLessThanOrEqual(0.5)
+  },
+}

package/src/components/ToggleGroup/ToggleGroup.tsx

@@ -1,9 +1,11 @@
-import {type ReactNode, useCallback} from 'react'
+import {type ReactNode, useCallback, useLayoutEffect, useRef} from 'react'
 import {html} from 'react-strict-dom'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import type {ToggleSize} from '../Toggle/Toggle'
 import {ToggleGroupContext, type Orientation} from './ToggleGroupContext'
 import {useFieldGroupLabelling} from '../Field/FieldContext'
+import {ScrollArea} from '../ScrollArea/ScrollArea'
+import {useRovingFocus} from './useRovingFocus'
 import {styles} from './styles.css'
 
 interface ToggleGroupProps {
@@ -21,6 +23,16 @@ interface ToggleGroupProps {
   orientation?: Orientation
   /** Size applied to all child toggles. */
   size?: ToggleSize
+  /** Items wrap onto rows, each with its own border (default false). Enables
+   *  roving focus: one tab stop, arrow keys move between items. */
+  wrap?: boolean
+  // holds-until: the registry generator (packages/cli/scripts) reads a
+  // discriminated union. `{wrap?: false; maxRows?: never} | {wrap: true;
+  // maxRows?: number}` is the right type, but today it drops both props from
+  // the registry the CLI and MCP serve.
+  /** Caps a wrapping group at this many rows (plus half a row, hinting more)
+   *  and scrolls the rest. Only with `wrap`; ignored without it. */
+  maxRows?: number
   /** Accessible name when the group is not inside a Field.Root (inside one,
    *  the Field.Label names it). */
   'aria-label'?: string
@@ -37,6 +49,8 @@ export function ToggleGroup({
   disabled = false,
   orientation = 'horizontal',
   size = 'default',
+  wrap = false,
+  maxRows,
   children,
   ...labelling
 }: ToggleGroupProps) {
@@ -57,16 +71,79 @@ export function ToggleGroup({
     [value, multiple, setValue],
   )
 
+  const rootRef = useRef<HTMLDivElement>(null)
+  const roving = useRovingFocus({enabled: wrap, pressed: value, rootRef})
+  const scrolls = wrap && maxRows !== undefined
+  const pressedValue = value[0]
+
+  // bring the pressed toggle into view by moving the viewport itself, never
+  // scrollIntoView, which would scroll the page too
+  const {items} = roving
+  useLayoutEffect(() => {
+    if (!scrolls || pressedValue === undefined) return
+    const viewport = rootRef.current?.closest<HTMLElement>('[data-duro-scroll]')
+    if (!viewport) return
+    // Measured against the viewport's own box, not offsetTop: a positioned
+    // ancestor (a Drawer panel) would otherwise be the reference.
+    const centre = () => {
+      const el = items.current.get(pressedValue)
+      if (!el || viewport.clientHeight === 0) return false
+      const top =
+        el.getBoundingClientRect().top - viewport.getBoundingClientRect().top + viewport.scrollTop
+      const centered = top - (viewport.clientHeight - el.offsetHeight) / 2
+      const max = viewport.scrollHeight - viewport.clientHeight
+      viewport.scrollTop = Math.min(Math.max(centered, 0), Math.max(max, 0))
+      return true
+    }
+    if (centre()) return
+    // Not laid out yet (a container still opening): centre once it has a size.
+    const observer = new ResizeObserver(() => {
+      if (centre()) observer.disconnect()
+    })
+    observer.observe(viewport)
+    return () => observer.disconnect()
+  }, [scrolls, pressedValue, items])
+
+  const group = (
+    <html.div
+      ref={rootRef}
+      role="toolbar"
+      aria-orientation={orientation}
+      {...a11y}
+      style={[styles.root, orientation === 'vertical' && styles.vertical, wrap && styles.wrap]}
+    >
+      {children}
+    </html.div>
+  )
+
   return (
-    <ToggleGroupContext.Provider value={{value, toggle, disabled, orientation, size}}>
-      <html.div
-        role="toolbar"
-        aria-orientation={orientation}
-        {...a11y}
-        style={[styles.root, orientation === 'vertical' && styles.vertical]}
-      >
-        {children}
-      </html.div>
+    <ToggleGroupContext.Provider
+      value={{
+        value,
+        toggle,
+        disabled,
+        orientation,
+        size,
+        wrap,
+        tabStopValue: roving.tabStopValue,
+        register: roving.register,
+        onItemFocus: roving.onItemFocus,
+      }}
+    >
+      {scrolls ? (
+        <ScrollArea.Root>
+          <ScrollArea.Viewport
+            rovingOwner
+            style={size === 'small' ? styles.maxRowsSmall(maxRows) : styles.maxRowsDefault(maxRows)}
+          >
+            <ScrollArea.Content>
+              <html.div style={styles.scrollContent}>{group}</html.div>
+            </ScrollArea.Content>
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      ) : (
+        group
+      )}
     </ToggleGroupContext.Provider>
   )
 }

package/src/components/ToggleGroup/ToggleGroupContext.ts

@@ -10,6 +10,12 @@ export interface ToggleGroupContextValue {
   disabled: boolean
   orientation: Orientation
   size: ToggleSize
+  /** Items wrap onto rows with their own borders (and roving focus). */
+  wrap: boolean
+  /** The item holding the group's single tab stop (wrap only). */
+  tabStopValue: string | null
+  register: (itemValue: string, el: HTMLElement) => () => void
+  onItemFocus: (itemValue: string) => void
 }
 
 export const ToggleGroupContext = createContext<ToggleGroupContextValue | null>(null)

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

@@ -1,6 +1,7 @@
 import {css} from 'react-strict-dom'
+import {ROW_HEIGHT} from '../Toggle/rowHeight'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
-import {radii} from '@duro-app/tokens/tokens/spacing.css'
+import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 export const styles = css.create({
   root: {
@@ -11,6 +12,34 @@ export const styles = css.create({
     borderColor: colors.border,
     overflow: 'hidden',
   },
+  wrap: {
+    display: 'flex',
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: spacing.xs,
+    borderWidth: 0,
+    borderRadius: 0,
+    overflow: 'visible',
+  },
+  // the scroll content: room for focus rings to draw
+  scrollContent: {
+    position: 'relative',
+    padding: spacing.xs,
+  },
+  // shows rows + 0.5 rows so the cut-off row hints at more; shorter content
+  // sizes itself (max, not fixed). Row heights match the wrapped Toggles.
+  maxRowsSmall: (rows: number) => ({
+    maxHeight: {
+      default: `calc((${rows} + 0.5) * ${ROW_HEIGHT.small}px + ${rows} * ${spacing.xs} + 2 * ${spacing.xs})`,
+      '@media (pointer: coarse)': `calc((${rows} + 0.5) * ${ROW_HEIGHT.coarse}px + ${rows} * ${spacing.xs} + 2 * ${spacing.xs})`,
+    },
+  }),
+  maxRowsDefault: (rows: number) => ({
+    maxHeight: {
+      default: `calc((${rows} + 0.5) * ${ROW_HEIGHT.default}px + ${rows} * ${spacing.xs} + 2 * ${spacing.xs})`,
+      '@media (pointer: coarse)': `calc((${rows} + 0.5) * ${ROW_HEIGHT.coarse}px + ${rows} * ${spacing.xs} + 2 * ${spacing.xs})`,
+    },
+  }),
   vertical: {
     flexDirection: 'column',
   },

package/src/components/ToggleGroup/useRovingFocus.ts

@@ -0,0 +1,121 @@
+import {useCallback, useEffect, useLayoutEffect, useRef, useState, type RefObject} from 'react'
+
+const ROW_TOLERANCE = 2
+
+function sameOrder(a: string[], b: string[]) {
+  return a.length === b.length && a.every((v, i) => v === b[i])
+}
+
+/**
+ * Roving focus for a wrapping ToggleGroup (WAI-ARIA toolbar pattern): one tab
+ * stop — the focused item, else the first pressed one, else the first — with
+ * arrow keys in reading order, Up/Down by visual row, Home/End.
+ */
+export function useRovingFocus({
+  enabled,
+  pressed,
+  rootRef,
+}: {
+  enabled: boolean
+  pressed: string[]
+  rootRef: RefObject<HTMLElement | null>
+}) {
+  const items = useRef(new Map<string, HTMLElement>())
+  const [order, setOrder] = useState<string[]>([])
+  const [focusedValue, setFocusedValue] = useState<string | null>(null)
+
+  const sync = useCallback(() => {
+    const entries = [...items.current.entries()].sort(([, a], [, b]) =>
+      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1,
+    )
+    const next = entries.map(([v]) => v)
+    setOrder((prev) => (sameOrder(prev, next) ? prev : next))
+  }, [])
+
+  const register = useCallback(
+    (value: string, el: HTMLElement) => {
+      items.current.set(value, el)
+      sync()
+      return () => {
+        if (items.current.get(value) === el) items.current.delete(value)
+        sync()
+      }
+    },
+    [sync],
+  )
+
+  // a focus holder that unmounted no longer holds the tab stop
+  useLayoutEffect(() => {
+    if (focusedValue !== null && !order.includes(focusedValue)) setFocusedValue(null)
+  }, [order, focusedValue])
+
+  const tabStopValue = !enabled
+    ? null
+    : focusedValue !== null && order.includes(focusedValue)
+      ? focusedValue
+      : (pressed.find((v) => order.includes(v)) ?? order[0] ?? null)
+
+  // native listener: RSD's onKeyDown event is a reduced shape (as in Tree)
+  useEffect(() => {
+    const root = rootRef.current
+    if (!enabled || !root) return
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.altKey || e.ctrlKey || e.metaKey) return
+      const els = order
+        .map((v) => items.current.get(v))
+        .filter((el): el is HTMLElement => !!el && !(el as HTMLButtonElement).disabled)
+      const i = els.indexOf(e.target as HTMLElement)
+      if (i < 0) return
+      let target: HTMLElement | undefined
+      switch (e.key) {
+        case 'ArrowRight':
+          target = els[Math.min(i + 1, els.length - 1)]
+          break
+        case 'ArrowLeft':
+          target = els[Math.max(i - 1, 0)]
+          break
+        case 'Home':
+          target = els[0]
+          break
+        case 'End':
+          target = els[els.length - 1]
+          break
+        case 'ArrowDown':
+        case 'ArrowUp': {
+          const down = e.key === 'ArrowDown'
+          const cur = els[i].getBoundingClientRect()
+          const cx = cur.left + cur.width / 2
+          const rects = els.map((el) => el.getBoundingClientRect())
+          // rows, by distinct top, in the direction of travel
+          const tops = [...new Set(rects.map((r) => Math.round(r.top)))].sort((a, b) => a - b)
+          const rowIdx = tops.findIndex((t) => Math.abs(t - cur.top) <= ROW_TOLERANCE)
+          const nextTop = tops[rowIdx + (down ? 1 : -1)]
+          if (nextTop === undefined) break
+          let best = Infinity
+          rects.forEach((r, k) => {
+            if (Math.abs(r.top - nextTop) > ROW_TOLERANCE) return
+            const d = Math.abs(r.left + r.width / 2 - cx)
+            if (d < best) {
+              best = d
+              target = els[k]
+            }
+          })
+          break
+        }
+        default:
+          return
+      }
+      e.preventDefault()
+      target?.focus()
+    }
+    root.addEventListener('keydown', onKeyDown)
+    return () => root.removeEventListener('keydown', onKeyDown)
+  }, [enabled, order, rootRef])
+
+  return {
+    tabStopValue,
+    register,
+    onItemFocus: setFocusedValue,
+    items,
+  }
+}