@lifesg/react-design-system 4.0.0-alpha.12 → 4.0.0-alpha.14

package/skills/fds-build/resources/components/form-date-range-input.md

@@ -0,0 +1,146 @@
+# Form.DateRangeInput
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Collecting a start and end date from the user (e.g. leave period, booking period, date range filter).
+-   Use `variant="week"` when the selection must always be a full calendar week.
+-   Use `variant="fixed-range"` when the duration is predetermined (e.g. always 7 days).
+
+## Usage
+
+`onChange` always receives both start and end as `YYYY-MM-DD` strings, even for week and fixed-range variants.
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+
+const LeavePeriodField = () => {
+    const [start, setStart] = useState("");
+    const [end, setEnd] = useState("");
+
+    return (
+        <Form.DateRangeInput
+            label="Leave period"
+            value={start}
+            valueEnd={end}
+            minDate="2024-01-01"
+            maxDate="2024-12-31"
+            onChange={(s, e) => {
+                setStart(s);
+                setEnd(e);
+            }}
+        />
+    );
+};
+```
+
+```tsx
+{
+    /* variant="week" — whole-week selection */
+}
+<Form.DateRangeInput
+    label="Select week"
+    variant="week"
+    value={start}
+    valueEnd={end}
+    onChange={(s, e) => {
+        setStart(s);
+        setEnd(e);
+    }}
+/>;
+
+{
+    /* variant="fixed-range" — valueEnd derived automatically; only store start */
+}
+<Form.DateRangeInput
+    label="14-day quarantine period"
+    variant="fixed-range"
+    numberOfDays={14}
+    value={start}
+    valueEnd={end}
+    onChange={(s, e) => {
+        setStart(s);
+        setEnd(e);
+    }}
+/>;
+```
+
+Width: defaults to 4 columns wide at `lg` and above; full-width on mobile. Use `max-width` via a CSS Module class:
+
+```tsx
+import styles from "./MyForm.module.css";
+
+<Form.DateRangeInput className={styles.dateRangeInput} ... />
+```
+
+```css
+/* MyForm.module.css */
+:where(body.fds-breakpoint-lg-min) .dateRangeInput {
+    max-width: 24rem;
+}
+```
+
+## YearMonthDisplay
+
+| Prop    | Type     | Description                       |
+| ------- | -------- | --------------------------------- |
+| `year`  | `number` | Currently displayed year (`YYYY`) |
+| `month` | `number` | Currently displayed month (1–12)  |
+
+## Props
+
+| Prop                       | Type                                             | Default       | Description                                                                                                                                                                                                                                                                                                             |
+| -------------------------- | ------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`                | `string`                                         | —             | —                                                                                                                                                                                                                                                                                                                       |
+| `id`                       | `string`                                         | —             | —                                                                                                                                                                                                                                                                                                                       |
+| `hideInputKeyboard`        | `boolean`                                        | —             | When `true`, suppresses the native on-screen keyboard on mobile devices while still allowing the calendar picker to open.                                                                                                                                                                                               |
+| `value`                    | `string`                                         | —             | The controlled value of the date input in `"YYYY-MM-DD"` or `"YYYY-M-D"` string format.                                                                                                                                                                                                                                 |
+| `valueEnd`                 | `string`                                         | —             | The controlled value of the end date input in `"YYYY-MM-DD"` or `"YYYY-M-D"` string format.                                                                                                                                                                                                                             |
+| `error`                    | `boolean`                                        | —             | Renders the input in an error state.                                                                                                                                                                                                                                                                                    |
+| `disabled`                 | `boolean`                                        | —             | —                                                                                                                                                                                                                                                                                                                       |
+| `readOnly`                 | `boolean`                                        | —             | —                                                                                                                                                                                                                                                                                                                       |
+| `variant`                  | `Exclude<Variant, "single" \| "multi">`          | "range"       | Selection model used by the calendar. - `"range"` — user picks a free-form start and end date independently. - `"week"` — selecting any day automatically expands the selection to the full calendar week. - `"fixed-range"` — selecting a start date automatically sets the end date to `numberOfDays - 1` days later. |
+| `numberOfDays`             | `number`                                         | 7             | Number of days in the selection window when `variant` is `"fixed-range"`. The end date is calculated as the selected start date plus `numberOfDays - 1` days.                                                                                                                                                           |
+| `withButton`               | `boolean`                                        | true          | Whether to show "Done" and "Cancel" action buttons inside the calendar dropdown. When `false`, a selection immediately commits and closes the calendar.                                                                                                                                                                 |
+| `zIndex`                   | `number`                                         | —             | The z-index of the calendar dropdown                                                                                                                                                                                                                                                                                    |
+| `dropdownRootNode`         | `RefObject<HTMLElement>`                         | document.body | The root element that contains the dropdown element.                                                                                                                                                                                                                                                                    |
+| `onChange`                 | `((startDate: string, endDate: string) => void)` | —             | Called when the user completes a valid date range selection. Both dates are provided in `"YYYY-MM-DD"` format. An empty string is passed for either date when the selection is cleared.                                                                                                                                 |
+| `onFocus`                  | `(() => void)`                                   | —             | Called when the input receives focus.                                                                                                                                                                                                                                                                                   |
+| `onBlur`                   | `(() => void)`                                   | —             | Called when focus leaves both the input and the calendar dropdown.                                                                                                                                                                                                                                                      |
+| `onYearMonthDisplayChange` | `((value: YearMonthDisplay) => void)`            | —             | Called when the visible month or year in the calendar changes.                                                                                                                                                                                                                                                          |
+| `minDate`                  | `string`                                         | —             | The minimum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                                                                                                                                                                                                                                               |
+| `maxDate`                  | `string`                                         | —             | The maximum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                                                                                                                                                                                                                                               |
+| `disabledDates`            | `string[]`                                       | —             | Dates to disable in `YYYY-MM-DD` format. Example: `["2023-04-30"]`                                                                                                                                                                                                                                                      |
+| `allowDisabledSelection`   | `boolean`                                        | —             | Specifies if dates normally disabled by `minDate`, `maxDate` and `disabledDates` are still selectable                                                                                                                                                                                                                   |
+| `showActiveMonthDaysOnly`  | `boolean`                                        | —             | Specifies if the calendar should display only dates for the selected month                                                                                                                                                                                                                                              |
+| `label`                    | `FormLabelProps \| string`                       | —             | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                                                                                                                                                                                                |
+| `errorMessage`             | `string \| React.ReactNode`                      | —             | Inline error text rendered below the input.                                                                                                                                                                                                                                                                             |
+| `layoutType`               | `FormElementLayoutType`                          | —             | Controls whether the container uses flex layout or a responsive column grid.                                                                                                                                                                                                                                            |
+| `xxlCols`                  | `ColSpan`                                        | —             | Column span at the `xxl` breakpoint.                                                                                                                                                                                                                                                                                    |
+| `xlCols`                   | `ColSpan`                                        | —             | Column span at the `xl` breakpoint.                                                                                                                                                                                                                                                                                     |
+| `lgCols`                   | `ColSpan`                                        | —             | Column span at the `lg` breakpoint.                                                                                                                                                                                                                                                                                     |
+| `mdCols`                   | `ColSpan`                                        | —             | Column span at the `md` breakpoint.                                                                                                                                                                                                                                                                                     |
+| `smCols`                   | `ColSpan`                                        | —             | Column span at the `sm` breakpoint.                                                                                                                                                                                                                                                                                     |
+| `xsCols`                   | `ColSpan`                                        | —             | Column span at the `xs` breakpoint.                                                                                                                                                                                                                                                                                     |
+| `xxsCols`                  | `ColSpan`                                        | —             | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set.                                                                                                                                                                        |
+
+## Rules
+
+-   Always supply a `label` so the field is accessible.
+-   Pass `value` (start) and `valueEnd` (end) for controlled usage; `onChange` receives both as `YYYY-MM-DD` strings.
+-   Use `minDate`/`maxDate` to restrict selection to valid business date ranges.
+-   Set `errorMessage` rather than `error` alone so users understand what is wrong.
+-   Use `withButton` (default `true`) to require explicit confirmation before the value is committed.
+-   Use `readOnly` on review screens where the range should be visible but not editable.
+-   Specify `dropdownRootNode` if the component is inside a scrollable container.
+-   `valueEnd` is only relevant for `variant="range"` and `variant="fixed-range"`.
+-   `numberOfDays` only applies when `variant="fixed-range"`.
+
+## Anti-patterns
+
+-   Do not use for single-date selection — use `Form.DateInput` instead.
+-   Do not set `numberOfDays` unless `variant="fixed-range"` is also set.
+-   Do not rely on `error` alone without an `errorMessage`.
+-   Do not allow end date before start date — validate in `onChange` before updating state.

package/skills/fds-build/resources/components/form-e-signature.md

@@ -0,0 +1,55 @@
+# Form.ESignature
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Forms that legally require a handwritten signature from the user (e.g. consent forms, declarations, agreements).
+-   Use `description` to guide the user on how to sign (e.g. "Sign within the box using your mouse or touchscreen").
+
+## Form-wrapper props
+
+| Prop                | Type                        | Description                             |
+| ------------------- | --------------------------- | --------------------------------------- |
+| `label`             | `string \| FormLabelProps`  | Field label                             |
+| `errorMessage`      | `string \| React.ReactNode` | Error message displayed below the field |
+| `data-error-testid` | `string`                    | Test identifier for the error message   |
+
+## Props
+
+| Prop              | Type                                | Default        | Description                                                                                                                                      |
+| ----------------- | ----------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `className`       | `string`                            | —              | —                                                                                                                                                |
+| `id`              | `string`                            | —              | —                                                                                                                                                |
+| `disabled`        | `boolean`                           | —              | —                                                                                                                                                |
+| `description`     | `string`                            | —              | Text rendered below the signature area.                                                                                                          |
+| `loadingLabel`    | `string`                            | "Uploading..." | Label displayed alongside the upload progress bar.                                                                                               |
+| `loadingProgress` | `number`                            | —              | When set to a number, replaces the signature area with an upload progress indicator. Remove or set to `undefined` to restore the signature area. |
+| `value`           | `string`                            | —              | The current signature as a base64 image dataURL. Pass `undefined` or omit to render the empty "Add signature" state.                             |
+| `onChange`        | `((value: string \| null) => void)` | —              | Called when the user saves a signature.                                                                                                          |
+| `label`           | `FormLabelProps \| string`          | —              | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                         |
+| `errorMessage`    | `string \| React.ReactNode`         | —              | Inline error text rendered below the input.                                                                                                      |
+| `layoutType`      | `FormElementLayoutType`             | —              | Controls whether the container uses flex layout or a responsive column grid.                                                                     |
+| `xxlCols`         | `ColSpan`                           | —              | Column span at the `xxl` breakpoint.                                                                                                             |
+| `xlCols`          | `ColSpan`                           | —              | Column span at the `xl` breakpoint.                                                                                                              |
+| `lgCols`          | `ColSpan`                           | —              | Column span at the `lg` breakpoint.                                                                                                              |
+| `mdCols`          | `ColSpan`                           | —              | Column span at the `md` breakpoint.                                                                                                              |
+| `smCols`          | `ColSpan`                           | —              | Column span at the `sm` breakpoint.                                                                                                              |
+| `xsCols`          | `ColSpan`                           | —              | Column span at the `xs` breakpoint.                                                                                                              |
+| `xxsCols`         | `ColSpan`                           | —              | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set. |
+
+## Rules
+
+-   Always supply a `label` so the field is accessible.
+-   Pass `value` and `onChange` together for controlled usage; the value is a base64-encoded PNG string.
+-   Use `loadingProgress` and `loadingLabel` to indicate server upload progress after the signature is submitted.
+-   Set `errorMessage` when signature validation fails (e.g. canvas is empty on submit).
+-   Use `disabled` when the signature field should be locked (e.g. after submission or in a locked step).
+-   `value` and the `onChange` return value are both base64-encoded PNG strings.
+-   `loadingProgress` and `loadingLabel` are used to show upload progress after the signature is captured.
+
+## Anti-patterns
+
+-   Do not use for typed signatures or checkbox confirmations — this component is for handwritten drawing input only.
+-   Do not store the raw base64 string in a URL parameter or cookie — it is large; use server-side storage.
+-   Do not omit `description` — users need guidance on where and how to draw their signature.

package/skills/fds-build/resources/components/form-input.md

@@ -0,0 +1,65 @@
+# Form.Input
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+Use for any single-line text entry inside a form. Always prefer `Form.Input` over the bare `Input` component when a label or error message is required.
+
+## Variants
+
+| `styleType`            | When to use                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| `"bordered"` (default) | Standard form fields — provides clear affordance                                            |
+| `"no-border"`          | Inline editing or contexts where a surrounding container already provides visual separation |
+
+## Usage
+
+```tsx
+import { Form } from "@lifesg/react-design-system/form";
+
+<Form.Input
+    label="Full name"
+    placeholder="Enter your name"
+    value={value}
+    onChange={(e) => {}}
+/>;
+```
+
+## Props
+
+| Prop           | Type                        | Default    | Description                                                                                                                                      |
+| -------------- | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `spacing`      | `number`                    | —          | Inserts a space after every `spacing` characters in the displayed value. Only applies when `type` is `"tel"`.                                    |
+| `allowClear`   | `boolean`                   | false      | Shows a clear button when the field has a value and is neither disabled nor read-only.                                                           |
+| `onClear`      | `() => void`                | —          | Called when the user activates the clear button. Use this to clear the controlled value.                                                         |
+| `styleType`    | `InputStyleType`            | "bordered" | Visual style variant.                                                                                                                            |
+| `label`        | `FormLabelProps \| string`  | —          | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                         |
+| `errorMessage` | `string \| React.ReactNode` | —          | Inline error text rendered below the input.                                                                                                      |
+| `layoutType`   | `FormElementLayoutType`     | —          | Controls whether the container uses flex layout or a responsive column grid.                                                                     |
+| `xxlCols`      | `ColSpan`                   | —          | Column span at the `xxl` breakpoint.                                                                                                             |
+| `xlCols`       | `ColSpan`                   | —          | Column span at the `xl` breakpoint.                                                                                                              |
+| `lgCols`       | `ColSpan`                   | —          | Column span at the `lg` breakpoint.                                                                                                              |
+| `mdCols`       | `ColSpan`                   | —          | Column span at the `md` breakpoint.                                                                                                              |
+| `smCols`       | `ColSpan`                   | —          | Column span at the `sm` breakpoint.                                                                                                              |
+| `xsCols`       | `ColSpan`                   | —          | Column span at the `xs` breakpoint.                                                                                                              |
+| `xxsCols`      | `ColSpan`                   | —          | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set. |
+
+## Rules
+
+-   Set `type="email"` for email fields and `type="tel"` for phone fields — triggers the correct mobile keyboard.
+-   Use `readOnly` on review or summary screens — not `disabled`. Disabled implies interaction is unavailable; read-only implies the field is intentionally non-editable in context.
+-   Use `allowClear` for optional fields and search-like inputs; pair with `onClear` to reset controlled value.
+-   Use `spacing` for formatted `tel` inputs (e.g. `spacing={4}` for `9123 4567`) — do not implement custom character splitting.
+-   Provide `errorMessage` rather than `error` alone — the string drives both the visual state and the accessible error text.
+-   Use `label` as a plain string for simple labels; use `FormLabelProps` (with `subtitle` or `addon`) only when additional context is needed.
+-   `error` is redundant when `errorMessage` is provided — `errorMessage` implies the error state automatically.
+-   `spacing` only has effect when `type="tel"`.
+-   `styleType="no-border"` removes the visible border — use only in contexts with a background that provides visual separation.
+
+## Anti-patterns
+
+-   Do not use `disabled` on review screens — use `readOnly`.
+-   Do not set both `error` and `errorMessage` — `errorMessage` is sufficient.
+-   Do not use `spacing` with input types other than `"tel"`.
+-   Do not use `styleType="no-border"` in a form context without a containing element that visually distinguishes the field.

package/skills/fds-build/resources/components/form-masked-input.md

@@ -0,0 +1,69 @@
+# Form.MaskedInput
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Displaying sensitive data that should be partially hidden by default with a user-controlled reveal toggle (e.g. NRIC, FIN, passport number, bank account number).
+-   Read-only fields that are loaded asynchronously and should show a loading / error state.
+
+## Form-wrapper props
+
+| Prop                | Type                        | Description                             |
+| ------------------- | --------------------------- | --------------------------------------- |
+| `label`             | `string \| FormLabelProps`  | Field label                             |
+| `errorMessage`      | `string \| React.ReactNode` | Error message displayed below the field |
+| `data-error-testid` | `string`                    | Test identifier for the error message   |
+
+## Props
+
+| Prop                | Type                          | Default          | Description                                                                                                                                         |
+| ------------------- | ----------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`             | `string`                      | —                | —                                                                                                                                                   |
+| `iconUnmask`        | `JSX.Element`                 | <EyeIcon />      | Icon rendered inside the toggle button while the value is masked                                                                                    |
+| `iconMask`          | `JSX.Element`                 | <EyeSlashIcon /> | Icon rendered inside the toggle button while the value is unmasked                                                                                  |
+| `iconActiveColor`   | `string`                      | —                | CSS color value applied to the mask-toggle icon when it is active                                                                                   |
+| `iconInactiveColor` | `string`                      | —                | CSS color value applied to the mask-toggle icon in its default inactive state.                                                                      |
+| `disableMask`       | `boolean`                     | false            | When `true`, the value is permanently unmasked.                                                                                                     |
+| `transformInput`    | `"uppercase" \| "lowercase"`  | —                | Automatically transforms the typed value before it is stored and passed to `onChange`.                                                              |
+| `loadState`         | `MaskedInputLoadState`        | —                | Retrieval state for the value. Only applies when `readOnly` is `true`.                                                                              |
+| `onMask`            | `(() => void)`                | —                | Called when the value transitions from unmasked to masked.                                                                                          |
+| `onUnmask`          | `(() => void)`                | —                | Called when the value transitions from masked to unmasked.                                                                                          |
+| `onTryAgain`        | `(() => void)`                | —                | Called when the user clicks the "Try again?" button shown in the `loadState="fail"` state. Only relevant when `readOnly` is `true`.                 |
+| `spacing`           | `number`                      | —                | Inserts a space after every `spacing` characters in the displayed value. Only applies when `type` is `"tel"`.                                       |
+| `allowClear`        | `boolean`                     | false            | Shows a clear button when the field has a value and is neither disabled nor read-only.                                                              |
+| `onClear`           | `() => void`                  | —                | Called when the user activates the clear button. Use this to clear the controlled value.                                                            |
+| `styleType`         | `InputStyleType`              | "bordered"       | Visual style variant.                                                                                                                               |
+| `maskRange`         | `number[]`                    | —                | Index range `[start, end]` of the characters to mask (inclusive, zero-based). Characters outside this range remain visible.                         |
+| `unmaskRange`       | `number[]`                    | —                | Index range `[start, end]` of the characters to keep visible (inclusive, zero-based). Characters outside this range are masked.                     |
+| `maskRegex`         | `RegExp`                      | —                | Regular expression whose matches are replaced with `maskChar`.                                                                                      |
+| `maskTransformer`   | `((value: string) => string)` | —                | Custom function that receives the raw value and returns the fully masked string. Takes precedence over `maskRegex`, `maskRange`, and `unmaskRange`. |
+| `maskChar`          | `string`                      | "•"              | Character used to replace each masked character in the displayed value.                                                                             |
+| `label`             | `FormLabelProps \| string`    | —                | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                            |
+| `errorMessage`      | `string \| React.ReactNode`   | —                | Inline error text rendered below the input.                                                                                                         |
+| `layoutType`        | `FormElementLayoutType`       | —                | Controls whether the container uses flex layout or a responsive column grid.                                                                        |
+| `xxlCols`           | `ColSpan`                     | —                | Column span at the `xxl` breakpoint.                                                                                                                |
+| `xlCols`            | `ColSpan`                     | —                | Column span at the `xl` breakpoint.                                                                                                                 |
+| `lgCols`            | `ColSpan`                     | —                | Column span at the `lg` breakpoint.                                                                                                                 |
+| `mdCols`            | `ColSpan`                     | —                | Column span at the `md` breakpoint.                                                                                                                 |
+| `smCols`            | `ColSpan`                     | —                | Column span at the `sm` breakpoint.                                                                                                                 |
+| `xsCols`            | `ColSpan`                     | —                | Column span at the `xs` breakpoint.                                                                                                                 |
+| `xxsCols`           | `ColSpan`                     | —                | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set.    |
+
+## Rules
+
+-   Always supply a `label` so the field is accessible.
+-   Choose one masking strategy per instance: `maskRange`, `unmaskRange`, `maskRegex`, or `maskTransformer`.
+-   Use `maskRange` for fixed-position sensitive segments (e.g. `[1, 4]` for NRIC middle characters).
+-   Use `maskRegex` when the characters to mask follow a pattern rather than a fixed range.
+-   Use `transformInput="uppercase"` for identifiers that are conventionally uppercase (e.g. NRIC, passport).
+-   Use `loadState` only when `readOnly` is also `true` — for fields that are fetched asynchronously.
+-   Provide `onTryAgain` when `loadState="fail"` so users can retry the fetch.
+-   `loadState` only takes effect when `readOnly` is also `true`.
+-   Provide only one of `maskRange`, `unmaskRange`, `maskRegex`, or `maskTransformer` per instance.
+
+## Anti-patterns
+
+-   Do not use for non-sensitive fields — masking adds friction and should be reserved for data that genuinely requires it.
+-   Do not set `loadState` without `readOnly` — it has no effect in editable mode.
+-   Do not combine multiple masking strategies (`maskRange` + `maskRegex`) on the same instance.

package/skills/fds-build/resources/components/form-multi-select.md

@@ -0,0 +1,100 @@
+# Form.MultiSelect
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+Use when users can select more than one option from a predefined list. For single selections use `Form.Select`. For hierarchical options use `Form.NestedMultiSelect`.
+
+## Variants
+
+| `variant`   | When to use                                              |
+| ----------- | -------------------------------------------------------- |
+| `"default"` | Standard form context                                    |
+| `"small"`   | Compact layouts — inline filters, dense data-entry forms |
+
+## Usage
+
+```tsx
+import { Form } from "@lifesg/react-design-system/form";
+
+const options = [
+    { value: "doc", label: "Document" },
+    { value: "img", label: "Image" },
+    { value: "pdf", label: "PDF" },
+];
+
+<Form.MultiSelect
+    label="File types"
+    options={options}
+    selectedOptions={selected}
+    valueExtractor={(opt) => opt.value}
+    listExtractor={(opt) => opt.label}
+    displayValueExtractor={(opt) => opt.label}
+    onSelectOptions={(opts) => {}}
+/>;
+```
+
+## Props
+
+| Prop                       | Type                                                          | Default       | Description                                                                                                                                      |
+| -------------------------- | ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `valueExtractor`           | `((item: T) => V)`                                            | —             | Extracts the comparable value from an option item.                                                                                               |
+| `listExtractor`            | `((item: T) => string \| ListItemDisplayProps)`               | —             | Extracts the display text for a list item.                                                                                                       |
+| `renderListItem`           | `\| ((item: T, args: ListItemRenderArgs) => JSX.Element)`     | —             | Renders a fully custom element for each list item.                                                                                               |
+| `renderCustomCallToAction` | `\| ((hideOptions: () => void, options: T[]) => JSX.Element)` | —             | Renders a custom call-to-action at the bottom of the dropdown list.                                                                              |
+| `readOnly`                 | `boolean`                                                     | —             | —                                                                                                                                                |
+| `selectedOptions`          | `T[]`                                                         | —             | The currently selected options.                                                                                                                  |
+| `onSelectOptions`          | `((options: T[]) => void)`                                    | —             | Called when the selection changes. Receives the updated array of selected options after each user interaction.                                   |
+| `onBlur`                   | `(() => void)`                                                | —             | Called when focus leaves both the trigger and dropdown.                                                                                          |
+| `variant`                  | `DropdownVariantType`                                         | "default"     | Controls the height of the trigger and dropdown items.                                                                                           |
+| `alignment`                | `DropdownAlignmentType`                                       | —             | Aligns the dropdown relative to the trigger element.                                                                                             |
+| `dropdownZIndex`           | `number`                                                      | —             | CSS `z-index` applied to the dropdown overlay.                                                                                                   |
+| `maxSelectable`            | `number`                                                      | —             | Caps the number of options that can be simultaneously selected.                                                                                  |
+| `customLabels`             | `DropdownCustomLabelProps`                                    | —             | Overrides the default labels shown inside the dropdown and on the trigger.                                                                       |
+| `dropdownWidth`            | `string`                                                      | —             | Custom width for the dropdown. When specified, the dropdown uses this width instead of matching the trigger element width.                       |
+| `dropdownRootNode`         | `RefObject<HTMLElement>`                                      | document.body | The root element that contains the dropdown element.                                                                                             |
+| `options` \*               | `T[]`                                                         | —             | The list of selectable options rendered in the dropdown.                                                                                         |
+| `optionsLoadState`         | `ItemsLoadStateType`                                          | "success"     | Indicates the load state of options fetched asynchronously. Renders a loading spinner, error retry, or the list depending on the state.          |
+| `optionTruncationType`     | `TruncateType`                                                | "end"         | Controls how long option labels are truncated when they overflow. Specify `"none"` to display option labels in full.                             |
+| `onShowOptions`            | `(() => void)`                                                | —             | Called when the dropdown list becomes visible.                                                                                                   |
+| `onHideOptions`            | `(() => void)`                                                | —             | Called when the dropdown list is hidden.                                                                                                         |
+| `onRetry`                  | `(() => void)`                                                | —             | Called when the user activates the retry action after a load failure.                                                                            |
+| `name`                     | `string`                                                      | —             | Name attribute forwarded to the underlying button element.                                                                                       |
+| `disabled`                 | `boolean`                                                     | —             | —                                                                                                                                                |
+| `enableSearch`             | `boolean`                                                     | —             | Renders a search bar inside the dropdown when `true`.                                                                                            |
+| `hideNoResultsDisplay`     | `boolean`                                                     | —             | Suppresses the built-in "no results" message when `true`.                                                                                        |
+| `noResultsDescription`     | `React.ReactNode`                                             | —             | —                                                                                                                                                |
+| `searchPlaceholder`        | `string`                                                      | —             | —                                                                                                                                                |
+| `searchFunction`           | `((searchValue: string) => T[])`                              | —             | Custom filter function invoked on each keystroke in the search input.                                                                            |
+| `onSearch`                 | `(() => void)`                                                | —             | Called when the user types in the search input.                                                                                                  |
+| `label`                    | `FormLabelProps \| string`                                    | —             | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                         |
+| `errorMessage`             | `string \| React.ReactNode`                                   | —             | Inline error text rendered below the input.                                                                                                      |
+| `layoutType`               | `FormElementLayoutType`                                       | —             | Controls whether the container uses flex layout or a responsive column grid.                                                                     |
+| `xxlCols`                  | `ColSpan`                                                     | —             | Column span at the `xxl` breakpoint.                                                                                                             |
+| `xlCols`                   | `ColSpan`                                                     | —             | Column span at the `xl` breakpoint.                                                                                                              |
+| `lgCols`                   | `ColSpan`                                                     | —             | Column span at the `lg` breakpoint.                                                                                                              |
+| `mdCols`                   | `ColSpan`                                                     | —             | Column span at the `md` breakpoint.                                                                                                              |
+| `smCols`                   | `ColSpan`                                                     | —             | Column span at the `sm` breakpoint.                                                                                                              |
+| `xsCols`                   | `ColSpan`                                                     | —             | Column span at the `xs` breakpoint.                                                                                                              |
+| `xxsCols`                  | `ColSpan`                                                     | —             | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set. |
+
+## Rules
+
+-   Always provide `options` — the component has no meaning without it.
+-   Provide `valueExtractor` and `listExtractor` for typed option arrays — treat as required.
+-   Always provide `displayValueExtractor` alongside `valueExtractor` when option objects have separate label/value fields. Without it, the component falls back to `valueExtractor`, showing raw values instead of labels in the closed selector.
+-   Use `maxSelectable` when there is a business rule limiting how many options can be chosen; the component enforces it automatically.
+-   Use `enableSearch` when the list exceeds ~10 items.
+-   Provide `customLabels` to localise or contextualise "Select all", "Clear all", and count labels.
+-   Use `optionsLoadState` to communicate async loading states.
+-   Only override `dropdownZIndex` or `dropdownRootNode` when there are confirmed z-index or scroll conflicts.
+-   `onSelectOptions` receives the complete updated selection array — not a delta.
+-   Unlike `Form.Select`, there is no `readOnly` prop — use `disabled` for non-editable states.
+
+## Anti-patterns
+
+-   Do not use `Form.MultiSelect` when only one option can be selected — use `Form.Select`.
+-   Do not use the deprecated `searchPlaceholder` or `noResultsDescription` props directly — use `customLabels`.
+-   Do not set both `error` and `errorMessage`.
+-   Do not manage selection capping manually in `onSelectOptions` — use `maxSelectable` instead.