@arbor-education/design-system.components 0.12.0 → 0.13.1

package/src/components/formField/inputs/radio/RadioButtonInput.stories.tsx

@@ -1,15 +1,226 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { useState } from 'react';
 import { fn } from 'storybook/test';
-
 import { RadioButtonInput } from './RadioButtonInput';
 import { RadioButtonGroup } from './RadioButtonGroup';
-import { useState } from 'react';
+
+// ---------------------------------------------------------------------------
+// Component description — built as joined arrays to avoid no-useless-escape
+// on backtick code spans inside template literals.
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'The **RadioButtonInput** is the Arbor design system radio control — a labelled, accessible single-select',
+  'input for choosing exactly one option from a mutually exclusive set.',
+  'Always use at least two `RadioButtonInput` elements grouped by a shared `name` attribute,',
+  'or compose them with `RadioButtonGroup` which handles the group semantics automatically.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Single-select from a fixed set** — when exactly one option must be chosen and no "none" state',
+  '  is meaningful (e.g. "Which grouping should the attendance report use?")',
+  '- **Mutually exclusive choices** — when selecting one option implicitly deselects all others',
+  '  (e.g. "Notification method: Email / SMS / Post")',
+  '- **Short lists of 2–6 options** — radio buttons work best when all options are visible at once.',
+  '  For longer lists, consider `SelectDropdown` instead.',
+  '- **A default must always exist** — unlike checkboxes, radio buttons communicate that one option',
+  '  is always required. Pre-select the most common or safest option.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Instead of RadioButtonInput... | Use... | Why |',
+  '|---|---|---|',
+  '| Multiple options can be selected | [`CheckboxInput`](?path=/docs/components-formfield-inputs-checkbox--docs) | Checkboxes communicate multi-select; radios communicate single-select |',
+  '| Long lists (7+ options) | [`SelectDropdown`](?path=/docs/components-formfield-inputs-selectdropdown--docs) | Dropdowns save vertical space and are easier to scan |',
+  '| A single on/off toggle (instant apply) | [`Toggle`](?path=/docs/components-toggle--docs) | Toggle communicates immediate effect; radio needs a Submit/Save action |',
+  '| A lone single radio button | (avoid) | A lone radio button is always confusing — radios only make sense in groups of 2+ |',
+  '',
+  '---',
+  '',
+  '### Design guidance',
+  '',
+  '- **Always use in groups of 2+** — a single radio button has no meaning. The browser only enforces',
+  '  mutual exclusivity when there are multiple radios sharing the same `name` attribute.',
+  '- **Click target is the entire row** — the `<label>` element wraps both the indicator circle and the',
+  '  label text, so clicking anywhere on the row selects that option.',
+  '- **Vertical layout is the default** — stack radio buttons vertically. Horizontal layouts are only',
+  '  appropriate for very short sets with brief labels (e.g. "Yes / No").',
+  '- **Pre-select a sensible default** — radio buttons imply that a choice is required. Always start with',
+  '  one option selected rather than leaving all options unselected.',
+  '- **Error validation is at the field level** — do not show per-option errors.',
+  '  Render one error message below the entire group (see the `WithError` and `RadioGroupWithError` stories).',
+  '- **Keyboard interaction** — Tab moves focus to the radio group; arrow keys move between options',
+  '  within the group; Space selects the focused option. This is native browser behaviour.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical gotchas',
+  '',
+  '#### 1. `hasError` is ARIA-only — it makes zero visual difference',
+  '`hasError={true}` sets `aria-invalid="true"` on the native `<input>`. There are NO CSS rules',
+  'that change the appearance of the indicator circle based on `aria-invalid`.',
+  'To show a visible error state, YOU must render an error message element below the group.',
+  'See the `WithError` and `RadioGroupWithError` stories for the correct pattern.',
+  '',
+  '```tsx',
+  '// WRONG — hasError alone shows no visible change',
+  '<RadioButtonInput hasError name="period" value="term" label="Current term" checked onChange={() => {}} />',
+  '',
+  '// CORRECT — pair hasError with a visible error message rendered by the consumer',
+  '<div>',
+  '  <RadioButtonInput hasError name="period" value="term" label="Current term" checked onChange={() => {}} />',
+  '  <p role="alert" style={{ color: "var(--form-field-text-error-color-error-text)" }}>',
+  '    Please select a valid report period.',
+  '  </p>',
+  '</div>',
+  '```',
+  '',
+  '#### 2. `name` is not TypeScript-required but is functionally mandatory',
+  'TypeScript will not warn you if you omit `name`, but without it the browser cannot enforce',
+  'mutual exclusivity — all radios in the "group" can be selected simultaneously.',
+  'Always provide a `name` prop that is shared across all options in a group.',
+  '',
+  '```tsx',
+  '// BAD — no name; browser cannot enforce mutual exclusivity',
+  '<RadioButtonInput value="email" label="Email" checked onChange={() => {}} />',
+  '<RadioButtonInput value="sms" label="SMS" checked={false} onChange={() => {}} />',
+  '',
+  '// GOOD — shared name groups them correctly',
+  '<RadioButtonInput name="notification-method" value="email" label="Email" checked onChange={() => {}} />',
+  '<RadioButtonInput name="notification-method" value="sms" label="SMS" checked={false} onChange={() => {}} />',
+  '```',
+  '',
+  '#### 3. `checked` defaults to `false` — this component is always controlled',
+  'The component destructures `checked = false`, so React treats it as a controlled input from',
+  'the moment it mounts. You must always pair `checked` with an `onChange` handler.',
+  'Without `onChange`, the radio will appear frozen — clicking will not select it.',
+  '',
+  '#### 4. `option.id` is the React key in `RadioButtonGroup` — omitting it causes key warnings',
+  '`RadioButtonGroup` uses `option.id` as the React `key` when mapping over options.',
+  'Every option object must include an `id` field, or React will warn about missing keys.',
+  '',
+  '#### 5. `RadioButtonGroup` API differs from `CheckboxGroup`',
+  '`RadioButtonGroup` uses a single `checkedValue: string` + `onChange` at the group level.',
+  '`CheckboxGroup` uses per-item `checked` + `onChange` in each option object.',
+  'Do not mix up the two APIs.',
+  '',
+  '```tsx',
+  '// RadioButtonGroup — single checkedValue at group level',
+  '<RadioButtonGroup',
+  '  name="grouping"',
+  '  checkedValue={selectedValue}',
+  '  onChange={(e) => setSelectedValue(e.target.value)}',
+  '  options={[',
+  '    { id: "opt-year", value: "year-group", label: "Year group" },',
+  '    { id: "opt-reg", value: "reg-form", label: "Registration form" },',
+  '  ]}',
+  '/>',
+  '',
+  '// CheckboxGroup — per-item checked + onChange',
+  '<CheckboxGroup',
+  '  options={[',
+  '    { id: "opt-a", label: "Option A", checked: true, onChange: (e) => {} },',
+  '    { id: "opt-b", label: "Option B", checked: false, onChange: (e) => {} },',
+  '  ]}',
+  '/>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **Keyboard interaction** — Tab moves focus to the radio group; arrow keys (Up/Down or Left/Right)',
+  '  cycle through options within the group; Space selects the focused option. This is native browser',
+  '  behaviour requiring no custom JavaScript.',
+  '- **`aria-invalid`** — set by `hasError={true}` on the real `<input>`. Screen readers will announce',
+  '  the input as invalid, but consumers must also render a visible error message so sighted users see it.',
+  '- **Group labelling** — always wrap `RadioButtonInput` elements in `RadioButtonGroup` (which uses',
+  '  `Fieldset` + `<legend>` internally) or in your own `<fieldset>` + `<legend>`. The legend is',
+  '  announced by screen readers as the group name before each individual option label.',
+  '- **Never use a lone radio button** — a single radio button is inaccessible because there is no way',
+  '  to deselect it. Use a checkbox instead, or add at least one more option.',
+  '- **`id` on each option** — required both as the React key in `RadioButtonGroup` and for potential',
+  '  `aria-describedby` associations (e.g. linking to an inline error message).',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { RadioButtonInput, RadioButtonGroup } from '@arbor-education/design-system.components';",
+  '',
+  '// Prop type shorthand',
+  'function MyField(props: RadioButtonInput.Props) { ... }',
+  'function MyGroup(props: RadioButtonGroup.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `RadioButtonInput.Props` | `label`, `hasError`, plus all `InputHTMLAttributes<HTMLInputElement>` except `type` |',
+  '| `RadioButtonGroup.Props` | `name`, `options: RadioButtonInputProps[]`, `checkedValue`, `onChange`, plus `Fieldset.Props` (`legend`, `HTMLFieldSetElement` attrs) |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[CheckboxInput](?path=/docs/components-formfield-inputs-checkbox--docs)',
+  '· [Toggle](?path=/docs/components-toggle--docs)',
+  '· [FormField](?path=/docs/components-formfield--docs)',
+  '· [Fieldset](?path=/docs/components-formfield-fieldset--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function RadioButtonInputDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 
 const meta = {
   title: 'Components/FormField/Inputs/RadioButton',
   component: RadioButtonInput,
   parameters: {
     layout: 'centered',
+    docs: {
+      page: RadioButtonInputDocsPage,
+    },
   },
   tags: ['autodocs'],
   args: {
@@ -18,89 +229,759 @@ const meta = {
   argTypes: {
     checked: {
       control: 'boolean',
-      description: 'Whether the radio button is checked',
+      description: [
+        'Whether the radio button is selected. The component is always controlled — `checked` defaults to `false`',
+        'in the component destructuring, so React treats it as a controlled input immediately.',
+        'You must always pair this prop with an `onChange` handler, otherwise the radio will appear frozen.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
     disabled: {
       control: 'boolean',
-      description: 'Disable the radio button',
+      description: [
+        'Disables the radio button. Applies muted styling and removes it from the tab order.',
+        'The value is NOT submitted in a form when disabled.',
+        'Always accompany a disabled radio with a tooltip or helper text explaining why it is disabled.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
     hasError: {
       control: 'boolean',
-      description: 'Show error state',
+      description: [
+        '**ARIA-only** — sets `aria-invalid="true"` on the native `<input>` element.',
+        'This makes ZERO visual difference to the indicator circle — there are no CSS rules for the error state.',
+        'Consumers must separately render a visible error message below the group.',
+        'See the `WithError` and `RadioGroupWithError` stories for the correct pattern.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+      },
     },
     label: {
       control: 'text',
-      description: 'Label text for the radio button',
+      description: [
+        'Visible label text rendered next to the indicator circle.',
+        'When present, it is wrapped in a `.ds-radio-button-input__text` span and the click target',
+        'expands to the entire row.',
+        'When absent, only the indicator circle is rendered — always provide `aria-label` in that case.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
     name: {
       control: 'text',
-      description: 'Name attribute for the radio button group',
+      description: [
+        'HTML `name` attribute — functionally mandatory even though TypeScript does not require it.',
+        'All radio buttons in the same group must share the same `name` value so the browser can enforce',
+        'mutual exclusivity (selecting one deselects all others with the same name).',
+        'Omitting `name` means multiple radios can be "selected" simultaneously — a broken experience.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
     value: {
       control: 'text',
-      description: 'Value attribute for the radio button',
+      description: [
+        'The value submitted with the form when this radio button is selected.',
+        'Also the value used in `RadioButtonGroup` — the `checkedValue` prop is compared against each',
+        'option\'s `value` to determine which radio is selected.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    onChange: {
+      description: [
+        'Change event handler — required for controlled usage. Fires when the user selects this option.',
+        'Access the selected value via `e.target.value`.',
+        'Without this prop, a controlled radio will appear frozen when clicked.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'ChangeEventHandler<HTMLInputElement>' },
+      },
+    },
+    id: {
+      control: 'text',
+      description: [
+        'HTML `id` attribute — spread onto the native `<input>` element.',
+        'Required by `RadioButtonGroup` (passed via `options`) to key list items.',
+        'Also useful for associating external `aria-describedby` targets (e.g. an error message).',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    className: {
+      control: 'text',
+      description: [
+        'Additional CSS class names applied to the outer `<label>` container element',
+        '(the `.ds-radio-button-input__container` wrapper), not to the indicator circle itself.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
   },
 } satisfies Meta<typeof RadioButtonInput>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof RadioButtonInput>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string | string[]): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: Array.isArray(description) ? description.join(' ') : description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stateful template components
+// Named components avoid hooks-in-callbacks lint issues (react-hooks plugin
+// is NOT configured in this project — do not add eslint-disable comments).
+// ---------------------------------------------------------------------------
+
+const RadioGroupTemplate = () => {
+  const [grouping, setGrouping] = useState('year-group');
+
+  return (
+    <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+      <RadioButtonGroup
+        legend="Attendance grouping"
+        name="attendance-grouping"
+        checkedValue={grouping}
+        onChange={e => setGrouping(e.target.value)}
+        options={[
+          { id: 'opt-custom', value: 'custom-group', label: 'Custom group' },
+          { id: 'opt-year', value: 'year-group', label: 'Year group' },
+          { id: 'opt-reg', value: 'reg-form', label: 'Registration form' },
+        ]}
+      />
+      <p style={{ margin: 'var(--spacing-medium) 0 0', color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>
+        Selected:
+        {' '}
+        {grouping}
+      </p>
+    </div>
+  );
+};
+
+const RadioGroupWithErrorTemplate = () => {
+  const [method, setMethod] = useState('');
+
+  return (
+    <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+      <RadioButtonGroup
+        legend="Notification method"
+        name="notification-method"
+        checkedValue={method}
+        onChange={e => setMethod(e.target.value)}
+        options={[
+          { id: 'opt-email', value: 'email', label: 'Email', hasError: true },
+          { id: 'opt-sms', value: 'sms', label: 'SMS', hasError: true },
+          { id: 'opt-post', value: 'post', label: 'Post', hasError: true },
+        ]}
+      />
+      <p
+        role="alert"
+        style={{
+          margin: 'var(--spacing-small) 0 0',
+          color: 'var(--form-field-text-error-color-error-text)',
+          fontSize: 'var(--font-size-2-13)',
+        }}
+      >
+        Please select a notification method to continue.
+      </p>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
-// Default radio button
 export const Default: Story = {
   args: {
-    name: 'example',
-    value: 'option1',
-    label: 'Option 1',
+    name: 'report-period',
+    value: 'current-term',
+    label: 'Current term',
     checked: false,
+    disabled: false,
+    hasError: false,
   },
+  render: args => (
+    <div style={{ padding: 'var(--spacing-xlarge)' }}>
+      <RadioButtonInput {...args} />
+    </div>
+  ),
 };
 
-// Checked radio button
-export const Checked: Story = {
-  args: {
-    name: 'example',
-    value: 'option1',
-    label: 'Option 1',
-    checked: true,
+export const Checked: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)' }}>
+        <RadioButtonInput
+          id="checked-example"
+          name="report-period"
+          value="current-term"
+          checked
+          onChange={fn()}
+          label="Current term"
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
+
+function CheckedExample() {
+  return (
+    <RadioButtonInput
+      id="report-current-term"
+      name="report-period"
+      value="current-term"
+      checked
+      onChange={(e) => console.log(e.target.value)}
+      label="Current term"
+    />
+  );
+}
+
+export default CheckedExample;
+          `.trim(),
+        },
+      },
+    },
   },
-};
+  'The selected (checked) state — the indicator circle fills with a solid inner dot. `checked` is always controlled; pair it with an `onChange` handler so the user can change the selection.',
+);
 
-// Disabled radio button
-export const Disabled: Story = {
-  args: {
-    name: 'example',
-    value: 'option1',
-    label: 'Option 1',
-    disabled: true,
+export const Disabled: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)' }}>
+        <RadioButtonInput
+          id="disabled-example"
+          name="report-period"
+          value="last-term"
+          checked={false}
+          disabled
+          onChange={fn()}
+          label="Last term"
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  // Disabled — pair with a Tooltip or helper text explaining why.
+  return (
+    <RadioButtonInput
+      id="report-last-term"
+      name="report-period"
+      value="last-term"
+      checked={false}
+      disabled
+      onChange={() => {}}
+      label="Last term"
+    />
+  );
+}
+
+export default DisabledExample;
+          `.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    'A disabled, unselected radio button. The control renders with muted styling and the cursor changes to `not-allowed`.',
+    'The field is removed from the tab order and its value is not submitted in a form.',
+    'Always accompany a disabled radio with a tooltip or visible helper text that explains why it is',
+    'disabled — for example: "Last term data is not yet available."',
+  ].join(' '),
+);
 
-// Disabled and checked
-export const DisabledChecked: Story = {
-  args: {
-    name: 'example',
-    value: 'option1',
-    label: 'Option 1',
-    disabled: true,
-    checked: true,
+export const DisabledChecked: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)' }}>
+        <RadioButtonInput
+          id="disabled-checked-example"
+          name="report-period"
+          value="current-term"
+          checked
+          disabled
+          onChange={fn()}
+          label="Current term"
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
+
+function DisabledCheckedExample() {
+  // Disabled and already selected — read-only enforced selection.
+  return (
+    <RadioButtonInput
+      id="report-current-term"
+      name="report-period"
+      value="current-term"
+      checked
+      disabled
+      onChange={() => {}}
+      label="Current term"
+    />
+  );
+}
+
+export default DisabledCheckedExample;
+          `.trim(),
+        },
+      },
+    },
   },
-};
+  'A disabled radio button that is already selected. This is appropriate for read-only settings where the current selection is system-enforced and cannot be changed. Always provide a tooltip or helper text explaining the constraint.',
+);
+
+export const WithError: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+        <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>
+          Report period
+        </p>
+        <RadioButtonInput
+          id="error-current-term"
+          name="error-report-period"
+          value="current-term"
+          checked={false}
+          hasError
+          onChange={fn()}
+          label="Current term"
+        />
+        <RadioButtonInput
+          id="error-last-term"
+          name="error-report-period"
+          value="last-term"
+          checked={false}
+          hasError
+          onChange={fn()}
+          label="Last term"
+        />
+        <RadioButtonInput
+          id="error-full-year"
+          name="error-report-period"
+          value="full-year"
+          checked={false}
+          hasError
+          onChange={fn()}
+          label="Full academic year"
+        />
+        <p
+          role="alert"
+          style={{
+            margin: 0,
+            color: 'var(--form-field-text-error-color-error-text)',
+            fontSize: 'var(--font-size-2-13)',
+          }}
+        >
+          Please select a report period to continue.
+        </p>
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
+
+function WithErrorExample() {
+  // IMPORTANT: hasError sets aria-invalid="true" on the <input> but makes
+  // NO visual change to the indicator circle — there are zero CSS rules for
+  // the error state. You MUST render the error message yourself.
+  return (
+    <div>
+      <RadioButtonInput
+        id="period-current"
+        name="report-period"
+        value="current-term"
+        checked={false}
+        hasError
+        onChange={() => {}}
+        label="Current term"
+      />
+      <RadioButtonInput
+        id="period-last"
+        name="report-period"
+        value="last-term"
+        checked={false}
+        hasError
+        onChange={() => {}}
+        label="Last term"
+      />
+      <RadioButtonInput
+        id="period-full"
+        name="report-period"
+        value="full-year"
+        checked={false}
+        hasError
+        onChange={() => {}}
+        label="Full academic year"
+      />
+      {/* Consumer-rendered error message — hasError alone shows nothing visually */}
+      <p role="alert" style={{ color: 'var(--form-field-text-error-color-error-text)' }}>
+        Please select a report period to continue.
+      </p>
+    </div>
+  );
+}
+
+export default WithErrorExample;
+          `.trim(),
+        },
+      },
+    },
+  },
+  [
+    '**Important:** `hasError={true}` sets `aria-invalid="true"` on the native `<input>` — this is',
+    'ARIA-only and makes zero visual difference to the indicator circle.',
+    'There are no CSS rules in the design system that change the indicator\'s appearance based on `aria-invalid`.',
+    'To communicate the error visually, you must render your own error message below the group (shown here',
+    'with `role="alert"` so screen readers announce it automatically).',
+    'Error validation should always be at the field level, not per-option.',
+  ].join(' '),
+);
+
+export const WithoutLabel: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)', alignItems: 'flex-start' }}>
+        <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>
+          Unselected (no label — indicator only):
+        </p>
+        <RadioButtonInput
+          id="no-label-unselected"
+          name="no-label-group"
+          value="option-a"
+          checked={false}
+          onChange={fn()}
+          aria-label="Option A"
+        />
+        <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>
+          Selected (no label):
+        </p>
+        <RadioButtonInput
+          id="no-label-selected"
+          name="no-label-group"
+          value="option-b"
+          checked
+          onChange={fn()}
+          aria-label="Option B"
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
+
+function WithoutLabelExample() {
+  // When there is no visible label, always provide aria-label for screen readers.
+  return (
+    <RadioButtonInput
+      id="option-a"
+      name="my-group"
+      value="option-a"
+      checked={isSelected}
+      onChange={(e) => setSelected(e.target.value)}
+      aria-label="Option A"
+    />
+  );
+}
+
+export default WithoutLabelExample;
+          `.trim(),
+        },
+      },
+    },
+  },
+  [
+    'RadioButtonInput without a `label` prop — renders just the indicator circle with no adjacent text.',
+    'When omitting `label`, always pass `aria-label` or `aria-labelledby` so screen reader users',
+    'understand what each option represents.',
+  ].join(' '),
+);
+
+export const AllStates: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+        <p style={{ margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>
+          Enabled states:
+        </p>
+        <RadioButtonInput
+          id="all-unselected"
+          name="all-states-group"
+          value="unselected"
+          checked={false}
+          onChange={fn()}
+          label="Unselected — default state"
+        />
+        <RadioButtonInput
+          id="all-selected"
+          name="all-states-group"
+          value="selected"
+          checked
+          onChange={fn()}
+          label="Selected — inner dot filled"
+        />
+        <p style={{ margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }}>
+          Disabled states:
+        </p>
+        <RadioButtonInput
+          id="all-disabled-unselected"
+          name="all-disabled-group"
+          value="disabled-unselected"
+          checked={false}
+          disabled
+          onChange={fn()}
+          label="Disabled unselected"
+        />
+        <RadioButtonInput
+          id="all-disabled-selected"
+          name="all-disabled-group"
+          value="disabled-selected"
+          checked
+          disabled
+          onChange={fn()}
+          label="Disabled selected"
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
 
-// Radio button group example
-export const RadioGroup: Story = {
-  render: () => {
-    const options = [{ label: 'Option 1', value: 'option1' }, { label: 'Option 2', value: 'option2' }, { label: 'Option 3', value: 'option3' }];
-    const [checkedValue, setCheckedValue] = useState<string>(options[0]?.value ?? '');
+function AllStatesExample() {
+  // Static display of all four visual states.
+  // In a real application every RadioButtonInput needs an onChange handler.
+  return (
+    <>
+      {/* Enabled */}
+      <RadioButtonInput name="g1" value="a" checked={false} onChange={() => {}} label="Unselected" />
+      <RadioButtonInput name="g1" value="b" checked onChange={() => {}} label="Selected" />
+      {/* Disabled */}
+      <RadioButtonInput name="g2" value="c" checked={false} disabled onChange={() => {}} label="Disabled unselected" />
+      <RadioButtonInput name="g2" value="d" checked disabled onChange={() => {}} label="Disabled selected" />
+    </>
+  );
+}
 
-    return (
+export default AllStatesExample;
+          `.trim(),
+        },
+      },
+    },
+  },
+  'A side-by-side reference showing all four visual states: unselected, selected, disabled unselected, and disabled selected. There is no visual error state on the indicator circle — `hasError` is ARIA-only. See the `WithError` story for the correct error pattern.',
+);
+
+export const RadioGroup: Story = withDescription(
+  {
+    render: () => <RadioGroupTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { RadioButtonGroup } from '@arbor-education/design-system.components';
+
+function AttendanceGroupingExample() {
+  const [grouping, setGrouping] = useState('year-group');
+
+  return (
+    <RadioButtonGroup
+      legend="Attendance grouping"
+      name="attendance-grouping"
+      checkedValue={grouping}
+      onChange={(e) => setGrouping(e.target.value)}
+      options={[
+        { id: 'opt-custom', value: 'custom-group', label: 'Custom group' },
+        { id: 'opt-year', value: 'year-group', label: 'Year group' },
+        { id: 'opt-reg', value: 'reg-form', label: 'Registration form' },
+      ]}
+    />
+  );
+}
+
+export default AttendanceGroupingExample;
+          `.trim(),
+        },
+      },
+    },
+  },
+  [
+    '`RadioButtonGroup` is the canonical way to render a set of radio buttons.',
+    'It composes `Fieldset` (which renders a `<fieldset>` + `<legend>`) and maps `options` to individual `RadioButtonInput` elements.',
+    'The `legend` prop is announced by screen readers as the group label before each option.',
+    'A single `checkedValue` + `onChange` at the group level manages the selection state — the group',
+    'compares `checkedValue` against each option\'s `value` to determine which radio is selected.',
+    'Try selecting different options — the state display below updates in real time.',
+  ].join(' '),
+);
+
+export const RadioGroupDisabled: Story = withDescription(
+  {
+    name: 'RadioGroup — Fieldset-level disabled',
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <RadioButtonGroup
+          legend="Report period (locked — academic year not yet published)"
+          name="disabled-report-period"
+          checkedValue="current-term"
+          onChange={fn()}
+          disabled
+          options={[
+            { id: 'dis-opt-current', value: 'current-term', label: 'Current term' },
+            { id: 'dis-opt-last', value: 'last-term', label: 'Last term' },
+            { id: 'dis-opt-full', value: 'full-year', label: 'Full academic year' },
+          ]}
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { RadioButtonGroup } from '@arbor-education/design-system.components';
+
+function DisabledGroupExample() {
+  // Passing disabled to RadioButtonGroup flows through Fieldset's HTMLFieldSetElement props,
+  // disabling ALL child radio buttons at once — native HTML behaviour, zero extra JavaScript.
+  return (
+    <RadioButtonGroup
+      legend="Report period (locked — academic year not yet published)"
+      name="report-period"
+      checkedValue="current-term"
+      onChange={() => {}}
+      disabled
+      options={[
+        { id: 'opt-current', value: 'current-term', label: 'Current term' },
+        { id: 'opt-last', value: 'last-term', label: 'Last term' },
+        { id: 'opt-full', value: 'full-year', label: 'Full academic year' },
+      ]}
+    />
+  );
+}
+
+export default DisabledGroupExample;
+          `.trim(),
+        },
+      },
+    },
+  },
+  [
+    'Passing `disabled` to `RadioButtonGroup` flows through the underlying `<fieldset>` element',
+    '(via `Fieldset`\'s `HTMLFieldSetElement` props), which disables ALL child `<input>` elements at once —',
+    'native HTML behaviour, zero extra JavaScript.',
+    'This is the correct pattern for locking an entire radio group (e.g. a settings panel that is',
+    'read-only until the academic year is published).',
+  ].join(' '),
+);
+
+export const RadioGroupWithError: Story = withDescription(
+  {
+    name: 'RadioGroup — field-level error',
+    render: () => <RadioGroupWithErrorTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { RadioButtonGroup } from '@arbor-education/design-system.components';
+
+function NotificationMethodWithErrorExample() {
+  const [method, setMethod] = useState('');
+
+  // hasError in each option sets aria-invalid="true" on each <input>.
+  // This makes ZERO visual difference to the indicator circles — there are
+  // no CSS rules for the aria-invalid error state. The visible error message
+  // below is the only thing that communicates the error to sighted users.
+  return (
+    <div>
       <RadioButtonGroup
-        legend="Radio group"
-        name="group"
-        options={options}
-        checkedValue={checkedValue}
-        onChange={e => setCheckedValue(e.target.value)}
+        legend="Notification method"
+        name="notification-method"
+        checkedValue={method}
+        onChange={(e) => setMethod(e.target.value)}
+        options={[
+          { id: 'opt-email', value: 'email', label: 'Email', hasError: true },
+          { id: 'opt-sms', value: 'sms', label: 'SMS', hasError: true },
+          { id: 'opt-post', value: 'post', label: 'Post', hasError: true },
+        ]}
       />
-    );
+      {/* Consumer-rendered error message — hasError alone shows nothing visually */}
+      <p role="alert" style={{ color: 'var(--form-field-text-error-color-error-text)' }}>
+        Please select a notification method to continue.
+      </p>
+    </div>
+  );
+}
+
+export default NotificationMethodWithErrorExample;
+          `.trim(),
+        },
+      },
+    },
   },
-};
+  [
+    '**Field-level validation** — error state is shown at the group level, not per option.',
+    '`hasError` is passed to each option in the `options` array, which sets `aria-invalid="true"`',
+    'on each native `<input>`. Screen readers will announce each option as invalid.',
+    '**However, `hasError` makes ZERO visual change to the indicator circles** — there are no CSS rules',
+    'for the error state. The visible error message rendered below the group (with `role="alert"`) is',
+    'the only thing that communicates the error to sighted users.',
+    'Start with no option selected and note how the error message is present — select any option to',
+    'resolve the validation in a real implementation.',
+  ].join(' '),
+);