@duro-app/ui 4.4.0 → 5.0.0

package/src/components/Textarea/Textarea.stories.tsx

@@ -3,6 +3,7 @@ import {expect, fn} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Textarea} from './Textarea'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 const meta: Meta<typeof Textarea> = {
   title: 'Components/Textarea',
@@ -76,7 +77,7 @@ export const CustomRows: Story = {
 }
 
 const stackStyles = css.create({
-  stack: {display: 'flex', flexDirection: 'column', gap: spacing.ms, maxWidth: 320},
+  stack: {display: 'flex', flexDirection: 'column', gap: spacing.ms, maxWidth: sizes.panelSm},
 })
 
 export const AllVariants: Story = {

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

@@ -3,6 +3,7 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
 
 export const styles = css.create({
   base: {
@@ -16,7 +17,7 @@ export const styles = css.create({
     lineHeight: typography.lineHeight,
     color: colors.text,
     backgroundColor: colors.bg,
-    borderWidth: 1,
+    borderWidth: borders.hairline,
     borderStyle: 'solid',
     borderRadius: radii.sm,
     resize: 'vertical' as const,
@@ -25,7 +26,7 @@ export const styles = css.create({
     transitionTimingFunction: easing.standard,
     outlineWidth: {
       default: 0,
-      ':focus-visible': 2,
+      ':focus-visible': borders.focusRing,
     },
     outlineStyle: {
       default: 'none',
@@ -37,7 +38,7 @@ export const styles = css.create({
     },
     outlineOffset: {
       default: 0,
-      ':focus-visible': 1,
+      ':focus-visible': borders.focusOffsetSm,
     },
   },
   default: {

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

@@ -7,6 +7,8 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {shadows} from '@duro-app/tokens/tokens/shadows.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 const meta: Meta<typeof ThemeProvider> = {
   title: 'Theme/ThemeProvider',
@@ -27,7 +29,7 @@ const sampleStyles = css.create({
   card: {
     padding: spacing.md,
     backgroundColor: colors.bgCard,
-    borderWidth: 1,
+    borderWidth: borders.hairline,
     borderStyle: 'solid',
     borderColor: colors.border,
     borderRadius: radii.md,
@@ -53,10 +55,10 @@ const sampleStyles = css.create({
     flexWrap: 'wrap',
   },
   swatch: {
-    width: 48,
-    height: 48,
+    width: sizes.iconXxl,
+    height: sizes.iconXxl,
     borderRadius: radii.sm,
-    borderWidth: 1,
+    borderWidth: borders.hairline,
     borderStyle: 'solid',
     borderColor: colors.border,
   },
@@ -131,7 +133,7 @@ const sideBySideStyles = css.create({
   },
   column: {
     flex: 1,
-    minWidth: 280,
+    minWidth: sizes.gridColMd,
   },
   label: {
     fontSize: typography.fontSizeSm,

package/src/components/Toast/Toast.stories.tsx

@@ -3,13 +3,14 @@ import {expect, userEvent, waitFor} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {ToastProvider, useToast} from './ToastProvider'
 import {radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
 
 const s = css.create({
   row: {display: 'flex', flexDirection: 'row', gap: spacing.sm, flexWrap: 'wrap'},
   btn: {
     padding: spacing.sm,
     borderRadius: radii.sm,
-    borderWidth: 1,
+    borderWidth: borders.hairline,
     borderStyle: 'solid',
     cursor: 'pointer',
   },

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

@@ -1,9 +1,11 @@
 import {css} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
-import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
+import {microSpacing, radii, spacing} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {shadows} from '@duro-app/tokens/tokens/shadows.css'
-import {easing} from '@duro-app/tokens/tokens/motion.css'
+import {duration, easing} 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'
 
 const enter = css.keyframes({
   from: {opacity: 0, transform: 'translateY(10px)'},
@@ -31,17 +33,17 @@ export const styles = css.create({
     pointerEvents: 'auto',
     boxSizing: 'border-box',
     width: '100%',
-    maxWidth: 440,
+    maxWidth: sizes.toastMaxW,
     display: 'flex',
     flexDirection: 'row',
     alignItems: 'flex-start',
     gap: spacing.sm,
     padding: spacing.md,
     borderRadius: radii.sm,
-    borderWidth: 1,
+    borderWidth: borders.hairline,
     borderStyle: 'solid',
     borderColor: colors.border,
-    borderLeftWidth: 3,
+    borderLeftWidth: borders.accent,
     backgroundColor: colors.bgCard,
     boxShadow: shadows.lg,
     color: colors.text,
@@ -51,7 +53,7 @@ export const styles = css.create({
       default: enter,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
-    animationDuration: '160ms',
+    animationDuration: duration.brisk,
     animationTimingFunction: easing.easeOut,
   },
   success: {borderLeftColor: colors.successBorder},
@@ -63,7 +65,7 @@ export const styles = css.create({
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    paddingTop: 1,
+    paddingTop: microSpacing.px1,
   },
   iconSuccess: {color: colors.successText},
   iconError: {color: colors.errorText},
@@ -74,14 +76,14 @@ export const styles = css.create({
     minWidth: 0,
     display: 'flex',
     flexDirection: 'column',
-    gap: 2,
+    gap: microSpacing.px2,
   },
   message: {
     color: colors.text,
   },
   action: {
     alignSelf: 'flex-start',
-    marginTop: 2,
+    marginTop: microSpacing.px2,
     padding: 0,
     borderWidth: 0,
     backgroundColor: 'transparent',
@@ -91,9 +93,9 @@ export const styles = css.create({
     textDecorationLine: 'underline',
     cursor: 'pointer',
     outlineStyle: {default: 'none', ':focus-visible': 'solid'},
-    outlineWidth: 2,
+    outlineWidth: borders.focusRing,
     outlineColor: colors.accent,
-    outlineOffset: 2,
+    outlineOffset: borders.focusOffset,
     borderRadius: radii.sm,
   },
   closeBtn: {
@@ -101,7 +103,7 @@ export const styles = css.create({
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    padding: 2,
+    padding: microSpacing.px2,
     marginTop: -1,
     borderWidth: 0,
     backgroundColor: 'transparent',
@@ -109,8 +111,8 @@ export const styles = css.create({
     cursor: 'pointer',
     borderRadius: radii.sm,
     outlineStyle: {default: 'none', ':focus-visible': 'solid'},
-    outlineWidth: 2,
+    outlineWidth: borders.focusRing,
     outlineColor: colors.accent,
-    outlineOffset: 1,
+    outlineOffset: borders.focusOffsetSm,
   },
 })

package/src/components/Toggle/Toggle.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Toggle button with pressed/unpressed state. Works standalone or within ToggleGroup for multi/single selection.',
+    'Toggle button with pressed/unpressed state. Works standalone or within ToggleGroup for multi/single selection. Under a coarse pointer (touch) every Toggle is at least sizes.touchTarget (44px) square; in a wrapping ToggleGroup each keeps its own border and a fixed row height.',
   whenToUse: [
     'Toolbar buttons that toggle on/off (bold, italic, grid view)',
     'Within ToggleGroup for selecting from visible options',

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/styles.css.ts

@@ -3,13 +3,15 @@ import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration, easing} 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'
 
 export const styles = css.create({
   base: {
     display: 'inline-flex',
     alignItems: 'center',
     justifyContent: 'center',
-    borderWidth: 1,
+    borderWidth: borders.hairline,
     borderStyle: 'solid',
     cursor: 'pointer',
     fontFamily: typography.fontFamily,
@@ -17,10 +19,12 @@ export const styles = css.create({
     transitionProperty: 'background-color, border-color, color, opacity',
     transitionDuration: duration.fast,
     transitionTimingFunction: easing.standard,
-    outlineWidth: {default: 0, ':focus-visible': 2},
+    outlineWidth: {default: 0, ':focus-visible': borders.focusRing},
     outlineStyle: 'solid',
     outlineColor: colors.accent,
-    outlineOffset: 2,
+    outlineOffset: borders.focusOffset,
+    minWidth: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
+    minHeight: {default: null, '@media (pointer: coarse)': sizes.touchTarget},
   },
   sizeDefault: {
     padding: `${spacing.sm} ${spacing.md}`,
@@ -34,6 +38,16 @@ export const styles = css.create({
     borderRadius: radii.sm,
     gap: spacing.xs,
   },
+  // wrapped toggles: a fixed block size per size, the touch target under a
+  // coarse pointer. ToggleGroup's maxRows arithmetic reads the same tokens.
+  wrappedDefault: {
+    boxSizing: 'border-box',
+    height: {default: sizes.controlMd, '@media (pointer: coarse)': sizes.touchTarget},
+  },
+  wrappedSmall: {
+    boxSizing: 'border-box',
+    height: {default: sizes.controlSm, '@media (pointer: coarse)': sizes.touchTarget},
+  },
   unpressed: {
     backgroundColor: {
       default: 'transparent',
@@ -56,7 +70,7 @@ export const styles = css.create({
   grouped: {
     borderWidth: 0,
     borderRadius: 0,
-    borderRightWidth: 1,
+    borderRightWidth: borders.hairline,
     borderRightStyle: 'solid',
     // Override any borderColor set by pressed state — dividers always use border token
     borderColor: colors.border,

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, sizes.touchTarget (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,7 +3,10 @@ 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 {SIZES_PX} from '@duro-app/tokens/keys'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 const meta: Meta<typeof ToggleGroup> = {
   title: 'Components/ToggleGroup',
@@ -158,3 +161,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: sizes.panelSm},
+})
+
+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(SIZES_PX.controlSm)
+    // exact: Toggle's styles read the same size tokens, and a drift must fail here
+    const toggle = canvas.getAllByRole('button')[0].getBoundingClientRect()
+    await expect(Math.abs(toggle.height - SIZES_PX.controlSm)).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 - SIZES_PX.controlMd)).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)