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

package/dist/components/combobox/Combobox.stories.js

@@ -1,262 +1,763 @@
 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 { useRef, useState } from 'react';
 import { Icon } from '../icon/Icon';
 import { comboboxAsyncSearchOptions, comboboxGroupedPeopleOptions, comboboxPeopleOptions, } from '../../mocks/comboboxStoryOptions';
 import { Combobox } from './Combobox';
+// ─── Docs-page content ────────────────────────────────────────────────────────
+const DESCRIPTION_INTRO = `
+The \`Combobox\` component is a searchable, accessible select field that supports
+single-select, multi-select, grouped options, async search, and item creation —
+built on Radix UI Popover for reliable portal-based positioning.
+`.trim();
+const USAGE_GUIDANCE = `
+### When to use
+
+- Selecting one or more items from a searchable list (teachers, pupils, subjects, year groups).
+- Filtering a dataset where the user needs to type to narrow down many options.
+- Allowing users to create new values on the fly (e.g. adding a new tag or subject name).
+- Async-loaded lists where options are fetched from an API as the user types.
+
+---
+
+### When NOT to use
+
+| Situation | Use instead |
+|-----------|-------------|
+| A short list (≤ 6 items) with no need to search | \`SelectDropdown\` |
+| Free-text search that triggers a navigation or query action | \`SearchBar\` |
+| A simple true/false toggle | \`Checkbox\` or \`Toggle\` |
+| Picking a date or time | \`DatePicker\` / \`TimePicker\` |
+`.trim();
+const DEVELOPER_NOTES = `
+> **Built on Radix UI Popover.** The dropdown renders into a portal — do NOT place
+> the Combobox inside a container with \`overflow: hidden\` or \`position: relative\`
+> that clips its stacking context. This will cause the dropdown to be cut off.
+
+---
+
+### \`value\` is always \`string[]\`
+
+> **Critical:** Even in single-select mode, \`value\` and \`defaultValue\` are
+> **always arrays**. This is the most common integration bug.
+
+\`\`\`tsx
+// ✅ Correct — value is string[]
+<Combobox value={['alice-johnson']} onValueChange={(vals) => setVal(vals)} />
+
+// ❌ Wrong — value must not be a plain string
+<Combobox value="alice-johnson" />
+\`\`\`
+
+---
+
+### Controlled vs uncontrolled
+
+Use \`value\` + \`onValueChange\` for controlled mode. Use \`defaultValue\` for
+uncontrolled initial selection. Do not mix both.
+
+\`\`\`tsx
+// Controlled
+const [selected, setSelected] = useState<string[]>([]);
+<Combobox value={selected} onValueChange={setSelected} options={options} />
+
+// Uncontrolled with initial value
+<Combobox defaultValue={['alice-johnson']} options={options} />
+\`\`\`
+
+---
+
+### Async search
+
+When you pass \`onSearch\`, **all client-side filtering is disabled** — you are
+responsible for updating the \`options\` array yourself (e.g. from an API response).
+The component does NOT debounce; add your own debounce inside \`onSearch\`.
+
+\`\`\`tsx
+<Combobox
+  options={results}
+  onSearch={async (query) => {
+    const data = await fetchStaff(query);
+    setResults(data);
+  }}
+/>
+\`\`\`
+
+---
+
+### Keyboard navigation
+
+| Key | Action |
+|-----|--------|
+| \`↓\` / \`↑\` | Move focus through options |
+| \`Enter\` | Select the focused option |
+| \`Escape\` | Close the dropdown |
+| \`Backspace\` | Remove the last selected tag (multi-select) |
+| \`Tab\` | Close the dropdown and advance focus |
+
+---
+
+### Grouped options
+
+Options with the same \`group\` string are rendered under a shared group heading.
+The \`group\` string is **case-sensitive** and must match exactly across all options
+in the same group.
+
+\`\`\`tsx
+const options = [
+  { value: 'alice', label: 'Alice Johnson', group: 'Teachers' },
+  { value: 'bob',   label: 'Bob Smith',     group: 'Teachers' },   // same group ✅
+  { value: 'carol', label: 'Carol White',   group: 'teachers' },   // different group ❌
+];
+\`\`\`
+
+---
+
+### Accessibility
+
+- The trigger renders a combobox role with \`aria-expanded\`, \`aria-haspopup\`, and
+  \`aria-controls\` wired to the listbox.
+- Options use \`aria-selected\` and \`aria-disabled\` where appropriate.
+- Pass \`aria-label\` when there is no visible \`<label>\` element nearby.
+- Pass \`aria-describedby\` to link to a \`<FormField>\` hint or error message.
+- Pass \`aria-invalid\` alongside \`hasError\` to signal validation failure to
+  assistive technology.
+
+---
+
+### Sub-components (escape hatches)
+
+The compound sub-components (\`Combobox.Trigger\`, \`Combobox.ButtonTrigger\`,
+\`Combobox.Listbox\`) exist for advanced layout needs where the trigger and listbox
+must be separated in the DOM. For 99% of use cases, use \`<Combobox />\` directly.
+`.trim();
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[SelectDropdown](?path=/docs/components-formfield-inputs-selectdropdown--docs) · [SearchBar](?path=/docs/components-searchbar--docs) · [FormField](?path=/docs/components-formfield--docs) · [CheckboxInput](?path=/docs/components-formfield-inputs-checkbox--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 ComboboxDocsPage() {
+    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/Combobox',
     component: Combobox,
     tags: ['autodocs'],
     parameters: {
+        layout: 'padded',
         docs: {
-            description: {
-                component: 'Default usage is `<Combobox … />` with props such as `triggerVariant` and `multiple`. `Combobox.Trigger`, `Combobox.ButtonTrigger`, and `Combobox.Listbox` are composition escape hatches.',
-            },
+            page: ComboboxDocsPage,
         },
     },
+    decorators: [
+        (Story) => (_jsx("div", { "data-surface": "base", "data-colour-mode": "light", style: { padding: 'var(--size-space-400)', maxWidth: 480, minHeight: 300 }, children: _jsx(Story, {}) })),
+    ],
     argTypes: {
-        dropdownOnFocus: {
+        options: {
+            control: 'object',
+            description: 'Array of `ComboboxOption` objects `{ value: string; label: string; tagLabel?: string; iconName?: IconName; disabled?: boolean; group?: string }`.',
+        },
+        multiple: {
             control: 'boolean',
-            description: 'When true, focusing the input opens the dropdown if there are items to show.',
+            description: 'Allow multiple selections. Each selected value is shown as a tag chip.',
         },
-        showDropdownTrigger: {
+        placeholder: {
+            control: 'text',
+            description: 'Placeholder text shown in the trigger when no value is selected.',
+        },
+        disabled: {
+            control: 'boolean',
+            description: 'Disables the entire combobox — trigger and dropdown become non-interactive.',
+        },
+        loading: {
+            control: 'boolean',
+            description: 'Shows a loading indicator inside the dropdown while options are being fetched.',
+        },
+        hasError: {
+            control: 'boolean',
+            description: 'Applies error styling to the trigger. Pair with `aria-invalid` for full accessibility.',
+        },
+        searchType: {
+            control: 'inline-radio',
+            options: ['prefix', 'substring'],
+            description: '`prefix` (default) matches from the start of the label. `substring` matches anywhere. You can also pass a custom function `(query, options) => ComboboxOption[]`.',
+        },
+        highlightStringMatches: {
             control: 'boolean',
-            description: 'When true, shows the chevron trigger button.',
+            description: 'Highlight the matching portion of each option label while the user is typing.',
+        },
+        selectedValueDisplay: {
+            control: 'inline-radio',
+            options: ['tags', 'text'],
+            description: '`tags` (default) renders each selected value as a chip. `text` shows a comma-separated string — useful in space-constrained button triggers.',
+        },
+        showClearAll: {
+            control: 'boolean',
+            description: 'Show a "Clear all" button inside the trigger when one or more values are selected.',
+        },
+        clearAllLabel: {
+            control: 'text',
+            description: 'Label for the clear-all button. Defaults to `"Clear all"`.',
         },
         triggerVariant: {
             control: 'inline-radio',
             options: ['input', 'button'],
-            description: 'Choose trigger style: input-in-trigger or button-style summary trigger.',
+            description: '`input` (default) renders an inline text field. `button` renders a clickable button; the search field moves into the dropdown.',
+        },
+        allowCreate: {
+            control: 'boolean',
+            description: 'Show a "Create X" row when the typed query does not match any existing option.',
+        },
+        showDropdownTrigger: {
+            control: 'boolean',
+            description: 'Show or hide the chevron button at the end of the trigger. Defaults to `true`.',
+        },
+        dropdownOnFocus: {
+            control: 'boolean',
+            description: 'Open the dropdown automatically when the trigger receives focus. Defaults to `true`.',
+        },
+        showSelectionCountBadge: {
+            control: 'boolean',
+            description: 'Show a badge with the number of selected items (useful with `triggerVariant="button"`).',
         },
+        // Callbacks — not controllable via the controls panel
+        onValueChange: { control: false },
+        onSearch: { control: false },
+        onCreateNew: { control: false },
+        onDeleteCreated: { control: false },
+        renderOption: { control: false },
+        getTagLabel: { control: false },
+        triggerEndContent: { control: false },
     },
-    decorators: [
-        Story => (_jsx("div", { "data-surface": "base", "data-colour-mode": "light", className: "bg-surface text-on-surface-default", style: { padding: 32, maxWidth: 420 }, children: _jsx(Story, {}) })),
-    ],
 };
 export default meta;
-const withDescription = (story, description) => ({
-    ...story,
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function withDescription(description, story) {
+    return {
+        ...story,
+        parameters: {
+            ...story.parameters,
+            docs: {
+                ...story.parameters?.docs,
+                description: { story: description },
+            },
+        },
+    };
+}
+// ─── Stories ──────────────────────────────────────────────────────────────────
+// 1. Default — wired to Controls
+export const Default = {
+    args: {
+        options: comboboxPeopleOptions,
+        placeholder: 'Select a teacher...',
+        multiple: false,
+        disabled: false,
+        loading: false,
+        hasError: false,
+        searchType: 'prefix',
+        highlightStringMatches: false,
+        selectedValueDisplay: 'tags',
+        showClearAll: false,
+    },
+    render: args => _jsx(Combobox, { ...args }),
+};
+// 2. ControlledSingleSelect
+function ControlledSingleSelectTemplate() {
+    const [value, setValue] = useState([]);
+    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 'var(--size-space-300)' }, children: [_jsx(Combobox, { id: "controlled-combobox", options: comboboxPeopleOptions, value: value, onValueChange: setValue, placeholder: "Select a teacher..." }), _jsxs("p", { className: "ds-text", style: { margin: 0 }, children: ["Selected:", ' ', value.length > 0 ? value.join(', ') : '(none)'] })] }));
+}
+export const ControlledSingleSelect = withDescription('Controlled mode: `value` and `onValueChange` are managed by the parent component. **`value` is always `string[]`** — even for single-select. This is the most common integration mistake.', {
+    render: () => _jsx(ControlledSingleSelectTemplate, {}),
     parameters: {
-        ...story.parameters,
         docs: {
-            ...story.parameters?.docs,
-            description: {
-                story: description,
+            source: {
+                code: `
+function ControlledExample() {
+  // value is ALWAYS string[] — even for single-select
+  const [value, setValue] = useState<string[]>([]);
+
+  return (
+    <FormField label="Class teacher" htmlFor="teacher-select">
+      <Combobox
+        id="teacher-select"
+        options={teacherOptions}
+        value={value}
+        onValueChange={setValue}
+        placeholder="Select a teacher..."
+      />
+    </FormField>
+  );
+}
+          `.trim(),
             },
         },
     },
 });
-/** Enough rows to exceed `.ds-combobox__listbox` max-height so keyboard nav scrolls. */
-const manyScrollableOptions = Array.from({ length: 45 }, (_, i) => ({
-    value: `scroll-demo-${i + 1}`,
-    label: `Option ${i + 1}`,
-    iconName: 'user',
-}));
-const timeOptions = ['13:00', '13:30', '14:00', '14:30', '15:00'].map(time => ({
-    value: time,
-    label: time,
-}));
-export const ScrollableLongList = withDescription({
-    args: {
-        options: manyScrollableOptions,
-        placeholder: 'Open the list and move with arrow keys…',
-    },
-}, 'Exercises a scrollable listbox with enough items to validate keyboard navigation and active-row scrolling.');
-export const ButtonTriggerSingleSelect = withDescription({
+// 3. SingleSelect
+export const SingleSelect = withDescription('Single-select mode (default). Type to filter the list by prefix. Press Enter or click to select.', {
     args: {
         options: comboboxPeopleOptions,
-        placeholder: 'Students',
-        triggerVariant: 'button',
-    },
-}, 'Shows the button-style trigger in single-select mode before the search input moves into the popover.');
-export const ButtonTriggerPlainTextValue = withDescription({
-    args: {
-        options: timeOptions,
-        placeholder: 'Select time',
-        triggerVariant: 'button',
-        selectedValueDisplay: 'text',
-        showDropdownTrigger: false,
-        triggerEndContent: _jsx(Icon, { name: "clock-3", size: 16 }),
-        defaultValue: ['14:30'],
+        placeholder: 'Select a teacher...',
     },
-}, 'Uses plain-text selected-value rendering instead of tags, which suits a single selected time or similarly compact values.');
-export const ButtonTriggerMultiSelect = withDescription({
+});
+// 4. MultiSelect
+export const MultiSelect = withDescription('Set `multiple` to allow multiple selections — each selected value is shown as a removable tag chip. Press Backspace to remove the last tag.', {
     args: {
-        options: manyScrollableOptions,
-        defaultValue: ['scroll-demo-1', 'scroll-demo-2', 'scroll-demo-3'],
-        placeholder: 'Students',
+        options: comboboxPeopleOptions,
         multiple: true,
-        triggerVariant: 'button',
+        placeholder: 'Select teachers...',
     },
-}, 'Demonstrates the button trigger variant with multiple selected chips and the selection count badge.');
-export const SingleSelect = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} multiple placeholder="Select teachers..." />',
+            },
+        },
+    },
+});
+// 5. WithDefaultValue
+export const WithDefaultValue = withDescription('`defaultValue` sets the initial selection in uncontrolled mode. Note that `defaultValue` must be a `string[]` even for single-select.', {
     args: {
         options: comboboxPeopleOptions,
-        placeholder: 'Search people...',
+        defaultValue: ['alice-johnson'],
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} defaultValue={[\'alice-johnson\']} />',
+            },
+        },
     },
-}, 'Basic single-select Combobox with built-in client-side prefix matching.');
-export const SubstringSearch = withDescription({
+});
+// 6. SubstringSearch
+export const SubstringSearch = withDescription('Pass `searchType="substring"` to match anywhere in the label — not just the start. Type "son" to see it match "Alice Johnson" and "Alice Williamson".', {
     args: {
         options: comboboxPeopleOptions,
-        placeholder: 'Search people...',
         searchType: 'substring',
+        placeholder: 'Type part of a name...',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} searchType="substring" placeholder="Type part of a name..." />',
+            },
+        },
     },
-}, 'Switches the built-in matching mode from prefix search to substring search.');
-export const HighlightedMatches = withDescription({
+});
+// 7. HighlightedMatches
+export const HighlightedMatches = withDescription('Add `highlightStringMatches` to highlight the matching portion of each option label as the user types. Works best with `searchType="substring"`.', {
     args: {
         options: comboboxPeopleOptions,
-        placeholder: 'Search people...',
         searchType: 'substring',
         highlightStringMatches: true,
+        placeholder: 'Type to highlight matches...',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} searchType="substring" highlightStringMatches placeholder="Type to highlight matches..." />',
+            },
+        },
     },
-}, 'Highlights the matched portions of each option while using substring filtering.');
-export const MultiSelect = withDescription({
+});
+// 8. WithGroups
+export const WithGroups = withDescription('Options with the same `group` string are visually grouped under a shared heading. The `group` value must match exactly (case-sensitive) across all options in the same group.', {
     args: {
-        options: comboboxPeopleOptions,
+        options: comboboxGroupedPeopleOptions,
         multiple: true,
-        placeholder: 'Search people...',
-        showClearAll: true,
+        placeholder: 'Select staff...',
     },
-}, 'Basic multi-select Combobox with removable chips and a clear-all action.');
-export const WithDefaultValue = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                code: `
+const options = [
+  { value: 'alice', label: 'Alice Johnson', group: 'Teachers' },
+  { value: 'bob',   label: 'Bob Smith',     group: 'Teachers' },
+  { value: 'carol', label: 'Carol White',   group: 'Support Staff' },
+  { value: 'rachel', label: 'Rachel Green', group: 'Admin' },
+];
+
+<Combobox options={options} multiple placeholder="Select staff..." />
+          `.trim(),
+            },
+        },
+    },
+});
+// 9. Disabled
+export const Disabled = withDescription('The entire combobox is non-interactive when `disabled` is set. The trigger becomes visually muted and cannot be clicked or focused.', {
     args: {
         options: comboboxPeopleOptions,
-        multiple: true,
-        defaultValue: ['alice', 'bob', 'charlie'],
-        placeholder: 'Search people...',
-        showClearAll: true,
+        disabled: true,
+        placeholder: 'Not available',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} disabled placeholder="Not available" />',
+            },
+        },
     },
-}, 'Starts with preselected values so chip rendering and removal can be reviewed immediately.');
-export const WithGroups = withDescription({
+});
+// 10. ErrorState
+export const ErrorState = withDescription('Set `hasError` to apply error styling to the trigger. Always pair with `aria-invalid` so assistive technology can identify the invalid field. Wrap in `FormField` to display the error message.', {
     args: {
-        options: comboboxGroupedPeopleOptions,
+        'options': comboboxPeopleOptions,
+        'hasError': true,
+        'aria-invalid': true,
+        'placeholder': 'Select a teacher...',
+    },
+    render: args => _jsx(Combobox, { ...args }),
+    parameters: {
+        docs: {
+            source: {
+                code: `
+<Combobox
+  options={teacherOptions}
+  hasError
+  aria-invalid
+  placeholder="Select a teacher..."
+/>
+          `.trim(),
+            },
+        },
+    },
+});
+// 11. LoadingState
+export const LoadingState = withDescription('Set `loading` to show a loading indicator inside the dropdown while options are being fetched. Use this during async search operations before the results arrive.', {
+    args: {
+        options: [],
+        loading: true,
+        placeholder: 'Searching...',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: `
+// Typically used while an async fetch is in-flight:
+<Combobox
+  options={results}
+  loading={isFetching}
+  onSearch={handleSearch}
+  placeholder="Search staff..."
+/>
+          `.trim(),
+            },
+        },
+    },
+});
+// 12. ButtonTriggerSingleSelect
+export const ButtonTriggerSingleSelect = withDescription('`triggerVariant="button"` renders a clickable button as the trigger instead of an inline input. The search field moves inside the dropdown. Ideal for toolbar filters and compact layouts.', {
+    args: {
+        options: comboboxPeopleOptions,
+        triggerVariant: 'button',
+        placeholder: 'Filter by teacher',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} triggerVariant="button" placeholder="Filter by teacher" />',
+            },
+        },
+    },
+});
+// 13. ButtonTriggerMultiSelect
+export const ButtonTriggerMultiSelect = withDescription('Button trigger with `multiple` enabled. Use `showSelectionCountBadge` to show a badge with the number of selected items — useful when the trigger label should not grow in size.', {
+    args: {
+        options: comboboxPeopleOptions,
+        triggerVariant: 'button',
         multiple: true,
-        placeholder: 'Search people...',
+        placeholder: 'Filter by teachers',
+        showSelectionCountBadge: true,
     },
-}, 'Shows grouped options in the dropdown while keeping the same multi-select interaction model.');
-export const Disabled = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} triggerVariant="button" multiple placeholder="Filter by teachers" showSelectionCountBadge />',
+            },
+        },
+    },
+});
+// 14. ButtonTriggerPlainTextValue
+export const ButtonTriggerPlainTextValue = withDescription('`selectedValueDisplay="text"` shows the selected value(s) as a comma-separated text string instead of tag chips — useful when space is limited inside a button trigger.', {
     args: {
         options: comboboxPeopleOptions,
-        disabled: true,
-        defaultValue: ['alice'],
-        placeholder: 'Search people...',
+        triggerVariant: 'button',
+        selectedValueDisplay: 'text',
+        multiple: true,
+        placeholder: 'Filter by teacher',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} triggerVariant="button" selectedValueDisplay="text" multiple placeholder="Filter by teacher" />',
+            },
+        },
     },
-}, 'Displays the disabled state with an existing selected value.');
-export const HiddenTrigger = withDescription({
+});
+// 15. HiddenTrigger
+export const HiddenTrigger = withDescription('Set `showDropdownTrigger={false}` to hide the chevron button at the end of the input. The dropdown can still be opened by typing or focusing the field.', {
     args: {
         options: comboboxPeopleOptions,
-        placeholder: 'Search people...',
         showDropdownTrigger: false,
+        placeholder: 'No chevron shown...',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} showDropdownTrigger={false} placeholder="No chevron shown..." />',
+            },
+        },
     },
-}, 'Hides the chevron trigger while keeping focus, typing, and keyboard opening behavior.');
-export const ManualOpenOnFocus = withDescription({
+});
+// 16. ManualOpenOnFocus
+export const ManualOpenOnFocus = withDescription('Set `dropdownOnFocus={false}` to prevent the dropdown from opening automatically on focus — the user must start typing or click the chevron to open it.', {
     args: {
         options: comboboxPeopleOptions,
-        placeholder: 'Search people...',
         dropdownOnFocus: false,
+        placeholder: 'Focus me — dropdown stays closed',
     },
-}, 'Disables focus-open so the list appears only after typing or explicit keyboard interaction.');
-export const CustomOptionLayout = withDescription({
-    args: {
-        options: comboboxPeopleOptions,
-        placeholder: 'Search people...',
-        multiple: true,
-        renderOption: (option, selected) => (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", children: _jsx("input", { type: "checkbox", checked: selected, readOnly: true, tabIndex: -1 }) }), _jsx("span", { className: "ds-combobox__option-label", children: option.label })] })),
+    parameters: {
+        docs: {
+            source: {
+                code: '<Combobox options={teacherOptions} dropdownOnFocus={false} placeholder="Focus me — dropdown stays closed" />',
+            },
+        },
     },
-}, 'Uses `renderOption` to swap the row content while the Combobox still owns selection and listbox behavior.');
-const delay = (ms) => new Promise((resolve) => {
-    setTimeout(resolve, ms);
 });
-async function searchPeople(query) {
-    await delay(700);
-    const q = query.trim().toLowerCase();
-    if (!q)
-        return comboboxAsyncSearchOptions;
-    return comboboxAsyncSearchOptions.filter(p => p.label.toLowerCase().includes(q));
-}
-const AsyncSearchTemplate = ({ allowCreate = false, searchType = 'substring', highlightStringMatches = true, }) => {
-    const [options, setOptions] = useState([]);
-    const [loading, setLoading] = useState(false);
-    const requestIdRef = useRef(0);
+// ─── Async search template ─────────────────────────────────────────────────────
+function AsyncSearchTemplate() {
+    const [options, setOptions] = useState(comboboxPeopleOptions);
+    const timerRef = useRef(null);
     const handleSearch = (query) => {
-        const id = ++requestIdRef.current;
-        setLoading(true);
-        void searchPeople(query).then((next) => {
-            if (id !== requestIdRef.current)
-                return;
-            setOptions(next);
-            setLoading(false);
-        });
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => {
+            setOptions(comboboxAsyncSearchOptions.filter(o => o.label.toLowerCase().startsWith(query.toLowerCase())));
+        }, 300);
     };
-    return (_jsx(Combobox, { options: options, multiple: true, placeholder: "Type to search...", loading: loading, allowCreate: allowCreate, searchType: searchType, highlightStringMatches: highlightStringMatches, onSearch: handleSearch }));
-};
-export const AsyncSearch = withDescription({
-    args: {
-        allowCreate: false,
-        searchType: 'substring',
-        highlightStringMatches: true,
+    return _jsx(Combobox, { options: options, onSearch: handleSearch, placeholder: "Search staff..." });
+}
+// 17. AsyncSearch
+export const AsyncSearch = withDescription('Pass `onSearch` to take control of filtering. The component disables all client-side matching — you update the `options` array yourself (e.g. via an API call). This example simulates a 300 ms network delay.', {
+    render: () => _jsx(AsyncSearchTemplate, {}),
+    parameters: {
+        docs: {
+            source: {
+                code: `
+function AsyncSearchExample() {
+  const [options, setOptions] = useState<ComboboxOption[]>([]);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const handleSearch = (query: string) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(async () => {
+      const results = await fetchStaff(query);
+      setOptions(results);
+    }, 300);
+  };
+
+  return (
+    <Combobox
+      options={options}
+      onSearch={handleSearch}
+      placeholder="Search staff..."
+    />
+  );
+}
+          `.trim(),
+            },
+        },
     },
-    render: args => (_jsx(AsyncSearchTemplate, { allowCreate: args.allowCreate, searchType: args.searchType, highlightStringMatches: args.highlightStringMatches })),
-}, 'Simulates async search results with local data so loading, filtering, and optional create flows can be reviewed.');
-const CreateNewTemplate = () => {
+});
+// ─── Create new template ───────────────────────────────────────────────────────
+function CreateNewTemplate() {
     const [options, setOptions] = useState(comboboxPeopleOptions);
-    const handleCreate = (name) => {
-        const newOpt = {
-            value: name.toLowerCase().replace(/\s/g, '-'),
-            label: name,
-            iconName: 'user',
-        };
-        setOptions(prev => [...prev, newOpt]);
-        return newOpt;
+    const handleCreate = (input) => {
+        const newOption = { value: input.toLowerCase().replace(/\s+/g, '-'), label: input };
+        setOptions(prev => [...prev, newOption]);
+        return newOption;
     };
-    const handleDelete = (value) => {
-        setOptions(prev => prev.filter(opt => opt.value !== value));
-    };
-    return (_jsx(Combobox, { options: options, multiple: true, placeholder: "Search or create...", allowCreate: true, onCreateNew: handleCreate, onDeleteCreated: handleDelete }));
-};
-export const CreateNew = withDescription({
+    return (_jsx(Combobox, { options: options, multiple: true, allowCreate: true, onCreateNew: handleCreate, placeholder: "Select or add a teacher..." }));
+}
+// 18. CreateNew
+export const CreateNew = withDescription('Set `allowCreate` to show a "Create X" option when the typed query does not match any existing option. The `onCreateNew` callback receives the typed string and must return a new `ComboboxOption`.', {
     render: () => _jsx(CreateNewTemplate, {}),
-}, 'Demonstrates multi-select creation and deletion of user-added options.');
-const SingleSelectCreateTemplate = () => {
-    const [options, setOptions] = useState(comboboxPeopleOptions);
-    const handleCreate = (name) => {
-        const newOpt = {
-            value: name.toLowerCase().replace(/\s/g, '-'),
-            label: name,
-            iconName: 'user',
-        };
-        setOptions(prev => [...prev, newOpt]);
-        return newOpt;
+    parameters: {
+        docs: {
+            source: {
+                code: `
+function CreateNewExample() {
+  const [options, setOptions] = useState(initialOptions);
+
+  const handleCreate = (input: string) => {
+    const newOption = {
+      value: input.toLowerCase().replace(/\\s+/g, '-'),
+      label: input,
     };
-    const handleDelete = (value) => {
-        setOptions(prev => prev.filter(opt => opt.value !== value));
+    setOptions((prev) => [...prev, newOption]);
+    return newOption;
+  };
+
+  return (
+    <Combobox
+      options={options}
+      multiple
+      allowCreate
+      onCreateNew={handleCreate}
+      placeholder="Select or add a teacher..."
+    />
+  );
+}
+          `.trim(),
+            },
+        },
+    },
+});
+// ─── Single select create template ────────────────────────────────────────────
+function SingleSelectCreateTemplate() {
+    const [options, setOptions] = useState(comboboxPeopleOptions);
+    const handleCreate = (input) => {
+        const newOption = { value: input.toLowerCase().replace(/\s+/g, '-'), label: input };
+        setOptions(prev => [...prev, newOption]);
+        return newOption;
     };
-    return (_jsx(Combobox, { options: options, placeholder: "Search or create...", allowCreate: true, onCreateNew: handleCreate, onDeleteCreated: handleDelete }));
-};
-export const SingleSelectCreate = withDescription({
+    return (_jsx(Combobox, { options: options, allowCreate: true, onCreateNew: handleCreate, placeholder: "Select or add a teacher..." }));
+}
+// 19. SingleSelectCreate
+export const SingleSelectCreate = withDescription('`allowCreate` works in single-select mode too — useful for fields like "Add a subject" where the user can either pick from existing values or type a new one.', {
     render: () => _jsx(SingleSelectCreateTemplate, {}),
-}, 'Shows single-select creation where a newly created option becomes the current value immediately.');
-export const CustomTagLabel = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                code: `
+function SingleSelectCreateExample() {
+  const [options, setOptions] = useState(initialOptions);
+
+  const handleCreate = (input: string) => {
+    const newOption = {
+      value: input.toLowerCase().replace(/\\s+/g, '-'),
+      label: input,
+    };
+    setOptions((prev) => [...prev, newOption]);
+    return newOption;
+  };
+
+  return (
+    <Combobox
+      options={options}
+      allowCreate
+      onCreateNew={handleCreate}
+      placeholder="Select or add a teacher..."
+    />
+  );
+}
+          `.trim(),
+            },
+        },
+    },
+});
+// 20. CustomOptionLayout
+export const CustomOptionLayout = withDescription('Use `renderOption` to fully customise how each option is rendered inside the dropdown — useful for adding avatars, icons, or additional metadata alongside the label.', {
     args: {
-        options: [
-            { value: 'u1', label: 'Alice Johnson (Year 10, Class A)', tagLabel: 'Alice J.', iconName: 'user' },
-            { value: 'u2', label: 'Bob Smith (Year 11, Class B)', tagLabel: 'Bob S.', iconName: 'user' },
-            { value: 'u3', label: 'Charlie Brown (Year 10, Class A)', tagLabel: 'Charlie B.', iconName: 'user' },
-        ],
+        options: comboboxPeopleOptions,
         multiple: true,
-        placeholder: 'Search students...',
-        showClearAll: true,
+        placeholder: 'Select teachers...',
+        renderOption: (option) => (_jsxs("span", { style: { display: 'flex', alignItems: 'center', gap: 'var(--size-space-200)' }, children: [_jsx(Icon, { name: "user", size: 16 }), _jsx("span", { children: option.label })] })),
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: `
+<Combobox
+  options={teacherOptions}
+  multiple
+  placeholder="Select teachers..."
+  renderOption={(option) => (
+    <span style={{ display: 'flex', alignItems: 'center', gap: 'var(--size-space-200)' }}>
+      <Icon name="user" size={16} />
+      <span>{option.label}</span>
+    </span>
+  )}
+/>
+          `.trim(),
+            },
+        },
     },
-}, 'Uses `tagLabel` to shorten selected chip text while preserving fuller option labels in the dropdown.');
-export const WithDisabledOptions = withDescription({
+});
+// 21. CustomTagLabel
+export const CustomTagLabel = withDescription('Use `getTagLabel` to customise the label shown inside a selected tag chip — useful when the full option label is too long to display comfortably in the trigger.', {
+    args: {
+        options: comboboxPeopleOptions,
+        multiple: true,
+        placeholder: 'Select teachers...',
+        getTagLabel: (option) => option.label.split(' ')[0] ?? option.label,
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: `
+<Combobox
+  options={teacherOptions}
+  multiple
+  placeholder="Select teachers..."
+  getTagLabel={(option) => option.label.split(' ')[0]}
+/>
+          `.trim(),
+            },
+        },
+    },
+});
+// 22. WithDisabledOptions
+export const WithDisabledOptions = withDescription('Individual options can be disabled by setting `disabled: true` on the option object. Disabled options are visible but cannot be selected.', {
     args: {
-        options: [
-            { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
-            { value: 'bob', label: 'Bob Smith', iconName: 'user', disabled: true },
-            { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
-        ],
+        options: comboboxPeopleOptions.map((o, i) => ({ ...o, disabled: i % 3 === 1 })),
         multiple: true,
-        placeholder: 'Search people...',
+        placeholder: 'Select teachers...',
     },
-}, 'Includes a disabled option to show how unavailable rows appear and behave inside the listbox.');
+    parameters: {
+        docs: {
+            source: {
+                code: `
+const options = [
+  { value: 'alice', label: 'Alice Johnson' },
+  { value: 'bob',   label: 'Bob Smith',    disabled: true },
+  { value: 'carol', label: 'Carol White' },
+  { value: 'dan',   label: 'Dan Brown',   disabled: true },
+];
+
+<Combobox options={options} multiple placeholder="Select teachers..." />
+          `.trim(),
+            },
+        },
+    },
+});
+// 23. ScrollableLongList
+export const ScrollableLongList = withDescription('The dropdown scrolls automatically when there are many options. Here we render 50 generated options to demonstrate the scrollable list and confirm search still works at scale.', {
+    args: {
+        options: Array.from({ length: 50 }, (_, i) => ({
+            value: `option-${i}`,
+            label: `Option ${i + 1}`,
+        })),
+        multiple: true,
+        placeholder: 'Search 50 options...',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: `
+const options = Array.from({ length: 50 }, (_, i) => ({
+  value: \`option-\${i}\`,
+  label: \`Option \${i + 1}\`,
+}));
+
+<Combobox options={options} multiple placeholder="Search 50 options..." />
+          `.trim(),
+            },
+        },
+    },
+});
 //# sourceMappingURL=Combobox.stories.js.map