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

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

@@ -0,0 +1,108 @@
+# Form.PredictiveTextInput
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   The option set is too large for a static dropdown and must be fetched dynamically (e.g. address lookup, postal code search, product search, large dataset autocomplete).
+-   Users need to type to narrow down results before selecting.
+
+## Usage
+
+### Location search — three extractors working together
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+
+interface Location {
+    id: string;
+    name: string;
+    address: string;
+}
+
+const LocationSearchExample = () => {
+    const [selected, setSelected] = useState<Location | undefined>();
+
+    const fetchOptions = async (input: string): Promise<Location[]> => {
+        const res = await api.searchLocations(input);
+        return res.results;
+    };
+
+    return (
+        <Form.PredictiveTextInput<Location, string>
+            label="Search location"
+            minimumCharacters={3} // fetch only after 3 chars typed
+            fetchOptions={fetchOptions}
+            // Populates the text field when an option is selected
+            valueExtractor={(item) => item.name}
+            // Populates each row in the dropdown list
+            listExtractor={(item) => `${item.name} — ${item.address}`}
+            // Displays the chosen value as a chip / confirmation label
+            displayValueExtractor={(item) => item.name}
+            selectedOption={selected}
+            onSelectOption={(item) => setSelected(item ?? undefined)}
+        />
+    );
+};
+```
+
+**How the three extractors divide responsibility:**
+
+| Extractor               | When it runs               | What it renders                  |
+| ----------------------- | -------------------------- | -------------------------------- |
+| `listExtractor`         | While the dropdown is open | Each option row in the list      |
+| `valueExtractor`        | After selection            | The text field value             |
+| `displayValueExtractor` | After selection            | The chip / confirmed-value label |
+
+Debounce `fetchOptions` internally (e.g. with `setTimeout` or a library) — the component calls it on every character change.
+
+## Props
+
+| Prop                    | Type                                            | Default         | Description                                                                                                                                                 |
+| ----------------------- | ----------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                    | `string`                                        | —               | —                                                                                                                                                           |
+| `className`             | `string`                                        | —               | —                                                                                                                                                           |
+| `minimumCharacters`     | `number`                                        | 3               | Minimum number of characters the user must type before `fetchOptions` is called and the dropdown opens.                                                     |
+| `placeholder`           | `string`                                        | "Enter here..." | Placeholder text shown inside the input when it is empty.                                                                                                   |
+| `readOnly`              | `boolean`                                       | —               | —                                                                                                                                                           |
+| `disabled`              | `boolean`                                       | —               | —                                                                                                                                                           |
+| `error`                 | `boolean`                                       | —               | Applies error styling to the input wrapper.                                                                                                                 |
+| `selectedOption`        | `T`                                             | —               | The currently confirmed option. Updating this prop resets the displayed text and clears the dropdown options list. Pass `undefined` to clear the selection. |
+| `alignment`             | `DropdownAlignmentType`                         | —               | Horizontal alignment of the dropdown relative to the input element.                                                                                         |
+| `dropdownZIndex`        | `number`                                        | —               | CSS `z-index` applied to the dropdown overlay.                                                                                                              |
+| `dropdownRootNode`      | `RefObject<HTMLElement>`                        | document.body   | The root element that contains the dropdown element.                                                                                                        |
+| `dropdownWidth`         | `string`                                        | —               | Custom width for the dropdown. When specified, the dropdown uses this width instead of matching the trigger element width.                                  |
+| `fetchOptions` \*       | `(input: string) => Promise<T[]>`               | —               | Async function called with the current input string to retrieve matching options. A rejected promise triggers the error state in the dropdown.              |
+| `valueExtractor`        | `((item: T) => V)`                              | —               | Derives the submitted value `V` from a selected item `T`.                                                                                                   |
+| `listExtractor`         | `((item: T) => string \| ListItemDisplayProps)` | —               | Derives the display label for each option in the dropdown list.                                                                                             |
+| `displayValueExtractor` | `((option: T) => string)`                       | —               | Derives the text shown in the input field after an option is selected.                                                                                      |
+| `onSelectOption`        | `\| ((option: T, extractedValue: V) => void)`   | —               | Called when the user selects an option from the dropdown or clears the field.                                                                               |
+| `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.
+-   `fetchOptions` is required — it must be async and return an array of option objects.
+-   Debounce inside `fetchOptions` to avoid flooding the API on every keystroke.
+-   Set `minimumCharacters` to a value that produces useful results — `3` is the default, but adjust for your data source.
+-   Always provide `valueExtractor`, `listExtractor`, and `displayValueExtractor` — omitting any of these produces inconsistent display behaviour.
+-   Use `selectedOption` and `onSelectOption` for controlled selection.
+-   Set `errorMessage` when the selected option fails validation.
+-   `fetchOptions` is called on every keystroke after `minimumCharacters` is reached — debounce inside the function if needed.
+-   Generic type `T` is the option object shape; `V` is the extracted value type.
+
+## Anti-patterns
+
+-   Do not use when the full option list is small and known upfront — use `Form.Select` or `Form.MultiSelect` instead.
+-   Do not use `fetchOptions` without debouncing — each keystroke fires a new call.
+-   Do not omit extractor functions — the component cannot determine what to display without them.

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

@@ -0,0 +1,103 @@
+# Form.Select
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+Use when users must select exactly one option from a predefined list. For multiple selections use `Form.MultiSelect`. For hierarchical options use `Form.NestedSelect`.
+
+## 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: "sg", label: "Singapore" },
+    { value: "my", label: "Malaysia" },
+];
+
+<Form.Select
+    label="Country"
+    options={options}
+    selectedOption={selected}
+    valueExtractor={(opt) => opt.value}
+    listExtractor={(opt) => opt.label}
+    displayValueExtractor={(opt) => opt.label}
+    onSelectOption={(opt) => {}}
+/>;
+```
+
+## Props
+
+| Prop                         | Type                                                          | Default       | Description                                                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `readOnly`                   | `boolean`                                                     | —             | —                                                                                                                                                |
+| `selectedOption`             | `T`                                                           | —             | The currently selected option. The component syncs to this value on each render.                                                                 |
+| `onSelectOption`             | `((option: T, extractedValue: V) => void)`                    | —             | Called when the user picks an item from the dropdown.                                                                                            |
+| `displayValueExtractor`      | `((option: T) => string)`                                     | —             | Derives the display string shown in the trigger for the selected option. Takes precedence over `valueExtractor` + `valueToStringFunction`.       |
+| `valueToStringFunction`      | `((value: V) => string)`                                      | —             | Function to convert selected value into a display string                                                                                         |
+| `renderCustomSelectedOption` | `((option: T) => JSX.Element)`                                | —             | Renders a custom element for the currently selected option.                                                                                      |
+| `onBlur`                     | `(() => void)`                                                | —             | Called when focus leaves both the trigger and dropdown.                                                                                          |
+| `variant`                    | `DropdownVariantType`                                         | "default"     | Visual size variant of the trigger and dropdown.                                                                                                 |
+| `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.                                                                                             |
+| `dropdownWidth`              | `string`                                                      | —             | Custom width for the dropdown. When specified, the dropdown uses this width instead of matching the trigger element width.                       |
+| `customLabels`               | `DropdownCustomLabelProps`                                    | —             | Overrides the default labels shown inside the dropdown and on the trigger.                                                                       |
+| `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`                                                     | —             | —                                                                                                                                                |
+| `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.                                                                                                       |
+| `isOptionDisabled`           | `((item: T) => boolean)`                                      | —             | Returns `true` if the given option should be shown but not selectable.                                                                           |
+| `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.                                                                              |
+| `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` when the option objects are not plain strings — these are effectively required for typed option arrays.
+-   Always provide `displayValueExtractor` alongside `valueExtractor` when option objects have separate label/value fields. Without it, the component falls back to `valueExtractor`, showing the raw value (e.g. "sg") in the closed selector instead of the label (e.g. "Singapore").
+-   Use `optionsLoadState` to communicate async loading states — set to `"loading"` while fetching, `"failed"` on error (triggers retry UI).
+-   Use `enableSearch` when the list exceeds ~10 items.
+-   Provide `customLabels.searchPlaceholder` instead of the deprecated `searchPlaceholder` prop.
+-   Use `readOnly` on review screens — not `disabled`.
+-   Only override `dropdownZIndex` or `dropdownRootNode` when there are confirmed z-index or scroll conflicts.
+-   Use `dropdownWidth` when the dropdown must be wider than the trigger (e.g. long option text).
+-   `options` is the only mandatory component-specific prop.
+-   Only specify `dropdownRootNode` when the default `body` rendering causes scroll or z-index conflicts.
+
+## Anti-patterns
+
+-   Do not use `Form.Select` when users can choose more than one option — use `Form.MultiSelect`.
+-   Do not use the deprecated `searchPlaceholder` or `noResultsDescription` props directly — use `customLabels`.
+-   Do not set both `error` and `errorMessage`.
+-   Do not use `disabled` on review screens — use `readOnly`.

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

@@ -0,0 +1,116 @@
+# Form.Slider
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Selecting a single numeric value within a bounded range (e.g. budget, age, percentage, rating).
+-   When the relative position of a value matters more than typing an exact number.
+
+## Usage
+
+### Basic slider with display-only `onChange` and API-safe `onChangeEnd`
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+
+const BudgetSlider = () => {
+    const [displayValue, setDisplayValue] = useState(500);
+
+    const handleChange = (value: number) => {
+        // Safe: fires continuously during drag — update display only
+        setDisplayValue(value);
+    };
+
+    const handleChangeEnd = (value: number) => {
+        // Safe: fires once on mouse/touch release — trigger API calls here
+        fetchResults({ maxBudget: value });
+    };
+
+    return (
+        <Form.Slider
+            label={`Budget: $${displayValue}`}
+            min={0}
+            max={2000}
+            step={100}
+            value={displayValue}
+            onChange={handleChange}
+            onChangeEnd={handleChangeEnd}
+            showSliderLabels
+            sliderLabelPrefix="$"
+            showIndicatorLabel
+            indicatorLabelPrefix="$"
+        />
+    );
+};
+```
+
+**Never put API calls or expensive state updates in `onChange`** — it fires on every pixel of drag movement. Use `onChangeEnd` instead.
+
+### Custom track colours
+
+`colors` takes a two-element array: `[leftTrackColor, rightTrackColor]`.
+
+```tsx
+<Form.Slider
+    label="Risk level"
+    min={0}
+    max={10}
+    colors={["#4caf50", "#e0e0e0"]}
+    showSliderLabels
+    sliderLabelSuffix=" / 10"
+/>
+```
+
+## Props
+
+| Prop                   | Type                                   | Default | Description                                                                                                                                      |
+| ---------------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`                | `number`                               | 0       | The controlled value of the thumb.                                                                                                               |
+| `ariaLabel`            | `string`                               | —       | Accessible label for the thumb.                                                                                                                  |
+| `onChange`             | `((value: number) => void)`            | —       | Called on every selection change.                                                                                                                |
+| `onChangeEnd`          | `((value: number) => void)`            | —       | Called when a thumb is released after selection is complete.                                                                                     |
+| `className`            | `string`                               | —       | —                                                                                                                                                |
+| `id`                   | `string`                               | —       | —                                                                                                                                                |
+| `min`                  | `number`                               | 0       | The lower bound of the slider range.                                                                                                             |
+| `max`                  | `number`                               | 100     | The upper bound of the slider range.                                                                                                             |
+| `step`                 | `number`                               | 1       | The interval between selectable values.                                                                                                          |
+| `disabled`             | `boolean`                              | —       | —                                                                                                                                                |
+| `readOnly`             | `boolean`                              | —       | —                                                                                                                                                |
+| `colors`               | `(string)[]`                           | —       | Colours applied to each track segment in order. The array length should equal to `numOfThumbs + 1`.                                              |
+| `showSliderLabels`     | `boolean`                              | —       | Renders label text at the minimum and maximum ends of the track.                                                                                 |
+| `sliderLabelPrefix`    | `string`                               | —       | Text prepended to each slider label value. Ignored when `renderSliderLabel` is provided.                                                         |
+| `sliderLabelSuffix`    | `string`                               | —       | Text appended to each slider label value. Ignored when `renderSliderLabel` is provided.                                                          |
+| `showIndicatorLabel`   | `boolean`                              | —       | Renders a label above the slider showing the current selection.                                                                                  |
+| `indicatorLabelPrefix` | `string`                               | —       | Text prepended to the indicator label value.                                                                                                     |
+| `indicatorLabelSuffix` | `string`                               | —       | Text appended to the indicator label value.                                                                                                      |
+| `renderSliderLabel`    | `((value: number) => React.ReactNode)` | —       | Custom renderer for the slider labels shown at the min and max track ends. Takes precedence over `sliderLabelPrefix` and `sliderLabelSuffix`.    |
+| `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.
+-   Always set `min` and `max` to meaningful bounds for the use case.
+-   Use `step` to restrict values to meaningful increments (e.g. `step={500}` for a budget slider).
+-   Use `onChangeEnd` for expensive operations (API calls, heavy computations) — `onChange` fires on every pixel of movement.
+-   Enable `showSliderLabels` so users know the range bounds.
+-   Enable `showIndicatorLabel` so users can see the current value while dragging.
+-   Provide `ariaLabel` when the label alone does not fully describe the slider's purpose to screen readers.
+-   `onChange` fires continuously during drag; use `onChangeEnd` for expensive operations such as API calls.
+-   `colors` array format is `[leftTrack, rightTrack]`.
+
+## Anti-patterns
+
+-   Do not use `onChange` to trigger API calls — use `onChangeEnd` to avoid flooding the network.
+-   Do not use when the user needs to enter a precise value — prefer a number input in that case.
+-   Do not omit `min` and `max` — the defaults (0–100) may not be appropriate for the domain.

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

@@ -0,0 +1,116 @@
+# Form.Textarea
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+Use for freeform long-text entry — descriptions, comments, reasons, or any field where users need more than one line. Use `Form.Input` for single-line text.
+
+## Usage
+
+### 1. Basic controlled textarea
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+
+const [value, setValue] = useState("");
+
+<Form.Textarea
+    label="Description"
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+    placeholder="Enter a description..."
+    rows={4}
+/>;
+```
+
+### 2. With `maxLength` — auto-renders a character counter
+
+```tsx
+<Form.Textarea
+    label="Comments"
+    maxLength={200}
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+/>;
+{
+    /* A counter "0 / 200" appears below automatically — no extra code needed */
+}
+```
+
+### 3. With `renderCustomCounter`
+
+The prop signature is `(maxLength: number, currentValueLength: number) => JSX.Element`. Note the argument order: `maxLength` first, then `currentValueLength`.
+
+```tsx
+<Form.Textarea
+    label="Comments"
+    maxLength={200}
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+    renderCustomCounter={(maxLength, currentValueLength) => (
+        <span
+            style={{
+                color: currentValueLength > maxLength * 0.9 ? "red" : "inherit",
+            }}
+        >
+            {currentValueLength} of {maxLength} characters used
+        </span>
+    )}
+/>
+```
+
+### 4. With `transformValue`
+
+`transformValue` runs on every input event and replaces the raw value before it is applied. Do not duplicate this logic in `onChange`.
+
+```tsx
+<Form.Textarea
+    label="Reference code"
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+    transformValue={(raw) => raw.toUpperCase()}
+    maxLength={50}
+/>;
+{
+    /* User types "abc" → stored value becomes "ABC" */
+}
+```
+
+## Props
+
+| Prop                  | Type                                                                  | Default | Description                                                                                                                                      |
+| --------------------- | --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `errorMessage`        | `string \| React.ReactNode`                                           | —       | Inline error text rendered below the textarea. Also sets the input into an error state.                                                          |
+| `transformValue`      | `((value: string) => string)`                                         | —       | Transforms user input on every change event.                                                                                                     |
+| `prefix`              | `string`                                                              | —       | A read-only string permanently displayed at the start of the textarea.                                                                           |
+| `renderCustomCounter` | `\| ((maxLength: number, currentValueLength: number) => JSX.Element)` | —       | Replaces the built-in character counter displayed below the textarea. Called only when `maxLength` is provided.                                  |
+| `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
+
+-   Set `rows` to match the expected content length — a short reason field needs fewer rows than a free-text description.
+-   Set `resize="none"` when the textarea height is fixed by design to prevent layout disruption.
+-   Provide `maxLength` when a character limit must be enforced — the built-in counter appears automatically.
+-   Use `renderCustomCounter` only when the default counter format does not meet content requirements.
+-   Use `transformValue` for on-the-fly normalisation (e.g. forced capitalisation) — do not replicate this in `onChange`.
+-   Provide `errorMessage` rather than `error` alone.
+-   Setting native `maxLength` renders a character counter below the textarea automatically.
+-   `renderCustomCounter` overrides the default counter UI when `maxLength` is set.
+-   `error` is redundant when `errorMessage` is provided.
+-   `transformValue` runs on every input event — use for normalisation (e.g. uppercase conversion).
+
+## Anti-patterns
+
+-   Do not use `Form.Textarea` for single-line inputs — use `Form.Input`.
+-   Do not implement a manual character counter in consumer code when `maxLength` is set — the built-in counter handles it.
+-   Do not set both `error` and `errorMessage`.

package/skills/fds-build/resources/components/form-time-range-picker.md

@@ -0,0 +1,98 @@
+# Form.TimeRangePicker
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Collecting a start and end time from the user (e.g. operating hours, meeting slot, booking window).
+-   Use `variant="combobox"` with `interval` when users should pick from fixed time slots (e.g. every 30 minutes).
+-   Use `variant="dial"` (default) for freeform time selection.
+
+## Usage
+
+```tsx
+import styles from "./MyForm.module.css";
+
+<Form.TimeRangePicker className={styles.timeRangePicker} ... />
+```
+
+```css
+/* MyForm.module.css */
+:where(body.fds-breakpoint-lg-min) .timeRangePicker {
+    max-width: 24rem;
+}
+```
+
+Defaults to 4 columns wide at `lg` and above; full-width on mobile. Use `max-width` via a CSS Module class.
+
+## Combobox-variant-specific props
+
+| Prop                     | Type     | Default | Description                                                  |
+| ------------------------ | -------- | ------- | ------------------------------------------------------------ |
+| `interval`               | `number` | `15`    | Minutes between each dropdown option                         |
+| `startLimit`             | `string` | —       | Earliest time shown in the dropdown                          |
+| `endLimit`               | `string` | —       | Latest time shown in the dropdown                            |
+| `initialScrollStartTime` | `string` | —       | Time the start dropdown scrolls to when start field is empty |
+| `initialScrollEndTime`   | `string` | —       | Time the end dropdown scrolls to when end field is empty     |
+
+## TimeRangePickerValue
+
+| Prop    | Type     | Description                                                                                                 |
+| ------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `start` | `string` | Start time. Dial 24hr: `"HH:mm"`, dial 12hr: `"hh:mmA"`. Combobox 24hr: `"HH:mm"`, combobox 12hr: `"h:mma"` |
+| `end`   | `string` | End time, same format as `start`                                                                            |
+
+## Props
+
+| Prop                     | Type                                      | Default       | Description                                                                                                                                      |
+| ------------------------ | ----------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `className`              | `string`                                  | —             | —                                                                                                                                                |
+| `id`                     | `string`                                  | —             | —                                                                                                                                                |
+| `style`                  | `React.CSSProperties`                     | —             | —                                                                                                                                                |
+| `aria-labelledby`        | `string`                                  | —             | ID of an element that labels both start and end time inputs.                                                                                     |
+| `aria-describedby`       | `string`                                  | —             | ID of an element that describes both start and end time inputs.                                                                                  |
+| `aria-invalid`           | `boolean`                                 | —             | —                                                                                                                                                |
+| `value`                  | `TimeRangePickerValue`                    | —             | An object with `start` and `end` values as an empty string or a string based format.                                                             |
+| `format`                 | `TimeRangePickerFormat`                   | "24hr"        | The time display and input format.                                                                                                               |
+| `disabled`               | `boolean`                                 | —             | —                                                                                                                                                |
+| `readOnly`               | `boolean`                                 | —             | —                                                                                                                                                |
+| `error`                  | `boolean`                                 | —             | —                                                                                                                                                |
+| `variant`                | `TimeRangePickerVariant`                  | "dial"        | The picker interaction style.                                                                                                                    |
+| `interval`               | `number`                                  | —             | Minute interval between each option in the combobox dropdowns.                                                                                   |
+| `startLimit`             | `string`                                  | —             | Earliest selectable time shown in the combobox dropdowns.                                                                                        |
+| `endLimit`               | `string`                                  | —             | Latest selectable time shown in the combobox dropdowns.                                                                                          |
+| `initialScrollStartTime` | `string`                                  | —             | The time that the start field dropdown scrolls to on open..                                                                                      |
+| `initialScrollEndTime`   | `string`                                  | —             | The time that the end field dropdown scrolls to on open.                                                                                         |
+| `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.                                                                                             |
+| `onChange`               | `((value: TimeRangePickerValue) => void)` | —             | Called when the selected time range changes.                                                                                                     |
+| `onFocus`                | `(() => void)`                            | —             | Called when the field receives focus.                                                                                                            |
+| `onBlur`                 | `(() => void)`                            | —             | Called when the field loses focus.                                                                                                               |
+| `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` receives a `TimeRangePickerValue`.
+-   Match `format` to the expected string format in `TimeRangePickerValue`.
+-   Use `startLimit`/`endLimit` with `combobox` variant to restrict available options to valid business hours.
+-   Set `errorMessage` rather than `error` alone.
+-   Use `dropdownRootNode` when inside a modal or scrollable container.
+-   Time string format differs between `dial` and `combobox` variants — see `TimeRangePickerValue` above.
+-   `interval`, `startLimit`, `endLimit`, and `initialScroll*` props only apply when `variant="combobox"`.
+
+## Anti-patterns
+
+-   Do not use for single time selection — use `Form.TimePicker` instead.
+-   Do not mix dial and combobox time string formats — the format differs between variants.
+-   Do not set combobox-specific props (`interval`, `startLimit`, `endLimit`, `initialScroll*`) when `variant="dial"`.