@transferwise/components 46.131.2 → 46.132.1

package/src/inputs/SelectInput/_stories/SelectInput.story.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-webpack5';
-import { expect, fn, type Mock, screen, userEvent, within, waitFor } from 'storybook/test';
+import { fn, type Mock } from 'storybook/test';
 import { Calendar, ChevronDown } from '@transferwise/icons';
 import { Flag } from '@wise/art';
 import { clsx } from 'clsx';
@@ -10,7 +10,6 @@ import { getMonthNames } from '../../../common/dateUtils';
 import Drawer from '../../../drawer';
 import { Field } from '../../../field/Field';
 import Modal from '../../../modal';
-import { wait } from '../../../test-utils/wait';
 import {
   SelectInput,
   type SelectInputItem,
@@ -19,6 +18,12 @@ import {
   SelectInputTriggerButton,
 } from '..';
 
+/**
+ * A searchable, accessible combobox for selecting a single or multiple values.
+ * Supports flat and grouped items, optional filtering, custom triggers, a clear button,
+ * and a custom footer. Renders a popover on desktop and a bottom sheet on mobile.
+ * Lists with 50+ items are automatically virtualised.
+ */
 const meta = {
   title: 'Forms/SelectInput',
   component: SelectInput,
@@ -30,14 +35,33 @@ const meta = {
   },
   argTypes: {
     parentId: {
+      table: { category: 'WDS internal' },
+    },
+    renderTrigger: {
       table: {
-        category: 'WDS internal',
+        defaultValue: { summary: 'Default trigger (InputGroup + ButtonInput)' },
       },
     },
+    // Events
+    onClear: {
+      table: { category: 'Events' },
+    },
+    onFilterChange: {
+      table: { category: 'Events' },
+    },
+    onChange: {
+      table: { category: 'Events' },
+    },
+    onClose: {
+      table: { category: 'Events' },
+    },
+    onOpen: {
+      table: { category: 'Events' },
+    },
   },
   parameters: {
-    docs: { toc: true },
     actions: { argTypesRegex: '' },
+    docs: { toc: true },
   },
 } satisfies Meta<typeof SelectInput>;
 export default meta;
@@ -54,57 +78,6 @@ const months: Month[] = getMonthNames('en-US').map((name, index) => ({
   name,
 }));
 
-export const Months: Story<Month | null> = {
-  args: {
-    placeholder: 'Month',
-    items: months.map((month) => ({
-      type: 'option',
-      value: month,
-    })),
-    renderValue: (month) => <SelectInputOptionContent title={month.name} />,
-  },
-  render: function Render({ onChange, onClear, ...args }) {
-    const [selectedMonth, setSelectedMonth] = useState<Month | null>(null);
-
-    return (
-      <SelectInput
-        {...args}
-        value={selectedMonth}
-        onChange={(month) => {
-          setSelectedMonth(month);
-          onChange?.(month);
-        }}
-        onClear={() => {
-          setSelectedMonth(null);
-          onClear?.();
-        }}
-      />
-    );
-  },
-  play: async ({ canvasElement, step }) => {
-    const canvas = within(canvasElement);
-
-    await step('renders placeholder', async () => {
-      const triggerButton = canvas.getByRole('combobox');
-      await waitFor(async () => expect(triggerButton).toHaveTextContent('Month'));
-    });
-
-    await step('selects option via mouse', async () => {
-      const triggerButton = canvas.getByRole('combobox');
-
-      await userEvent.click(triggerButton);
-      await userEvent.unhover(triggerButton);
-
-      const option = within(screen.getByRole('listbox')).getByRole('option', {
-        name: 'May',
-      });
-      await userEvent.click(option);
-
-      await waitFor(async () => expect(triggerButton).toHaveTextContent('May'));
-    });
-  },
-};
-
 interface Currency {
   code: string;
   name: string;
@@ -140,9 +113,9 @@ const otherCurrencies: Currency[] = [
     name: 'Australian dollar',
   },
   {
-    code: 'ÅLD',
-    name: 'Ålandian peso',
-    countries: ['Ålandia'],
+    code: 'JPY',
+    name: 'Japanese yen',
+    countries: ['Japan'],
   },
 ];
 
@@ -182,18 +155,18 @@ const CurrenciesArgs = {
   renderFooter: ({ resultsEmpty, queryNormalized }) =>
     resultsEmpty && queryNormalized != null && /^[a-z]{3}$/u.test(queryNormalized) ? (
       <>
-        It’s not possible use {queryNormalized.toUpperCase()} yet.{' '}
+        It is not possible to use {queryNormalized.toUpperCase()} yet.{' '}
         <a href="#_" className="np-text-link-default" onClick={(event) => event.preventDefault()}>
-          Email me when it’s available.
+          Email me when it is available.
         </a>
       </>
     ) : (
       <>
-        Can’t find it?{' '}
+        Cannot find it?{' '}
         <a href="#_" className="np-text-link-default" onClick={(event) => event.preventDefault()}>
           Request the currency you need,
         </a>{' '}
-        and we’ll notify you once it’s available.
+        and we will notify you once it is available.
       </>
     ),
   filterable: true,
@@ -201,69 +174,244 @@ const CurrenciesArgs = {
   size: 'lg',
 } satisfies Story<Currency>['args'];
 
-export const Currencies: Story<Currency> = {
-  args: CurrenciesArgs,
-  play: async ({ step }) => {
-    await step('Tab to the combobox', async () => {
-      await userEvent.tab();
-    });
-
-    await step('Open the combobox', async () => {
-      await userEvent.keyboard(' ');
-    });
-
-    await step('Check if options are displayed', async () => {
-      await waitFor(async () => expect(await screen.findAllByRole('option')).toHaveLength(9));
-      await waitFor(async () => expect(screen.getByText(/^Can’t find it?/u)).toBeInTheDocument());
-    });
-
-    await step('Type "huf" in the combobox', async () => {
-      // this is workaround for Chromatic: Firefox and Edge tests failing.
-      // Unclear on a proper solution
-      await wait(750);
-      const input = await screen.findByRole('combobox');
-      await userEvent.type(input, 'huf');
-    });
-
-    await step('Check if no options are displayed', async () => {
-      // this is workaround for Chromatic: Firefox and Edge tests failing.
-      // Unclear on a proper solution
-      await wait(750);
-      await expect(await screen.findByText(/^No results found/u)).toBeInTheDocument();
-      await expect(await screen.findByText(/^It’s not possible use HUF yet./u)).toBeInTheDocument();
-      await waitFor(
-        async () => {
-          await expect(screen.queryAllByRole('option')).toHaveLength(0);
-        },
-        { timeout: 1500 },
+const previewArgGroup = {
+  table: { category: 'Storybook Preview', type: { summary: undefined } },
+};
+
+type PlaygroundArgs = {
+  size?: 'sm' | 'md' | 'lg';
+  filterable?: boolean;
+  filterPlaceholder?: string;
+  disabled?: boolean;
+  placeholder?: string;
+  multiple?: boolean;
+  previewWithGroups: boolean;
+  previewClearable: boolean;
+  previewWithFooter: boolean;
+};
+
+export const Playground: StoryObj<PlaygroundArgs> = {
+  argTypes: {
+    previewWithGroups: {
+      name: 'Preview with groups',
+      control: 'boolean',
+      ...previewArgGroup,
+    },
+    previewClearable: {
+      name: 'Preview with clear button',
+      control: 'boolean',
+      ...previewArgGroup,
+    },
+    previewWithFooter: {
+      name: 'Preview with footer',
+      control: 'boolean',
+      ...previewArgGroup,
+    },
+  },
+  args: {
+    disabled: false,
+    multiple: false,
+    filterable: true,
+    filterPlaceholder: 'Type a currency / country',
+    placeholder: 'Select a currency',
+    size: 'lg',
+    previewWithGroups: true,
+    previewClearable: true,
+    previewWithFooter: true,
+  },
+  render: function Render({
+    previewWithGroups,
+    previewClearable,
+    previewWithFooter,
+    multiple,
+    filterPlaceholder,
+    ...args
+  }) {
+    const [singleValue, setSingleValue] = useState<Currency | undefined>(undefined);
+    const [multiValue, setMultiValue] = useState<Currency[]>([]);
+
+    const items: SelectInputItem<Currency>[] = previewWithGroups
+      ? [
+          {
+            type: 'group',
+            label: 'Popular currencies',
+            options: popularCurrencies.map(currencyOption),
+          },
+          { type: 'group', label: 'All currencies', options: allCurrencies.map(currencyOption) },
+        ]
+      : allCurrencies.map(currencyOption);
+
+    const renderValue = (currency: Currency, withinTrigger: boolean) => {
+      if (multiple && withinTrigger) return currency.code;
+      return (
+        <SelectInputOptionContent
+          title={currency.code}
+          note={withinTrigger ? undefined : currency.name}
+          icon={<Flag code={currency.code} intrinsicSize={24} />}
+        />
       );
-    });
+    };
 
-    await step('Remove last two characters', async () => {
-      await wait(500);
-      const input = await screen.findByRole('combobox');
-      await userEvent.type(input, '{Backspace}{Backspace}');
-    });
+    const renderFooter = previewWithFooter
+      ? ({
+          resultsEmpty,
+          queryNormalized,
+        }: {
+          resultsEmpty: boolean;
+          queryNormalized: string | null | undefined;
+        }) =>
+          resultsEmpty && queryNormalized != null && /^[a-z]{3}$/u.test(queryNormalized) ? (
+            <>It is not possible to use {queryNormalized.toUpperCase()} yet.</>
+          ) : (
+            <>
+              Cannot find it?{' '}
+              <a href="#_" className="np-text-link-default" onClick={(e) => e.preventDefault()}>
+                Request the currency
+              </a>
+            </>
+          )
+      : undefined;
 
-    await step('Check if two options are displayed', async () => {
-      await waitFor(async () =>
-        expect(within(screen.getByRole('listbox')).queryAllByRole('option')).toHaveLength(2),
+    if (multiple) {
+      return (
+        <SelectInput<Currency, true>
+          {...(args as SelectInputProps<Currency, true>)}
+          multiple
+          items={items}
+          value={multiValue}
+          renderValue={renderValue}
+          renderFooter={renderFooter}
+          filterPlaceholder={filterPlaceholder}
+          onClear={previewClearable ? () => setMultiValue([]) : undefined}
+          onChange={setMultiValue}
+        />
       );
-    });
+    }
+
+    return (
+      <SelectInput<Currency>
+        {...(args as SelectInputProps<Currency>)}
+        items={items}
+        value={singleValue}
+        renderValue={renderValue}
+        renderFooter={renderFooter}
+        filterPlaceholder={filterPlaceholder}
+        onClear={previewClearable ? () => setSingleValue(undefined) : undefined}
+        onChange={setSingleValue}
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      canvas: { sourceState: 'hidden' },
+    },
+  },
+};
+
+/**
+ * The simplest usage: a flat list of options with no icons or grouping.
+ * `renderValue` controls what is shown in both the trigger and each dropdown row.
+ */
+export const Basic: Story<Month | null> = {
+  args: {
+    placeholder: 'Month',
+    items: months.map((month) => ({
+      type: 'option',
+      value: month,
+    })),
+    renderValue: (month) => <SelectInputOptionContent title={month.name} />,
+  },
+  render: function Render({ onChange, onClear, ...args }) {
+    const [selectedMonth, setSelectedMonth] = useState<Month | null>(null);
 
-    await step('Type "e" in the combobox', async () => {
-      const input = await screen.findByRole('combobox');
-      await userEvent.type(input, '{Backspace}e');
-    });
+    return (
+      <SelectInput
+        {...args}
+        value={selectedMonth}
+        onChange={(month) => {
+          setSelectedMonth(month);
+          onChange?.(month);
+        }}
+        onClear={() => {
+          setSelectedMonth(null);
+          onClear?.();
+        }}
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  placeholder="Month"
+  items={[
+    { type: 'option', value: { id: 1, name: 'January' } },
+    { type: 'option', value: { id: 2, name: 'February' } },
+    // ... 10 more months
+  ]}
+  renderValue={(month) => <SelectInputOptionContent title={month.name} />}
+  value={selectedMonth}
+  onChange={setSelectedMonth}
+/>`,
+      },
+    },
+  },
+};
 
-    await step('Check if aria-activedescendant is not set', async () => {
-      const input = screen.getByRole('combobox');
-      await waitFor(async () => expect(input).toHaveAttribute('aria-activedescendant'));
-    });
+/**
+ * A real-world currency selector with grouped items, flag icons, filterable search,
+ * and a custom footer. `renderValue` receives a `withinTrigger` boolean to render
+ * a compact version inside the trigger/selected state (code only, no full currency name).
+ */
+export const Grouping: Story<Currency> = {
+  args: CurrenciesArgs,
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  filterable
+  filterPlaceholder="Type a currency / country"
+  size="lg"
+  items={[
+    {
+      type: 'group',
+      label: 'Popular currencies',
+      options: popularCurrencies.map((c) => ({
+        type: 'option',
+        value: c,
+        filterMatchers: [c.code, c.name, ...(c.countries ?? [])],
+      })),
+    },
+    // ... more groups
+  ]}
+  defaultValue={popularCurrencies[0]}
+  renderValue={(currency, withinTrigger) => (
+    <SelectInputOptionContent
+      title={currency.code}
+      note={withinTrigger ? undefined : currency.name}
+      icon={<Flag code={currency.code} intrinsicSize={24} />}
+    />
+  )}
+  renderFooter={({ resultsEmpty }) =>
+    resultsEmpty ? (
+      <>Cannot find it? <a>Request the currency you need.</a></>
+    ) : null
+  }
+/>`,
+      },
+    },
   },
 };
 
-export const MultipleCurrencies: Story<Currency, true> = {
+/**
+ * When `multiple` is `true`, `value` and `onChange` operate on arrays. Use the
+ * `withinTrigger` argument in `renderValue` to show a compact summary inside the
+ * trigger (e.g. currency codes joined by commas).
+ */
+export const MultiSelect: Story<Currency, true> = {
+  argTypes: {
+    multiple: { table: { disable: true } },
+  },
   args: {
     ...CurrenciesArgs,
     multiple: true,
@@ -280,35 +428,46 @@ export const MultipleCurrencies: Story<Currency, true> = {
         />
       ),
   },
-  play: async ({ canvasElement, step, args }) => {
-    const canvas = within(canvasElement);
-
-    await step('Open the combobox', async () => {
-      const triggerButton = canvas.getByRole('combobox');
-      await userEvent.click(triggerButton);
-      await wait(500);
-      await userEvent.unhover(triggerButton);
-      await expect(args.onOpen).toHaveBeenCalledOnce();
-    });
-
-    await step('Select EUR option', async () => {
-      const option = within(screen.getByRole('listbox')).getAllByRole('option', {
-        name: /^EUR/u,
-      })[0];
-      await wait(500);
-      await userEvent.click(option);
-    });
-
-    await step('Check if selected options are displayed', async () => {
-      const triggerButton = document.querySelector('button[role="combobox"]');
-      await waitFor(async () => expect(triggerButton).toHaveTextContent('USD, EUR'));
-    });
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  multiple
+  filterable
+  placeholder="Choose currencies…"
+  items={[
+    { type: 'option', value: { code: 'USD', name: 'United States Dollar' }, filterMatchers: ['USD', 'United States Dollar'] },
+    // ... more options
+  ]}
+  defaultValue={[currencies[0]]}
+  renderValue={(currency, withinTrigger) =>
+    withinTrigger
+      ? currency.code
+      : (
+        <SelectInputOptionContent
+          title={currency.code}
+          note={currency.name}
+          icon={<Flag code={currency.code} intrinsicSize={24} />}
+        />
+      )
+  }
+/>`,
+      },
+    },
   },
 };
 
-export const WithSelectAll: Story<Currency, true> = {
+/**
+ * Groups can have an `action` button (e.g. "Select all" / "Deselect all") rendered
+ * next to the group heading. The label should update dynamically based on whether
+ * all items in that group are selected.
+ */
+export const WithGroupActions: Story<Currency, true> = {
+  argTypes: {
+    multiple: { table: { disable: true } },
+  },
   args: {
-    ...MultipleCurrencies.args,
+    ...MultiSelect.args,
   },
   render: function Render(args) {
     const [selectedItems, setSelectedItems] = useState<Currency[]>([]);
@@ -363,21 +522,87 @@ export const WithSelectAll: Story<Currency, true> = {
       />
     );
   },
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  multiple
+  items={[
+    {
+      type: 'group',
+      label: 'Popular currencies',
+      options: popularCurrencies.map(currencyOption),
+      action: {
+        label: allSelected(popularCurrencies) ? 'Deselect all' : 'Select all',
+        onClick: () => toggleItems(popularCurrencies),
+      },
+    },
+    // ... more groups
+  ]}
+  value={selectedItems}
+  onChange={setSelectedItems}
+  onClear={() => setSelectedItems([])}
+/>`,
+      },
+    },
+  },
 };
 
+/** Pass `onClear` to show a clear button when a value is selected. */
 export const WithClear: Story<Currency> = {
+  argTypes: {
+    onClear: { table: { disable: true } },
+  },
   args: {
     ...CurrenciesArgs,
     onClear: fn() satisfies Mock,
   },
-  play: async ({ step }) => {
-    await step('Has clear button', async () => {
-      const clearBtn = await screen.findByRole('button', { name: 'Clear' });
-      await expect(clearBtn).toBeInTheDocument();
-    });
+  render: function Render({ onChange, onClear, defaultValue: _dv, ...args }) {
+    const [value, setValue] = useState<Currency | undefined>(popularCurrencies[0]);
+    return (
+      <SelectInput
+        {...args}
+        value={value}
+        onChange={(currency) => {
+          setValue(currency);
+          onChange?.(currency);
+        }}
+        onClear={() => {
+          setValue(undefined);
+          onClear?.();
+        }}
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  filterable
+  size="lg"
+  items={[
+    { type: 'option', value: { code: 'USD', name: 'United States Dollar' }, filterMatchers: ['USD', 'United States Dollar'] },
+    // ... more options
+  ]}
+  defaultValue={currencies[0]}
+  renderValue={(currency) => (
+    <SelectInputOptionContent
+      title={currency.code}
+      icon={<Flag code={currency.code} intrinsicSize={24} />}
+    />
+  )}
+  onClear={() => setValue(undefined)}
+/>`,
+      },
+    },
   },
 };
 
+/**
+ * Use `renderTrigger` with `SelectInputTriggerButton` to fully customise the trigger
+ * appearance. The interactive element **must** be `SelectInputTriggerButton` to receive
+ * the correct ARIA attributes (`aria-expanded`, `aria-haspopup`, `aria-controls`).
+ */
 export const CustomTrigger: Story<Month> = {
   args: {
     placeholder: 'Month',
@@ -397,28 +622,39 @@ export const CustomTrigger: Story<Month> = {
       </SelectInputTriggerButton>
     ),
   },
-  play: async ({ canvasElement, step, args }) => {
-    const canvas = within(canvasElement);
-
-    await step('Open the combobox', async () => {
-      const triggerButton = canvas.getByRole('combobox');
-      await userEvent.click(triggerButton);
-      await expect(args.onOpen).toHaveBeenCalledOnce();
-    });
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  placeholder="Month"
+  items={monthItems}
+  renderValue={(month, withinTrigger) =>
+    withinTrigger ? month.name : <SelectInputOptionContent title={month.name} />
+  }
+  renderTrigger={({ content, className }) => (
+    <SelectInputTriggerButton
+      className={clsx(className, 'btn-unstyled np-text-link-large align-items-center')}
+      style={{ display: 'inline-flex', columnGap: '0.25rem' }}
+    >
+      {content}
+      <ChevronDown size={16} />
+    </SelectInputTriggerButton>
+  )}
+/>`,
+      },
+    },
   },
 };
 
-const quarters = [
-  months.slice(0, 3),
-  months.slice(3, 6),
-  months.slice(6, 9),
-  months.slice(9, 12),
-] as const;
-
+/**
+ * Combines grouped items, `separator` items, disabled options, and filterable search.
+ * `SelectInputOptionContent` supports `title`, `note` (inline), and
+ * `description` (below-title) for rich two-line option layouts.
+ */
 export const Advanced: Story<Month> = {
   args: {
     placeholder: 'Month',
-    items: quarters
+    items: [months.slice(0, 3), months.slice(3, 6), months.slice(6, 9), months.slice(9, 12)]
       .flatMap<SelectInputItem<Month>>((quarterMonths, quarterIndex) => [
         {
           type: 'group',
@@ -442,19 +678,46 @@ export const Advanced: Story<Month> = {
       />
     ),
     filterable: true,
-    filterPlaceholder: 'Type a month’s name',
+    filterPlaceholder: "Type a month's name",
   },
-  play: async ({ canvasElement, step }) => {
-    const canvas = within(canvasElement);
-
-    await step('Open the combobox', async () => {
-      const triggerButton = canvas.getByRole('combobox');
-      await userEvent.click(triggerButton);
-    });
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  filterable
+  filterPlaceholder="Type a month name"
+  items={[
+    {
+      type: 'group',
+      label: 'Quarter #1',
+      options: [
+        { type: 'option', value: jan, filterMatchers: ['January'] },
+        { type: 'option', value: feb, filterMatchers: ['February'] },
+        { type: 'option', value: mar, filterMatchers: ['March'], disabled: true },
+      ],
+    },
+    { type: 'separator' },
+    // ... more groups
+  ]}
+  renderValue={(month) => (
+    <SelectInputOptionContent
+      title={month.name}
+      note="Note"
+      description={\`Month #\${month.id}\`}
+      icon={<Calendar size={24} />}
+    />
+  )}
+/>`,
+      },
+    },
   },
 };
 
-export const ManyItems: Story<string, true> = {
+/**
+ * Lists with 50+ items are automatically virtualised using a windowed renderer.
+ * This example renders 1,000 numbered options with multi-select enabled.
+ */
+export const Virtualization: Story<string, true> = {
   args: {
     multiple: true,
     items: Array.from({ length: 1000 }, (_, index) => ({
@@ -472,18 +735,257 @@ export const ManyItems: Story<string, true> = {
       ),
     filterable: true,
   },
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  multiple
+  filterable
+  items={Array.from({ length: 1000 }, (_, i) => ({
+    type: 'option',
+    value: String(i + 1),
+  }))}
+  renderValue={(value, withinTrigger) =>
+    withinTrigger ? value : <SelectInputOptionContent title={value} />
+  }
+/>`,
+      },
+    },
+  },
 };
 
-export const WithinField = {
-  args: Months.args,
-  decorators: [
-    (Story) => (
-      <Field message="Something went wrong" sentiment="negative" label="Month">
-        <Story />
+/** The `disabled` prop prevents all interaction. */
+export const Disabled: Story<Currency> = {
+  argTypes: {
+    disabled: { table: { disable: true } },
+    id: { table: { disable: true } },
+    name: { table: { disable: true } },
+    multiple: { table: { disable: true } },
+    placeholder: { table: { disable: true } },
+    items: { table: { disable: true } },
+    autocomplete: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    value: { table: { disable: true } },
+    compareValues: { table: { disable: true } },
+    renderValue: { table: { disable: true } },
+    renderFooter: { table: { disable: true } },
+    renderTrigger: { table: { disable: true } },
+    filterable: { table: { disable: true } },
+    filterPlaceholder: { table: { disable: true } },
+    sortFilteredOptions: { table: { disable: true } },
+    className: { table: { disable: true } },
+    UNSAFE_triggerButtonProps: { table: { disable: true } },
+    triggerRef: { table: { disable: true } },
+    parentId: { table: { disable: true } },
+    onFilterChange: { table: { disable: true } },
+    onChange: { table: { disable: true } },
+    onClose: { table: { disable: true } },
+    onOpen: { table: { disable: true } },
+    onClear: { table: { disable: true } },
+  },
+  args: {
+    ...CurrenciesArgs,
+    disabled: true,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput
+  disabled
+  filterable
+  size="lg"
+  items={currencyItems}
+  defaultValue={currencies[0]}
+  renderValue={(currency) => (
+    <SelectInputOptionContent
+      title={currency.code}
+      icon={<Flag code={currency.code} intrinsicSize={24} />}
+    />
+  )}
+/>`,
+      },
+    },
+  },
+};
+
+/** Three size variants: `sm`, `md`, and `lg`. */
+export const Sizes: Story<Currency> = {
+  argTypes: {
+    size: { table: { disable: true } },
+  },
+  render: (args) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '400px' }}>
+      <SelectInput<Currency>
+        {...args}
+        size="sm"
+        placeholder="Small"
+        items={popularCurrencies.map(currencyOption)}
+        renderValue={(c) => <SelectInputOptionContent title={c.code} note={c.name} />}
+      />
+      <SelectInput<Currency>
+        {...args}
+        size="md"
+        placeholder="Medium"
+        items={popularCurrencies.map(currencyOption)}
+        renderValue={(c) => <SelectInputOptionContent title={c.code} note={c.name} />}
+      />
+      <SelectInput<Currency>
+        {...args}
+        size="lg"
+        placeholder="Large (default)"
+        items={popularCurrencies.map(currencyOption)}
+        renderValue={(c) => <SelectInputOptionContent title={c.code} note={c.name} />}
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<SelectInput size="sm" placeholder="Small" items={currencyItems} renderValue={renderCurrency} />
+<SelectInput size="md" placeholder="Medium" items={currencyItems} renderValue={renderCurrency} />
+<SelectInput size="lg" placeholder="Large" items={currencyItems} renderValue={renderCurrency} />`,
+      },
+    },
+  },
+};
+
+/**
+ * "Commit on close" pattern: stage selections locally and apply them only when the
+ * dropdown closes. Useful when each selection change is expensive (e.g. an API call)
+ * or when the UX requires confirmation before updating external state.
+ */
+export const WithCommitOnClose: Story<Currency, true> = {
+  argTypes: {
+    onClose: { table: { disable: true } },
+  },
+  render: function Render(args) {
+    const [committedValues, setCommittedValues] = useState<Currency[]>([popularCurrencies[0]]);
+    const [stagedValues, setStagedValues] = useState<Currency[]>([popularCurrencies[0]]);
+
+    return (
+      <div>
+        <p className="m-t-2 np-text-body-small">
+          Applied: {committedValues.map((c) => c.code).join(', ') || 'none'}
+        </p>
+        <SelectInput<Currency, true>
+          {...args}
+          multiple
+          filterable
+          filterPlaceholder="Type a currency / country"
+          size="lg"
+          placeholder="Choose currencies…"
+          items={[
+            {
+              type: 'group',
+              label: 'Popular currencies',
+              options: popularCurrencies.map(currencyOption),
+            },
+            {
+              type: 'group',
+              label: 'All currencies',
+              options: allCurrencies.map(currencyOption),
+            },
+          ]}
+          renderValue={(currency, withinTrigger) =>
+            withinTrigger ? (
+              currency.code
+            ) : (
+              <SelectInputOptionContent
+                title={currency.code}
+                note={currency.name}
+                icon={<Flag code={currency.code} intrinsicSize={24} />}
+              />
+            )
+          }
+          value={stagedValues}
+          onChange={setStagedValues}
+          onClose={() => setCommittedValues(stagedValues)}
+          onClear={() => {
+            setStagedValues([]);
+            setCommittedValues([]);
+          }}
+        />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `const [committedValues, setCommittedValues] = useState([]);
+const [stagedValues, setStagedValues] = useState([]);
+
+<SelectInput
+  multiple
+  value={stagedValues}
+  onChange={setStagedValues}
+  onClose={() => setCommittedValues(stagedValues)}
+  onClear={() => { setStagedValues([]); setCommittedValues([]); }}
+  // ...items, renderValue
+/>`,
+      },
+    },
+  },
+};
+
+/**
+ * Wrap with `Field` to inherit error state and label association automatically.
+ * `Field` injects `aria-describedby` on the trigger pointing to the validation
+ * message — no manual wiring required.
+ */
+export const WithinField: Story<Month> = {
+  args: {
+    placeholder: "Today's Month",
+    items: months.map((month) => ({
+      type: 'option',
+      value: month,
+    })),
+    renderValue: (month) => <SelectInputOptionContent title={month.name} />,
+  },
+  render: function Render({ onChange, ...args }) {
+    const currentMonthIndex = new Date().getMonth();
+    const defaultMonth = months[currentMonthIndex === 0 ? 2 : 0];
+    const [selectedMonth, setSelectedMonth] = useState<Month>(defaultMonth);
+    const isCorrect = selectedMonth.id === currentMonthIndex + 1;
+
+    return (
+      <Field
+        label="Today's Month"
+        message={isCorrect ? undefined : 'Please select the current month'}
+        sentiment={isCorrect ? undefined : 'negative'}
+      >
+        <SelectInput
+          {...args}
+          value={selectedMonth}
+          onChange={(month) => {
+            setSelectedMonth(month);
+            onChange?.(month);
+          }}
+        />
       </Field>
-    ),
-  ],
-} satisfies Story<Month | null>;
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `const isCorrect = selectedMonth.id === currentMonthIndex + 1;
+
+<Field
+  label="Today's Month"
+  message={isCorrect ? undefined : 'Please select the current month'}
+  sentiment={isCorrect ? undefined : 'negative'}
+>
+  <SelectInput
+    placeholder="Today's Month"
+    items={monthItems}
+    renderValue={(month) => <SelectInputOptionContent title={month.name} />}
+    value={selectedMonth}
+    onChange={setSelectedMonth}
+  />
+</Field>`,
+      },
+    },
+  },
+};
 
 export const WithinDrawer: Story<Currency> = {
   args: CurrenciesArgs,
@@ -506,6 +1008,28 @@ export const WithinDrawer: Story<Currency> = {
       );
     },
   ],
+  parameters: {
+    docs: {
+      source: {
+        code: `<Drawer open={open} onClose={() => setOpen(false)}>
+  <SelectInput
+    filterable
+    filterPlaceholder="Type a currency / country"
+    size="lg"
+    items={currencyItems}
+    renderValue={(currency, withinTrigger) => (
+      <SelectInputOptionContent
+        title={currency.code}
+        note={withinTrigger ? undefined : currency.name}
+        icon={<Flag code={currency.code} intrinsicSize={24} />}
+      />
+    )}
+    onChange={setSelectedCurrency}
+  />
+</Drawer>`,
+      },
+    },
+  },
 };
 
 export const WithinModal: Story<Currency> = {
@@ -518,11 +1042,42 @@ export const WithinModal: Story<Currency> = {
           <Button v2 onClick={() => setOpen(true)}>
             Open modal
           </Button>
-          <Modal open={open} body={<Story />} onClose={() => setOpen(false)} />
+          <Modal
+            title="Select a currency"
+            open={open}
+            body={<Story />}
+            onClose={() => setOpen(false)}
+          />
         </>
       );
     },
   ],
+  parameters: {
+    docs: {
+      source: {
+        code: `<Modal
+  open={open}
+  onClose={() => setOpen(false)}
+  body={
+    <SelectInput
+      filterable
+      filterPlaceholder="Type a currency / country"
+      size="lg"
+      items={currencyItems}
+      renderValue={(currency, withinTrigger) => (
+        <SelectInputOptionContent
+          title={currency.code}
+          note={withinTrigger ? undefined : currency.name}
+          icon={<Flag code={currency.code} intrinsicSize={24} />}
+        />
+      )}
+      onChange={setSelectedCurrency}
+    />
+  }
+/>`,
+      },
+    },
+  },
 };
 
 interface Country {
@@ -546,7 +1101,7 @@ const countries: Country[] = [
   { code: 'NL', name: 'Netherlands' },
   { code: 'CH', name: 'Switzerland' },
   { code: 'SE', name: 'Sweden' },
-  { code: 'AL', name: 'Ålandia' },
+  { code: 'MX', name: 'Mexico' },
 ];
 
 function countryOption(country: Country) {
@@ -557,6 +1112,11 @@ function countryOption(country: Country) {
   } satisfies SelectInputItem;
 }
 
+/**
+ * Use `name` and `autocomplete` to integrate with the browser's native autofill.
+ * The component renders a hidden `<input>` that carries the selected value,
+ * making it submittable inside a `<form>` and detectable by password managers.
+ */
 export const WithAutocomplete: Story<string> = {
   args: {
     name: 'country',
@@ -581,43 +1141,59 @@ export const WithAutocomplete: Story<string> = {
     const [selectedCountry, setSelectedCountry] = useState<string | undefined>(undefined);
 
     return (
-      <div>
-        <form
-          method="post"
-          onSubmit={(e) => {
-            e.preventDefault();
-            console.log(
-              `Form submitted with country: ${selectedCountry}. This saves data for browser autocomplete!`,
-            );
-          }}
-        >
-          <div>
-            <label htmlFor="country-select" className="block text-sm font-medium mb-2">
-              Country Selection with Autocomplete:
-            </label>
-            <SelectInput
-              {...args}
-              id="country-select"
-              value={selectedCountry}
-              onChange={(country) => {
-                setSelectedCountry(country);
-                onChange?.(country);
-                console.log('Country selected via SelectInput:', country);
-              }}
-              onClear={() => {
-                setSelectedCountry(undefined);
-                onClear?.();
-              }}
-            />
-          </div>
-
-          <Button type="submit" v2 className="m-t-2" data-testid="submit-btn">
-            Submit Form
-          </Button>
-        </form>
-      </div>
+      <form method="post" onSubmit={(e) => e.preventDefault()}>
+        <Field label="Country">
+          <SelectInput
+            {...args}
+            id="country-select"
+            value={selectedCountry}
+            onChange={(country) => {
+              setSelectedCountry(country);
+              onChange?.(country);
+            }}
+            onClear={() => {
+              setSelectedCountry(undefined);
+              onClear?.();
+            }}
+          />
+        </Field>
+        <Button type="submit" v2 className="m-t-2" data-testid="submit-btn">
+          Submit Form
+        </Button>
+      </form>
     );
   },
+  parameters: {
+    docs: {
+      source: {
+        code: `<form method="post">
+  <Field label="Country">
+    <SelectInput
+      name="country"
+      autocomplete="country-name"
+      filterable
+      filterPlaceholder="Type a country name"
+      size="lg"
+      items={[
+        { type: 'option', value: 'US', filterMatchers: ['US', 'United States'] },
+        { type: 'option', value: 'GB', filterMatchers: ['GB', 'United Kingdom'] },
+        // ... more countries
+      ]}
+      renderValue={(code, withinTrigger) => (
+        <SelectInputOptionContent
+          title={withinTrigger ? code : countryName(code)}
+          note={withinTrigger ? undefined : code}
+          icon={<Flag code={code} intrinsicSize={24} />}
+        />
+      )}
+      value={selectedCountry}
+      onChange={setSelectedCountry}
+    />
+  </Field>
+</form>`,
+      },
+    },
+  },
 };
 
 interface CountryWithCurrency extends Country {
@@ -640,7 +1216,7 @@ function countryWithCurrencyOption(country: CountryWithCurrency) {
   } satisfies SelectInputItem<CountryWithCurrency>;
 }
 
-export const WithCustomSearchResultSorting: Story<CountryWithCurrency> = {
+export const WithBuiltInSearchResultSorting: Story<CountryWithCurrency> = {
   args: {
     items: countriesWithCurrency.map(countryWithCurrencyOption),
     compareValues: 'code',
@@ -661,8 +1237,8 @@ export const WithCustomSearchResultSorting: Story<CountryWithCurrency> = {
       <div>
         <p className="m-b-3 np-text-body-default" style={{ maxWidth: '600px' }}>
           This example uses the built-in <code>SelectInput.sortByRelevance</code> helper to sort
-          filtered results by relevance. It prioritises: exact matches → starts with → contains →
-          alphabetical.
+          filtered results by relevance (You can implement your own). This one prioritises: exact
+          matches → starts with → contains → alphabetical.
           <br />
           <br />
           Try searching for &quot;united&quot; to see the sorting tiers in action: