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

package/src/components/combobox/Combobox.stories.tsx

@@ -1,4 +1,13 @@
 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 { useRef, useState } from 'react';
 import { Icon } from 'Components/icon/Icon';
 import {
@@ -7,352 +16,950 @@ import {
   comboboxPeopleOptions,
 } from '../../mocks/comboboxStoryOptions';
 import { Combobox } from './Combobox';
-import type { ComboboxOption, ComboboxProps } from './types';
+import type { ComboboxOption } from './types';
+
+// ─── 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
 
-const meta: Meta<typeof Combobox> = {
+- 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 (
+    <>
+      <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>
+    </>
+  );
+}
+
+// ─── 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: React.ComponentType) => (
+      <div
+        data-surface="base"
+        data-colour-mode="light"
+        style={{ padding: 'var(--size-space-400)', maxWidth: 480, minHeight: 300 }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
   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:
+        '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: 'When true, shows the chevron trigger button.',
+      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 => (
-      <div data-surface="base" data-colour-mode="light" className="bg-surface text-on-surface-default" style={{ padding: 32, maxWidth: 420 }}>
-        <Story />
-      </div>
-    ),
-  ],
-};
+} satisfies Meta<typeof Combobox>;
 
 export default meta;
-
 type Story = StoryObj<typeof Combobox>;
 
-const withDescription = (story: Story, description: string): Story => ({
-  ...story,
-  parameters: {
-    ...story.parameters,
-    docs: {
-      ...story.parameters?.docs,
-      description: {
-        story: description,
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function withDescription(description: string, story: Story): Story {
+  return {
+    ...story,
+    parameters: {
+      ...story.parameters,
+      docs: {
+        ...story.parameters?.docs,
+        description: { story: description },
       },
     },
-  },
-});
-
-/** Enough rows to exceed `.ds-combobox__listbox` max-height so keyboard nav scrolls. */
-const manyScrollableOptions: ComboboxOption[] = Array.from({ length: 45 }, (_, i) => ({
-  value: `scroll-demo-${i + 1}`,
-  label: `Option ${i + 1}`,
-  iconName: 'user',
-}));
+  };
+}
 
-const timeOptions: ComboboxOption[] = ['13:00', '13:30', '14:00', '14:30', '15:00'].map(time => ({
-  value: time,
-  label: time,
-}));
+// ─── Stories ──────────────────────────────────────────────────────────────────
 
-export const ScrollableLongList: Story = 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: Story = withDescription({
+// 1. Default — wired to Controls
+export const Default: Story = {
   args: {
     options: comboboxPeopleOptions,
-    placeholder: 'Students',
-    triggerVariant: 'button',
+    placeholder: 'Select a teacher...',
+    multiple: false,
+    disabled: false,
+    loading: false,
+    hasError: false,
+    searchType: 'prefix',
+    highlightStringMatches: false,
+    selectedValueDisplay: 'tags',
+    showClearAll: false,
   },
-}, 'Shows the button-style trigger in single-select mode before the search input moves into the popover.');
+  render: args => <Combobox {...args} />,
+};
 
-export const ButtonTriggerPlainTextValue: Story = withDescription({
-  args: {
-    options: timeOptions,
-    placeholder: 'Select time',
-    triggerVariant: 'button',
-    selectedValueDisplay: 'text',
-    showDropdownTrigger: false,
-    triggerEndContent: <Icon name="clock-3" size={16} />,
-    defaultValue: ['14:30'],
-  },
-}, 'Uses plain-text selected-value rendering instead of tags, which suits a single selected time or similarly compact values.');
+// 2. ControlledSingleSelect
+function ControlledSingleSelectTemplate() {
+  const [value, setValue] = useState<string[]>([]);
 
-export const ButtonTriggerMultiSelect: Story = withDescription({
-  args: {
-    options: manyScrollableOptions,
-    defaultValue: ['scroll-demo-1', 'scroll-demo-2', 'scroll-demo-3'],
-    placeholder: 'Students',
-    multiple: true,
-    triggerVariant: 'button',
-  },
-}, 'Demonstrates the button trigger variant with multiple selected chips and the selection count badge.');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--size-space-300)' }}>
+      <Combobox
+        id="controlled-combobox"
+        options={comboboxPeopleOptions}
+        value={value}
+        onValueChange={setValue}
+        placeholder="Select a teacher..."
+      />
+      <p className="ds-text" style={{ margin: 0 }}>
+        Selected:
+        {' '}
+        {value.length > 0 ? value.join(', ') : '(none)'}
+      </p>
+    </div>
+  );
+}
 
-export const SingleSelect: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    placeholder: 'Search people...',
-  },
-}, 'Basic single-select Combobox with built-in client-side prefix matching.');
+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: () => <ControlledSingleSelectTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+function ControlledExample() {
+  // value is ALWAYS string[] — even for single-select
+  const [value, setValue] = useState<string[]>([]);
 
-export const SubstringSearch: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    placeholder: 'Search people...',
-    searchType: 'substring',
+  return (
+    <FormField label="Class teacher" htmlFor="teacher-select">
+      <Combobox
+        id="teacher-select"
+        options={teacherOptions}
+        value={value}
+        onValueChange={setValue}
+        placeholder="Select a teacher..."
+      />
+    </FormField>
+  );
+}
+          `.trim(),
+        },
+      },
+    },
   },
-}, 'Switches the built-in matching mode from prefix search to substring search.');
-
-export const HighlightedMatches: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    placeholder: 'Search people...',
-    searchType: 'substring',
-    highlightStringMatches: true,
+);
+
+// 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: 'Select a teacher...',
+    },
   },
-}, 'Highlights the matched portions of each option while using substring filtering.');
-
-export const MultiSelect: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    multiple: true,
-    placeholder: 'Search people...',
-    showClearAll: true,
+);
+
+// 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: comboboxPeopleOptions,
+      multiple: true,
+      placeholder: 'Select teachers...',
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} multiple placeholder="Select teachers..." />',
+        },
+      },
+    },
   },
-}, 'Basic multi-select Combobox with removable chips and a clear-all action.');
-
-export const WithDefaultValue: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    multiple: true,
-    defaultValue: ['alice', 'bob', 'charlie'],
-    placeholder: 'Search people...',
-    showClearAll: true,
+);
+
+// 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,
+      defaultValue: ['alice-johnson'],
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} defaultValue={[\'alice-johnson\']} />',
+        },
+      },
+    },
   },
-}, 'Starts with preselected values so chip rendering and removal can be reviewed immediately.');
-
-export const WithGroups: Story = withDescription({
-  args: {
-    options: comboboxGroupedPeopleOptions,
-    multiple: true,
-    placeholder: 'Search people...',
+);
+
+// 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,
+      searchType: 'substring',
+      placeholder: 'Type part of a name...',
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} searchType="substring" placeholder="Type part of a name..." />',
+        },
+      },
+    },
   },
-}, 'Shows grouped options in the dropdown while keeping the same multi-select interaction model.');
-
-export const Disabled: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    disabled: true,
-    defaultValue: ['alice'],
-    placeholder: 'Search people...',
+);
+
+// 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,
+      searchType: 'substring',
+      highlightStringMatches: true,
+      placeholder: 'Type to highlight matches...',
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} searchType="substring" highlightStringMatches placeholder="Type to highlight matches..." />',
+        },
+      },
+    },
   },
-}, 'Displays the disabled state with an existing selected value.');
-
-export const HiddenTrigger: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    placeholder: 'Search people...',
-    showDropdownTrigger: false,
+);
+
+// 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: comboboxGroupedPeopleOptions,
+      multiple: true,
+      placeholder: 'Select staff...',
+    },
+    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(),
+        },
+      },
+    },
   },
-}, 'Hides the chevron trigger while keeping focus, typing, and keyboard opening behavior.');
-
-export const ManualOpenOnFocus: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    placeholder: 'Search people...',
-    dropdownOnFocus: false,
+);
+
+// 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,
+      disabled: true,
+      placeholder: 'Not available',
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} disabled placeholder="Not available" />',
+        },
+      },
+    },
   },
-}, 'Disables focus-open so the list appears only after typing or explicit keyboard interaction.');
-
-export const CustomOptionLayout: Story = withDescription({
-  args: {
-    options: comboboxPeopleOptions,
-    placeholder: 'Search people...',
-    multiple: true,
-    renderOption: (option, selected) => (
-      <>
-        <span aria-hidden="true">
-          <input type="checkbox" checked={selected} readOnly tabIndex={-1} />
-        </span>
-        <span className="ds-combobox__option-label">{option.label}</span>
-      </>
-    ),
+);
+
+// 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': comboboxPeopleOptions,
+      'hasError': true,
+      'aria-invalid': true,
+      'placeholder': 'Select a teacher...',
+    },
+    render: args => <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: 'Filter by teachers',
+      showSelectionCountBadge: true,
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} triggerVariant="button" multiple placeholder="Filter by teachers" showSelectionCountBadge />',
+        },
+      },
+    },
   },
-}, 'Uses `renderOption` to swap the row content while the Combobox still owns selection and listbox behavior.');
+);
+
+// 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,
+      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" />',
+        },
+      },
+    },
+  },
+);
+
+// 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,
+      showDropdownTrigger: false,
+      placeholder: 'No chevron shown...',
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} showDropdownTrigger={false} placeholder="No chevron shown..." />',
+        },
+      },
+    },
+  },
+);
+
+// 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,
+      dropdownOnFocus: false,
+      placeholder: 'Focus me — dropdown stays closed',
+    },
+    parameters: {
+      docs: {
+        source: {
+          code: '<Combobox options={teacherOptions} dropdownOnFocus={false} placeholder="Focus me — dropdown stays closed" />',
+        },
+      },
+    },
+  },
+);
 
-const delay = (ms: number) => new Promise<void>((resolve) => {
-  setTimeout(resolve, ms);
-});
+// ─── Async search template ─────────────────────────────────────────────────────
 
-async function searchPeople(query: string): Promise<ComboboxOption[]> {
-  await delay(700);
-  const q = query.trim().toLowerCase();
-  if (!q) return comboboxAsyncSearchOptions;
-  return comboboxAsyncSearchOptions.filter(p => p.label.toLowerCase().includes(q));
-}
+function AsyncSearchTemplate() {
+  const [options, setOptions] = useState(comboboxPeopleOptions);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const handleSearch = (query: string) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => {
+      setOptions(
+        comboboxAsyncSearchOptions.filter(o =>
+          o.label.toLowerCase().startsWith(query.toLowerCase()),
+        ),
+      );
+    }, 300);
+  };
 
-type AsyncSearchTemplateProps = Pick<
-  ComboboxProps,
-  'allowCreate' | 'searchType' | 'highlightStringMatches'
->;
+  return <Combobox options={options} onSearch={handleSearch} placeholder="Search staff..." />;
+}
 
-const AsyncSearchTemplate = ({
-  allowCreate = false,
-  searchType = 'substring',
-  highlightStringMatches = true,
-}: AsyncSearchTemplateProps) => {
+// 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: () => <AsyncSearchTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          code: `
+function AsyncSearchExample() {
   const [options, setOptions] = useState<ComboboxOption[]>([]);
-  const [loading, setLoading] = useState(false);
-  const requestIdRef = useRef(0);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const handleSearch = (query: string) => {
-    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(async () => {
+      const results = await fetchStaff(query);
+      setOptions(results);
+    }, 300);
   };
 
   return (
     <Combobox
       options={options}
-      multiple
-      placeholder="Type to search..."
-      loading={loading}
-      allowCreate={allowCreate}
-      searchType={searchType}
-      highlightStringMatches={highlightStringMatches}
       onSearch={handleSearch}
+      placeholder="Search staff..."
     />
   );
-};
-
-export const AsyncSearch: Story = withDescription({
-  args: {
-    allowCreate: false,
-    searchType: 'substring',
-    highlightStringMatches: true,
+}
+          `.trim(),
+        },
+      },
+    },
   },
-  render: args => (
-    <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 = () => {
-  const [options, setOptions] = useState<ComboboxOption[]>(comboboxPeopleOptions);
+// ─── Create new template ───────────────────────────────────────────────────────
 
-  const handleCreate = (name: string) => {
-    const newOpt: ComboboxOption = {
-      value: name.toLowerCase().replace(/\s/g, '-'),
-      label: name,
-      iconName: 'user',
-    };
-    setOptions(prev => [...prev, newOpt]);
-    return newOpt;
-  };
+function CreateNewTemplate() {
+  const [options, setOptions] = useState(comboboxPeopleOptions);
 
-  const handleDelete = (value: string) => {
-    setOptions(prev => prev.filter(opt => opt.value !== value));
+  const handleCreate = (input: string) => {
+    const newOption = { value: input.toLowerCase().replace(/\s+/g, '-'), label: input };
+    setOptions(prev => [...prev, newOption]);
+    return newOption;
   };
 
   return (
     <Combobox
       options={options}
       multiple
-      placeholder="Search or create..."
       allowCreate
       onCreateNew={handleCreate}
-      onDeleteCreated={handleDelete}
+      placeholder="Select or add a teacher..."
     />
   );
-};
-
-export const CreateNew: Story = withDescription({
-  render: () => <CreateNewTemplate />,
-}, 'Demonstrates multi-select creation and deletion of user-added options.');
-
-const SingleSelectCreateTemplate = () => {
-  const [options, setOptions] = useState<ComboboxOption[]>(comboboxPeopleOptions);
+}
 
-  const handleCreate = (name: string) => {
-    const newOpt: ComboboxOption = {
-      value: name.toLowerCase().replace(/\s/g, '-'),
-      label: name,
-      iconName: 'user',
+// 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: () => <CreateNewTemplate />,
+    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,
     };
-    setOptions(prev => [...prev, newOpt]);
-    return newOpt;
+    setOptions((prev) => [...prev, newOption]);
+    return newOption;
   };
 
-  const handleDelete = (value: string) => {
-    setOptions(prev => prev.filter(opt => opt.value !== value));
+  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: string) => {
+    const newOption = { value: input.toLowerCase().replace(/\s+/g, '-'), label: input };
+    setOptions(prev => [...prev, newOption]);
+    return newOption;
   };
 
   return (
     <Combobox
       options={options}
-      placeholder="Search or create..."
       allowCreate
       onCreateNew={handleCreate}
-      onDeleteCreated={handleDelete}
+      placeholder="Select or add a teacher..."
     />
   );
-};
+}
 
-export const SingleSelectCreate: Story = withDescription({
-  render: () => <SingleSelectCreateTemplate />,
-}, 'Shows single-select creation where a newly created option becomes the current value immediately.');
+// 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: () => <SingleSelectCreateTemplate />,
+    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;
+  };
 
-export const CustomTagLabel: Story = withDescription({
-  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' },
-    ],
-    multiple: true,
-    placeholder: 'Search students...',
-    showClearAll: true,
+  return (
+    <Combobox
+      options={options}
+      allowCreate
+      onCreateNew={handleCreate}
+      placeholder="Select or add a teacher..."
+    />
+  );
+}
+          `.trim(),
+        },
+      },
+    },
   },
-}, 'Uses `tagLabel` to shorten selected chip text while preserving fuller option labels in the dropdown.');
+);
+
+// 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: comboboxPeopleOptions,
+      multiple: true,
+      placeholder: 'Select teachers...',
+      renderOption: (option: ComboboxOption) => (
+        <span style={{ display: 'flex', alignItems: 'center', gap: 'var(--size-space-200)' }}>
+          <Icon name="user" size={16} />
+          <span>{option.label}</span>
+        </span>
+      ),
+    },
+    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(),
+        },
+      },
+    },
+  },
+);
+
+// 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: ComboboxOption) => 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: comboboxPeopleOptions.map((o, i) => ({ ...o, disabled: i % 3 === 1 })),
+      multiple: true,
+      placeholder: 'Select teachers...',
+    },
+    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}\`,
+}));
 
-export const WithDisabledOptions: Story = withDescription({
-  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' },
-    ],
-    multiple: true,
-    placeholder: 'Search people...',
+<Combobox options={options} multiple placeholder="Search 50 options..." />
+          `.trim(),
+        },
+      },
+    },
   },
-}, 'Includes a disabled option to show how unavailable rows appear and behave inside the listbox.');
+);