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

package/dist/components/formField/inputs/checkbox/CheckboxInput.stories.js

@@ -1,26 +1,733 @@
-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 { CheckboxInput } from './CheckboxInput';
 import { CheckboxGroup } from './CheckboxGroup';
+// ---------------------------------------------------------------------------
+// Component description — built as joined arrays to avoid no-useless-escape
+// on backtick code spans inside template literals.
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'The **CheckboxInput** is the Arbor design system checkbox control — a labelled, accessible toggle',
+    'for multi-select forms, boolean settings, and the canonical "select all" + indeterminate pattern.',
+].join(' ');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- **Multi-select lists** — when zero, one, or many options can be chosen simultaneously',
+    '  (e.g. "Which year groups should receive this communication?")',
+    '- **Single boolean settings** in a form that has a Save or Apply button',
+    '  (e.g. "Include past students in attendance report")',
+    '- **"Select all" with indeterminate state** — a parent checkbox that reflects the selection',
+    '  state of a group of child checkboxes',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Instead of CheckboxInput... | Use... | Why |',
+    '|---|---|---|',
+    '| Instant-apply boolean setting | [`Toggle`](?path=/docs/components-toggle--docs) | Toggle applies immediately; checkbox needs a Save action |',
+    '| Single-select from a list | [`RadioButtonInput`](?path=/docs/components-formfield-inputs-radiobutton--docs) | Radio communicates mutual exclusivity to screen readers |',
+    '| Free text entry | `TextInput` or `TextArea` | Checkboxes are binary; they cannot represent arbitrary text |',
+    '',
+    '---',
+    '',
+    '### Design guidance',
+    '',
+    '- **Click target is the entire row** — the label element wraps both the control and the label',
+    '  text, so clicking anywhere on the row toggles the checkbox.',
+    '- **Focus ring changes shape with label presence** — with a label, the focus ring is a pill',
+    '  (`--checkbox-radius`, 8px) wrapping the whole row. Without a label,',
+    '  it is a tight square (`--checkbox-input-control-radius`, 4px) around the control only.',
+    '- **Label text** — always phrase labels positively.',
+    '  Write "Include past students in attendance report" not "Do not exclude students who have left".',
+    '- **Disabled checkboxes** — always accompany a disabled control with a tooltip or helper text',
+    '  explaining why it cannot be interacted with. The user deserves to know.',
+    '- **Group checkboxes in a fieldset** — when presenting a list of options, wrap them in',
+    '  `CheckboxGroup` (which uses `Fieldset` internally) so the legend/heading is announced',
+    '  as the group label by screen readers.',
+    '- **The border is NOT a CSS border** — it is an inset `box-shadow`.',
+    '  Overriding the `border` property will have no visible effect.',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical gotchas',
+    '',
+    '#### 1. `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 checkbox will be visually frozen — toggling will not update it.',
+    '',
+    '```tsx',
+    '// BAD — no onChange; checkbox appears frozen',
+    '<CheckboxInput checked={isChecked} label="Include past students" />',
+    '',
+    '// GOOD — paired with onChange',
+    '<CheckboxInput',
+    '  checked={isChecked}',
+    '  onChange={(e) => setIsChecked(e.target.checked)}',
+    '  label="Include past students"',
+    '/>',
+    '```',
+    '',
+    '#### 2. `aria-checked="mixed"` is set automatically — do not spread it manually',
+    'When `indeterminate={true}`, the component sets `aria-checked="mixed"` on the real input.',
+    'Never pass `aria-checked` via `...rest` — the `{...rest}` spread comes after the explicit `aria-checked` in the JSX,',
+    'so your value would override the component\'s logic and break the indeterminate announcement for screen readers.',
+    '',
+    '#### 3. No `forwardRef` — consumers cannot attach a `ref` to CheckboxInput',
+    'The component uses an internal `ref` for the indeterminate DOM API. There is no `forwardRef`',
+    'wrapper, so `ref` passed from outside will not reach the underlying `<input>` element.',
+    '',
+    '#### 4. Label absence changes focus ring shape',
+    'Without a `label` prop, the container has no `.ds-checkbox-label__text` child, so the CSS',
+    '`:focus-within:not(:has(.ds-checkbox-label__text))` selector fires and applies the tighter',
+    '`--checkbox-input-control-radius` (4px square) instead of the pill `--checkbox-radius` (8px).',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- **The custom visual span is `aria-hidden="true"`** — all accessibility information flows',
+    '  through the real (visually hidden) native `<input>`. The custom span is purely decorative.',
+    '- **Keyboard interaction** — Tab moves focus between checkboxes; Space toggles the focused',
+    '  checkbox. This is native browser behaviour and requires no custom JavaScript.',
+    '- **`aria-checked="mixed"`** is automatically applied when `indeterminate={true}`,',
+    '  correctly communicating the partial-selection state to screen readers.',
+    '- **Group labelling** — wrap related checkboxes in `CheckboxGroup`. The Fieldset legend',
+    '  is announced as the group name by screen readers, giving vital context to each option.',
+    '- **Disabled explanation** — the `disabled` attribute removes the element from the tab order.',
+    '  Always provide a tooltip or visible helper text explaining why the checkbox is disabled,',
+    '  so non-keyboard users also receive the explanation.',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { CheckboxInput, CheckboxGroup } from '@arbor-education/design-system.components';",
+    '',
+    '// Prop type shorthand',
+    'function MyField(props: CheckboxInput.Props) { ... }',
+    'function MyGroup(props: CheckboxGroup.Props) { ... }',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `CheckboxInput.Props` | `indeterminate`, `label`, plus all `InputHTMLAttributes<HTMLInputElement>` |',
+    '| `CheckboxGroup.Props` | `options: CheckboxInputProps[]`, plus all `Fieldset.Props` (`legend`, `HTMLFieldSetElement` attrs) |',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[Toggle](?path=/docs/components-toggle--docs)',
+    '· [RadioButtonInput](?path=/docs/components-formfield-inputs-radiobutton--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 CheckboxInputDocsPage() {
+    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/Checkbox',
     component: CheckboxInput,
-};
-export const Default = {
     parameters: {
         layout: 'centered',
+        docs: {
+            page: CheckboxInputDocsPage,
+        },
     },
     tags: ['autodocs'],
     args: {
-        disabled: false,
+        onChange: fn(),
+    },
+    argTypes: {
+        checked: {
+            control: 'boolean',
+            description: [
+                'Whether the checkbox is checked. 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 checkbox will appear frozen.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        indeterminate: {
+            control: 'boolean',
+            description: [
+                'Displays the checkbox in the indeterminate (partially-selected) state, shown as a minus icon.',
+                'When `true`, the component sets `aria-checked="mixed"` automatically and applies the indeterminate',
+                'CSS state via the DOM API (`inputRef.current.indeterminate = true`). This cannot be set as a raw HTML attribute.',
+                'The canonical use case is a "Select all" checkbox that reflects partial child-item selection.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        label: {
+            control: 'text',
+            description: [
+                'Visible label text rendered next to the control. When present, the label is wrapped in a',
+                '`.ds-checkbox-label__text` span and the click target expands to the entire row.',
+                'When absent, only the control square is rendered — the focus ring also tightens from a pill',
+                '(`--checkbox-radius`, 8px) to a square (`--checkbox-input-control-radius`, 4px).',
+                'Label text should be positively phrased: "Include past students" not "Do not exclude past students".',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        disabled: {
+            control: 'boolean',
+            description: [
+                'Disables the checkbox. Applies muted styling and removes it from the tab order.',
+                'The value is NOT submitted in a form when disabled.',
+                'Always accompany a disabled checkbox with a tooltip or helper text explaining why it is disabled.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        onChange: {
+            description: [
+                'Change event handler — required for controlled usage. Fires whenever the user toggles the checkbox.',
+                'Access the new value via `e.target.checked`. Without this prop, a controlled checkbox will appear frozen.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'ChangeEventHandler<HTMLInputElement>' },
+            },
+        },
+        id: {
+            control: 'text',
+            description: [
+                'HTML `id` attribute — spread onto the real hidden `<input>` element.',
+                'Required by `CheckboxGroup` (passed through `options`) to key list items.',
+                'Also useful for associating external labels or `aria-describedby` targets.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        className: {
+            control: 'text',
+            description: [
+                'Additional CSS class names applied to the outer `<label>` container element',
+                '(the `.ds-checkbox-input__container` wrapper), not to the control square itself.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+    },
+};
+export default meta;
+// ---------------------------------------------------------------------------
+// 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 InteractiveControlledTemplate = () => {
+    const [attendanceSummary, setAttendanceSummary] = useState(false);
+    const [absenceAlerts, setAbsenceAlerts] = useState(true);
+    const [lateArrivals, setLateArrivals] = useState(false);
+    return (_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: "Notification preferences \u2014 all three are independently controlled via local state." }), _jsx(CheckboxInput, { id: "attendance-summary", checked: attendanceSummary, onChange: e => setAttendanceSummary(e.target.checked), label: "Include past students in attendance report" }), _jsx(CheckboxInput, { id: "absence-alerts", checked: absenceAlerts, onChange: e => setAbsenceAlerts(e.target.checked), label: "Send absence alert to parents" }), _jsx(CheckboxInput, { id: "late-arrivals", checked: lateArrivals, onChange: e => setLateArrivals(e.target.checked), label: "Notify form tutor of late arrivals" }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: ["State: attendance summary", ' ', attendanceSummary ? 'on' : 'off', ", absence alerts", ' ', absenceAlerts ? 'on' : 'off', ", late arrival notifications", ' ', lateArrivals ? 'on' : 'off', "."] })] }));
+};
+const PUPIL_OPTIONS = [
+    { id: 'pupil-maya', label: 'Maya Osei-Bonsu' },
+    { id: 'pupil-rahul', label: 'Rahul Kapoor' },
+    { id: 'pupil-freya', label: 'Freya Lindqvist' },
+];
+const SelectAllWithIndeterminateTemplate = () => {
+    const [selected, setSelected] = useState(new Set(['pupil-maya']));
+    const allChecked = selected.size === PUPIL_OPTIONS.length;
+    const someChecked = selected.size > 0 && !allChecked;
+    const handleSelectAll = (e) => {
+        if (e.target.checked) {
+            setSelected(new Set(PUPIL_OPTIONS.map(o => o.id)));
+        }
+        else {
+            setSelected(new Set());
+        }
+    };
+    const handleOption = (id) => (e) => {
+        setSelected((prev) => {
+            const next = new Set(prev);
+            if (e.target.checked) {
+                next.add(id);
+            }
+            else {
+                next.delete(id);
+            }
+            return next;
+        });
+    };
+    return (_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: "Generate end-of-term report for:" }), _jsx(CheckboxInput, { id: "select-all-pupils", checked: allChecked, indeterminate: someChecked, onChange: handleSelectAll, label: "All pupils in Year 9 Elm" }), _jsx("div", { style: { paddingLeft: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }, children: PUPIL_OPTIONS.map(option => (_jsx(CheckboxInput, { id: option.id, checked: selected.has(option.id), onChange: handleOption(option.id), label: option.label }, option.id))) }), _jsxs("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: [selected.size, ' ', "of", PUPIL_OPTIONS.length, ' ', "pupils selected."] })] }));
+};
+const CheckboxGroupStoryTemplate = () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxGroup, { legend: "Absence alert recipients", options: [
+            { id: 'recipient-parent', label: 'Parent / guardian', checked: true, onChange: fn() },
+            { id: 'recipient-tutor', label: 'Form tutor', checked: false, onChange: fn() },
+            { id: 'recipient-head', label: 'Head of year', checked: false, onChange: fn() },
+        ] }) }));
+const CheckboxGroupDisabledTemplate = () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxGroup, { legend: "Report export options (locked for current academic year)", disabled: true, options: [
+            { id: 'export-pdf', label: 'Generate end-of-term report', checked: true, onChange: fn() },
+            { id: 'export-csv', label: 'Export attendance data as CSV', checked: false, onChange: fn() },
+            { id: 'export-email', label: 'Email summary to head of year', checked: false, onChange: fn() },
+        ] }) }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = {
+    args: {
         checked: false,
         indeterminate: false,
-        label: 'Label text',
+        label: 'Include past students in attendance report',
+        disabled: false,
     },
+    render: args => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxInput, { ...args }) })),
 };
-export const CheckboxGroupStory = {
-    render: () => {
-        return (_jsx(CheckboxGroup, { legend: "Checkbox group", options: [{ id: 'option1', label: 'Option 1' }, { id: 'option2', label: 'Option 2' }, { id: 'option3', label: 'Option 3' }] }));
+export const Checked = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxInput, { id: "checked-example", checked: true, onChange: fn(), label: "Send absence alert to parents" }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function CheckedExample() {
+  return (
+    <CheckboxInput
+      id="absence-alerts"
+      checked
+      onChange={(e) => console.log(e.target.checked)}
+      label="Send absence alert to parents"
+    />
+  );
+}
+
+export default CheckedExample;
+          `.trim(),
+            },
+        },
     },
-};
-export default meta;
+}, 'The checked state — a blue filled control with a white check icon. The `checked` prop is always controlled; pair it with an `onChange` handler so the user can toggle it.');
+export const Indeterminate = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxInput, { id: "indeterminate-example", checked: false, indeterminate: true, onChange: fn(), label: "All pupils in Year 9 Elm" }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function IndeterminateExample() {
+  // Indeterminate is the "some but not all" state — typically used on a
+  // "Select all" parent checkbox when child items are partially selected.
+  return (
+    <CheckboxInput
+      id="select-all"
+      checked={false}
+      indeterminate
+      onChange={(e) => console.log('Select all toggled:', e.target.checked)}
+      label="All pupils in Year 9 Elm"
+    />
+  );
+}
+
+export default IndeterminateExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    'The indeterminate state — a blue filled control with a minus icon, signalling partial selection.',
+    '`indeterminate` is set via the DOM API (`inputRef.current.indeterminate = true`) inside a `useEffect`.',
+    'You just pass `indeterminate={true}` as a prop — the component handles the DOM wiring.',
+    'The component also automatically sets `aria-checked="mixed"` so screen readers correctly',
+    'announce the partial-selection state. See the **SelectAllWithIndeterminate** story for the',
+    'full interactive "select all" pattern.',
+].join(' '));
+export const DisabledUnchecked = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxInput, { id: "disabled-unchecked", checked: false, disabled: true, onChange: fn(), label: "Lock timetable for current academic year" }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function DisabledUncheckedExample() {
+  // Disabled — pair with a Tooltip explaining why so users understand the constraint.
+  return (
+    <CheckboxInput
+      id="lock-timetable"
+      checked={false}
+      disabled
+      onChange={() => {}}
+      label="Lock timetable for current academic year"
+    />
+  );
+}
+
+export default DisabledUncheckedExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    'A disabled, unchecked checkbox. 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 checkbox with a tooltip or helper text that explains why it is',
+    'disabled — for example: "This option is unavailable until the academic year has been published."',
+].join(' '));
+export const DisabledChecked = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxInput, { id: "disabled-checked", checked: true, disabled: true, onChange: fn(), label: "Lock timetable for current academic year" }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function DisabledCheckedExample() {
+  return (
+    <CheckboxInput
+      id="lock-timetable"
+      checked
+      disabled
+      onChange={() => {}}
+      label="Lock timetable for current academic year"
+    />
+  );
+}
+
+export default DisabledCheckedExample;
+          `.trim(),
+            },
+        },
+    },
+}, 'A disabled, already-checked checkbox. This is appropriate for read-only settings that are currently active but cannot be changed — for example, a system-enforced policy. Always provide a tooltip or helper text explaining why the option cannot be toggled.');
+export const DisabledIndeterminate = withDescription({
+    render: () => (_jsx("div", { style: { padding: 'var(--spacing-xlarge)' }, children: _jsx(CheckboxInput, { id: "disabled-indeterminate", checked: false, indeterminate: true, disabled: true, onChange: fn(), label: "All pupils in Year 9 Elm" }) })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function DisabledIndeterminateExample() {
+  return (
+    <CheckboxInput
+      id="select-all"
+      checked={false}
+      indeterminate
+      disabled
+      onChange={() => {}}
+      label="All pupils in Year 9 Elm"
+    />
+  );
+}
+
+export default DisabledIndeterminateExample;
+          `.trim(),
+            },
+        },
+    },
+}, 'A disabled indeterminate checkbox — the partial-selection state rendered in muted styling. The minus icon uses `--checkbox-input-control-indeterminate-disabled-color-icon`, a distinct token from the enabled indeterminate icon colour, so the disabled state is visually differentiated.');
+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: "Unchecked (no label \u2014 tight square focus ring):" }), _jsx(CheckboxInput, { id: "no-label-unchecked", checked: false, onChange: fn(), "aria-label": "Include in report" }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)' }, children: "Checked (no label):" }), _jsx(CheckboxInput, { id: "no-label-checked", checked: true, onChange: fn(), "aria-label": "Include in report" })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function WithoutLabelExample() {
+  // When there is no visible label, always provide aria-label for screen readers.
+  // The focus ring becomes a tight square (--checkbox-input-control-radius: 4px)
+  // instead of the wider pill (--checkbox-radius: 8px).
+  return (
+    <CheckboxInput
+      id="row-select"
+      checked={isSelected}
+      onChange={(e) => setIsSelected(e.target.checked)}
+      aria-label="Select this student row"
+    />
+  );
+}
+
+export default WithoutLabelExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    'CheckboxInput without a `label` prop — renders just the control square with no adjacent text.',
+    'This is typical in data table row-selection columns where the column header provides the context.',
+    'When omitting `label`, always pass `aria-label` or `aria-labelledby` so screen reader users',
+    'understand what the checkbox controls.',
+    'The focus ring also changes: without `.ds-checkbox-label__text` present, the CSS selector',
+    '`:focus-within:not(:has(.ds-checkbox-label__text))` applies `--checkbox-input-control-radius`',
+    '(4px square) instead of the pill `--checkbox-radius` (8px).',
+].join(' '));
+export const AllStates = withDescription({
+    render: () => (_jsxs("div", { style: { maxWidth: '32rem', 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(CheckboxInput, { id: "all-unchecked", checked: false, onChange: fn(), label: "Unchecked \u2014 default state" }), _jsx(CheckboxInput, { id: "all-checked", checked: true, onChange: fn(), label: "Checked \u2014 option selected" }), _jsx(CheckboxInput, { id: "all-indeterminate", checked: false, indeterminate: true, onChange: fn(), label: "Indeterminate \u2014 partial selection" }), _jsx("p", { style: { margin: 0, color: 'var(--color-grey-600)', fontSize: 'var(--font-size-2-13)', marginTop: 'var(--spacing-small)' }, children: "Disabled states:" }), _jsx(CheckboxInput, { id: "all-disabled-unchecked", checked: false, disabled: true, onChange: fn(), label: "Disabled unchecked" }), _jsx(CheckboxInput, { id: "all-disabled-checked", checked: true, disabled: true, onChange: fn(), label: "Disabled checked" }), _jsx(CheckboxInput, { id: "all-disabled-indeterminate", checked: false, indeterminate: true, disabled: true, onChange: fn(), label: "Disabled indeterminate" })] })),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function AllStatesExample() {
+  // Static display of all six visual states.
+  // In a real application every CheckboxInput needs an onChange handler.
+  return (
+    <>
+      {/* Enabled */}
+      <CheckboxInput id="s1" checked={false} onChange={() => {}} label="Unchecked" />
+      <CheckboxInput id="s2" checked onChange={() => {}} label="Checked" />
+      <CheckboxInput id="s3" checked={false} indeterminate onChange={() => {}} label="Indeterminate" />
+      {/* Disabled */}
+      <CheckboxInput id="s4" checked={false} disabled onChange={() => {}} label="Disabled unchecked" />
+      <CheckboxInput id="s5" checked disabled onChange={() => {}} label="Disabled checked" />
+      <CheckboxInput id="s6" checked={false} indeterminate disabled onChange={() => {}} label="Disabled indeterminate" />
+    </>
+  );
+}
+
+export default AllStatesExample;
+          `.trim(),
+            },
+        },
+    },
+}, 'A side-by-side reference showing all six visual states: unchecked, checked, indeterminate, and their three disabled counterparts. The icon colour token changes between enabled and disabled variants — checked-disabled uses `--checkbox-input-control-checked-disabled-color-icon` while indeterminate-disabled uses `--checkbox-input-control-indeterminate-disabled-color-icon`.');
+export const InteractiveControlled = withDescription({
+    render: () => _jsx(InteractiveControlledTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+function NotificationPreferencesExample() {
+  const [attendanceSummary, setAttendanceSummary] = useState(false);
+  const [absenceAlerts, setAbsenceAlerts] = useState(true);
+  const [lateArrivals, setLateArrivals] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+      <CheckboxInput
+        id="attendance-summary"
+        checked={attendanceSummary}
+        onChange={(e) => setAttendanceSummary(e.target.checked)}
+        label="Include past students in attendance report"
+      />
+      <CheckboxInput
+        id="absence-alerts"
+        checked={absenceAlerts}
+        onChange={(e) => setAbsenceAlerts(e.target.checked)}
+        label="Send absence alert to parents"
+      />
+      <CheckboxInput
+        id="late-arrivals"
+        checked={lateArrivals}
+        onChange={(e) => setLateArrivals(e.target.checked)}
+        label="Notify form tutor of late arrivals"
+      />
+    </div>
+  );
+}
+
+export default NotificationPreferencesExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    'Three independently controlled checkboxes wired to local `useState`. Each checkbox manages its own boolean state.',
+    'This is the fundamental controlled-checkbox pattern in React: `checked` reflects state, `onChange`',
+    'reads `e.target.checked` and calls the setter. Try toggling each option — the status text below updates in real time.',
+].join(' '));
+export const SelectAllWithIndeterminate = withDescription({
+    render: () => _jsx(SelectAllWithIndeterminateTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { CheckboxInput } from '@arbor-education/design-system.components';
+
+const PUPILS = [
+  { id: 'pupil-maya', label: 'Maya Osei-Bonsu' },
+  { id: 'pupil-rahul', label: 'Rahul Kapoor' },
+  { id: 'pupil-freya', label: 'Freya Lindqvist' },
+];
+
+function SelectAllExample() {
+  const [selected, setSelected] = useState(new Set(['pupil-maya']));
+
+  const allChecked = selected.size === PUPILS.length;
+  const someChecked = selected.size > 0 && !allChecked;
+
+  const handleSelectAll = (e) => {
+    setSelected(e.target.checked ? new Set(PUPILS.map((p) => p.id)) : new Set());
+  };
+
+  const handlePupil = (id) => (e) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      e.target.checked ? next.add(id) : next.delete(id);
+      return next;
+    });
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+      {/* Parent "Select all" checkbox */}
+      <CheckboxInput
+        id="select-all"
+        checked={allChecked}
+        indeterminate={someChecked}
+        onChange={handleSelectAll}
+        label="All pupils in Year 9 Elm"
+      />
+      {/* Child checkboxes */}
+      <div style={{ paddingLeft: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-medium)' }}>
+        {PUPILS.map((pupil) => (
+          <CheckboxInput
+            key={pupil.id}
+            id={pupil.id}
+            checked={selected.has(pupil.id)}
+            onChange={handlePupil(pupil.id)}
+            label={pupil.label}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default SelectAllExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    'The canonical indeterminate pattern: a "Select all" parent checkbox whose state is derived from its children.',
+    '`allChecked` is `true` when every item is in the set; `someChecked` drives `indeterminate`',
+    'when at least one (but not all) items are selected.',
+    'Try checking and unchecking individual pupils — the parent checkbox transitions between',
+    'unchecked → indeterminate → checked automatically.',
+    'Clicking the parent when indeterminate selects all; clicking again deselects all.',
+].join(' '));
+export const CheckboxGroupStory = withDescription({
+    name: 'CheckboxGroup',
+    render: () => _jsx(CheckboxGroupStoryTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxGroup } from '@arbor-education/design-system.components';
+
+function AbsenceAlertRecipientsExample() {
+  return (
+    <CheckboxGroup
+      legend="Absence alert recipients"
+      options={[
+        { id: 'recipient-parent', label: 'Parent / guardian', checked: true, onChange: () => {} },
+        { id: 'recipient-tutor', label: 'Form tutor', checked: false, onChange: () => {} },
+        { id: 'recipient-head', label: 'Head of year', checked: false, onChange: () => {} },
+      ]}
+    />
+  );
+}
+
+export default AbsenceAlertRecipientsExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    '`CheckboxGroup` composes `Fieldset` and a list of `CheckboxInput` instances. Pass your options as an',
+    'array of `CheckboxInput.Props` objects to the `options` prop — each object is spread onto a',
+    '`CheckboxInput`, so every `CheckboxInputProps` is valid here (including `checked`, `onChange`,',
+    '`disabled`, `indeterminate`, and `label`).',
+    'The `legend` prop renders a `<legend>` inside the `<fieldset>` — screen readers announce it as',
+    'the group label before each option, giving essential context.',
+    'The vertical gap between options is controlled by the token',
+    '`--checkbox-or-radio-button-group-spacing-gap-vertical` inside Fieldset — do not add your own gap wrapper.',
+].join(' '));
+export const CheckboxGroupDisabled = withDescription({
+    name: 'CheckboxGroup — Fieldset-level disabled',
+    render: () => _jsx(CheckboxGroupDisabledTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { CheckboxGroup } from '@arbor-education/design-system.components';
+
+function LockedReportOptionsExample() {
+  // Pass disabled directly on CheckboxGroup — it flows through Fieldset's
+  // HTMLFieldSetElement props and disables ALL child checkboxes at once.
+  return (
+    <CheckboxGroup
+      legend="Report export options (locked for current academic year)"
+      disabled
+      options={[
+        { id: 'export-pdf', label: 'Generate end-of-term report', checked: true, onChange: () => {} },
+        { id: 'export-csv', label: 'Export attendance data as CSV', checked: false, onChange: () => {} },
+        { id: 'export-email', label: 'Email summary to head of year', checked: false, onChange: () => {} },
+      ]}
+    />
+  );
+}
+
+export default LockedReportOptionsExample;
+          `.trim(),
+            },
+        },
+    },
+}, [
+    'Passing `disabled` to `CheckboxGroup` flows through the underlying `<fieldset>` element,',
+    'which disables ALL child `<input>` elements at once — native HTML behaviour, zero extra JavaScript.',
+    'This is the correct pattern for locking an entire group (e.g. a settings panel that is read-only',
+    'until the academic year is published). Individual options can still be disabled via their own',
+    '`disabled` prop inside `options` if you need partial disabling.',
+].join(' '));
 //# sourceMappingURL=CheckboxInput.stories.js.map