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

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

@@ -0,0 +1,77 @@
+# Form.Timepicker
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+> **Casing:** the export is `Form.Timepicker` (lowercase `p`), not `Form.TimePicker`.
+
+## When to use
+
+-   Collecting a single time value from the user (e.g. appointment time, start time, notification time).
+-   Use `format="12hr"` for consumer-facing forms where AM/PM is more intuitive.
+-   Use `format="24hr"` (default) for operational or technical contexts.
+
+## Usage
+
+```tsx
+import styles from "./MyForm.module.css";
+
+<Form.Timepicker className={styles.timepicker} ... />
+```
+
+```css
+/* MyForm.module.css */
+:where(body.fds-breakpoint-lg-min) .timepicker {
+    max-width: 24rem;
+}
+```
+
+Defaults to 4 columns wide at `lg` and above; full-width on mobile. Use `max-width` via a CSS Module class.
+
+## Props
+
+| Prop               | Type                        | Default                                                    | Description                                                                                                                                                               |
+| ------------------ | --------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`        | `string`                    | —                                                          | —                                                                                                                                                                         |
+| `id`               | `string`                    | —                                                          | —                                                                                                                                                                         |
+| `style`            | `React.CSSProperties`       | —                                                          | —                                                                                                                                                                         |
+| `aria-labelledby`  | `string`                    | —                                                          | ID of an element that labels the timepicker input.                                                                                                                        |
+| `aria-describedby` | `string`                    | —                                                          | ID of an element that describes the timepicker input.                                                                                                                     |
+| `value`            | `string`                    | —                                                          | The controlled time value as a string. - 24 hour uses "hh:mm" e.g. `{ start: "13:00", end: "14:00" }` - 12 hour uses "hh:mmA" e.g. `{ start: "01:00PM", end: "02:00PM" }` |
+| `placeholder`      | `string`                    | "hh:mm" for 24-hour format or "hh:mmA" for 12-hour format. | Placeholder text shown when no value is selected.                                                                                                                         |
+| `format`           | `TimepickerFormat`          | "24hr"                                                     | The time display and input format.                                                                                                                                        |
+| `disabled`         | `boolean`                   | —                                                          | —                                                                                                                                                                         |
+| `readOnly`         | `boolean`                   | —                                                          | —                                                                                                                                                                         |
+| `error`            | `boolean`                   | —                                                          | Renders the input in an error state when `true`.                                                                                                                          |
+| `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: string) => void)` | —                                                          | Called when the user confirms a selection.                                                                                                                                |
+| `onFocus`          | `(() => void)`              | —                                                          | Called when the timepicker input receives focus.                                                                                                                          |
+| `onBlur`           | `(() => void)`              | —                                                          | Called when focus leaves both the input and the dropdown.                                                                                                                 |
+| `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.
+-   Match `format` to the expected string format: `"HH:mm"` for 24hr, `"hh:mmA"` for 12hr.
+-   Set `errorMessage` rather than `error` alone so users understand what is wrong.
+-   Use `dropdownRootNode` when the picker is inside a modal or fixed container to avoid z-index issues.
+-   Use `alignment="right"` when the picker is near the right edge of the viewport.
+-   `onChange` fires only after the user clicks the Confirm button, not on every dial interaction.
+-   `onBlur` does not apply any in-progress selection — use `onChange` for committed values.
+
+## Anti-patterns
+
+-   Do not use for time-range selection — use `Form.TimeRangePicker` instead.
+-   Do not mix 12hr format strings with `format="24hr"` or vice versa.
+-   Do not rely on `onBlur` to capture the selected value — it does not commit the selection.

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

@@ -0,0 +1,138 @@
+# Form.UnitNumberInput
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Collecting a Singapore unit number in `#floor-unit` format (e.g. `#01-234`).
+-   Any address form that includes a unit number field for Singapore addresses.
+
+## Usage
+
+### Basic controlled usage with validation guard
+
+`onChange` returns a `floor-unit` string (e.g. `"03-12"`) or the sentinel string `"Invalid unit number"` for malformed input. Always check before persisting.
+
+```tsx
+import { useState } from "react";
+import { Form } from "@lifesg/react-design-system/form";
+
+const UnitField = () => {
+    const [value, setValue] = useState("");
+    const [error, setError] = useState("");
+
+    const handleChange = (val: string) => {
+        if (val === "Invalid unit number") {
+            setError("Please enter a valid unit number.");
+            // Do not persist — keep previous valid value in state
+        } else {
+            setError("");
+            setValue(val); // e.g. "03-12"
+        }
+    };
+
+    return (
+        <Form.UnitNumberInput
+            label="Unit number"
+            value={value}
+            onChange={handleChange}
+            errorMessage={error}
+        />
+    );
+};
+```
+
+### `onBlur` zero-pads automatically
+
+After the user tabs away, `onBlur` fires with the formatted value. The displayed value may change without any user input — update state accordingly.
+
+```tsx
+<Form.UnitNumberInput
+    label="Unit number"
+    value={value}
+    onChange={handleChange}
+    onBlur={(formatted) => {
+        // e.g. user typed "3-2" → formatted is "03-02"
+        setValue(formatted);
+    }}
+/>
+```
+
+### `onChangeRaw` — separate floor and unit
+
+Use `onChangeRaw` when downstream code needs floor and unit as distinct values, regardless of validity.
+
+```tsx
+<Form.UnitNumberInput
+    label="Unit number"
+    onChangeRaw={(parts: string[]) => {
+        const [floor, unit] = parts; // e.g. ["03", "12"]
+        setFloor(floor);
+        setUnit(unit);
+    }}
+/>
+```
+
+Width: defaults to 4 columns wide at `lg` and above; full-width on mobile. Use `max-width` via a CSS Module class:
+
+```tsx
+import styles from "./MyForm.module.css";
+
+<Form.UnitNumberInput className={styles.unitNumberInput} ... />
+```
+
+```css
+/* MyForm.module.css */
+:where(body.fds-breakpoint-lg-min) .unitNumberInput {
+    max-width: 24rem;
+}
+```
+
+## Props
+
+| Prop           | Type                          | Default   | Description                                                                                                                                      |
+| -------------- | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `className`    | `string`                      | —         | —                                                                                                                                                |
+| `id`           | `string`                      | —         | —                                                                                                                                                |
+| `style`        | `React.CSSProperties`         | —         | —                                                                                                                                                |
+| `tabIndex`     | `number`                      | —         | —                                                                                                                                                |
+| `readOnly`     | `boolean`                     | —         | —                                                                                                                                                |
+| `placeholder`  | `string`                      | "00-8888" | Placeholder text in `"floor-unit"` format.                                                                                                       |
+| `role`         | `React.AriaRole`              | —         | —                                                                                                                                                |
+| `value`        | `string`                      | —         | The combined unit number value in `"floor-unit"` format (e.g. `"01-234"`).                                                                       |
+| `name`         | `string`                      | —         | —                                                                                                                                                |
+| `error`        | `boolean`                     | —         | Renders the input in an error state.                                                                                                             |
+| `disabled`     | `boolean`                     | —         | —                                                                                                                                                |
+| `autoComplete` | `string`                      | —         | —                                                                                                                                                |
+| `onChange`     | `((value: string) => void)`   | —         | Called when the value of either sub-input changes.                                                                                               |
+| `onChangeRaw`  | `((value: string[]) => void)` | —         | Called when either sub-input changes.                                                                                                            |
+| `onBlur`       | `((value: string) => void)`   | —         | Called when focus leaves the component entirely.                                                                                                 |
+| `onBlurRaw`    | `((value: string[]) => void)` | —         | Called when focus leaves the component.                                                                                                          |
+| `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.
+-   Check the return value of `onChange` for `"Invalid unit number"` and handle it before persisting the value.
+-   Use `onChangeRaw` if you need floor and unit as separate values for downstream processing.
+-   Use `onBlur` to get the zero-padded, formatted value after the user finishes typing.
+-   Set `errorMessage` to explain validation failures.
+-   `onChange` returns `"Invalid unit number"` for malformed input — check for this string before saving.
+-   `onBlur` zero-pads the unit part (e.g. `"11-2"` → `"11-02"`).
+-   Use `onChangeRaw` / `onBlurRaw` when you need floor and unit as separate values.
+
+## Anti-patterns
+
+-   Do not use a plain text input for unit numbers — the component enforces the correct format automatically.
+-   Do not persist the value returned from `onChange` without first checking it is not `"Invalid unit number"`.
+-   Do not use for non-Singapore address formats — the component enforces the `floor-unit` structure.

package/skills/fds-build/resources/components/fullscreen-image-carousel.md

@@ -0,0 +1,159 @@
+# FullscreenImageCarousel
+
+Import: `import { FullscreenImageCarousel } from "@lifesg/react-design-system/fullscreen-image-carousel"`
+
+## When to use
+
+Use to display a fullscreen overlay carousel of images or custom content (e.g. PDFs, videos) with thumbnail navigation, zoom, and optional delete controls.
+
+## Sub-components
+
+-   `FullscreenImageCarouselItemProps` — union of `FullscreenImageCarouselImageItemProps` and `FullscreenImageCarouselCustomItemProps`
+
+## Usage
+
+### Mixed image and custom items
+
+Items use a discriminated union on `type`. Image items may omit `type` (defaults to image); custom items **must** set `type: "custom"` and provide `renderContent`.
+
+```tsx
+import { useState } from "react";
+import { FullscreenImageCarousel } from "@lifesg/react-design-system/fullscreen-image-carousel";
+
+const DocViewer = () => {
+    const [show, setShow] = useState(false);
+
+    const items = [
+        // Image item — type may be omitted
+        {
+            src: "https://example.com/photo.jpg",
+            alt: "Site photo",
+            fileName: "photo.jpg",
+            fileSize: "1.2 MB",
+        },
+        // Custom item — type is required
+        {
+            type: "custom" as const,
+            itemLabel: "PDF",
+            thumbnailSrc: "https://example.com/pdf-thumb.svg",
+            renderContent: () => (
+                <iframe
+                    src="https://example.com/document.pdf"
+                    title="PDF preview"
+                    style={{ width: "100%", height: "100%", border: "none" }}
+                />
+            ),
+        },
+    ];
+
+    const handleDelete = (item, index) => {
+        // Remove the item from your state; the delete button only appears
+        // because onDelete is provided.
+        removeItem(index);
+    };
+
+    return (
+        <>
+            <button onClick={() => setShow(true)}>View files</button>
+            <FullscreenImageCarousel
+                show={show}
+                items={items}
+                onClose={() => setShow(false)}
+                onDelete={handleDelete} // omit to hide delete button
+                showFirstAndLastNav
+            />
+        </>
+    );
+};
+```
+
+## Props — `FullscreenImageCarouselRef`
+
+| Prop                  | Type                                 | Default | Description                                                               |
+| --------------------- | ------------------------------------ | ------- | ------------------------------------------------------------------------- |
+| `currentItemIndex` \* | `number`                             | —       | Zero-based index of the currently visible item.                           |
+| `setCurrentItem` \*   | `(currentItemIndex: number) => void` | —       | Navigates directly to the item at the given zero-based index.             |
+| `goToPrevItem` \*     | `() => void`                         | —       | Navigates to the previous item, wrapping from the first item to the last. |
+| `goToNextItem` \*     | `() => void`                         | —       | Navigates to the next item, wrapping from the last item to the first.     |
+
+## Props — `FullscreenImageCarouselCustomAction`
+
+| Prop           | Type                                                              | Default | Description                              |
+| -------------- | ----------------------------------------------------------------- | ------- | ---------------------------------------- |
+| `icon` \*      | `JSX.Element`                                                     | —       | Icon element rendered inside the button. |
+| `ariaLabel` \* | `string`                                                          | —       | Accessible name for the button.          |
+| `onClick` \*   | `(item: FullscreenImageCarouselItemProps, index: number) => void` | —       | Called when the action is activated.     |
+
+## Props — `FullscreenImageCarouselProps`
+
+| Prop                     | Type                                                                   | Default  | Description                                                                                                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `items` \*               | `FullscreenImageCarouselItemProps[]`                                   | —        | The list of items to display. Each item is either an image or a custom content item.                                                                                           |
+| `initialActiveItemIndex` | `number`                                                               | 0        | Zero-based index of the item that is active when the carousel first opens.                                                                                                     |
+| `hideThumbnail`          | `boolean`                                                              | false    | Hides the thumbnail strip below the main slide.                                                                                                                                |
+| `hideNavigation`         | `boolean`                                                              | false    | Hides the previous and next arrow navigation buttons.                                                                                                                          |
+| `hideCounter`            | `boolean`                                                              | false    | Hides the slide position counter chip (e.g. "2/5").                                                                                                                            |
+| `hideMagnifier`          | `boolean`                                                              | false    | Hides the zoom in/out magnifier button. Has no effect on custom items, which never show the magnifier regardless of this prop.                                                 |
+| `customActions`          | `FullscreenImageCarouselCustomAction[]`                                | —        | Additional icon buttons rendered in the top bar, positioned before the default buttons. Applies to every item. An item's own `customActions` replaces this list for that item. |
+| `onDelete`               | `\| ((item: FullscreenImageCarouselItemProps, index: number) => void)` | —        | Called when the delete button is activated for the current item.                                                                                                               |
+| `onClose`                | `(() => void)`                                                         | —        | Called when the close button is activated or the Escape key is pressed.                                                                                                        |
+| `insets`                 | `Insets`                                                               | —        | Additional pixel insets applied to keep content within a safe area of the viewport and avoid overlap with device UI elements.                                                  |
+| `topBarRef`              | `React.Ref<HTMLDivElement>`                                            | —        | Ref to the top bar element, which holds the file info and the action buttons.                                                                                                  |
+| `show` \*                | `boolean`                                                              | false    | Controls whether the modal is visible.                                                                                                                                         |
+| `rootComponentId`        | `string`                                                               | —        | The `id` of the DOM element to portal the modal into.                                                                                                                          |
+| `animationFrom`          | `ModalAnimationDirection`                                              | "bottom" | Direction from which the modal animates in and out.                                                                                                                            |
+| `zIndex`                 | `number`                                                               | —        | The z-index applied to the overlay stack.                                                                                                                                      |
+
+## Props — `FullscreenImageCarouselImageItemProps`
+
+| Prop            | Type                                    | Default | Description                                                                                                                                                                         |
+| --------------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`          | `"image"`                               | —       | —                                                                                                                                                                                   |
+| `src` \*        | `string`                                | —       | URL of the full-resolution image shown in the slide.                                                                                                                                |
+| `alt`           | `string`                                | —       | Accessible label for the image.                                                                                                                                                     |
+| `thumbnailSrc`  | `string`                                | —       | URL of the image shown in the thumbnail strip. Falls back to `src` when omitted.                                                                                                    |
+| `renderContent` | `never`                                 | —       | —                                                                                                                                                                                   |
+| `fileName`      | `string`                                | —       | Display name of the file shown in the top info bar.                                                                                                                                 |
+| `fileSize`      | `string`                                | —       | Human-readable file size shown alongside `fileName` in the top info bar (e.g. "2.4 MB").                                                                                            |
+| `customActions` | `FullscreenImageCarouselCustomAction[]` | —       | Replaces the component-level `customActions` while this item is active. Leave `undefined` to inherit the component-level list. Pass `[]` to render no custom actions for this item. |
+
+## Props — `FullscreenImageCarouselCustomItemProps`
+
+| Prop               | Type                                    | Default | Description                                                                                                                                                                         |
+| ------------------ | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` \*          | `"custom"`                              | —       | —                                                                                                                                                                                   |
+| `thumbnailSrc`     | `string`                                | —       | The thumbnail image src. If omitted, a placeholder is shown in the thumbnail strip.                                                                                                 |
+| `itemLabel`        | `string`                                | "image" | Label for this item used in aria-labels (e.g. "PDF").                                                                                                                               |
+| `renderContent` \* | `() => React.ReactNode`                 | —       | Render prop for the full slide area. Consumer is responsible for the entire slide content (e.g. an iframe, embed, or custom viewer).                                                |
+| `fileName`         | `string`                                | —       | Display name of the file shown in the top info bar.                                                                                                                                 |
+| `fileSize`         | `string`                                | —       | Human-readable file size shown alongside `fileName` in the top info bar (e.g. "2.4 MB").                                                                                            |
+| `customActions`    | `FullscreenImageCarouselCustomAction[]` | —       | Replaces the component-level `customActions` while this item is active. Leave `undefined` to inherit the component-level list. Pass `[]` to render no custom actions for this item. |
+
+## Props — `ImageDimension`
+
+| Prop        | Type     | Default | Description |
+| ----------- | -------- | ------- | ----------- |
+| `width` \*  | `number` | —       | —           |
+| `height` \* | `number` | —       | —           |
+
+## Props — `FullscreenImageCarouselItemProps`
+
+| Prop            | Type                                    | Default | Description                                                                                                                                                                         |
+| --------------- | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`          | `"image"`                               | —       | —                                                                                                                                                                                   |
+| `thumbnailSrc`  | `string`                                | —       | URL of the image shown in the thumbnail strip. Falls back to `src` when omitted.                                                                                                    |
+| `renderContent` | `never`                                 | —       | —                                                                                                                                                                                   |
+| `fileName`      | `string`                                | —       | Display name of the file shown in the top info bar.                                                                                                                                 |
+| `fileSize`      | `string`                                | —       | Human-readable file size shown alongside `fileName` in the top info bar (e.g. "2.4 MB").                                                                                            |
+| `customActions` | `FullscreenImageCarouselCustomAction[]` | —       | Replaces the component-level `customActions` while this item is active. Leave `undefined` to inherit the component-level list. Pass `[]` to render no custom actions for this item. |
+
+## Rules
+
+-   Always provide `show` and `items` — both are required.
+-   Always wire `onClose` to set `show` to `false`; the component does not close itself.
+-   Do not reorder the `items` array while a delete is in flight.
+-   The delete button only appears when `onDelete` is provided — omit the prop to hide the button entirely.
+
+## Anti-patterns
+
+-   Do not use for inline image galleries — this component renders as a fullscreen modal overlay.

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

@@ -0,0 +1,41 @@
+# HistogramSlider
+
+Import: `import { HistogramSlider } from "@lifesg/react-design-system/histogram-slider"`
+
+A range slider with a histogram distribution chart above it — used in filter panels where showing the value distribution helps users pick a range (e.g. price range, age range).
+
+## Props — `HistogramBinProps`
+
+| Prop          | Type     | Default | Description                                              |
+| ------------- | -------- | ------- | -------------------------------------------------------- |
+| `count` \*    | `number` | —       | Number of items that fall within this bin's value range. |
+| `minValue` \* | `number` | —       | Lower bound of this bin's value range.                   |
+
+## Props — `HistogramSliderProps`
+
+| Prop               | Type                                   | Default | Description                                                                                                                                             |
+| ------------------ | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`        | `string`                               | —       | —                                                                                                                                                       |
+| `id`               | `string`                               | —       | —                                                                                                                                                       |
+| `bins` \*          | `HistogramBinProps[]`                  | —       | The set of bins to render as bars.                                                                                                                      |
+| `interval` \*      | `number`                               | —       | Controls the slider's step increment and minimum selectable range.                                                                                      |
+| `disabled`         | `boolean`                              | —       | —                                                                                                                                                       |
+| `readOnly`         | `boolean`                              | —       | —                                                                                                                                                       |
+| `value`            | `[number, number]`                     | —       | The selected range as `[start, end]`. When omitted, the selection is initialised to `[minValue, minValue + interval]` derived from the provided `bins`. |
+| `showRangeLabels`  | `boolean`                              | —       | When `true`, displays the current start and end values above the histogram.                                                                             |
+| `rangeLabelPrefix` | `string`                               | —       | Text prepended to each range label value. Has no effect when `renderRangeLabel` is provided.                                                            |
+| `rangeLabelSuffix` | `string`                               | —       | Text appended to each range label value. Has no effect when `renderRangeLabel` is provided.                                                             |
+| `ariaLabels`       | `[string, string]`                     | —       | Accessible labels for the two slider thumbs, as `[startLabel, endLabel]`.                                                                               |
+| `aria-labelledby`  | `string`                               | —       | ID of an element that labels the slider group.                                                                                                          |
+| `aria-describedby` | `string`                               | —       | ID of an element that describes the slider group.                                                                                                       |
+| `renderRangeLabel` | `((value: number) => React.ReactNode)` | —       | Custom renderer for each range label value. When provided, overrides the `rangeLabelPrefix` and `rangeLabelSuffix` combination.                         |
+| `onChange`         | `((value: [number, number]) => void)`  | —       | Called on every selection change.                                                                                                                       |
+| `onChangeEnd`      | `((value: [number, number]) => void)`  | —       | Called when a thumb is released after selection is complete.                                                                                            |
+| `renderEmptyView`  | `(() => React.ReactNode)`              | —       | Rendered in place of the histogram and slider when all bins have a count of zero.                                                                       |
+
+## Rules
+
+-   `onChange` fires continuously during drag — do not put API calls here; use `onChangeEnd`.
+-   `interval` must match the gap between `minValue` of consecutive bins.
+-   Always provide `ariaLabels` or `aria-labelledby` for accessibility.
+-   Pair with `Filter` in a filter sidebar — `HistogramSlider` is not a `Form.*` component and does not use `label`/`errorMessage`.

package/skills/fds-build/resources/components/icon.md

@@ -0,0 +1,167 @@
+# Icons
+
+Icons come from `@lifesg/react-icons` — a separate package. Each icon is its own named export.
+
+## Import pattern
+
+Icon names follow `{name}` → component name is `{PascalCase}Icon`:
+
+```tsx
+import { ArrowRightIcon } from "@lifesg/react-icons/arrow-right";
+import { TickCircleFillIcon } from "@lifesg/react-icons/tick-circle-fill";
+import { PersonIcon } from "@lifesg/react-icons/person";
+```
+
+Pattern: `kebab-case` name → import path `@lifesg/react-icons/{name}` → component `{PascalCase}Icon`
+
+## Available icons
+
+Icons come in two variants: outline (default) and filled (`-fill` suffix).
+
+### Arrows & Navigation
+
+`arrow-up` `arrow-down` `arrow-left` `arrow-right`
+`arrow-up-circle` `arrow-up-circle-fill` `arrow-down-circle` `arrow-down-circle-fill`
+`arrow-left-circle` `arrow-left-circle-fill` `arrow-right-circle` `arrow-right-circle-fill`
+`arrow-left-up` `arrow-left-down` `arrow-right-up` `arrow-right-down`
+`chevron-up` `chevron-down` `chevron-left` `chevron-right`
+`chevron-2-left` `chevron-2-right`
+`chevron-line-left` `chevron-line-right`
+`caret-up` `caret-down` `caret-left` `caret-right`
+`multi-chevron-up-down` `multi-chevron-down-up`
+`navigation` `navigation-fill`
+`external` `return`
+
+### Actions
+
+`plus` `plus-circle` `plus-circle-fill`
+`minus` `minus-circle` `minus-circle-fill` `minus-square` `minus-square-fill`
+`cross` `cross-circle` `cross-circle-fill`
+`tick` `tick-circle` `tick-circle-fill`
+`pencil` `pencil-fill` `pencil-stroke` `pencil-stroke-fill`
+`bin` `bin-fill`
+`copy` `copy-fill`
+`download` `upload`
+`share` `link`
+`login` `logout`
+`refresh` `replay` `retry`
+`drag-handle`
+`filter`
+`sort-ascending` `sort-descending`
+`fullscreen-open` `fullscreen-close`
+`read-more`
+`eraser`
+
+### Status & Feedback
+
+`tick-circle` `tick-circle-fill`
+`cross-circle` `cross-circle-fill`
+`exclamation-circle` `exclamation-circle-fill`
+`exclamation-triangle` `exclamation-triangle-fill`
+`i-circle` `i-circle-fill`
+`questionmark-circle` `questionmark-circle-fill`
+`thumb-up` `thumb-up-fill`
+`star` `star-fill` `star-half`
+
+### People & Identity
+
+`person` `person-fill`
+`person-2` `person-2-fill`
+`person-group` `person-group-fill`
+`person-plus` `person-plus-fill`
+`person-minus` `person-minus-fill`
+`person-2-plus` `person-2-plus-fill`
+`person-2-minus` `person-2-minus-fill`
+`person-gear` `person-gear-fill`
+`person-off` `person-off-fill`
+`id-card` `id-card-fill`
+
+### Communication
+
+`envelope` `envelope-fill`
+`envelope-open` `envelope-open-fill`
+`bell` `bell-fill`
+`phone` `phone-fill`
+`inbox` `inbox-fill`
+`speaker` `speaker-fill`
+
+### Files & Documents
+
+`doc` `doc-fill`
+`doc-pencil` `doc-pencil-fill`
+`album` `album-fill`
+`box` `box-fill`
+`index`
+`text` `text-fill`
+
+### Calendar & Time
+
+`calendar` `calendar-fill`
+`calendar-event` `calendar-event-fill`
+`calendar-plus` `calendar-plus-fill`
+`calendar-cross` `calendar-cross-fill`
+`calendar-dot` `calendar-dot-fill`
+`calendar-pencil` `calendar-pencil-fill`
+`calendar-tick` `calendar-tick-fill`
+`clock` `clock-fill`
+`recurring` `non-recurring`
+
+### Location & Maps
+
+`map` `map-fill`
+`pin` `pin-fill`
+`point`
+`navigation` `navigation-fill`
+`globe`
+`house` `house-fill`
+`building`
+`floor-plan` `floor-plan-fill`
+
+### Devices & Media
+
+`camera` `camera-fill`
+`tablet` `tablet-fill`
+`phone` `phone-fill`
+`cloud` `cloud-fill`
+`cloud-arrow-up` `cloud-arrow-up-fill`
+`cloud-arrow-down` `cloud-arrow-down-fill`
+`cloud-tick` `cloud-tick-fill`
+`qr`
+
+### UI & Layout
+
+`menu`
+`ellipsis-horizontal` `ellipsis-vertical`
+`gear` `gear-fill`
+`lock` `lock-fill`
+`eye` `eye-fill`
+`eye-slash` `eye-slash-fill`
+`list`
+`square` `square-fill`
+`square-2x2` `square-2x2-fill`
+`square-tick` `square-tick-fill`
+`circle` `circle-dot`
+`toggle-on` `toggle-on-fill`
+`toggle-off` `toggle-off-fill`
+`magnifier` `magnifier-plus` `magnifier-minus`
+
+### Misc
+
+`bookmark` `bookmark-fill`
+`chart` `chart-fill`
+`car`
+`dollar`
+`printer` `printer-fill`
+`lightbulb` `lightbulb-fill`
+`language`
+`ticket` `ticket-fill`
+`triangle-forward` `triangle-forward-fill`
+`align-left` `align-center` `align-right` `align-justify`
+`placeholder` `placeholder-image`
+
+## Rules
+
+-   Never guess an icon name — verify it exists in the list above before importing.
+-   `-fill` variants are the solid/filled version; the base name is outline.
+-   Fallback: if no suitable icon exists in `@lifesg/react-icons`, use `@mui/icons-material` as a secondary source.
+-   For icon-only buttons (`<Button icon={<Icon />} />`), always set `aria-label` — the icon alone is not accessible.

package/skills/fds-build/resources/components/image-button.md

@@ -0,0 +1,12 @@
+# ImageButton
+
+Import: `import { ImageButton } from "@lifesg/react-design-system/image-button"`
+
+## Props
+
+| Prop                    | Type      | Default | Description                                                                  |
+| ----------------------- | --------- | ------- | ---------------------------------------------------------------------------- |
+| `imgSrc` \*             | `string`  | —       | URL of the image to display inside the button.                               |
+| `selected`              | `boolean` | —       | Applies a selected visual style to indicate the button is the active choice. |
+| `error`                 | `boolean` | —       | Applies an error visual style to indicate a validation or selection error.   |
+| `focusableWhenDisabled` | `boolean` | false   | Keeps the button reachable via keyboard focus when `disabled` is `true`.     |