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

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

@@ -0,0 +1,159 @@
+# Form.NestedMultiSelect
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+Use when users can select multiple options from a hierarchically organised list of up to 3 levels. For hierarchical single-select use `Form.NestedSelect`. For flat multi-select use `Form.MultiSelect`.
+
+## Variants
+
+| `variant`   | When to use           |
+| ----------- | --------------------- |
+| `"default"` | Standard form context |
+| `"small"`   | Compact layouts       |
+
+| `mode`       | When to use                                                                              |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| `"default"`  | System decides initial expand state                                                      |
+| `"expand"`   | Expand all categories on open — for short, browsable lists                               |
+| `"collapse"` | Collapse all categories on open — for long lists where search is the primary interaction |
+
+## Usage
+
+### Multi-select with parallel keyPaths / values arrays
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+import { L1OptionProps } from "@lifesg/react-design-system/input-nested-select";
+
+interface SkillValue {
+    id: string;
+    name: string;
+}
+
+const options: L1OptionProps<SkillValue, SkillValue, SkillValue>[] = [
+    {
+        key: "design",
+        label: "Design",
+        subItems: [
+            {
+                key: "design-ux",
+                label: "UX Design",
+                value: { id: "ux", name: "UX Design" },
+            },
+            {
+                key: "design-ui",
+                label: "UI Design",
+                value: { id: "ui", name: "UI Design" },
+            },
+        ],
+    },
+    {
+        key: "engineering",
+        label: "Engineering",
+        subItems: [
+            {
+                key: "eng-fe",
+                label: "Frontend",
+                value: { id: "fe", name: "Frontend" },
+            },
+            {
+                key: "eng-be",
+                label: "Backend",
+                value: { id: "be", name: "Backend" },
+            },
+        ],
+    },
+];
+
+const NestedMultiSelectExample = () => {
+    // keyPaths[i] and values[i] always refer to the same selection — keep them in sync
+    const [keyPaths, setKeyPaths] = useState<string[][]>([
+        ["design", "design-ux"], // pre-selected: UX Design
+    ]);
+    const [values, setValues] = useState<SkillValue[]>([
+        { id: "ux", name: "UX Design" },
+    ]);
+
+    return (
+        <Form.NestedMultiSelect<SkillValue, SkillValue, SkillValue>
+            label="Skills"
+            options={options}
+            selectedKeyPaths={keyPaths}
+            // onSelectOptions provides the NEXT full selection state — replace, don't merge
+            onSelectOptions={(nextKeyPaths, nextValues) => {
+                setKeyPaths(nextKeyPaths);
+                setValues(nextValues as SkillValue[]);
+            }}
+            valueToStringFunction={(val) => val.name}
+            enableSearch
+        />
+    );
+};
+```
+
+**The parallel-array contract:** index `i` in `keyPaths` and index `i` in `values` always describe the same selected item. `onSelectOptions` delivers the complete next state — replace both arrays together, never splice one independently. Initialise both arrays with matching entries when pre-populating selections.
+
+## Props
+
+| Prop                    | Type                                                                                      | Default       | Description                                                                                                                                                           |
+| ----------------------- | ----------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` \*            | `L1OptionProps<V1, V2, V3>[]`                                                             | —             | —                                                                                                                                                                     |
+| `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`                                                                                 | —             | —                                                                                                                                                                     |
+| `selectedKeyPaths`      | `string[][]`                                                                              | —             | The currently selected options expressed as an array of key paths. Each key path is an ordered array of `key` strings from the root option down to the selected item. |
+| `onSelectOptions`       | `\| (( keyPaths: string[][], values: InputNestedMultiSelectValues<V1, V2, V3> ) => void)` | —             | Called after the selection changes.                                                                                                                                   |
+| `dropdownWidth`         | `string`                                                                                  | —             | Custom width for the dropdown. When specified, the dropdown uses this width instead of matching the trigger element width.                                            |
+| `onBlur`                | `(() => void)`                                                                            | —             | Called when focus leaves both the trigger and dropdown.                                                                                                               |
+| `customLabels`          | `DropdownCustomLabelProps`                                                                | —             | Overrides the default labels shown inside the dropdown and on the trigger.                                                                                            |
+| `readOnly`              | `boolean`                                                                                 | —             | —                                                                                                                                                                     |
+| `mode`                  | `ExpandMode`                                                                              | —             | Specifies if items are expanded or collapsed when the dropdown is opened                                                                                              |
+| `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.                                                                                                                        |
+| `dropdownRootNode`      | `RefObject<HTMLElement>`                                                                  | document.body | The root element that contains the dropdown element.                                                                                                                  |
+| `valueToStringFunction` | `((value: V1 \| V2 \| V3) => string)`                                                     | —             | Function to convert selected value into a string                                                                                                                      |
+| `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
+
+-   Every option node must have a unique `key` string — key paths are used for controlled state.
+-   Provide `valueToStringFunction` when values are not plain strings. The same function is applied to values at all nesting levels — ensure values are homogeneous across levels, or that the function handles all types.
+-   Use `enableSearch` when the total option count across all levels is large.
+-   Use `readOnly` on review screens — not `disabled`.
+-   Provide `customLabels` to localise "Select all", "Clear all", and count labels.
+-   `options` is the only mandatory component-specific prop.
+-   Options follow the same nested structure as `Form.NestedSelect`: `{ key: string, label: string, value: V, subItems?: L2OptionProps[] }`. Every option must have a unique `key`.
+-   `selectedKeyPaths` is an array of key-path arrays — one per selected item.
+-   `onSelectOptions` receives the complete updated `keyPaths` and `values` arrays on every change.
+-   `valueToStringFunction` uses a single callback for all nesting levels — values across levels must be the same type or handled uniformly.
+
+## Anti-patterns
+
+-   Do not use `Form.NestedMultiSelect` for flat option lists — use `Form.MultiSelect`.
+-   Do not use when only one option can be selected — use `Form.NestedSelect`.
+-   Do not use duplicate `key` values across options — selection state will break.
+-   Do not set both `error` and `errorMessage`.
+-   Do not use the deprecated `searchPlaceholder` or `noResultsDescription` props directly — use `customLabels`.

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

@@ -0,0 +1,151 @@
+# Form.NestedSelect
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+Use when options are organised in a hierarchy of up to 3 levels — e.g. industry → sector → role, or country → state → city. For flat single-select use `Form.Select`. For hierarchical multi-select use `Form.NestedMultiSelect`.
+
+## Variants
+
+| `variant`   | When to use           |
+| ----------- | --------------------- |
+| `"default"` | Standard form context |
+| `"small"`   | Compact layouts       |
+
+| `mode`       | When to use                                                                            |
+| ------------ | -------------------------------------------------------------------------------------- |
+| `"default"`  | System decides initial expand state based on selected path                             |
+| `"expand"`   | Expand all categories on open — useful when the list is short and browsing is expected |
+| `"collapse"` | Collapse all categories on open — useful for long lists where search is primary        |
+
+## Usage
+
+### Three-level hierarchy with controlled keyPath
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+import { L1OptionProps } from "@lifesg/react-design-system/input-nested-select";
+
+interface RoleValue {
+    id: string;
+    label: string;
+}
+
+const options: L1OptionProps<RoleValue, RoleValue, RoleValue>[] = [
+    {
+        key: "engineering",
+        label: "Engineering",
+        subItems: [
+            {
+                key: "engineering-frontend",
+                label: "Frontend",
+                subItems: [
+                    {
+                        key: "engineering-frontend-react",
+                        label: "React Developer",
+                        value: { id: "fe-react", label: "React Developer" },
+                    },
+                    {
+                        key: "engineering-frontend-vue",
+                        label: "Vue Developer",
+                        value: { id: "fe-vue", label: "Vue Developer" },
+                    },
+                ],
+            },
+            {
+                key: "engineering-backend",
+                label: "Backend",
+                value: { id: "be", label: "Backend Developer" },
+            },
+        ],
+    },
+];
+
+const NestedSelectExample = () => {
+    // keyPath is the path of keys from root to selected node
+    const [keyPath, setKeyPath] = useState<string[]>([]);
+    const [value, setValue] = useState<RoleValue | undefined>();
+
+    return (
+        <Form.NestedSelect<RoleValue, RoleValue, RoleValue>
+            label="Job role"
+            options={options}
+            selectedKeyPath={keyPath}
+            // onChange receives the full key path and the node's value
+            onChange={(path, val) => {
+                setKeyPath(path);
+                setValue(val);
+            }}
+            valueToStringFunction={(val) => val.label}
+            selectableCategory // intermediate nodes (e.g. "Backend") are also selectable
+            enableSearch
+        />
+    );
+};
+```
+
+**keyPath explains the selection:** `["engineering", "engineering-frontend", "engineering-frontend-react"]` means the user drilled through Engineering → Frontend → React Developer. An empty array means nothing is selected.
+
+## Props
+
+| Prop                    | Type                                                      | Default       | Description                                                                                                                                                                                         |
+| ----------------------- | --------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` \*            | `L1OptionProps<V1, V2, V3>[]`                             | —             | —                                                                                                                                                                                                   |
+| `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`                                                 | —             | —                                                                                                                                                                                                   |
+| `selectedKeyPath`       | `string[]`                                                | —             | Key path identifying the currently selected option. Each entry is the `key` of the option at that nesting level, ordered from level 1 to the selected level. Drives the controlled selection state. |
+| `selectableCategory`    | `boolean`                                                 | —             | When `true`, parent category labels are themselves selectable as options, not just expand/collapse toggles.                                                                                         |
+| `onSelectOption`        | `\| ((keyPath: string[], value: V1 \| V2 \| V3) => void)` | —             | Called when the user selects an option.                                                                                                                                                             |
+| `dropdownWidth`         | `string`                                                  | —             | Custom width for the dropdown. When specified, the dropdown uses this width instead of matching the trigger element width.                                                                          |
+| `onBlur`                | `(() => void)`                                            | —             | Called when focus leaves both the trigger and the dropdown.                                                                                                                                         |
+| `customLabels`          | `DropdownCustomLabelProps`                                | —             | Overrides the default labels shown inside the dropdown and on the trigger.                                                                                                                          |
+| `readOnly`              | `boolean`                                                 | —             | —                                                                                                                                                                                                   |
+| `mode`                  | `ExpandMode`                                              | —             | Specifies if items are expanded or collapsed when the dropdown is opened                                                                                                                            |
+| `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.                                                                                                                                                      |
+| `dropdownRootNode`      | `RefObject<HTMLElement>`                                  | document.body | The root element that contains the dropdown element.                                                                                                                                                |
+| `valueToStringFunction` | `((value: V1 \| V2 \| V3) => string)`                     | —             | Function to convert selected value into a string                                                                                                                                                    |
+| `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
+
+-   Every option node must have a unique `key` string — the key path is used for controlled state.
+-   Provide `valueToStringFunction` when values are not plain strings and the selected display needs to be derived from the value.
+-   Enable `selectableCategory` only when selecting a parent category is a valid business outcome — otherwise category nodes serve as navigational groupings only.
+-   Use `enableSearch` when the total option count across all levels is large.
+-   Use `readOnly` on review screens — not `disabled`.
+-   Provide `customLabels.searchPlaceholder` instead of the deprecated `searchPlaceholder` prop.
+-   `options` is the only mandatory component-specific prop.
+-   Options follow a nested structure: `{ key: string, label: string, value: V, subItems?: L2OptionProps[] }`. Every option must have a unique `key`.
+-   `selectedKeyPath` is an array of keys tracing the path to the selected leaf (e.g. `["parent-key", "child-key"]`).
+-   `selectableCategory` enables selection of non-leaf (parent category) nodes.
+
+## Anti-patterns
+
+-   Do not use `Form.NestedSelect` for flat option lists — use `Form.Select`.
+-   Do not use when multiple selections are needed — use `Form.NestedMultiSelect`.
+-   Do not use duplicate `key` values across options — selection state will break.
+-   Do not set both `error` and `errorMessage`.

package/skills/fds-build/resources/components/form-otp-verification.md

@@ -0,0 +1,175 @@
+# Form.OtpVerification
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Flows that require identity verification via a one-time password sent to a phone number or email address.
+-   The component manages the full multi-step UI: input contact → send OTP → enter OTP → verify.
+
+## Usage
+
+### Email variant
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+import { OtpVerificationState } from "@lifesg/react-design-system/otp-verification";
+
+const EmailOtpExample = () => {
+    const [otpState, setOtpState] = useState<OtpVerificationState>("default");
+    const [email, setEmail] = useState("");
+
+    return (
+        <Form.OtpVerification
+            label="Verify your email"
+            type="email"
+            emailValue={email}
+            onEmailChange={setEmail}
+            otpState={otpState}
+            onOtpStateChange={setOtpState}
+            onSendOtp={async () => {
+                // Throw to surface the error inline — do NOT return an error string
+                const res = await api.sendEmailOtp(email);
+                if (!res.ok) throw new Error("Invalid email address");
+            }}
+            onVerifyOtp={async (otpInput) => {
+                const res = await api.verifyOtp(otpInput);
+                if (!res.ok)
+                    throw new Error("Incorrect OTP. Please try again.");
+            }}
+            onResendOtp={async () => {
+                const res = await api.sendEmailOtp(email);
+                if (!res.ok) throw new Error("Could not resend OTP");
+            }}
+            verifyOtpCountdownTimer={300}
+        />
+    );
+};
+```
+
+### Phone variant (`fixedCountry` required)
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+import { OtpVerificationState } from "@lifesg/react-design-system/otp-verification";
+import { PhoneNumberInputValue } from "@lifesg/react-design-system/phone-number-input";
+
+const PhoneOtpExample = () => {
+    const [otpState, setOtpState] = useState<OtpVerificationState>("default");
+    const [phone, setPhone] = useState<PhoneNumberInputValue>({ number: "" });
+
+    return (
+        <Form.OtpVerification
+            label="Verify your mobile number"
+            type="phone-number"
+            phoneNumberValue={phone}
+            onPhoneNumberChange={setPhone}
+            fixedCountry // required when type="phone-number"; hides country selector
+            otpState={otpState}
+            onOtpStateChange={setOtpState}
+            onSendOtp={async () => {
+                const res = await api.sendSmsOtp(phone.number);
+                if (!res.ok) throw new Error("Invalid phone number");
+            }}
+            onVerifyOtp={async (otpInput) => {
+                const res = await api.verifyOtp(otpInput);
+                if (!res.ok)
+                    throw new Error("Incorrect OTP. Please try again.");
+            }}
+            onResendOtp={async () => {
+                const res = await api.sendSmsOtp(phone.number);
+                if (!res.ok) throw new Error("Could not resend OTP");
+            }}
+            verifyOtpCountdownTimer={180}
+        />
+    );
+};
+```
+
+**Key gotcha — callbacks must throw, not return error strings.**
+The component catches the thrown error and displays `error.message` inline.
+Returning a value (or nothing) always signals success and advances the state machine.
+
+## Phone-number-specific props
+
+| Prop                  | Type                                     | Description                                            |
+| --------------------- | ---------------------------------------- | ------------------------------------------------------ |
+| `phoneNumberValue`    | `PhoneNumberInputValue`                  | Controlled phone number value                          |
+| `onPhoneNumberChange` | `(value: PhoneNumberInputValue) => void` | Called when phone input changes                        |
+| `fixedCountry`        | `true`                                   | Locks the country code; required for phone-number type |
+
+## Email-specific props
+
+| Prop            | Type                      | Description                     |
+| --------------- | ------------------------- | ------------------------------- |
+| `emailValue`    | `string`                  | Controlled email value          |
+| `onEmailChange` | `(value: string) => void` | Called when email input changes |
+
+## PhoneNumberInputValue
+
+| Prop          | Type     | Description                 |
+| ------------- | -------- | --------------------------- |
+| `number`      | `string` | Phone number                |
+| `countryCode` | `string` | Country code (e.g. `"+65"`) |
+
+## Form-specific props
+
+| Prop    | Type                       | Description |
+| ------- | -------------------------- | ----------- |
+| `label` | `string \| FormLabelProps` | Field label |
+
+## Props
+
+| Prop                      | Type                                                                                                                                                                                                                                      | Default | Description                                                                                                                                      |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                      | `string`                                                                                                                                                                                                                                  | —       | —                                                                                                                                                |
+| `disabled`                | `boolean`                                                                                                                                                                                                                                 | —       | —                                                                                                                                                |
+| `readOnly`                | `boolean`                                                                                                                                                                                                                                 | —       | —                                                                                                                                                |
+| `className`               | `string`                                                                                                                                                                                                                                  | —       | —                                                                                                                                                |
+| `inputId`                 | `string`                                                                                                                                                                                                                                  | —       | The `id` attribute applied to the contact input field.                                                                                           |
+| `otpState` \*             | `OtpVerificationState`                                                                                                                                                                                                                    | —       | The current step in the OTP verification flow. Controls which sections are rendered.                                                             |
+| `onOtpStateChange` \*     | `(state: OtpVerificationState) => void`                                                                                                                                                                                                   | —       | Called when the component transition to a new `otpState`.                                                                                        |
+| `onSendOtp`               | `(() => Promise<void>)`                                                                                                                                                                                                                   | —       | Called when the user initiates sending the OTP. On resolution, the component transitions to `"sent"`.                                            |
+| `sendOtpError`            | `string`                                                                                                                                                                                                                                  | —       | Error message displayed below the contact input after a failed attempt.                                                                          |
+| `sendOtpPlaceholder`      | `string`                                                                                                                                                                                                                                  | —       | Placeholder text for the contact input field.                                                                                                    |
+| `otpReminderInterval`     | `number`                                                                                                                                                                                                                                  | 120     | Interval in seconds at which an accessibility announcement is made, reminding the user how many seconds remain before they can resend the OTP.   |
+| `type` \*                 | `"email"`                                                                                                                                                                                                                                 | —       | Discriminant that sets the contact input to email mode.                                                                                          |
+| `otpValue`                | `\| { /** * Static text displayed before the OTP input. */ prefix?: string; /** * Character displayed between the `prefix` and OTP input.. */ separator?: string; /** * The current OTP string entered by the user. */ value?: string; }` | —       | Controlled state of the OTP input field.                                                                                                         |
+| `onOtpChange`             | `((value: string) => void)`                                                                                                                                                                                                               | —       | Called when the OTP input value changes.                                                                                                         |
+| `onVerifyOtp`             | `((input: string) => Promise<void>)`                                                                                                                                                                                                      | —       | Called when the user submits the OTP for verification. On resolution the component transitions to `"verified"`.                                  |
+| `verifyOtpCountdownTimer` | `number`                                                                                                                                                                                                                                  | 60      | Duration in seconds of the resend cooldown after an OTP is sent.                                                                                 |
+| `onResendOtp`             | `(() => Promise<void>)`                                                                                                                                                                                                                   | —       | Called when the user requests to resend the OTP from the verification step.                                                                      |
+| `showVerifyOtpThumbnail`  | `boolean`                                                                                                                                                                                                                                 | —       | Whether to display the thumbnail image in the OTP verification section, visible in the `"sent"` state.                                           |
+| `verifyOtpIcon`           | `React.ReactNode`                                                                                                                                                                                                                         | —       | Custom icon in the OTP verification section, visible in the `"sent"` state.                                                                      |
+| `verifyOtpTitle`          | `string`                                                                                                                                                                                                                                  | —       | Custom heading in the OTP verification section, visible in the `"sent"` state.                                                                   |
+| `verifyOtpMessage`        | `string`                                                                                                                                                                                                                                  | —       | Custom body text in the OTP verification section, visible in the `"sent"` state.                                                                 |
+| `verifyOtpError`          | `string`                                                                                                                                                                                                                                  | —       | Error message displayed below the OTP input after a failed verification attempt.                                                                 |
+| `label`                   | `FormLabelProps \| string`                                                                                                                                                                                                                | —       | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                         |
+| `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.
+-   Control `otpState` externally and update it via `onOtpStateChange` — the component does not manage its own state.
+-   `onSendOtp`, `onVerifyOtp`, and `onResendOtp` must be async functions; throw an error inside them to trigger the corresponding error display (`sendOtpError`, `verifyOtpError`).
+-   Always pass `fixedCountry` when `type="phone-number"` — the prop is required to lock the country selector.
+-   Set `verifyOtpCountdownTimer` to match the actual OTP expiry window from your backend.
+-   Pass `sendOtpError` and `verifyOtpError` from server responses so users receive actionable feedback.
+-   `otpState` is externally controlled — the component does not manage its own flow state.
+-   `fixedCountry` is required when `type="phone-number"`.
+
+## Anti-patterns
+
+-   Do not try to manage the step sequence manually — use `otpState` and let `onOtpStateChange` drive transitions.
+-   Do not use for non-identity-verification scenarios — for simple code inputs, use a plain `Form.Input`.
+-   Do not omit `fixedCountry` for `type="phone-number"` — the country selector will be shown unexpectedly.
+-   Do not use synchronous functions for `onSendOtp`, `onVerifyOtp`, or `onResendOtp` — they must return Promises.

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

@@ -0,0 +1,87 @@
+# Form.PhoneNumberInput
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+Type import: `import type { PhoneNumberInputValue } from "@lifesg/react-design-system/phone-number-input"`
+
+## When to use
+
+-   Collecting a phone number that requires a country code prefix.
+-   International forms where users may have numbers from different countries.
+-   Use `fixedCountry` when the service only accepts numbers from one country (e.g. Singapore-only services).
+
+## Usage
+
+```tsx
+import styles from "./MyForm.module.css";
+
+<Form.PhoneNumberInput className={styles.phoneNumberInput} ... />
+```
+
+```css
+/* MyForm.module.css */
+:where(body.fds-breakpoint-lg-min) .phoneNumberInput {
+    max-width: 24rem;
+}
+```
+
+Defaults to 4 columns wide at `lg` and above; full-width on mobile. Use `max-width` via a CSS Module class.
+
+## PhoneNumberInputValue
+
+| Prop          | Type     | Description                                                                                                             |
+| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `number`      | `string` | The phone number                                                                                                        |
+| `countryCode` | `string` | The country code (e.g. `"+65"`). The `+` prefix is optional on input but always included in the `onChange` return value |
+
+## Props
+
+| Prop                      | Type                                       | Default  | Description                                                                                                                                      |
+| ------------------------- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`                   | `PhoneNumberInputValue`                    | —        | Controlled value containing the selected country code and phone number.                                                                          |
+| `error`                   | `boolean`                                  | —        | Renders the input in an error state when `true`.                                                                                                 |
+| `allowClear`              | `boolean`                                  | —        | Shows a clear button inside the input when `true` and the field has a value.                                                                     |
+| `className`               | `string`                                   | —        | —                                                                                                                                                |
+| `noBorder`                | `boolean`                                  | false    | Removes the visible border from the input group when `true`.                                                                                     |
+| `fixedCountry`            | `boolean`                                  | false    | When `true`, the country code is displayed as a static label and the user cannot change it. When `false`, a searchable dropdown is rendered.     |
+| `onChange`                | `((value: PhoneNumberInputValue) => void)` | —        | Called whenever the country or phone number changes.                                                                                             |
+| `onClear`                 | `() => void`                               | —        | Called when the clear button is activated.                                                                                                       |
+| `onBlur`                  | `(() => void)`                             | —        | Called when the input loses focus.                                                                                                               |
+| `optionPlaceholder`       | `string`                                   | "Select" | Placeholder text shown in the country code dropdown when no country is selected.                                                                 |
+| `optionSearchPlaceholder` | `string`                                   | —        | Placeholder text shown inside the search field of the country code dropdown. Only relevant when `enableSearch` is `true`.                        |
+| `enableSearch`            | `boolean`                                  | —        | Enables a search field inside the country code dropdown.                                                                                         |
+| `onHideOptions`           | `(() => void)`                             | —        | Called when the country code dropdown closes.                                                                                                    |
+| `onShowOptions`           | `(() => void)`                             | —        | Called when the country code dropdown opens.                                                                                                     |
+| `disabled`                | `boolean`                                  | —        | —                                                                                                                                                |
+| `name`                    | `string`                                   | —        | —                                                                                                                                                |
+| `pattern`                 | `string`                                   | —        | —                                                                                                                                                |
+| `placeholder`             | `string`                                   | —        | —                                                                                                                                                |
+| `readOnly`                | `boolean`                                  | —        | —                                                                                                                                                |
+| `id`                      | `string`                                   | —        | —                                                                                                                                                |
+| `autoComplete`            | `string`                                   | —        | —                                                                                                                                                |
+| `getAriaLabel`            | `((country?: CountryValue) => string)`     | —        | Returns the accessible label for the phone number 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 supply a `label` so the field is accessible.
+-   Pass `value` and `onChange` together for controlled usage; `onChange` returns `{ countryCode, number }`.
+-   Use `enableSearch` when the country list is long and users need to find their country quickly.
+-   Use `fixedCountry` together with a pre-set `value.countryCode` so the locked code is visible.
+-   Use `allowClear` when the field can be optionally cleared by the user.
+-   Set `errorMessage` rather than `error` alone so users understand what is wrong.
+
+## Anti-patterns
+
+-   Do not use a plain text input for international phone numbers — formatting and country code handling must be consistent.
+-   Do not use without `fixedCountry` when only one country is supported — it creates unnecessary friction.
+-   Do not omit `value.countryCode` when `fixedCountry` is true — the locked code won't render without it.