@arbor-education/design-system.components 0.15.0 → 0.16.1

package/dist/components/formField/inputs/selectDropdown/SelectDropdown.stories.js

@@ -1,185 +1,846 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
+import { FormField } from '../../../formField/FormField';
 import { SelectDropdown } from './SelectDropdown';
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'SelectDropdown is a stylised dropdown select input that matches the Arbor design language.',
+    'It supports single-select and multi-select, option grouping, icons, two-line item layouts,',
+    'and both controlled and uncontrolled state management.',
+    '',
+    '> **Built on [Radix UI DropdownMenu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu).**',
+    '> The dropdown panel renders via a portal — do **not** place SelectDropdown inside a container',
+    '> with `overflow: hidden`, or the panel will be clipped.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- Replacing a native `<select>` when you need the Arbor visual style',
+    '- Offering a list of options for single or multi-selection within a form',
+    '- Displaying options with icons, section headers, or group separators',
+    '- When built-in form serialisation is useful (a hidden `<input type="hidden">` is always rendered)',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Situation | Use instead |',
+    '|---|---|',
+    '| Need native browser select for mobile or performance | Plain `<select>` inside a FormField |',
+    '| Need async search or type-to-filter | Combobox |',
+    '| Need individual options to be disabled | Custom `Dropdown` composition |',
+    '| Thousands of options | No virtualisation — consider a search-first pattern |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical usage patterns',
+    '',
+    '**`errorText` does not exist on SelectDropdown.** Error text belongs on `FormField`. Pass `errorText`',
+    'to `FormField` and use `inputType="selectDropdown"` — it automatically wires `hasError`,',
+    '`aria-invalid`, and `aria-describedby` for you.',
+    '',
+    '**`hasError` is visual-only.** It applies error styling to the trigger button but tells screen readers',
+    'nothing. Always pair it with `aria-invalid={true}`.',
+    '',
+    '**`id` is dual-purpose.** It is set as both the `name` on the hidden form input and the `id` on the',
+    'trigger button. Set this when using inside a `<form>` or when you need a `<label htmlFor>` to target the trigger.',
+    '',
+    '**Multi-select count display.** With `multiple` and no `placeholder` prop, the trigger shows',
+    '`"Select (2)"` when two items are selected. Setting a `placeholder` suppresses the count — the',
+    'trigger shows your placeholder string instead. Choose deliberately.',
+    '',
+    '**Controlled vs uncontrolled.** Providing `selectedValues` activates controlled mode — the component',
+    'stops managing its own state. You must update `selectedValues` via `onSelectionChange` or the',
+    'dropdown will appear frozen. Do not mix `initialSelectedValues` with `selectedValues`.',
+    '',
+    '**Groups are automatic.** Add `group: "Year 7"` to options and the component clusters them under',
+    '`<h3>` section headers. Headers only appear when two or more distinct `group` values exist.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- Always pair `hasError` with `aria-invalid={true}` — `hasError` is visual-only',
+    '- Use `aria-describedBy` to link to your error/hint message element',
+    '- When used standalone (outside FormField), set `id` and associate a `<label htmlFor={id}>`',
+    '- When used inside `FormField`, label association and ARIA wiring are automatic — prefer that pattern',
+    '- Keyboard navigation is built in via Radix UI: `↑ ↓` to move through options, `Enter` to select, `Esc` to close',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { SelectDropdown } from '@arbor-education/design-system.components';",
+    '',
+    'function MySelect(props: SelectDropdown.Props) { ... }',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `SelectDropdown.Props` | Full props interface (`SelectDropdownInputProps`) |',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[FormField](?path=/docs/components-formfield--docs) · [Dropdown](?path=/docs/components-dropdown--docs) · [ColourPickerDropdown](?path=/docs/components-formfield-inputs-colourpickerdropdown--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.';
+function SelectDropdownDocsPage() {
+    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 })] }));
+}
+// ---------------------------------------------------------------------------
+// Option fixtures
+// ---------------------------------------------------------------------------
+const yearGroupOptions = [
+    { label: 'Year 7', value: 'year7' },
+    { label: 'Year 8', value: 'year8' },
+    { label: 'Year 9', value: 'year9' },
+    { label: 'Year 10', value: 'year10' },
+    { label: 'Year 11', value: 'year11' },
+];
+const subjectOptions = [
+    { label: 'Mathematics', value: 'maths' },
+    { label: 'English', value: 'english' },
+    { label: 'Science', value: 'science' },
+    { label: 'History', value: 'history' },
+    { label: 'Geography', value: 'geography' },
+    { label: 'Art', value: 'art' },
+];
+const subjectOptionsWithIcons = [
+    { label: 'Mathematics', value: 'maths', icon: 'chart-column-increasing' },
+    { label: 'English', value: 'english', icon: 'book-open' },
+    { label: 'Science', value: 'science', icon: 'circle-check' },
+    { label: 'History', value: 'history', icon: 'clock-3' },
+    { label: 'Geography', value: 'geography', icon: 'flag' },
+];
+const attendanceReasonOptions = [
+    { label: 'Authorised absence', value: 'authorised', header: 'Planned' },
+    { label: 'Holiday', value: 'holiday', header: 'Planned' },
+    { label: 'Medical appointment', value: 'medical', header: 'Health' },
+    { label: 'Illness', value: 'illness', header: 'Health' },
+    { label: 'Unauthorised absence', value: 'unauthorised', header: 'Unplanned' },
+    { label: 'Late arrival', value: 'late', header: 'Unplanned' },
+];
+const groupedYearOptions = [
+    { label: 'Year 7', value: 'year7', group: 'Lower school' },
+    { label: 'Year 8', value: 'year8', group: 'Lower school' },
+    { label: 'Year 9', value: 'year9', group: 'Lower school' },
+    { label: 'Year 10', value: 'year10', group: 'Upper school' },
+    { label: 'Year 11', value: 'year11', group: 'Upper school' },
+    { label: 'Year 12', value: 'year12', group: 'Sixth form' },
+    { label: 'Year 13', value: 'year13', group: 'Sixth form' },
+];
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     title: 'Components/FormField/Inputs/SelectDropdown',
     component: SelectDropdown,
-};
-export const Default = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-        ],
-        multiple: false,
-        onSelectionChange: (value) => { console.log(value); },
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            page: SelectDropdownDocsPage,
+        },
     },
-};
-export const WithIcon = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1', icon: '3-dot' },
-            { label: 'Option 2', value: 'option2', icon: 'user' },
-            { label: 'Option 3', value: 'option3', icon: 'chart-spline' },
-        ],
-        multiple: true,
-        onSelectionChange: (value) => { console.log(value); },
+    argTypes: {
+        'options': {
+            description: [
+                'Array of option items to display in the dropdown.',
+                'Each item must have a `value` string.',
+                '`label`, `icon`, `header`, and `group` are optional.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'SelectDropdownItemProps[]' },
+            },
+        },
+        'placeholder': {
+            description: [
+                'Text shown in the trigger when nothing is selected.',
+                'In multi-select mode, also shown when 2+ items are selected (suppressing the count display).',
+                'Defaults to `"Select"`.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: "'Select'" },
+            },
+        },
+        'multiple': {
+            description: [
+                'Enables multi-select mode.',
+                'The dropdown stays open after each selection and items toggle on/off.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'disabled': {
+            description: 'Disables the trigger button, preventing the dropdown from opening.',
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'hasError': {
+            description: [
+                '**Visual only.** Applies error styling to the trigger button.',
+                'Must be paired with `aria-invalid={true}` for screen reader support.',
+                'Do not pass `errorText` here — that prop does not exist. Use `FormField` with `errorText` instead.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'aria-invalid': {
+            description: [
+                'Communicates an invalid state to screen readers via the trigger button.',
+                'Always pair with `hasError`.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        'aria-describedBy': {
+            description: [
+                'ID of the element that describes this field (e.g. an error message or hint).',
+                'Passed through to the trigger button.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        'id': {
+            description: [
+                '**Dual-purpose.** Set as `name` on the hidden form input AND as `id` on the trigger button.',
+                'Required for label association (`<label htmlFor={id}>`) and form submission.',
+            ].join(' '),
+            control: 'text',
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        'alwaysShowPlaceholder': {
+            description: [
+                'When `true`, the trigger always displays the placeholder regardless of what is selected.',
+                'Use for action-style dropdowns (e.g. "Add filter") where the label must not change.',
+            ].join(' '),
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'false' },
+            },
+        },
+        'initialSelectedValues': {
+            description: [
+                'Uncontrolled mode only — sets the initial selection on mount.',
+                'Ignored if `selectedValues` is provided.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'string[]' },
+                defaultValue: { summary: '[]' },
+            },
+        },
+        'selectedValues': {
+            description: [
+                'Activates fully controlled mode.',
+                'You must update this via `onSelectionChange` — the component stops managing its own state.',
+                'Do not mix with `initialSelectedValues`.',
+            ].join(' '),
+            control: false,
+            table: {
+                type: { summary: 'string[]' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        'onSelectionChange': {
+            description: 'Fires after every selection change with the full updated array of selected values.',
+            action: 'onSelectionChange',
+            control: false,
+            table: {
+                type: { summary: '(value: string[]) => void' },
+            },
+        },
+        'open': {
+            description: 'Controls the open/closed state of the dropdown externally.',
+            control: 'boolean',
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
+        },
+        'onOpenChange': {
+            description: 'Fires when the dropdown attempts to open or close. Required when `open` is controlled.',
+            action: 'onOpenChange',
+            control: false,
+            table: {
+                type: { summary: '(open: boolean) => void' },
+            },
+        },
     },
 };
-export const DefaultWithGroups = {
-    args: {
-        title: 'titleValue',
-        multiple: true,
-        options: [
-            { label: 'Option 5', value: 'option5', group: 'Group 1' },
-            { label: 'Option 6', value: 'option6', group: 'Group 1' },
-            { label: 'Option 7', value: 'option7', group: 'Group 2' },
-            { label: 'Option 8', value: 'option8', group: 'Group 2' },
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-            { label: 'Option 4', value: 'option4' },
-            { label: 'Option 9', value: 'option9' },
-        ],
-        onSelectionChange: (value) => { console.log(value); },
-    },
-};
-export const DefaultMultiSelect = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-        ],
-        multiple: true,
-        onSelectionChange: (value) => { console.log(value); },
+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: description,
+            },
+        },
     },
+});
+// ---------------------------------------------------------------------------
+// Template components for stateful and composite stories
+// ---------------------------------------------------------------------------
+const WithInitialSelectionTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select a year group", initialSelectedValues: ['year9'], options: yearGroupOptions, onSelectionChange: values => console.log(values) }) }));
+const MultiSelectTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select subjects", multiple: true, options: subjectOptions, onSelectionChange: values => console.log(values) }) }));
+const MultiSelectWithCountTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { multiple: true, initialSelectedValues: ['maths', 'english', 'science'], options: subjectOptions, onSelectionChange: values => console.log(values) }) }));
+const DisabledTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select a year group", disabled: true, options: yearGroupOptions, onSelectionChange: values => console.log(values) }) }));
+const WithErrorTemplate = () => (_jsxs("div", { style: { maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }, children: [_jsx(SelectDropdown, { placeholder: "Select a year group", hasError: true, "aria-invalid": true, "aria-describedBy": "year-group-error", options: yearGroupOptions, onSelectionChange: values => console.log(values) }), _jsx("span", { id: "year-group-error", style: { fontSize: '0.875rem', color: 'var(--color-feedback-danger-600)' }, children: "Please select a year group" })] }));
+const WithIconsTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select a subject", options: subjectOptionsWithIcons, onSelectionChange: values => console.log(values) }) }));
+const WithItemHeadersTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select absence reason", options: attendanceReasonOptions, onSelectionChange: values => console.log(values) }) }));
+const WithGroupsTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select a year group", options: groupedYearOptions, onSelectionChange: values => console.log(values) }) }));
+const WithGroupsMultiSelectTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Select year groups", multiple: true, options: groupedYearOptions, onSelectionChange: values => console.log(values) }) }));
+const AlwaysShowPlaceholderTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { placeholder: "Add filter", alwaysShowPlaceholder: true, multiple: true, options: subjectOptions, onSelectionChange: values => console.log(values) }) }));
+const ControlledSingleSelectTemplate = () => {
+    const [selected, setSelected] = useState([]);
+    return (_jsxs("div", { style: { maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx(SelectDropdown, { placeholder: "Select a subject", selectedValues: selected, onSelectionChange: setSelected, options: subjectOptions }), _jsxs("span", { style: { fontSize: '0.875rem', color: 'var(--color-grey-600)' }, children: ["Selected:", ' ', selected.length > 0 ? selected.join(', ') : 'nothing yet'] })] }));
 };
-export const Placeholder = {
-    args: {
-        placeholder: 'placeholder',
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-        ],
-        onSelectionChange: (value) => { console.log(value); },
-    },
+const ControlledOpenTemplate = () => {
+    const [isOpen, setIsOpen] = useState(false);
+    return (_jsxs("div", { style: { maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }, children: [_jsx("button", { type: "button", onClick: () => setIsOpen(true), children: "Open dropdown externally" }), _jsx(SelectDropdown, { placeholder: "Select a subject", open: isOpen, onOpenChange: setIsOpen, options: subjectOptions, onSelectionChange: (values) => {
+                    console.log(values);
+                    setIsOpen(false);
+                } })] }));
 };
-export const EmptyPlaceHolder = {
+const InsideFormFieldTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Year group", id: "year-group-field", inputType: "selectDropdown", inputProps: {
+            placeholder: 'Select a year group',
+            options: yearGroupOptions,
+            onSelectionChange: values => console.log(values),
+        } }) }));
+const InsideFormFieldWithErrorTemplate = () => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(FormField, { label: "Year group", id: "year-group-error-field", inputType: "selectDropdown", errorText: "Please select a year group", inputProps: {
+            placeholder: 'Select a year group',
+            options: yearGroupOptions,
+            onSelectionChange: values => console.log(values),
+        } }) }));
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
     args: {
-        placeholder: '',
-        options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-        ],
+        options: yearGroupOptions,
+        placeholder: 'Select a year group',
+        multiple: false,
         disabled: false,
-        onSelectionChange: (value) => { console.log(value); },
     },
-};
-export const WithError = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-        ],
-        disabled: false,
-        errorText: 'This field is required',
-        onSelectionChange: (value) => { console.log(value); },
+    render: args => (_jsx("div", { style: { maxWidth: '320px' }, children: _jsx(SelectDropdown, { ...args }) })),
+}, 'The interactive canvas — every prop is wired to the Controls panel above. Use `options`, `placeholder`, `multiple`, and `disabled` to explore the full range of configurations.');
+export const WithInitialSelection = withDescription({
+    render: WithInitialSelectionTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function WithInitialSelectionExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select a year group"
+      initialSelectedValues={['year9']}
+      options={[
+        { label: 'Year 7', value: 'year7' },
+        { label: 'Year 8', value: 'year8' },
+        { label: 'Year 9', value: 'year9' },
+        { label: 'Year 10', value: 'year10' },
+        { label: 'Year 11', value: 'year11' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default WithInitialSelectionExample;
+`.trim(),
+            },
+        },
     },
-};
-export const Disabled = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
-        ],
-        disabled: true,
-        onSelectionChange: (value) => { console.log(value); },
+}, 'Uncontrolled mode with a pre-selected value via `initialSelectedValues`. The component manages its own state after mount — no `selectedValues` prop is needed. Use this when you only need to set a default and let the user take over.');
+export const MultiSelect = withDescription({
+    render: MultiSelectTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function MultiSelectExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select subjects"
+      multiple
+      options={[
+        { label: 'Mathematics', value: 'maths' },
+        { label: 'English', value: 'english' },
+        { label: 'Science', value: 'science' },
+        { label: 'History', value: 'history' },
+        { label: 'Geography', value: 'geography' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default MultiSelectExample;
+`.trim(),
+            },
+        },
     },
-};
-export const WithGroups = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1', group: 'Group 1' },
-            { label: 'Option 2', value: 'option2', group: 'Group 1' },
-            { label: 'Option 4', value: 'option4', group: 'Group 2' },
-            { label: 'Option 5', value: 'option5', group: 'Group 2' },
-            { label: 'Option 3', value: 'option3' },
-            { label: 'Option 6', value: 'option6' },
-            { label: 'Option 7', value: 'option7' },
-        ],
-        onSelectionChange: (value) => { console.log(value); },
+}, '`multiple={true}` allows selecting more than one item. The dropdown stays open after each selection so users can make multiple choices without re-opening. Items toggle on and off.');
+export const MultiSelectWithCount = withDescription({
+    render: MultiSelectWithCountTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function MultiSelectWithCountExample() {
+  return (
+    // No placeholder prop — the trigger shows "Select (3)" when items are selected.
+    // Setting a placeholder would suppress this count display.
+    <SelectDropdown
+      multiple
+      initialSelectedValues={['maths', 'english', 'science']}
+      options={[
+        { label: 'Mathematics', value: 'maths' },
+        { label: 'English', value: 'english' },
+        { label: 'Science', value: 'science' },
+        { label: 'History', value: 'history' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default MultiSelectWithCountExample;
+`.trim(),
+            },
+        },
     },
-};
-export const MultilineItems = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1', header: 'header1' },
-            { label: 'Option 2', value: 'option2', header: 'header2' },
-            { label: 'Option 3', value: 'option3', header: 'header3' },
-            { label: 'Option 4', value: 'option4', header: 'header4' },
-        ],
-        onSelectionChange: (value) => { console.log(value); },
+}, [
+    'When `multiple` is true and **no `placeholder` prop is set**, the trigger shows `"Select (3)"` when three items are selected.',
+    'Setting a `placeholder` suppresses this count — the trigger shows your placeholder text instead.',
+    'Choose deliberately based on whether you want users to see how many items are selected.',
+].join(' '));
+export const Disabled = withDescription({
+    render: DisabledTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select a year group"
+      disabled
+      options={[
+        { label: 'Year 7', value: 'year7' },
+        { label: 'Year 8', value: 'year8' },
+        { label: 'Year 9', value: 'year9' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default DisabledExample;
+`.trim(),
+            },
+        },
     },
-};
-export const MultilineItemsGrouped = {
-    args: {
-        title: 'titleValue',
-        options: [
-            { label: 'Option 1', value: 'option1', header: 'header1' },
-            { label: 'Option 2', value: 'option2', header: 'header2' },
-            { label: 'Option 3', value: 'option3', header: 'header3' },
-            { label: 'Option 4', value: 'option4', header: 'header4' },
-            { label: 'Option 5', value: 'option5', header: 'header5', group: 'Group 1' },
-            { label: 'Option 6', value: 'option6', header: 'header6', group: 'Group 1' },
-            { label: 'Option 7', value: 'option7', header: 'header7', group: 'Group 2' },
-            { label: 'Option 8', value: 'option8', header: 'header8', group: 'Group 2' },
-            { label: 'Option 9', value: 'option9', header: 'header9' },
-        ],
-        onSelectionChange: (value) => { console.log(value); },
+}, 'The `disabled` prop prevents the trigger from opening. Use when the field is not applicable in the current context — for example, a dependent field that requires another field to be filled first.');
+export const WithError = withDescription({
+    render: WithErrorTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function WithErrorExample() {
+  return (
+    <div>
+      <SelectDropdown
+        placeholder="Select a year group"
+        hasError
+        aria-invalid
+        aria-describedBy="year-group-error"
+        options={[
+          { label: 'Year 7', value: 'year7' },
+          { label: 'Year 8', value: 'year8' },
+          { label: 'Year 9', value: 'year9' },
+        ]}
+        onSelectionChange={(values) => console.log(values)}
+      />
+      <span id="year-group-error">Please select a year group</span>
+    </div>
+  );
+}
+export default WithErrorExample;
+`.trim(),
+            },
+        },
     },
-};
-export const MultilineItemsGroupedMultiSelect = {
-    args: {
-        title: 'titleValue',
-        multiple: true,
+}, [
+    '`hasError` applies error styling to the trigger. `aria-invalid` tells screen readers the field is invalid.',
+    '`aria-describedBy` links to the error message element by ID.',
+    '**All three should be used together for an accessible error state.**',
+    'When using `FormField`, these are wired automatically via `errorText` — prefer the `InsideFormFieldWithError` pattern.',
+].join(' '));
+export const WithIcons = withDescription({
+    render: WithIconsTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function WithIconsExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select a subject"
+      options={[
+        { label: 'Mathematics', value: 'maths', icon: 'chart-column-increasing' },
+        { label: 'English', value: 'english', icon: 'book-open' },
+        { label: 'Science', value: 'science', icon: 'circle-check' },
+        { label: 'History', value: 'history', icon: 'clock-3' },
+        { label: 'Geography', value: 'geography', icon: 'flag' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default WithIconsExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Options can include an `icon` prop to display an icon to the left of the label. Use icon names from the Arbor Icon component.');
+export const WithItemHeaders = withDescription({
+    render: WithItemHeadersTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function WithItemHeadersExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select absence reason"
+      options={[
+        { label: 'Authorised absence', value: 'authorised', header: 'Planned' },
+        { label: 'Holiday', value: 'holiday', header: 'Planned' },
+        { label: 'Medical appointment', value: 'medical', header: 'Health' },
+        { label: 'Illness', value: 'illness', header: 'Health' },
+        { label: 'Unauthorised absence', value: 'unauthorised', header: 'Unplanned' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default WithItemHeadersExample;
+`.trim(),
+            },
+        },
+    },
+}, 'The `header` prop on an option renders a small label above the option text, creating a two-line item layout. Use this to add context to complex options — for example, showing the category of an absence type alongside its name.');
+export const WithGroups = withDescription({
+    render: WithGroupsTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function WithGroupsExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select a year group"
+      options={[
+        { label: 'Year 7', value: 'year7', group: 'Lower school' },
+        { label: 'Year 8', value: 'year8', group: 'Lower school' },
+        { label: 'Year 9', value: 'year9', group: 'Lower school' },
+        { label: 'Year 10', value: 'year10', group: 'Upper school' },
+        { label: 'Year 11', value: 'year11', group: 'Upper school' },
+        { label: 'Year 12', value: 'year12', group: 'Sixth form' },
+        { label: 'Year 13', value: 'year13', group: 'Sixth form' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default WithGroupsExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Adding a `group` string to options automatically clusters them under section headings. Group headers are only rendered when two or more distinct group values exist. Items without a `group` are rendered ungrouped.');
+export const WithGroupsMultiSelect = withDescription({
+    render: WithGroupsMultiSelectTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function WithGroupsMultiSelectExample() {
+  return (
+    <SelectDropdown
+      placeholder="Select year groups"
+      multiple
+      options={[
+        { label: 'Year 7', value: 'year7', group: 'Lower school' },
+        { label: 'Year 8', value: 'year8', group: 'Lower school' },
+        { label: 'Year 9', value: 'year9', group: 'Lower school' },
+        { label: 'Year 10', value: 'year10', group: 'Upper school' },
+        { label: 'Year 11', value: 'year11', group: 'Upper school' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default WithGroupsMultiSelectExample;
+`.trim(),
+            },
+        },
+    },
+}, 'Grouped options combined with multi-select. The dropdown stays open while users make multiple selections across groups.');
+export const AlwaysShowPlaceholder = withDescription({
+    render: AlwaysShowPlaceholderTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function AlwaysShowPlaceholderExample() {
+  return (
+    <SelectDropdown
+      placeholder="Add filter"
+      alwaysShowPlaceholder
+      multiple
+      options={[
+        { label: 'Mathematics', value: 'maths' },
+        { label: 'English', value: 'english' },
+        { label: 'Science', value: 'science' },
+      ]}
+      onSelectionChange={(values) => console.log(values)}
+    />
+  );
+}
+export default AlwaysShowPlaceholderExample;
+`.trim(),
+            },
+        },
+    },
+}, '`alwaysShowPlaceholder` keeps the trigger label fixed regardless of selection state. Use for action-style dropdowns (e.g. "Add filter") where the trigger label should not change to reflect the selected value.');
+export const ControlledSingleSelect = withDescription({
+    render: ControlledSingleSelectTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function ControlledSingleSelectExample() {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <SelectDropdown
+      placeholder="Select a subject"
+      selectedValues={selected}
+      onSelectionChange={setSelected}
+      options={[
+        { label: 'Mathematics', value: 'maths' },
+        { label: 'English', value: 'english' },
+        { label: 'Science', value: 'science' },
+        { label: 'History', value: 'history' },
+      ]}
+    />
+  );
+}
+export default ControlledSingleSelectExample;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'Fully controlled single-select. Providing `selectedValues` activates controlled mode — the component stops managing its own state.',
+    'You **must** update `selectedValues` in response to `onSelectionChange`, otherwise the dropdown will appear frozen.',
+    'Use this pattern when the selected value needs to be derived from, or synchronised with, external state.',
+].join(' '));
+export const ControlledOpen = withDescription({
+    render: ControlledOpenTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { SelectDropdown } from '@arbor-education/design-system.components';
+
+function ControlledOpenExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <button type="button" onClick={() => setIsOpen(true)}>Open dropdown externally</button>
+      <SelectDropdown
+        placeholder="Select a subject"
+        open={isOpen}
+        onOpenChange={setIsOpen}
+        options={[
+          { label: 'Mathematics', value: 'maths' },
+          { label: 'English', value: 'english' },
+          { label: 'Science', value: 'science' },
+        ]}
+        onSelectionChange={(values) => {
+          console.log(values);
+          setIsOpen(false);
+        }}
+      />
+    </div>
+  );
+}
+export default ControlledOpenExample;
+`.trim(),
+            },
+        },
+    },
+}, '`open` and `onOpenChange` let you control the dropdown visibility externally. Use when you need to open the dropdown programmatically — from a toolbar button, a keyboard shortcut, or after completing a validation step.');
+export const InsideFormField = withDescription({
+    render: InsideFormFieldTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function InsideFormFieldExample() {
+  return (
+    <FormField
+      label="Year group"
+      id="year-group-field"
+      inputType="selectDropdown"
+      inputProps={{
+        placeholder: 'Select a year group',
         options: [
-            { label: 'Option 5', value: 'option5', header: 'header5', group: 'Group 1' },
-            { label: 'Option 6', value: 'option6', header: 'header6', group: 'Group 1' },
-            { label: 'Option 7', value: 'option7', header: 'header7', group: 'Group 2' },
-            { label: 'Option 8', value: 'option8', header: 'header8', group: 'Group 2' },
-            { label: 'Option 1', value: 'option1', header: 'header1' },
-            { label: 'Option 2', value: 'option2', header: 'header2' },
-            { label: 'Option 3', value: 'option3', header: 'header3' },
-            { label: 'Option 4', value: 'option4', header: 'header4' },
-            { label: 'Option 9', value: 'option9', header: 'header9' },
+          { label: 'Year 7', value: 'year7' },
+          { label: 'Year 8', value: 'year8' },
+          { label: 'Year 9', value: 'year9' },
+          { label: 'Year 10', value: 'year10' },
+          { label: 'Year 11', value: 'year11' },
         ],
-        onSelectionChange: (value) => { console.log(value); },
+        onSelectionChange: (values) => console.log(values),
+      }}
+    />
+  );
+}
+export default InsideFormFieldExample;
+`.trim(),
+            },
+        },
     },
-};
-export const ControlledOpen = {
-    args: {
-        title: 'titleValue',
+}, [
+    'The recommended way to use SelectDropdown in forms.',
+    '`FormField` with `inputType="selectDropdown"` provides an accessible `<label>` linked to the trigger,',
+    'and automatically wires `aria-invalid` and `aria-describedby` when `errorText` is set.',
+    'Pass SelectDropdown props via `inputProps`.',
+].join(' '));
+export const InsideFormFieldWithError = withDescription({
+    render: InsideFormFieldWithErrorTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function InsideFormFieldWithErrorExample() {
+  return (
+    <FormField
+      label="Year group"
+      id="year-group-error-field"
+      inputType="selectDropdown"
+      errorText="Please select a year group"
+      inputProps={{
+        placeholder: 'Select a year group',
         options: [
-            { label: 'Option 1', value: 'option1' },
-            { label: 'Option 2', value: 'option2' },
-            { label: 'Option 3', value: 'option3' },
+          { label: 'Year 7', value: 'year7' },
+          { label: 'Year 8', value: 'year8' },
+          { label: 'Year 9', value: 'year9' },
         ],
-        open: true,
-        onOpenChange: (open) => { console.log('open changed:', open); },
-        onSelectionChange: (value) => { console.log(value); },
+        onSelectionChange: (values) => console.log(values),
+      }}
+    />
+  );
+}
+export default InsideFormFieldWithErrorExample;
+`.trim(),
+            },
+        },
     },
-};
-export default meta;
+}, [
+    'Error state via `FormField`. Setting `errorText` on `FormField` automatically passes `hasError`,',
+    '`aria-invalid`, and `aria-describedby` to the SelectDropdown, and renders the error message below the field.',
+    'This is the correct and recommended pattern for accessible form validation.',
+].join(' '));
 //# sourceMappingURL=SelectDropdown.stories.js.map