@duro-app/ui 0.15.2 → 0.17.0

package/src/components/Form/Form.tsx

@@ -0,0 +1,59 @@
+import {type ReactNode, useCallback, useEffect, useRef} from 'react'
+import {html} from 'react-strict-dom'
+import {
+  useForm,
+  FormProvider,
+  type UseFormReturn,
+  type DefaultValues,
+  type FieldValues,
+} from 'react-hook-form'
+import {effectTsResolver} from '@hookform/resolvers/effect-ts'
+import type {Schema} from 'effect'
+import {FormContext} from './FormContext'
+
+export interface FormProps<T extends FieldValues> {
+  schema: Schema.Schema<T>
+  defaultValues: DefaultValues<T>
+  onSubmit: (data: T) => void | Promise<void>
+  children: ReactNode | ((methods: UseFormReturn<T>) => ReactNode)
+}
+
+export function Form<T extends FieldValues>({
+  schema,
+  defaultValues,
+  onSubmit,
+  children,
+}: FormProps<T>) {
+  const methods = useForm<T>({
+    resolver: effectTsResolver(schema),
+    defaultValues,
+    mode: 'onTouched',
+    reValidateMode: 'onChange',
+  })
+
+  const formRef = useRef<HTMLFormElement>(null)
+  const handleSubmit = useCallback(
+    (e: Event) => {
+      e.preventDefault()
+      void methods.handleSubmit(onSubmit)()
+    },
+    [methods, onSubmit],
+  )
+
+  useEffect(() => {
+    const el = formRef.current
+    if (!el) return
+    el.addEventListener('submit', handleSubmit)
+    return () => el.removeEventListener('submit', handleSubmit)
+  }, [handleSubmit])
+
+  return (
+    <FormProvider {...methods}>
+      <FormContext.Provider value={true}>
+        <html.form ref={formRef}>
+          {typeof children === 'function' ? children(methods) : children}
+        </html.form>
+      </FormContext.Provider>
+    </FormProvider>
+  )
+}

package/src/components/Form/FormContext.ts

@@ -0,0 +1,7 @@
+import {createContext, useContext} from 'react'
+
+export const FormContext = createContext(false)
+
+export function useFormContext() {
+  return useContext(FormContext)
+}

package/src/components/Grid/Grid.meta.ts

@@ -0,0 +1,30 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'CSS grid layout. Supports fixed column count (1-6) or responsive auto-fit via minColumnWidth.',
+  whenToUse: [
+    'Card grids, dashboard layouts, multi-column forms',
+    'Responsive layouts that should auto-adjust column count',
+  ],
+  whenNotToUse: [
+    'Single-column vertical layout — use Stack',
+    'Simple horizontal row — use Inline or Cluster',
+  ],
+  relatedTo: [
+    {component: 'Stack', relationship: 'Single-column vertical layout'},
+  ],
+  example: `// Responsive: columns auto-fit based on min width
+<Grid minColumnWidth="280px" gap="md">
+  <Card>A</Card>
+  <Card>B</Card>
+  <Card>C</Card>
+</Grid>
+
+// Fixed: always 3 columns
+<Grid columns={3} gap="md">
+  <Card>A</Card>
+  <Card>B</Card>
+  <Card>C</Card>
+</Grid>`,
+}

package/src/components/Inline/Inline.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Horizontal flex layout with NO wrapping. Items stay on one line and may overflow.',
+  whenToUse: [
+    'Toolbar or button group that must stay on one row',
+    'Horizontal alignment of a known, small number of items',
+    'Icon + text pairs, breadcrumbs, action rows',
+  ],
+  whenNotToUse: [
+    'Items that should wrap to the next line — use Cluster',
+    'Vertical stacking — use Stack',
+  ],
+  relatedTo: [
+    {component: 'Cluster', relationship: 'Same but wraps to next line'},
+    {component: 'Stack', relationship: 'Vertical equivalent'},
+  ],
+  example: `<Inline gap="sm" align="center">
+  <Button>Save</Button>
+  <Button variant="secondary">Cancel</Button>
+</Inline>`,
+}

package/src/components/Input/Input.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Text input with automatic Field/Form integration. Variant auto-switches to error when inside an invalid Field.',
+  whenToUse: [
+    'Single-line text entry (text, email, password, url, tel, number, search)',
+  ],
+  whenNotToUse: [
+    'Multi-line text — use Textarea',
+    'Picking from predefined options — use Select',
+  ],
+  relatedTo: [
+    {component: 'Field', relationship: 'Wrap in Field.Root for label + error'},
+    {component: 'InputGroup', relationship: 'Wrap in InputGroup.Root for prefix/suffix addons'},
+    {component: 'Textarea', relationship: 'Multi-line variant'},
+  ],
+  example: `<Field.Root name="email">
+  <Field.Label>Email</Field.Label>
+  <Input type="email" placeholder="you@example.com" autoComplete="email" />
+  <Field.Error />
+</Field.Root>`,
+}

package/src/components/Input/Input.tsx

@@ -30,6 +30,8 @@ interface InputProps {
   defaultValue?: string
   disabled?: boolean
   onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void
+  onBlur?: () => void
+  ref?: React.Ref<HTMLInputElement>
 }
 
 export function Input({
@@ -45,10 +47,20 @@ export function Input({
   defaultValue,
   disabled,
   onChange,
+  onBlur,
+  ref,
 }: InputProps) {
   const ctx = useFieldContext()
   const groupCtx = useInputGroupContext()
 
+  const fieldCtx = ctx?.field
+  const effectiveName = name ?? fieldCtx?.name
+  const effectiveValue = value ?? (fieldCtx ? String(fieldCtx.value ?? '') : undefined)
+  const effectiveOnChange = onChange ?? fieldCtx?.onChange
+  const effectiveOnBlur = onBlur ?? fieldCtx?.onBlur
+  const effectiveRef = ref ?? fieldCtx?.ref
+  const effectiveVariant = ctx?.invalid ? 'error' : variant
+
   // react-strict-dom omits web-only `pattern` from its types, but the
   // underlying DOM element supports it. Type-assert to pass it through.
   const extraProps = pattern !== undefined ? {pattern} : undefined
@@ -57,20 +69,22 @@ export function Input({
     <html.input
       id={ctx?.controlId}
       type={type}
-      name={name}
+      name={effectiveName}
       placeholder={placeholder}
       required={required}
       minLength={minLength}
       autoComplete={autoComplete}
-      value={value}
+      value={effectiveValue}
       defaultValue={defaultValue}
       disabled={disabled}
       aria-describedby={
         ctx ? `${ctx.descriptionId} ${ctx.invalid ? ctx.errorId : ''}`.trim() : undefined
       }
       aria-invalid={ctx?.invalid || variant === 'error' || undefined}
-      onChange={onChange}
-      style={[styles.base, styles[variant], groupCtx?.inGroup && styles.inGroup]}
+      onChange={effectiveOnChange as StrictInputProps['onChange']}
+      onBlur={effectiveOnBlur as StrictInputProps['onBlur']}
+      ref={effectiveRef as React.Ref<HTMLInputElement>}
+      style={[styles.base, styles[effectiveVariant], groupCtx?.inGroup && styles.inGroup]}
       {...(extraProps as Record<string, unknown>)}
     />
   )

package/src/components/LinkButton/LinkButton.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Button-styled hyperlink. Renders an <a> tag, not a <button>. Use for navigation, not actions.',
+  whenToUse: [
+    'Navigation that should look like a button (e.g., "Get started", "View all")',
+    'Links to external pages with button styling',
+  ],
+  whenNotToUse: [
+    'Triggering in-page actions — use Button',
+    'Plain text links — use a styled <a> tag',
+  ],
+  relatedTo: [
+    {component: 'Button', relationship: 'Button for actions; LinkButton for navigation'},
+  ],
+  example: `<LinkButton href="/signup" variant="primary">
+  Get started
+</LinkButton>
+
+<LinkButton href="https://docs.example.com" target="_blank" variant="secondary">
+  Read the docs
+</LinkButton>`,
+}

package/src/components/Menu/Menu.meta.ts

@@ -0,0 +1,33 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it).',
+  whenToUse: [
+    'Context menu or "more actions" dropdown',
+    'Navigation links in a dropdown',
+    'Overflow menu for toolbar actions',
+  ],
+  whenNotToUse: [
+    'Picking a value — use Select',
+    'Primary navigation — use SideNav or Tabs',
+  ],
+  anatomy: {
+    required: ['Root', 'Trigger', 'Popup', 'Item'],
+    optional: ['LinkItem'],
+  },
+  relatedTo: [
+    {component: 'Select', relationship: 'Select picks values; Menu triggers actions'},
+    {component: 'Button', relationship: 'Often used as Menu.Trigger content'},
+  ],
+  example: `<Menu.Root>
+  <Menu.Trigger>
+    <Button variant="secondary">Actions</Button>
+  </Menu.Trigger>
+  <Menu.Popup>
+    <Menu.Item onClick={() => console.log('edit')}>Edit</Menu.Item>
+    <Menu.Item onClick={() => console.log('duplicate')}>Duplicate</Menu.Item>
+    <Menu.LinkItem href="/settings">Settings</Menu.LinkItem>
+  </Menu.Popup>
+</Menu.Root>`,
+}

package/src/components/PageShell/PageShell.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Page-level layout wrapper. Centers content with max-width, padding, and an optional sticky header.',
+  whenToUse: [
+    'Top-level page layout',
+    'Any full-page view that needs centered content with consistent padding',
+  ],
+  whenNotToUse: [
+    'Nested section layouts — use Stack or Card',
+    'Sidebar layouts — combine with SideNav manually',
+  ],
+  relatedTo: [
+    {component: 'Stack', relationship: 'Use Stack for content within PageShell'},
+    {component: 'SideNav', relationship: 'Often placed alongside PageShell'},
+  ],
+  example: `<PageShell maxWidth="lg" padding="md" header={<Heading level={1}>Dashboard</Heading>}>
+  <Stack gap="lg">
+    <Card>Content section 1</Card>
+    <Card>Content section 2</Card>
+  </Stack>
+</PageShell>`,
+}

package/src/components/ScrollArea/ScrollArea.meta.ts

@@ -0,0 +1,27 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Custom scrollbar region with draggable thumb. Supports vertical and horizontal scrolling. Compound component — Root is required.',
+  whenToUse: [
+    'Custom-styled scrollbars for content overflow areas',
+    'Chat logs, code blocks, or long lists with constrained height',
+  ],
+  whenNotToUse: [
+    'Simple page-level scrolling — browser scroll is fine',
+    'Very short content that never overflows',
+  ],
+  anatomy: {
+    required: ['Root', 'Viewport', 'Content', 'Scrollbar', 'Thumb'],
+  },
+  example: `<ScrollArea.Root>
+  <ScrollArea.Viewport maxHeight={300}>
+    <ScrollArea.Content>
+      {/* Long content here */}
+    </ScrollArea.Content>
+  </ScrollArea.Viewport>
+  <ScrollArea.Scrollbar orientation="vertical">
+    <ScrollArea.Thumb orientation="vertical" />
+  </ScrollArea.Scrollbar>
+</ScrollArea.Root>`,
+}

package/src/components/Select/Select.meta.ts

@@ -0,0 +1,34 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it).',
+  whenToUse: [
+    'User must pick one option from a predefined list',
+    'Form field for country, category, role selection',
+  ],
+  whenNotToUse: [
+    'Triggering actions — use Menu',
+    'Multiple selections — use ToggleGroup or Checkbox group',
+    'Fewer than 3 options — consider Toggle or ToggleGroup',
+  ],
+  anatomy: {
+    required: ['Root', 'Trigger', 'Popup', 'Item'],
+    optional: ['Value', 'Icon', 'ItemText'],
+  },
+  relatedTo: [
+    {component: 'Menu', relationship: 'Menu triggers actions; Select picks a value'},
+    {component: 'ToggleGroup', relationship: 'For visible, small option sets'},
+  ],
+  example: `<Select.Root name="role" defaultValue="viewer">
+  <Select.Trigger>
+    <Select.Value placeholder="Select role" />
+    <Select.Icon />
+  </Select.Trigger>
+  <Select.Popup>
+    <Select.Item value="admin">Admin</Select.Item>
+    <Select.Item value="editor">Editor</Select.Item>
+    <Select.Item value="viewer">Viewer</Select.Item>
+  </Select.Popup>
+</Select.Root>`,
+}

package/src/components/SideNav/SideNav.meta.ts

@@ -0,0 +1,31 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Vertical side navigation with collapsible groups. Supports controlled and uncontrolled active item. Compound component — Root is required.',
+  whenToUse: [
+    'App-level sidebar navigation',
+    'Settings navigation with grouped sections',
+  ],
+  whenNotToUse: [
+    'In-page content switching — use Tabs',
+    'Top-level horizontal nav — use Inline with LinkButton',
+  ],
+  anatomy: {
+    required: ['Root', 'Group', 'Item'],
+  },
+  relatedTo: [
+    {component: 'Tabs', relationship: 'Tabs switch content in-place; SideNav navigates pages'},
+    {component: 'PageShell', relationship: 'Often placed alongside PageShell'},
+  ],
+  example: `<SideNav.Root defaultValue="dashboard">
+  <SideNav.Group label="Main">
+    <SideNav.Item value="dashboard">Dashboard</SideNav.Item>
+    <SideNav.Item value="analytics">Analytics</SideNav.Item>
+  </SideNav.Group>
+  <SideNav.Group label="Settings" defaultExpanded={false}>
+    <SideNav.Item value="profile">Profile</SideNav.Item>
+    <SideNav.Item value="billing">Billing</SideNav.Item>
+  </SideNav.Group>
+</SideNav.Root>`,
+}

package/src/components/Stack/Stack.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Vertical flex layout. Stacks children top-to-bottom with consistent gap.',
+  whenToUse: [
+    'Vertically stacking form fields, cards, or sections',
+    'Any column-direction layout with uniform spacing',
+  ],
+  whenNotToUse: [
+    'Horizontal layouts — use Inline (no wrap) or Cluster (wraps)',
+    'Grid layouts — use Grid',
+  ],
+  relatedTo: [
+    {component: 'Inline', relationship: 'Horizontal equivalent (no wrap)'},
+    {component: 'Cluster', relationship: 'Horizontal equivalent (wraps)'},
+  ],
+  example: `<Stack gap="md" align="stretch">
+  <Card>First</Card>
+  <Card>Second</Card>
+</Stack>`,
+}

package/src/components/Switch/Switch.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Toggle switch for on/off settings. Renders a hidden checkbox for form submission + a styled switch button.',
+  whenToUse: [
+    'On/off toggles in settings (notifications, dark mode, feature flags)',
+    'Immediate-effect toggles where the change applies instantly',
+  ],
+  whenNotToUse: [
+    'Form opt-in checkboxes — use Checkbox',
+    'Selecting between multiple options — use Select or ToggleGroup',
+  ],
+  relatedTo: [
+    {component: 'Checkbox', relationship: 'Checkbox for selection/opt-in; Switch for on/off settings'},
+    {component: 'Toggle', relationship: 'Toggle for toolbar pressed state; Switch for settings'},
+  ],
+  example: `<Switch
+  name="notifications"
+  defaultChecked={true}
+  onCheckedChange={(checked) => console.log(checked)}
+>
+  Enable notifications
+</Switch>`,
+}

package/src/components/Table/Table.meta.ts

@@ -0,0 +1,36 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Data table with CSS grid layout. Supports striped, bordered variants. Compound component — Root is required (throws without it). Requires `columns` prop on Root.',
+  whenToUse: [
+    'Displaying tabular data with rows and columns',
+    'Data lists with sortable/filterable columns',
+  ],
+  whenNotToUse: [
+    'Simple key-value pairs — use Stack with Text',
+    'Card-based layouts — use Grid with Card',
+  ],
+  anatomy: {
+    required: ['Root', 'Header', 'Body', 'Row', 'HeaderCell', 'Cell'],
+  },
+  relatedTo: [
+    {component: 'ScrollArea', relationship: 'Wrap Table in ScrollArea for horizontal overflow'},
+  ],
+  example: `<Table.Root variant="striped" size="md" columns={3}>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Name</Table.HeaderCell>
+      <Table.HeaderCell>Role</Table.HeaderCell>
+      <Table.HeaderCell>Status</Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Alice</Table.Cell>
+      <Table.Cell>Admin</Table.Cell>
+      <Table.Cell>Active</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>`,
+}

package/src/components/Tabs/Tabs.meta.ts

@@ -0,0 +1,31 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Tabbed interface with keyboard navigation. Supports horizontal and vertical orientation. Compound component — Root is required.',
+  whenToUse: [
+    'Switching between content panels in the same view',
+    'Settings pages with multiple sections',
+    'Organizing related content without page navigation',
+  ],
+  whenNotToUse: [
+    'Primary site navigation — use SideNav or links',
+    'Step-by-step wizard — use a custom stepper',
+  ],
+  anatomy: {
+    required: ['Root', 'List', 'Tab', 'Panel'],
+  },
+  relatedTo: [
+    {component: 'SideNav', relationship: 'For persistent navigation, not content switching'},
+  ],
+  example: `<Tabs.Root defaultValue="general">
+  <Tabs.List>
+    <Tabs.Tab value="general">General</Tabs.Tab>
+    <Tabs.Tab value="security">Security</Tabs.Tab>
+    <Tabs.Tab value="billing" disabled>Billing</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="general">General settings content</Tabs.Panel>
+  <Tabs.Panel value="security">Security settings content</Tabs.Panel>
+  <Tabs.Panel value="billing">Billing content</Tabs.Panel>
+</Tabs.Root>`,
+}

package/src/components/Textarea/Textarea.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Multi-line text input with automatic Field/Form integration. Same Field binding behavior as Input.',
+  whenToUse: [
+    'Multi-line text entry (comments, messages, descriptions)',
+  ],
+  whenNotToUse: [
+    'Single-line input — use Input',
+  ],
+  relatedTo: [
+    {component: 'Input', relationship: 'Single-line variant'},
+    {component: 'Field', relationship: 'Wrap in Field.Root for label + error'},
+  ],
+  example: `<Field.Root name="message">
+  <Field.Label>Message</Field.Label>
+  <Textarea placeholder="Tell us what you think..." rows={4} />
+  <Field.Description>At least 10 characters</Field.Description>
+  <Field.Error />
+</Field.Root>`,
+}

package/src/components/Textarea/Textarea.tsx

@@ -2,6 +2,8 @@ import {html} from 'react-strict-dom'
 import {useFieldContext} from '../Field/FieldContext'
 import {styles} from './styles.css'
 
+type StrictTextareaProps = React.ComponentProps<typeof html.textarea>
+
 export type TextareaVariant = 'default' | 'error'
 
 interface TextareaProps {
@@ -14,6 +16,8 @@ interface TextareaProps {
   defaultValue?: string
   disabled?: boolean
   onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void
+  onBlur?: () => void
+  ref?: React.Ref<HTMLTextAreaElement>
 }
 
 export function Textarea({
@@ -26,25 +30,37 @@ export function Textarea({
   defaultValue,
   disabled,
   onChange,
+  onBlur,
+  ref,
 }: TextareaProps) {
   const ctx = useFieldContext()
 
+  const fieldCtx = ctx?.field
+  const effectiveName = name ?? fieldCtx?.name
+  const effectiveValue = value ?? (fieldCtx ? String(fieldCtx.value ?? '') : undefined)
+  const effectiveOnChange = onChange ?? fieldCtx?.onChange
+  const effectiveOnBlur = onBlur ?? fieldCtx?.onBlur
+  const effectiveRef = ref ?? fieldCtx?.ref
+  const effectiveVariant = ctx?.invalid ? 'error' : variant
+
   return (
     <html.textarea
       id={ctx?.controlId}
-      name={name}
+      name={effectiveName}
       placeholder={placeholder}
       required={required}
       rows={rows}
-      value={value}
+      value={effectiveValue}
       defaultValue={defaultValue}
       disabled={disabled}
       aria-describedby={
         ctx ? `${ctx.descriptionId} ${ctx.invalid ? ctx.errorId : ''}`.trim() : undefined
       }
       aria-invalid={ctx?.invalid || variant === 'error' || undefined}
-      onChange={onChange}
-      style={[styles.base, styles[variant]]}
+      onChange={effectiveOnChange as StrictTextareaProps['onChange']}
+      onBlur={effectiveOnBlur as StrictTextareaProps['onBlur']}
+      ref={effectiveRef as React.Ref<HTMLTextAreaElement>}
+      style={[styles.base, styles[effectiveVariant]]}
     />
   )
 }

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

@@ -0,0 +1,30 @@
+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.',
+  whenToUse: [
+    'Toolbar buttons that toggle on/off (bold, italic, grid view)',
+    'Within ToggleGroup for selecting from visible options',
+  ],
+  whenNotToUse: [
+    'On/off settings — use Switch',
+    'Form checkboxes — use Checkbox',
+    'Submitting actions — use Button',
+  ],
+  relatedTo: [
+    {component: 'ToggleGroup', relationship: 'Group of Toggles with single/multi select'},
+    {component: 'Switch', relationship: 'Switch for settings; Toggle for toolbar actions'},
+    {component: 'Button', relationship: 'Button for actions; Toggle for state'},
+  ],
+  example: `// Standalone
+<Toggle pressed={isBold} onPressedChange={setIsBold} aria-label="Bold">
+  <Icon name="key" size={16} />
+</Toggle>
+
+// In a group
+<ToggleGroup value={['grid']} onValueChange={setView} multiple={false}>
+  <Toggle value="list">List</Toggle>
+  <Toggle value="grid">Grid</Toggle>
+</ToggleGroup>`,
+}

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

@@ -0,0 +1,30 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Container for Toggle buttons enabling single or multi selection. Provides context to child Toggles.',
+  whenToUse: [
+    'Visible option set where user picks one or more (view mode, filter categories)',
+    'Segmented control pattern',
+  ],
+  whenNotToUse: [
+    'Dropdown selection — use Select',
+    'Many options (5+) — use Select for space efficiency',
+    'Form checkboxes — use Checkbox group in Fieldset',
+  ],
+  relatedTo: [
+    {component: 'Toggle', relationship: 'Toggle children get group context'},
+    {component: 'Select', relationship: 'Select for larger option sets'},
+  ],
+  example: `<ToggleGroup
+  value={selected}
+  onValueChange={setSelected}
+  multiple={false}
+  orientation="horizontal"
+  size="default"
+>
+  <Toggle value="list">List view</Toggle>
+  <Toggle value="grid">Grid view</Toggle>
+  <Toggle value="board">Board view</Toggle>
+</ToggleGroup>`,
+}

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

@@ -119,7 +119,7 @@ export const Vertical: Story = {
     </ToggleGroup>
   ),
   play: async ({canvas}) => {
-    const group = canvas.getByRole('group')
+    const group = canvas.getByRole('toolbar')
     await expect(group).toHaveAttribute('aria-orientation', 'vertical')
   },
 }
@@ -153,7 +153,7 @@ export const AllVariants: Story = {
     </html.div>
   ),
   play: async ({canvas}) => {
-    const groups = canvas.getAllByRole('group')
+    const groups = canvas.getAllByRole('toolbar')
     await expect(groups.length).toBe(4)
   },
 }