@duro-app/ui 3.2.1 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^3.2.1"
+    "@duro-app/tokens": "^3.3.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/CheckboxGroup/CheckboxGroup.tsx

@@ -3,6 +3,7 @@ import {html} from 'react-strict-dom'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {Checkbox} from '../Checkbox/Checkbox'
 import {styles} from './styles.css'
+import {useFieldGroupLabelling} from '../Field/FieldContext'
 
 // --- Context ---
 
@@ -30,6 +31,11 @@ interface RootProps {
   onValueChange?: (value: string[]) => void
   orientation?: 'horizontal' | 'vertical'
   disabled?: boolean
+  /** Accessible name when the group is not inside a Field.Root (inside one,
+   *  the Field.Label names it). */
+  'aria-label'?: string
+  /** id of the element that names the group, when not inside a Field.Root. */
+  'aria-labelledby'?: string
   children: ReactNode
 }
 
@@ -40,7 +46,9 @@ function Root({
   orientation = 'vertical',
   disabled = false,
   children,
+  ...labelling
 }: RootProps) {
+  const a11y = useFieldGroupLabelling(labelling)
   const [value, setValue] = useControllableValue(controlledValue, defaultValue, onValueChange)
 
   const onToggle = useCallback(
@@ -57,6 +65,7 @@ function Root({
       <html.div
         role="group"
         aria-orientation={orientation}
+        {...a11y}
         style={[styles.root, orientation === 'horizontal' && styles.rootHorizontal]}
       >
         {children}
@@ -92,6 +101,9 @@ function Item({value, disabled: itemDisabled = false, children}: ItemProps) {
   )
 }
 
+// inside a Field.Root, the label names this group (see Field's `group`)
+Root.isFieldGroup = true as const
+
 export const CheckboxGroup = {
   Root,
   Item,

package/src/components/Field/Field.meta.ts

@@ -6,6 +6,7 @@ export const meta: ComponentMeta = {
   whenToUse: [
     'Any form input that needs a label and/or error message',
     'Standalone labeled input (without Form) with manual error display',
+    'A labelled GROUP of controls (ToggleGroup, CheckboxGroup, RadioGroup): the label names the group via aria-labelledby — detected for a direct child, `group` for a nested one',
   ],
   whenNotToUse: ['Bare input without label — use Input directly (rare)'],
   anatomy: {
@@ -21,6 +22,21 @@ export const meta: ComponentMeta = {
     {component: 'Input', kind: 'composition', relationship: 'Place Input inside Field.Root'},
     {component: 'Textarea', kind: 'composition', relationship: 'Place Textarea inside Field.Root'},
     {component: 'Select', kind: 'composition', relationship: 'Place Select inside Field.Root'},
+    {
+      component: 'ToggleGroup',
+      kind: 'composition',
+      relationship: 'Inside Field.Root the Field.Label names the group',
+    },
+    {
+      component: 'CheckboxGroup',
+      kind: 'composition',
+      relationship: 'Inside Field.Root the Field.Label names the group',
+    },
+    {
+      component: 'RadioGroup',
+      kind: 'composition',
+      relationship: 'Inside Field.Root the Field.Label names the group',
+    },
   ],
   example: `// Inside Form (auto-binds validation)
 <Field.Root name="email">
@@ -30,6 +46,17 @@ export const meta: ComponentMeta = {
   <Field.Error />
 </Field.Root>
 
+// A group of controls — the label names the group (aria-labelledby).
+// A direct ToggleGroup / CheckboxGroup / RadioGroup child is detected;
+// pass \`group\` when the group is nested (e.g. inside a Stack).
+<Field.Root>
+  <Field.Label>Type</Field.Label>
+  <ToggleGroup value={[type]} onValueChange={setType}>
+    <Toggle value="app">Application</Toggle>
+    <Toggle value="platform">Platform</Toggle>
+  </ToggleGroup>
+</Field.Root>
+
 // Standalone (manual error)
 <Field.Root invalid>
   <Field.Label>Email</Field.Label>

package/src/components/Field/Field.stories.tsx

@@ -3,6 +3,13 @@ import {expect} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
 import {Field} from './Field'
 import {Input} from '../Input/Input'
+import {ToggleGroup} from '../ToggleGroup/ToggleGroup'
+import {Toggle} from '../Toggle/Toggle'
+import {CheckboxGroup} from '../CheckboxGroup/CheckboxGroup'
+import {RadioGroup} from '../RadioGroup/RadioGroup'
+import {Checkbox} from '../Checkbox/Checkbox'
+import {Stack} from '../Stack/Stack'
+import {Fieldset} from '../Fieldset/Fieldset'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
 
 const meta: Meta = {
@@ -159,3 +166,89 @@ export const Disabled: Story = {
     await expect(input).toBeDisabled()
   },
 }
+
+export const GroupControls: Story = {
+  name: 'Group controls named by the label',
+  render: () => (
+    <html.div style={stackStyles.stack}>
+      {/* a direct ToggleGroup / CheckboxGroup / RadioGroup child is detected */}
+      <Field.Root>
+        <Field.Label>Type</Field.Label>
+        <ToggleGroup defaultValue={['app']}>
+          <Toggle value="app">Application</Toggle>
+          <Toggle value="platform">Platform</Toggle>
+        </ToggleGroup>
+        <Field.Description>What the record describes.</Field.Description>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Channels</Field.Label>
+        <CheckboxGroup.Root defaultValue={['mail']}>
+          <CheckboxGroup.Item value="mail">Mail</CheckboxGroup.Item>
+          <CheckboxGroup.Item value="sms">SMS</CheckboxGroup.Item>
+        </CheckboxGroup.Root>
+      </Field.Root>
+      <Field.Root>
+        <Field.Label>Plan</Field.Label>
+        <RadioGroup.Root defaultValue="free">
+          <RadioGroup.Item value="free">Free</RadioGroup.Item>
+          <RadioGroup.Item value="pro">Pro</RadioGroup.Item>
+        </RadioGroup.Root>
+      </Field.Root>
+      {/* a group that is not a direct child (here inside a Stack) says so */}
+      <Field.Root group>
+        <Field.Label>Technologies</Field.Label>
+        <Stack gap="sm">
+          <CheckboxGroup.Root orientation="horizontal">
+            <CheckboxGroup.Item value="pg">PostgreSQL</CheckboxGroup.Item>
+            <CheckboxGroup.Item value="kafka">Kafka</CheckboxGroup.Item>
+          </CheckboxGroup.Root>
+        </Stack>
+      </Field.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    // each group control carries the Field.Label's text as its accessible name
+    await expect(canvas.getByRole('toolbar', {name: 'Type'})).toBeInTheDocument()
+    await expect(canvas.getByRole('group', {name: 'Channels'})).toBeInTheDocument()
+    await expect(canvas.getByRole('radiogroup', {name: 'Plan'})).toBeInTheDocument()
+    await expect(canvas.getByRole('group', {name: 'Technologies'})).toBeInTheDocument()
+    // the description reaches the group too
+    await expect(canvas.getByRole('toolbar', {name: 'Type'})).toHaveAccessibleDescription(
+      'What the record describes.',
+    )
+    // a group's label is not a <label for> pointing at nothing
+    for (const text of ['Type', 'Channels', 'Plan', 'Technologies']) {
+      const label = canvas.getByText(text)
+      await expect(label.tagName).not.toBe('LABEL')
+      await expect(label.id).not.toBe('')
+    }
+  },
+}
+
+export const SingleControlStillLabelled: Story = {
+  name: 'A single input keeps its <label for>',
+  render: () => (
+    <Field.Root>
+      <Field.Label>Name</Field.Label>
+      <Input placeholder="Name" />
+    </Field.Root>
+  ),
+  play: async ({canvas}) => {
+    const label = canvas.getByText('Name')
+    await expect(label.tagName).toBe('LABEL')
+    await expect(canvas.getByRole('textbox', {name: 'Name'})).toBeInTheDocument()
+  },
+}
+
+export const FieldsetLegendNamesTheGroup: Story = {
+  name: 'Fieldset legend names its group',
+  render: () => (
+    <Fieldset.Root>
+      <Fieldset.Legend>Notifications</Fieldset.Legend>
+      <Checkbox value="a">Weekly digest</Checkbox>
+    </Fieldset.Root>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByRole('group', {name: 'Notifications'})).toBeInTheDocument()
+  },
+}

package/src/components/Field/Field.tsx

@@ -9,6 +9,11 @@ import {styles} from './styles.css'
 // --- Root ---
 interface RootProps {
   name?: string
+  /** The control is a group of controls rather than one input — the label
+   *  then names the group (`aria-labelledby`) instead of pointing `for` at an
+   *  input. Detected automatically when a direct child is a ToggleGroup,
+   *  CheckboxGroup.Root or RadioGroup.Root; set it for any other group. */
+  group?: boolean
   invalid?: boolean
   required?: boolean
   disabled?: boolean
@@ -16,18 +21,31 @@ interface RootProps {
   children: ReactNode
 }
 
-function Root({name, ...props}: RootProps) {
+/** A group control marks itself so a Field can tell it holds a group. */
+export type FieldGroupComponent = {isFieldGroup?: true}
+
+function holdsGroup(children: ReactNode): boolean {
+  let found = false
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && (child.type as FieldGroupComponent).isFieldGroup) found = true
+  })
+  return found
+}
+
+function Root({name, group, ...props}: RootProps) {
   const formCtx = useFormContext()
+  const isGroup = group ?? holdsGroup(props.children)
   if (name && formCtx) {
-    return <ControlledRoot name={name} formCtx={formCtx} {...props} />
+    return <ControlledRoot name={name} formCtx={formCtx} group={isGroup} {...props} />
   }
-  return <StaticRoot {...props} />
+  return <StaticRoot group={isGroup} {...props} />
 }
 
 // Always calls useController — no conditional hooks
 function ControlledRoot({
   name,
   formCtx,
+  group,
   invalid: invalidProp = false,
   required,
   disabled,
@@ -36,6 +54,7 @@ function ControlledRoot({
 }: {
   name: string
   formCtx: NonNullable<ReturnType<typeof useFormContext>>
+  group: boolean
   invalid?: boolean
   required?: boolean
   disabled?: boolean
@@ -54,6 +73,8 @@ function ControlledRoot({
   const ctx = useMemo(
     () => ({
       controlId: `${id}-control`,
+      labelId: `${id}-label`,
+      group,
       descriptionId: `${id}-description`,
       errorId: `${id}-error`,
       invalid,
@@ -72,6 +93,7 @@ function ControlledRoot({
     }),
     [
       id,
+      group,
       invalid,
       required,
       effectiveDisabled,
@@ -95,12 +117,14 @@ function ControlledRoot({
 
 // Current behavior, no RHF dependency
 function StaticRoot({
+  group,
   invalid = false,
   required,
   disabled,
   labelPosition = 'top',
   children,
 }: {
+  group: boolean
   invalid?: boolean
   required?: boolean
   disabled?: boolean
@@ -111,6 +135,8 @@ function StaticRoot({
   const ctx = useMemo(
     () => ({
       controlId: `${id}-control`,
+      labelId: `${id}-label`,
+      group,
       descriptionId: `${id}-description`,
       errorId: `${id}-error`,
       invalid,
@@ -118,7 +144,7 @@ function StaticRoot({
       disabled,
       labelPosition,
     }),
-    [id, invalid, required, disabled, labelPosition],
+    [id, group, invalid, required, disabled, labelPosition],
   )
 
   return (
@@ -170,9 +196,8 @@ function Label({children}: LabelProps) {
   const ctx = useFieldContext()
   const isSide = ctx?.labelPosition === 'side'
   const indicator = ctx?.necessityIndicator
-
-  return (
-    <html.label for={ctx?.controlId} style={[styles.label, isSide && styles.labelSide]}>
+  const content = (
+    <>
       {children}
       {indicator === 'icon' && ctx?.required && (
         <html.span style={styles.necessityIcon} aria-hidden={true}>
@@ -184,6 +209,25 @@ function Label({children}: LabelProps) {
           {ctx?.required ? ' (required)' : ' (optional)'}
         </html.span>
       )}
+    </>
+  )
+
+  // A group is not a labelable element: `for` would point at nothing. The
+  // group names itself from this id instead (aria-labelledby).
+  if (ctx?.group) {
+    return (
+      <html.span id={ctx.labelId} style={[styles.label, isSide && styles.labelSide]}>
+        {content}
+      </html.span>
+    )
+  }
+  return (
+    <html.label
+      id={ctx?.labelId}
+      for={ctx?.controlId}
+      style={[styles.label, isSide && styles.labelSide]}
+    >
+      {content}
     </html.label>
   )
 }

package/src/components/Field/FieldContext.ts

@@ -3,6 +3,12 @@ import type {LabelPosition, NecessityIndicator} from '../Form/FormContext'
 
 interface FieldContextValue {
   controlId: string
+  /** id of the Field.Label — what a GROUP control points `aria-labelledby` at. */
+  labelId: string
+  /** The control is a group (ToggleGroup, CheckboxGroup, RadioGroup, a set of
+   *  checkboxes): the label names the group instead of pointing `for` at one
+   *  input, which a group is not. */
+  group?: boolean
   descriptionId: string
   errorId: string
   invalid: boolean
@@ -27,3 +33,22 @@ export const FieldContext = createContext<FieldContextValue | null>(null)
 export function useFieldContext() {
   return useContext(FieldContext)
 }
+
+interface GroupLabelling {
+  'aria-label'?: string
+  'aria-labelledby'?: string
+}
+
+/** The accessible-name wiring for a group control: its own `aria-label` /
+ *  `aria-labelledby` when given, else the enclosing Field's label and its
+ *  description / error. Outside a Field with neither, the group is unnamed —
+ *  pass one. */
+export function useFieldGroupLabelling(own: GroupLabelling) {
+  const ctx = useFieldContext()
+  const describedBy = ctx ? `${ctx.descriptionId} ${ctx.invalid ? ctx.errorId : ''}`.trim() : ''
+  return {
+    'aria-label': own['aria-label'],
+    'aria-labelledby': own['aria-labelledby'] ?? (own['aria-label'] ? undefined : ctx?.labelId),
+    'aria-describedby': describedBy || undefined,
+  }
+}

package/src/components/Fieldset/Fieldset.tsx

@@ -1,4 +1,4 @@
-import type {ReactNode} from 'react'
+import {type ReactNode, Children, createContext, isValidElement, useContext, useId} from 'react'
 import {html} from 'react-strict-dom'
 import type {SpacingToken} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
@@ -23,15 +23,26 @@ interface RootProps {
   children: ReactNode
 }
 
+// the Legend's id, so the group can name itself after it
+const LegendIdContext = createContext<string | undefined>(undefined)
+
 function Root({disabled = false, gap = 'md', children}: RootProps) {
+  const legendId = useId()
+  let hasLegend = false
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && child.type === Legend) hasLegend = true
+  })
   return (
-    <html.div
-      role="group"
-      aria-disabled={disabled || undefined}
-      style={[styles.root, gapMap[gap], disabled && styles.disabled]}
-    >
-      {children}
-    </html.div>
+    <LegendIdContext.Provider value={legendId}>
+      <html.div
+        role="group"
+        aria-labelledby={hasLegend ? legendId : undefined}
+        aria-disabled={disabled || undefined}
+        style={[styles.root, gapMap[gap], disabled && styles.disabled]}
+      >
+        {children}
+      </html.div>
+    </LegendIdContext.Provider>
   )
 }
 
@@ -40,8 +51,14 @@ interface LegendProps {
   children: ReactNode
 }
 
+/** Names the group: the Root points `aria-labelledby` at it. */
 function Legend({children}: LegendProps) {
-  return <html.span style={styles.legend}>{children}</html.span>
+  const id = useContext(LegendIdContext)
+  return (
+    <html.span id={id} style={styles.legend}>
+      {children}
+    </html.span>
+  )
 }
 
 export const Fieldset = {

package/src/components/RadioGroup/RadioGroup.tsx

@@ -2,6 +2,7 @@ import {type ReactNode, createContext, useContext, useCallback} from 'react'
 import {html} from 'react-strict-dom'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {styles} from './styles.css'
+import {useFieldGroupLabelling} from '../Field/FieldContext'
 
 // --- Context ---
 
@@ -29,6 +30,11 @@ interface RootProps {
   onValueChange?: (value: string) => void
   orientation?: 'horizontal' | 'vertical'
   disabled?: boolean
+  /** Accessible name when the group is not inside a Field.Root (inside one,
+   *  the Field.Label names it). */
+  'aria-label'?: string
+  /** id of the element that names the group, when not inside a Field.Root. */
+  'aria-labelledby'?: string
   children: ReactNode
 }
 
@@ -39,7 +45,9 @@ function Root({
   orientation = 'vertical',
   disabled = false,
   children,
+  ...labelling
 }: RootProps) {
+  const a11y = useFieldGroupLabelling(labelling)
   const [value, setValue] = useControllableValue(controlledValue, defaultValue, onValueChange)
 
   const onSelect = useCallback(
@@ -56,6 +64,7 @@ function Root({
       <html.div
         role="radiogroup"
         aria-orientation={orientation}
+        {...a11y}
         style={[styles.root, orientation === 'horizontal' && styles.rootHorizontal]}
       >
         {children}
@@ -104,6 +113,9 @@ function Item({value, disabled: itemDisabled = false, children}: ItemProps) {
   )
 }
 
+// inside a Field.Root, the label names this group (see Field's `group`)
+Root.isFieldGroup = true as const
+
 export const RadioGroup = {
   Root,
   Item,

package/src/components/ToggleGroup/ToggleGroup.tsx

@@ -3,6 +3,7 @@ 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 {styles} from './styles.css'
 
 interface ToggleGroupProps {
@@ -20,6 +21,11 @@ interface ToggleGroupProps {
   orientation?: Orientation
   /** Size applied to all child toggles. */
   size?: ToggleSize
+  /** Accessible name when the group is not inside a Field.Root (inside one,
+   *  the Field.Label names it). */
+  'aria-label'?: string
+  /** id of the element that names the group, when not inside a Field.Root. */
+  'aria-labelledby'?: string
   children: ReactNode
 }
 
@@ -32,7 +38,9 @@ export function ToggleGroup({
   orientation = 'horizontal',
   size = 'default',
   children,
+  ...labelling
 }: ToggleGroupProps) {
+  const a11y = useFieldGroupLabelling(labelling)
   const [value, setValue] = useControllableValue(controlledValue, defaultValue, onValueChange)
 
   const toggle = useCallback(
@@ -54,6 +62,7 @@ export function ToggleGroup({
       <html.div
         role="toolbar"
         aria-orientation={orientation}
+        {...a11y}
         style={[styles.root, orientation === 'vertical' && styles.vertical]}
       >
         {children}
@@ -61,3 +70,6 @@ export function ToggleGroup({
     </ToggleGroupContext.Provider>
   )
 }
+
+// inside a Field.Root, the label names this group (see Field's `group`)
+ToggleGroup.isFieldGroup = true as const