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

package/dist/components/formField/inputs/radio/RadioButtonInput.stories.js

@@ -1,13 +1,191 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+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 (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     title: 'Components/FormField/Inputs/RadioButton',
     component: RadioButtonInput,
     parameters: {
         layout: 'centered',
+        docs: {
+            page: RadioButtonInputDocsPage,
+        },
     },
     tags: ['autodocs'],
     args: {
@@ -16,74 +194,525 @@ 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' },
+            },
         },
     },
 };
 export default meta;
-// Default radio button
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...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 (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: [_jsx(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' },
+                ] }), _jsxs("p", { style: { margin: 'var(--spacing-medium) 0 0', color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: ["Selected:", ' ', grouping] })] }));
+};
+const RadioGroupWithErrorTemplate = () => {
+    const [method, setMethod] = useState('');
+    return (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: [_jsx(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 },
+                ] }), _jsx("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)',
+                }, children: "Please select a notification method to continue." })] }));
+};
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 export const Default = {
     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 => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(RadioButtonInput, { ...args }) })),
 };
-// Checked radio button
-export const Checked = {
-    args: {
-        name: 'example',
-        value: 'option1',
-        label: 'Option 1',
-        checked: true,
+export const Checked = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(RadioButtonInput, { id: "checked-example", name: "report-period", value: "current-term", checked: true, onChange: fn(), label: "Current term" }) })),
+    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(),
+            },
+        },
     },
-};
-// Disabled radio button
-export const Disabled = {
-    args: {
-        name: 'example',
-        value: 'option1',
-        label: 'Option 1',
-        disabled: true,
+}, '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.');
+export const Disabled = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(RadioButtonInput, { id: "disabled-example", name: "report-period", value: "last-term", checked: false, disabled: true, onChange: fn(), label: "Last term" }) })),
+    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(),
+            },
+        },
     },
-};
-// Disabled and checked
-export const DisabledChecked = {
-    args: {
-        name: 'example',
-        value: 'option1',
-        label: 'Option 1',
-        disabled: true,
-        checked: true,
+}, [
+    '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(' '));
+export const DisabledChecked = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(RadioButtonInput, { id: "disabled-checked-example", name: "report-period", value: "current-term", checked: true, disabled: true, onChange: fn(), label: "Current term" }) })),
+    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(),
+            },
+        },
     },
-};
-// Radio button group example
-export const RadioGroup = {
-    render: () => {
-        const options = [{ label: 'Option 1', value: 'option1' }, { label: 'Option 2', value: 'option2' }, { label: 'Option 3', value: 'option3' }];
-        const [checkedValue, setCheckedValue] = useState(options[0]?.value ?? '');
-        return (_jsx(RadioButtonGroup, { legend: "Radio group", name: "group", options: options, checkedValue: checkedValue, onChange: e => setCheckedValue(e.target.value) }));
+}, '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 = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Report period" }), _jsx(RadioButtonInput, { id: "error-current-term", name: "error-report-period", value: "current-term", checked: false, hasError: true, onChange: fn(), label: "Current term" }), _jsx(RadioButtonInput, { id: "error-last-term", name: "error-report-period", value: "last-term", checked: false, hasError: true, onChange: fn(), label: "Last term" }), _jsx(RadioButtonInput, { id: "error-full-year", name: "error-report-period", value: "full-year", checked: false, hasError: true, onChange: fn(), label: "Full academic year" }), _jsx("p", { role: "alert", style: {
+                    margin: 0,
+                    color: 'var(--form-field-text-error-color-error-text)',
+                    fontSize: 'var(--font-size-2-13)',
+                }, children: "Please select a report period to continue." })] })),
+    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 = withDescription({
+    render: () => (_jsxs("div", { style: { padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)', alignItems: 'flex-start' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Unselected (no label \u2014 indicator only):" }), _jsx(RadioButtonInput, { id: "no-label-unselected", name: "no-label-group", value: "option-a", checked: false, onChange: fn(), "aria-label": "Option A" }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Selected (no label):" }), _jsx(RadioButtonInput, { id: "no-label-selected", name: "no-label-group", value: "option-b", checked: true, onChange: fn(), "aria-label": "Option B" })] })),
+    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 = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }, children: [_jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Enabled states:" }), _jsx(RadioButtonInput, { id: "all-unselected", name: "all-states-group", value: "unselected", checked: false, onChange: fn(), label: "Unselected \u2014 default state" }), _jsx(RadioButtonInput, { id: "all-selected", name: "all-states-group", value: "selected", checked: true, onChange: fn(), label: "Selected \u2014 inner dot filled" }), _jsx("p", { style: { margin: 'var(--spacing-small) 0 0', color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Disabled states:" }), _jsx(RadioButtonInput, { id: "all-disabled-unselected", name: "all-disabled-group", value: "disabled-unselected", checked: false, disabled: true, onChange: fn(), label: "Disabled unselected" }), _jsx(RadioButtonInput, { id: "all-disabled-selected", name: "all-disabled-group", value: "disabled-selected", checked: true, disabled: true, onChange: fn(), label: "Disabled selected" })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { RadioButtonInput } from '@arbor-education/design-system.components';
+
+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" />
+    </>
+  );
+}
+
+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 = withDescription({
+    render: () => _jsx(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 = withDescription({
+    name: 'RadioGroup — Fieldset-level disabled',
+    render: () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(RadioButtonGroup, { legend: "Report period (locked \u2014 academic year not yet published)", name: "disabled-report-period", checkedValue: "current-term", onChange: fn(), disabled: true, 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' },
+            ] }) })),
+    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 = withDescription({
+    name: 'RadioGroup — field-level error',
+    render: () => _jsx(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="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(' '));
 //# sourceMappingURL=RadioButtonInput.stories.js.map