Add helper text and error text components to RadioGroup and CheckboxGroup

[loicplaire]

Problem

The forms documentation demonstrates wrapping RadioGroup and CheckboxGroup in Fieldset components to provide helper text and error messages. However, this pattern creates several issues:

1. Screen reader compatibility

Critical issue: When aria-describedby is set on the <fieldset> element (via Fieldset.Root), many screen readers (e.g. Voice Over) don't reliably announce the associated helper text and error messages. Screen readers expect aria-describedby on the interactive group element (role="radiogroup" or the checkbox group container), not the fieldset wrapper.

<!-- Pattern shown in Ark UI docs: aria-describedby on fieldset - unreliable -->
<template>
  <Fieldset.Root>
    <Fieldset.Legend>Select frameworks</Fieldset.Legend>
    <RadioGroup.Root name="framework">
      <RadioGroup.Item value="react">
        <RadioGroup.ItemControl />
        <RadioGroup.ItemText>React</RadioGroup.ItemText>
      </RadioGroup.Item>
    </RadioGroup.Root>
    <Fieldset.HelperText>Choose your preferred framework</Fieldset.HelperText>
    <Fieldset.ErrorText>Please select a framework</Fieldset.ErrorText>
  </Fieldset.Root>
</template>

This renders as:

<fieldset aria-describedby="helper-id error-id">
  <legend>Select frameworks</legend>
  <div role="radiogroup">
    <!-- Screen readers may not announce helper/error text -->
  </div>
  <span id="helper-id">Choose your preferred framework</span>
  <span id="error-id">Please select a framework</span>
</fieldset>

Better pattern: aria-describedby on the radiogroup element ensures reliable announcements:

<div role="radiogroup" aria-labelledby="legend-id" aria-describedby="helper-id error-id">
  <!-- Screen readers consistently announce helper/error text -->
</div>

2. Redundant semantics

RadioGroup.Root already renders with role="radiogroup". Wrapping in <fieldset> creates double grouping semantics:

<!-- Redundant: both fieldset AND radiogroup provide grouping -->
<fieldset aria-labelledby="legend-id">
  <legend id="legend-id">Choose option</legend>
  <div role="radiogroup">
    <!-- Both elements semantically group the radios -->
  </div>
</fieldset>

Per WAI-ARIA APG, you should use either fieldset+legend or radiogroup+aria-labelledby, not both.

3. Inconsistency with Field pattern

Field works naturally for single controls:

<Field.Root>
  <Field.Label>Name</Field.Label>
  <Field.Input />
  <Field.HelperText>Enter your name</Field.HelperText>
</Field.Root>

But RadioGroup/CheckboxGroup feel forced with Fieldset:

<Fieldset.Root>
  <Fieldset.Legend>Framework</Fieldset.Legend>
  <RadioGroup.Root>
    <!-- RadioGroup is self-contained but needs external wrapper -->
  </RadioGroup.Root>
  <Fieldset.HelperText>Choose one</Fieldset.HelperText>
</Fieldset.Root>

4. API gaps

• Missing: RadioGroup.HelperText and RadioGroup.ErrorText
• Checkbox.Group has no label component at all ❌
• Currently requires Fieldset which has the screen reader issues

Proposed solution

Add helper text and error text components to RadioGroup and CheckboxGroup:

<!-- RadioGroup: Label exists, add HelperText/ErrorText -->
<RadioGroup.Root>
  <RadioGroup.Label>Select framework</RadioGroup.Label>
  <RadioGroup.HelperText>Choose your preferred framework</RadioGroup.HelperText>
  <RadioGroup.Item value="react">
    <RadioGroup.ItemControl />
    <RadioGroup.ItemText>React</RadioGroup.ItemText>
  </RadioGroup.Item>
  <RadioGroup.Item value="vue">
    <RadioGroup.ItemControl />
    <RadioGroup.ItemText>Vue</RadioGroup.ItemText>
  </RadioGroup.Item>
  <RadioGroup.ErrorText>Please select a framework</RadioGroup.ErrorText>
</RadioGroup.Root>

<!-- CheckboxGroup: Add Label, HelperText, ErrorText -->
<Checkbox.Group>
  <Checkbox.GroupLabel>Select frameworks</Checkbox.GroupLabel>
  <Checkbox.GroupHelperText>Choose your preferred frameworks</Checkbox.GroupHelperText>
  <Checkbox.Root value="react">
    <Checkbox.Label>React</Checkbox.Label>
    <Checkbox.Control />
  </Checkbox.Root>
  <Checkbox.Root value="vue">
    <Checkbox.Label>Vue</Checkbox.Label>
    <Checkbox.Control />
  </Checkbox.Root>
  <Checkbox.GroupErrorText>Select at least one</Checkbox.GroupErrorText>
</Checkbox.Group>

Benefits

1. Reliable screen reader support - ARIA attributes on the correct interactive elements
2. No redundant semantics - radiogroup role + aria-labelledby is sufficient per APG
3. Simpler composition - no external wrappers needed
4. Consistent API - both RadioGroup and CheckboxGroup have same pattern
5. Better DX - matches Field pattern and other libraries
6. Keeps Fieldset for appropriate use cases - true multi-control groups (multiple inputs, mixed control types)

Our current workaround

We have to use Fieldset.Context in templates to access fieldset IDs, then manually apply ARIA attributes to the inner group elements:

<template>
  <Fieldset.Root>
    <Fieldset.Legend>{{ label }}</Fieldset.Legend>
    <Fieldset.Context v-slot="fieldset">
      <RadioGroup.Root v-bind="getRadioGroupProps(fieldset)">
        <slot />
      </RadioGroup.Root>
    </Fieldset.Context>
    <Fieldset.HelperText>{{ helperText }}</Fieldset.HelperText>
    <Fieldset.ErrorText>{{ errorText }}</Fieldset.ErrorText>
  </Fieldset.Root>
</template>

<script setup>
function getRadioGroupProps(fieldset) {
  const describedByIds = []
  if (helperText && fieldset.ids.helperText) {
    describedByIds.push(fieldset.ids.helperText)
  }
  if (errorText && fieldset.ids.errorText) {
    describedByIds.push(fieldset.ids.errorText)
  }
  
  return {
    'aria-labelledby': fieldset.ids.legend,
    'aria-describedby': describedByIds.join(' ') || undefined,
  }
}
</script>

This ensures screen readers announce the helper and error text, but requires this workaround for every wrapper component when we feel it should be part of Ark UI.

Keen to get more background information on the current architectural choices and the suggestions above.

Thanks!