@arbor-education/design-system.components 0.14.0 → 0.16.0

package/src/components/formField/inputs/selectDropdown/SelectDropdown.stories.tsx

@@ -1,200 +1,1111 @@
-import type { Meta } from '@storybook/react-vite';
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { FormField } from 'Components/formField/FormField';
 import { SelectDropdown } from './SelectDropdown';
 
-const meta: Meta<typeof 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 (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 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' as const },
+  { label: 'English', value: 'english', icon: 'book-open' as const },
+  { label: 'Science', value: 'science', icon: 'circle-check' as const },
+  { label: 'History', value: 'history', icon: 'clock-3' as const },
+  { label: 'Geography', value: 'geography', icon: 'flag' as const },
+];
+
+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,
-};
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: SelectDropdownDocsPage,
+    },
+  },
+  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' },
+      },
+    },
+  },
+} satisfies Meta<typeof SelectDropdown>;
+
+export default meta;
+type Story = StoryObj<typeof SelectDropdown>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
 
-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: string[]) => { console.log(value); },
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
   },
+});
+
+// ---------------------------------------------------------------------------
+// Template components for stateful and composite stories
+// ---------------------------------------------------------------------------
+
+const WithInitialSelectionTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select a year group"
+      initialSelectedValues={['year9']}
+      options={yearGroupOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const MultiSelectTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select subjects"
+      multiple
+      options={subjectOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const MultiSelectWithCountTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      multiple
+      initialSelectedValues={['maths', 'english', 'science']}
+      options={subjectOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const DisabledTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select a year group"
+      disabled
+      options={yearGroupOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const WithErrorTemplate = () => (
+  <div style={{ maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+    <SelectDropdown
+      placeholder="Select a year group"
+      hasError
+      aria-invalid
+      aria-describedBy="year-group-error"
+      options={yearGroupOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+    <span
+      id="year-group-error"
+      style={{ fontSize: '0.875rem', color: 'var(--color-feedback-danger-600)' }}
+    >
+      Please select a year group
+    </span>
+  </div>
+);
+
+const WithIconsTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select a subject"
+      options={subjectOptionsWithIcons}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const WithItemHeadersTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select absence reason"
+      options={attendanceReasonOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const WithGroupsTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select a year group"
+      options={groupedYearOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const WithGroupsMultiSelectTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Select year groups"
+      multiple
+      options={groupedYearOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const AlwaysShowPlaceholderTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <SelectDropdown
+      placeholder="Add filter"
+      alwaysShowPlaceholder
+      multiple
+      options={subjectOptions}
+      onSelectionChange={values => console.log(values)}
+    />
+  </div>
+);
+
+const ControlledSingleSelectTemplate = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+  return (
+    <div style={{ maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <SelectDropdown
+        placeholder="Select a subject"
+        selectedValues={selected}
+        onSelectionChange={setSelected}
+        options={subjectOptions}
+      />
+      <span style={{ fontSize: '0.875rem', color: 'var(--color-grey-600)' }}>
+        Selected:
+        {' '}
+        {selected.length > 0 ? selected.join(', ') : 'nothing yet'}
+      </span>
+    </div>
+  );
 };
 
-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: string[]) => { console.log(value); },
-  },
+const ControlledOpenTemplate = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <div style={{ maxWidth: '320px', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+      <button type="button" onClick={() => setIsOpen(true)}>
+        Open dropdown externally
+      </button>
+      <SelectDropdown
+        placeholder="Select a subject"
+        open={isOpen}
+        onOpenChange={setIsOpen}
+        options={subjectOptions}
+        onSelectionChange={(values) => {
+          console.log(values);
+          setIsOpen(false);
+        }}
+      />
+    </div>
+  );
 };
 
-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: string[]) => { console.log(value); },
+const InsideFormFieldTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <FormField
+      label="Year group"
+      id="year-group-field"
+      inputType="selectDropdown"
+      inputProps={{
+        placeholder: 'Select a year group',
+        options: yearGroupOptions,
+        onSelectionChange: values => console.log(values),
+      }}
+    />
+  </div>
+);
+
+const InsideFormFieldWithErrorTemplate = () => (
+  <div style={{ maxWidth: '320px' }}>
+    <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),
+      }}
+    />
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      options: yearGroupOptions,
+      placeholder: 'Select a year group',
+      multiple: false,
+      disabled: false,
+    },
+    render: args => (
+      <div style={{ maxWidth: '320px' }}>
+        <SelectDropdown {...args} />
+      </div>
+    ),
   },
-};
+  '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: Story = withDescription(
+  {
+    render: WithInitialSelectionTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
 
-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: string[]) => { console.log(value); },
+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(),
+        },
+      },
+    },
   },
-};
+  '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 Placeholder = {
-  args: {
-    placeholder: 'placeholder',
-    title: 'titleValue',
-    options: [
-      { label: 'Option 1', value: 'option1' },
-      { label: 'Option 2', value: 'option2' },
-      { label: 'Option 3', value: 'option3' },
-    ],
-    onSelectionChange: (value: string[]) => { console.log(value); },
+export const MultiSelect: Story = 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(),
+        },
+      },
+    },
   },
-};
+  '`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 EmptyPlaceHolder = {
-  args: {
-    placeholder: '',
-    options: [
-      { label: 'Option 1', value: 'option1' },
-      { label: 'Option 2', value: 'option2' },
-      { label: 'Option 3', value: 'option3' },
-    ],
-    disabled: false,
-    onSelectionChange: (value: string[]) => { console.log(value); },
+export const MultiSelectWithCount: Story = 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(),
+        },
+      },
+    },
   },
-};
+  [
+    '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 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: string[]) => { console.log(value); },
+export const Disabled: Story = 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(),
+        },
+      },
+    },
   },
-};
+  '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 Disabled = {
-  args: {
-    title: 'titleValue',
-    options: [
-      { label: 'Option 1', value: 'option1' },
-      { label: 'Option 2', value: 'option2' },
-      { label: 'Option 3', value: 'option3' },
-    ],
-    disabled: true,
-    onSelectionChange: (value: string[]) => { console.log(value); },
+export const WithError: Story = 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(),
+        },
+      },
+    },
   },
-};
+  [
+    '`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: Story = withDescription(
+  {
+    render: WithIconsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
 
-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: string[]) => { console.log(value); },
+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: Story = withDescription(
+  {
+    render: WithItemHeadersTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
 
-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: string[]) => { console.log(value); },
+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: Story = withDescription(
+  {
+    render: WithGroupsTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
 
-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: string[]) => { console.log(value); },
+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: Story = withDescription(
+  {
+    render: WithGroupsMultiSelectTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
 
-export const MultilineItemsGroupedMultiSelect = {
-  args: {
-    title: 'titleValue',
-    multiple: true,
-    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' },
-    ],
-    onSelectionChange: (value: string[]) => { console.log(value); },
+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: Story = withDescription(
+  {
+    render: AlwaysShowPlaceholderTemplate,
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { SelectDropdown } from '@arbor-education/design-system.components';
 
-export const ControlledOpen = {
-  args: {
-    title: 'titleValue',
-    options: [
-      { label: 'Option 1', value: 'option1' },
-      { label: 'Option 2', value: 'option2' },
-      { label: 'Option 3', value: 'option3' },
-    ],
-    open: true,
-    onOpenChange: (open: boolean) => { console.log('open changed:', open); },
-    onSelectionChange: (value: string[]) => { console.log(value); },
+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 default meta;
+export const ControlledSingleSelect: Story = 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: Story = 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: Story = 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: '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 InsideFormFieldExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '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: Story = 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: 'Year 7', value: 'year7' },
+          { label: 'Year 8', value: 'year8' },
+          { label: 'Year 9', value: 'year9' },
+        ],
+        onSelectionChange: (values) => console.log(values),
+      }}
+    />
+  );
+}
+export default InsideFormFieldWithErrorExample;
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    '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(' '),
+);