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

package/skills/fds-build/resources/components/file-upload.md

@@ -0,0 +1,105 @@
+# FileUpload
+
+Import: `import { FileUpload } from "@lifesg/react-design-system/file-upload"`
+
+## When to use
+
+-   Forms that require users to attach one or more files (e.g. supporting documents, ID scans, images).
+-   Use `sortable` when file order matters for downstream processing.
+-   Use `editableFileItems` when image files need alt-text or descriptions.
+-   Use `readOnly` on review or summary screens to display uploaded files without allowing changes.
+
+## Usage
+
+```tsx
+import { FileUpload } from "@lifesg/react-design-system/file-upload";
+
+<FileUpload
+    title="Upload supporting documents"
+    description="PDF, JPG, or PNG. Max 5 MB each."
+    accept=".pdf,.jpg,.png"
+    fileItems={fileItems}
+    onChange={(files) => {}}
+    onDelete={(item) => {}}
+/>;
+```
+
+## Custom labels
+
+| Prop                             | Type     | Default          | Description                                       |
+| -------------------------------- | -------- | ---------------- | ------------------------------------------------- |
+| `customLabels.uploadButtonLabel` | `string` | `"Upload files"` | Label of the button that triggers the file dialog |
+
+## Props — `FileItemProps`
+
+| Prop                    | Type                        | Default | Description                                                                                                                                                                 |
+| ----------------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` \*                 | `string`                    | —       | Unique identifier used to target delete, edit, and sort operations.                                                                                                         |
+| `name` \*               | `string`                    | —       | The display name of the file                                                                                                                                                |
+| `type` \*               | `string`                    | —       | The MIME type of the file (e.g. `"application/pdf"`).                                                                                                                       |
+| `size` \*               | `number`                    | —       | The size of the file in bytes. Displayed as formatted text when provided.                                                                                                   |
+| `description`           | `string`                    | —       | The alt text or description of the file                                                                                                                                     |
+| `progress`              | `number`                    | —       | Upload progress expressed as a fraction between 0 and 1. When provided, a progress indicator is rendered on the file item.                                                  |
+| `errorMessage`          | `string \| React.ReactNode` | —       | Error message shown on the file item to indicate an upload failure. Accepts a plain string or a React node for richer error display.                                        |
+| `thumbnailImageDataUrl` | `string`                    | —       | URL or data URL for a thumbnail image shown alongside the file entry. When not provided, a PDF icon is displayed for PDF files only; other file types show no default icon. |
+| `truncateText`          | `boolean`                   | true    | Truncates long file names with an ellipsis when `true`.                                                                                                                     |
+
+## Props — `FileInputProps`
+
+| Prop        | Type                                 | Default | Description                                                      |
+| ----------- | ------------------------------------ | ------- | ---------------------------------------------------------------- |
+| `accept`    | `string`                             | —       | Defines the file types that is accepted                          |
+| `capture`   | `boolean \| "user" \| "environment"` | —       | Specifies which camera to use for capture of image or video data |
+| `multiple`  | `boolean`                            | —       | Specifies if user is allowed to select more than one file.       |
+| `disabled`  | `boolean`                            | —       | —                                                                |
+| `id`        | `string`                             | —       | —                                                                |
+| `className` | `string`                             | —       | —                                                                |
+| `name`      | `string`                             | —       | —                                                                |
+
+## Props — `FileUploadProps`
+
+| Prop                       | Type                                     | Default    | Description                                                                                                                                                                    |
+| -------------------------- | ---------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`                    | `string \| JSX.Element`                  | —          | Heading rendered at the top of the component. Accepts a plain string or a JSX element for rich formatting.                                                                     |
+| `description`              | `string \| JSX.Element`                  | —          | Supporting text rendered below `title`. Accepts a plain string or a JSX element for rich formatting.                                                                           |
+| `styleType`                | `FileUploadStyle`                        | "bordered" | Visual style variant for the component.                                                                                                                                        |
+| `maxFiles`                 | `number`                                 | —          | Maximum number of files the component will accept. Once `fileItems.length` reaches this value, uploading is disabled until an item is removed.                                 |
+| `warning`                  | `string \| JSX.Element`                  | —          | Warning message rendered inside the component. Accepts a plain string or a JSX element for rich formatting.                                                                    |
+| `fileItems`                | `FileItemProps[]`                        | —          | Controlled list of file items displayed in the file list. Update this array in response to `onChange`, `onDelete`, `onEdit`, and `onSort` to reflect the current upload state. |
+| `editableFileItems`        | `boolean`                                | false      | When `true`, image file items render an editable description field. Editing triggers `onEdit` with the updated `FileItemProps`.                                                |
+| `fileDescriptionMaxLength` | `number`                                 | —          | Character limit for the description input on editable image file items. Only applies when `editableFileItems` is `true`.                                                       |
+| `descriptionRequired`      | `boolean`                                | true       | When `false`, the save button on an editable file item is enabled even when the description field is empty.                                                                    |
+| `descriptionLabel`         | `FormLabelProps`                         | —          | Overrides the default label and subtext for the description input field on editable file items.                                                                                |
+| `sortable`                 | `boolean`                                | false      | When `true`, file items can be reordered via drag-and-drop. The reordered list is emitted via `onSort`.                                                                        |
+| `errorMessage`             | `string \| JSX.Element`                  | —          | General error message rendered below the file list. Accepts a plain string or a JSX element for rich formatting.                                                               |
+| `readOnly`                 | `boolean`                                | —          | When `true`, the upload button and drop zone are hidden and file items are rendered without delete or edit controls.                                                           |
+| `customLabels`             | `{ uploadButtonLabel?: string }`         | —          | Overrides default label text for elements within the component.                                                                                                                |
+| `onChange`                 | `((files: File[]) => void)`              | —          | Called with the newly uploaded files. Receives only the files that fit within the remaining `maxFiles` slots.                                                                  |
+| `onEdit`                   | `((fileItem: FileItemProps) => void)`    | —          | Called when the user saves an edited description on a file item.                                                                                                               |
+| `onDelete`                 | `((fileItem: FileItemProps) => void)`    | —          | Called when the user clicks the delete button on a file item.                                                                                                                  |
+| `onSort`                   | `((fileItems: FileItemProps[]) => void)` | —          | Called after the user reorders file items via drag-and-drop. Only fired when `sortable` is `true`.                                                                             |
+| `accept`                   | `string`                                 | —          | Defines the file types that is accepted                                                                                                                                        |
+| `capture`                  | `boolean \| "user" \| "environment"`     | —          | Specifies which camera to use for capture of image or video data                                                                                                               |
+| `multiple`                 | `boolean`                                | —          | Specifies if user is allowed to select more than one file.                                                                                                                     |
+| `disabled`                 | `boolean`                                | —          | —                                                                                                                                                                              |
+| `id`                       | `string`                                 | —          | —                                                                                                                                                                              |
+| `className`                | `string`                                 | —          | —                                                                                                                                                                              |
+| `name`                     | `string`                                 | —          | —                                                                                                                                                                              |
+
+## Rules
+
+-   Always manage `fileItems` state in the parent — the component does not store files internally.
+-   Always handle `onChange` to convert incoming `File[]` into `FileItemProps[]` and add them to state.
+-   Always handle `onDelete` to remove the corresponding item from state.
+-   Use `maxFiles` to enforce the maximum number of attachments allowed by the backend.
+-   Use `progress` on individual `FileItemProps` to show per-file upload progress.
+-   Use `errorMessage` on individual `FileItemProps` to surface per-file upload errors.
+-   Use the component-level `errorMessage` for overall validation errors (e.g. "At least one file is required").
+-   Use `accept` (inherited from `<input type="file">`) to restrict file types to what the backend accepts.
+
+## Anti-patterns
+
+-   Do not use without wiring `onChange` and `onDelete` — the list will not update.
+-   Do not store files in component state inside the same component that renders `FileUpload` — hoist state to the form level.
+-   Do not skip `id`, `name`, `type`, and `size` in `FileItemProps` — they are required fields.
+-   Do not use `editableFileItems` for non-image files — description editing only applies to images.

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

@@ -0,0 +1,228 @@
+# Filter
+
+Import: `import { Filter } from "@lifesg/react-design-system/filter"`
+
+## When to use
+
+Use on listing pages to narrow a result set. `Filter` automatically switches between a desktop sidebar and a mobile modal at the `lg-max` breakpoint.
+
+## Composition
+
+```
+Filter                                  ← recommended: auto-switches sidebar ↔ modal at lg breakpoint
+├── Filter.Item title="Sort by"         ← section header + collapsible wrapper
+│   └── {RadioButton group}             ← sort options use RadioButton, not Filter.Checkbox
+├── Filter.Item title="Category"
+│   └── Filter.Checkbox                 ← multi-select filter options
+└── Filter.Item title="..."
+    └── Filter.Checkbox
+```
+
+Manual variants (bypass auto-responsive):
+
+```
+Filter.Sidebar                          ← desktop sidebar only
+Filter.Modal                            ← mobile modal only
+Filter.Page                             ← full-page filter (mobile-only flows)
+```
+
+`Filter.Item` is the only valid direct child of `Filter`, `Filter.Sidebar`, or `Filter.Modal`. Use `RadioButton` for sort (single-select); use `Filter.Checkbox` for multi-select filters.
+
+## Variants
+
+| Variant                  | When to use                                                     |
+| ------------------------ | --------------------------------------------------------------- |
+| `<Filter>` (recommended) | Auto-responsive — desktop sidebar + mobile modal                |
+| `<Filter.Sidebar>`       | Desktop sidebar only — when bypassing auto-responsive behaviour |
+| `<Filter.Modal>`         | Mobile modal only — when bypassing auto-responsive behaviour    |
+
+## Usage
+
+### Auto-responsive Filter (recommended)
+
+`Filter` renders a sidebar on desktop and a modal on mobile automatically. Pass children as a function to receive `mode` (`"desktop" | "mobile"`) when you need to render differently per viewport.
+
+```tsx
+import { useState } from "react";
+import { Filter } from "@lifesg/react-design-system/filter";
+import { RadioButton } from "@lifesg/react-design-system/radio-button";
+
+const ListingFilter = () => {
+    const [category, setCategory] = useState("all");
+    const [activeCount, setActiveCount] = useState(0);
+
+    const handleClear = () => {
+        setCategory("all");
+        setActiveCount(0);
+    };
+
+    return (
+        <Filter
+            count={activeCount}
+            onClear={handleClear}
+            onDone={() => {
+                /* commit draft state */
+            }}
+            onDismiss={() => {
+                /* discard draft state */
+            }}
+        >
+            {(mode) => (
+                <>
+                    <Filter.Item title="Category">
+                        <RadioButton
+                            name="category"
+                            value="all"
+                            checked={category === "all"}
+                            onChange={() => setCategory("all")}
+                        >
+                            All
+                        </RadioButton>
+                        <RadioButton
+                            name="category"
+                            value="news"
+                            checked={category === "news"}
+                            onChange={() => setCategory("news")}
+                        >
+                            News
+                        </RadioButton>
+                    </Filter.Item>
+                    <Filter.Item title="Sort by" collapsible={false}>
+                        <RadioButton name="sort" value="newest" defaultChecked>
+                            Newest first
+                        </RadioButton>
+                        <RadioButton name="sort" value="oldest">
+                            Oldest first
+                        </RadioButton>
+                    </Filter.Item>
+                </>
+            )}
+        </Filter>
+    );
+};
+```
+
+Key points:
+
+-   `onDone` and `onDismiss` are mobile-only callbacks; they are ignored on desktop.
+-   `collapsible={false}` on sort sections keeps them always expanded.
+-   `count` drives the active-filter badge in the header.
+
+## Props — `FilterBaseProps`
+
+| Prop                      | Type                                       | Default | Description                                                                                                                                                                                  |
+| ------------------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                      | `string`                                   | —       | —                                                                                                                                                                                            |
+| `className`               | `string`                                   | —       | —                                                                                                                                                                                            |
+| `style`                   | `CSSProperties`                            | —       | —                                                                                                                                                                                            |
+| `count`                   | `number`                                   | —       | Number of active filter selections displayed as a badge on the header and toggle button.                                                                                                     |
+| `clearButtonDisabled`     | `boolean`                                  | false   | When `true`, the clear button is rendered in a disabled state.                                                                                                                               |
+| `onClear`                 | `(() => void)`                             | —       | Called when the clear button is pressed.                                                                                                                                                     |
+| `children`                | `ReactNode \| ((mode: Mode) => ReactNode)` | —       | Content rendered inside the filter panel. Pass a render function to receive the current `Mode` and conditionally render different content for desktop (`"default"`) and mobile (`"mobile"`). |
+| `headerTitle`             | `string`                                   | —       | —                                                                                                                                                                                            |
+| `toggleFilterButtonLabel` | `string`                                   | —       | —                                                                                                                                                                                            |
+| `doneButtonLabel`         | `string`                                   | —       | —                                                                                                                                                                                            |
+
+## Props — `FilterSidebarProps`
+
+| Prop                      | Type                                       | Default | Description                                                                                                                                                                                  |
+| ------------------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `customLabels`            | `FilterSidebarCustomLabelProps`            | —       | Overrides default labels used by the sidebar variant.                                                                                                                                        |
+| `id`                      | `string`                                   | —       | —                                                                                                                                                                                            |
+| `className`               | `string`                                   | —       | —                                                                                                                                                                                            |
+| `style`                   | `CSSProperties`                            | —       | —                                                                                                                                                                                            |
+| `count`                   | `number`                                   | —       | Number of active filter selections displayed as a badge on the header and toggle button.                                                                                                     |
+| `clearButtonDisabled`     | `boolean`                                  | false   | When `true`, the clear button is rendered in a disabled state.                                                                                                                               |
+| `onClear`                 | `(() => void)`                             | —       | Called when the clear button is pressed.                                                                                                                                                     |
+| `children`                | `ReactNode \| ((mode: Mode) => ReactNode)` | —       | Content rendered inside the filter panel. Pass a render function to receive the current `Mode` and conditionally render different content for desktop (`"default"`) and mobile (`"mobile"`). |
+| `headerTitle`             | `string`                                   | —       | —                                                                                                                                                                                            |
+| `toggleFilterButtonLabel` | `string`                                   | —       | —                                                                                                                                                                                            |
+| `doneButtonLabel`         | `string`                                   | —       | —                                                                                                                                                                                            |
+
+## Props — `FilterModalProps`
+
+| Prop                      | Type                                       | Default | Description                                                                                                                                                                                  |
+| ------------------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onDismiss`               | `(() => void)`                             | —       | Called when the dismiss (close) button is pressed in the modal overlay.                                                                                                                      |
+| `onDone`                  | `(() => void)`                             | —       | Called when the done button is pressed in the modal overlay.                                                                                                                                 |
+| `onModalOpen`             | `() => void`                               | —       | Called when the modal overlay is opened by the toggle button.                                                                                                                                |
+| `toggleFilterButtonStyle` | `ButtonStyleType`                          | "light" | Visual style of the toggle button that opens the modal.                                                                                                                                      |
+| `customLabels`            | `FilterModalCustomLabelProps`              | —       | Overrides default labels used by the modal variant.                                                                                                                                          |
+| `insets`                  | `Insets`                                   | —       | Safe-area insets applied to the modal header and footer, useful for notch or home-indicator offsets on mobile devices.                                                                       |
+| `id`                      | `string`                                   | —       | —                                                                                                                                                                                            |
+| `className`               | `string`                                   | —       | —                                                                                                                                                                                            |
+| `style`                   | `CSSProperties`                            | —       | —                                                                                                                                                                                            |
+| `count`                   | `number`                                   | —       | Number of active filter selections displayed as a badge on the header and toggle button.                                                                                                     |
+| `clearButtonDisabled`     | `boolean`                                  | false   | When `true`, the clear button is rendered in a disabled state.                                                                                                                               |
+| `onClear`                 | `(() => void)`                             | —       | Called when the clear button is pressed.                                                                                                                                                     |
+| `children`                | `ReactNode \| ((mode: Mode) => ReactNode)` | —       | Content rendered inside the filter panel. Pass a render function to receive the current `Mode` and conditionally render different content for desktop (`"default"`) and mobile (`"mobile"`). |
+| `headerTitle`             | `string`                                   | —       | —                                                                                                                                                                                            |
+| `toggleFilterButtonLabel` | `string`                                   | —       | —                                                                                                                                                                                            |
+| `doneButtonLabel`         | `string`                                   | —       | —                                                                                                                                                                                            |
+
+## Props — `FilterProps`
+
+| Prop                      | Type                                                              | Default | Description                                                                                                                                                                                  |
+| ------------------------- | ----------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `customLabels`            | `\| FilterModalCustomLabelProps \| FilterSidebarCustomLabelProps` | —       | Overrides default labels for the active variant. Only the labels relevant to the current mode (sidebar or modal) are used.                                                                   |
+| `id`                      | `string`                                                          | —       | —                                                                                                                                                                                            |
+| `className`               | `string`                                                          | —       | —                                                                                                                                                                                            |
+| `style`                   | `CSSProperties`                                                   | —       | —                                                                                                                                                                                            |
+| `count`                   | `number`                                                          | —       | Number of active filter selections displayed as a badge on the header and toggle button.                                                                                                     |
+| `clearButtonDisabled`     | `boolean`                                                         | false   | When `true`, the clear button is rendered in a disabled state.                                                                                                                               |
+| `onClear`                 | `(() => void)`                                                    | —       | Called when the clear button is pressed.                                                                                                                                                     |
+| `children`                | `ReactNode \| ((mode: Mode) => ReactNode)`                        | —       | Content rendered inside the filter panel. Pass a render function to receive the current `Mode` and conditionally render different content for desktop (`"default"`) and mobile (`"mobile"`). |
+| `headerTitle`             | `string`                                                          | —       | —                                                                                                                                                                                            |
+| `toggleFilterButtonLabel` | `string`                                                          | —       | —                                                                                                                                                                                            |
+| `doneButtonLabel`         | `string`                                                          | —       | —                                                                                                                                                                                            |
+| `onDismiss`               | `(() => void)`                                                    | —       | Called when the dismiss (close) button is pressed in the modal overlay.                                                                                                                      |
+| `onDone`                  | `(() => void)`                                                    | —       | Called when the done button is pressed in the modal overlay.                                                                                                                                 |
+| `onModalOpen`             | `() => void`                                                      | —       | Called when the modal overlay is opened by the toggle button.                                                                                                                                |
+| `toggleFilterButtonStyle` | `ButtonStyleType`                                                 | "light" | Visual style of the toggle button that opens the modal.                                                                                                                                      |
+| `insets`                  | `Insets`                                                          | —       | Safe-area insets applied to the modal header and footer, useful for notch or home-indicator offsets on mobile devices.                                                                       |
+
+## Props — `FilterItemProps`
+
+| Prop                | Type                                                                                     | Default | Description                                                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*       | `\| React.ReactNode \| ((mode: Mode, state: { minimised: boolean }) => React.ReactNode)` | —       | Content rendered inside the filter item. Pass a render function to receive the current `Mode` and minimised state, enabling content to adapt between desktop and mobile contexts. |
+| `showDivider`       | `boolean`                                                                                | true    | Whether a divider line is shown above the item in desktop mode.                                                                                                                   |
+| `showMobileDivider` | `boolean`                                                                                | true    | Whether a divider line is shown above the item in mobile mode.                                                                                                                    |
+| `title`             | `string`                                                                                 | —       | Label rendered in the item header.                                                                                                                                                |
+| `addon`             | `FormLabelAddonProps`                                                                    | —       | Optional popover addon displayed inline with the title.                                                                                                                           |
+| `className`         | `string`                                                                                 | —       | —                                                                                                                                                                                 |
+| `id`                | `string`                                                                                 | —       | —                                                                                                                                                                                 |
+| `collapsible`       | `boolean`                                                                                | true    | Whether the item can be expanded or collapsed in desktop mode. Items are always expanded in mobile mode regardless of this setting.                                               |
+| `initialExpanded`   | `boolean`                                                                                | false   | Initial expanded state for the uncontrolled component. Has no effect when `expanded` is provided.                                                                                 |
+| `expanded`          | `boolean`                                                                                | —       | Controls the expanded state. When provided, the component is controlled and `onExpandChange` must be used to update the value.                                                    |
+| `onExpandChange`    | `((expanded: boolean) => void)`                                                          | —       | Called when the user toggles the expand/collapse state.                                                                                                                           |
+| `minimisable`       | `boolean`                                                                                | false   | Whether the item content can be minimised to show a truncated height with a "View more" button.                                                                                   |
+| `minimisedHeight`   | `number`                                                                                 | —       | Height in pixels to clip the content when minimised. Defaults to 50% of content height, capped at 216 px.                                                                         |
+| `style`             | `React.CSSProperties`                                                                    | —       | —                                                                                                                                                                                 |
+
+## Props — `FilterPageProps`
+
+| Prop          | Type              | Default | Description                                       |
+| ------------- | ----------------- | ------- | ------------------------------------------------- |
+| `children` \* | `React.ReactNode` | —       | —                                                 |
+| `onDismiss`   | `(() => void)`    | —       | Called when the back (dismiss) button is pressed. |
+| `onDone`      | `(() => void)`    | —       | Called when the done button is pressed.           |
+
+## Rules
+
+-   `Filter` is the recommended entry point — it automatically renders `Filter.Sidebar` on desktop and `Filter.Modal` on mobile.
+-   Always provide `onClear` to reset all filter state in a single handler.
+-   Set `collapsible={false}` on sort sections — sort options should always be visible.
+-   Pass children as a function `(mode) => ReactNode` to render different content on desktop vs mobile.
+-   `Filter.Modal` has a built-in Done button — do not add an external Apply button; use `onDone` to react to it.
+-   Add a keyword search input (`Form.Input`) above the `Filter` component — search is not built into `Filter`.
+-   Use `count` to show the number of active filters in the header.
+-   Use `Filter.Sidebar` or `Filter.Modal` directly only when overriding the responsive behaviour.
+-   `Filter.Page` is used inside `Filter.Modal` only, for drill-down sub-pages.
+
+## Anti-patterns
+
+-   Do not pass `viewport`, `showSearch`, or `searchText` — these props do not exist.
+-   Do not use `headerTitle`, `toggleFilterButtonLabel`, or `doneButtonLabel` directly on `Filter` — these are deprecated. Use `customLabels` instead.
+-   Do not add an external Apply button when using `Filter.Modal` — the built-in Done button handles it.
+-   Do not use `Filter.Sidebar` and `Filter.Modal` separately unless you need to override responsive behaviour — use `Filter` instead.

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

@@ -0,0 +1,94 @@
+# Footer
+
+Import: `import { Footer } from "@lifesg/react-design-system/footer"`
+
+## When to use
+
+Place at the bottom of every page. Required on all pages.
+
+## Variants
+
+| Variant                 | When to use                                                      |
+| ----------------------- | ---------------------------------------------------------------- |
+| `<Footer />` (no props) | Standard pages — disclaimer links and copyright are theme-driven |
+| `links`                 | Pages with navigational footer links (max 2 columns)             |
+| `copyrightInfo`         | Custom copyright text required                                   |
+| `layout="stretch"`      | Full-width layout — pair with `Navbar layout="stretch"`          |
+
+## Usage
+
+```tsx
+import { Footer } from "@lifesg/react-design-system/footer";
+
+{
+    /* Standard footer — no props required */
+}
+<Footer />;
+
+{
+    /* Footer with navigation links */
+}
+<Footer
+    links={[
+        [
+            { children: "About us", href: "/about" },
+            { children: "Contact", href: "/contact" },
+        ],
+    ]}
+    lastUpdated={new Date("2025-01-01")}
+/>;
+```
+
+## Props — `DisclaimerLinks`
+
+| Prop                  | Type                      | Default | Description |
+| --------------------- | ------------------------- | ------- | ----------- |
+| `privacy`             | `DisclaimerTextLinkProps` | —       | —           |
+| `termsOfUse`          | `DisclaimerTextLinkProps` | —       | —           |
+| `reportVulnerability` | `DisclaimerTextLinkProps` | —       | —           |
+
+## Props — `FooterLinkProps`
+
+| Prop             | Type                       | Default     | Description                                                                                                   |
+| ---------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `data-options`   | `T`                        | —           | Any custom attributes you would like to pass to the link                                                      |
+| `weight`         | `TypographyWeight`         | "regular"   | Font weight of the link text.                                                                                 |
+| `external`       | `boolean`                  | —           | Appends an external-link icon after the link text to signal that the destination is outside the current site. |
+| `underlineStyle` | `TypographyUnderlineStyle` | "underline" | Text-decoration style for the link.                                                                           |
+
+## Props — `FooterProps`
+
+| Prop                | Type                                   | Default   | Description                                                                                                                                                                                                                  |
+| ------------------- | -------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `links`             | `FooterLinkProps<T>[][]`               | —         | The footer links. Multi array to present in different columns                                                                                                                                                                |
+| `showDownloadAddon` | `boolean`                              | —         | Indicates if the download app icons are to be present                                                                                                                                                                        |
+| `showResourceAddon` | `boolean`                              | —         | Indicates if additional app resources should be displayed. When both `showDownloadAddon` and `showResourceAddon` are `true`, `showDownloadAddon` takes priority and the resource add-on is not rendered.                     |
+| `children`          | `JSX.Element \| JSX.Element[]`         | —         | Custom component. This overrides the logo, links and download section                                                                                                                                                        |
+| `disclaimerLinks`   | `DisclaimerLinks`                      | —         | Override attributes for the built-in disclaimer links. Each supplied key is merged with the theme defaults. Omitted keys fall back to the default URLs for the active theme.                                                 |
+| `copyrightInfo`     | `string`                               | —         | A custom copyright text                                                                                                                                                                                                      |
+| `logoSrc`           | `string`                               | —         | Custom logo source                                                                                                                                                                                                           |
+| `logoAlt`           | `string`                               | —         | Custom logo alt text                                                                                                                                                                                                         |
+| `lastUpdated`       | `Date`                                 | —         | Date displayed in the copyright line as "Last updated D MMMM YYYY".                                                                                                                                                          |
+| `onFooterLinkClick` | `((link: FooterLinkProps<T>) => void)` | —         | Called when a footer navigation link is clicked. Receives the full `FooterLinkProps` for the clicked link. If the link defines its own `onClick` handler, that handler takes priority and `onFooterLinkClick` is not called. |
+| `layout`            | `"default" \| "stretch"`               | "default" | Controls whether the footer content is constrained to a maximum width or stretches to fill the full viewport width.                                                                                                          |
+| `id`                | `string`                               | —         | —                                                                                                                                                                                                                            |
+| `className`         | `string`                               | —         | —                                                                                                                                                                                                                            |
+| `hideLogo`          | `boolean`                              | —         | Suppresses the logo even when a `logoSrc` or a theme-based logo URL is available.                                                                                                                                            |
+
+## Rules
+
+-   Use `<Footer />` with no props for standard pages — do not add unnecessary props.
+-   `layout` must match the Navbar `layout` prop; do not mix `"default"` and `"stretch"`.
+-   Wrap the app in a flex column layout so the footer stays pinned to the bottom on short pages:
+    -   Outer wrapper: `display: flex; flex-direction: column; min-height: 100vh`
+    -   Page content area: `flex: 1`
+-   Disclaimer link text cannot be customised — only `href` and event handlers can be overridden via `disclaimerLinks`.
+-   `copyrightInfo` overrides `lastUpdated` — do not set both.
+-   When `showDownloadAddon` and `showResourceAddon` are both `true`, download takes precedence.
+-   `links` is a 2D array: each inner array is one column of links.
+
+## Anti-patterns
+
+-   Do not omit the flex layout wrapper — the footer will not stick to the bottom on short pages.
+-   Do not pass `children` and `links` together — `children` replaces the top section entirely.
+-   Do not customise disclaimer link labels — they are legally fixed strings.

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

@@ -0,0 +1,85 @@
+# Form.DateInput
+
+Import: `import { Form } from "@lifesg/react-design-system/form"`
+
+## When to use
+
+-   Collecting a single date from the user (e.g. date of birth, appointment date, submission deadline).
+-   Any form field that requires calendar-based date selection.
+
+## Usage
+
+```tsx
+import styles from "./MyForm.module.css";
+
+<Form.DateInput className={styles.dateInput} ... />
+```
+
+```css
+/* MyForm.module.css */
+:where(body.fds-breakpoint-lg-min) .dateInput {
+    max-width: 24rem;
+}
+```
+
+Defaults to 4 columns wide at `lg` and above; full-width on mobile. Use `max-width` via a CSS Module class — `max-width` constrains the component without conflicting with its internal `width: 100%`.
+
+## YearMonthDisplay
+
+| Prop    | Type     | Description                       |
+| ------- | -------- | --------------------------------- |
+| `year`  | `number` | Currently displayed year (`YYYY`) |
+| `month` | `number` | Currently displayed month (1–12)  |
+
+## Props
+
+| Prop                       | Type                                  | Default       | Description                                                                                                                                             |
+| -------------------------- | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`                | `string`                              | —             | —                                                                                                                                                       |
+| `id`                       | `string`                              | —             | —                                                                                                                                                       |
+| `dropdownRootNode`         | `RefObject<HTMLElement>`              | document.body | The root element that contains the dropdown element.                                                                                                    |
+| `readOnly`                 | `boolean`                             | —             | —                                                                                                                                                       |
+| `hideInputKeyboard`        | `boolean`                             | —             | When `true`, suppresses the native on-screen keyboard on mobile devices while still allowing the calendar picker to open.                               |
+| `value`                    | `string`                              | —             | The controlled value of the date input in `"YYYY-MM-DD"` or `"YYYY-M-D"` string format.                                                                 |
+| `error`                    | `boolean`                             | —             | Renders the input in an error state.                                                                                                                    |
+| `disabled`                 | `boolean`                             | —             | —                                                                                                                                                       |
+| `withButton`               | `boolean`                             | true          | Whether to show "Done" and "Cancel" action buttons inside the calendar dropdown. When `false`, a selection immediately commits and closes the calendar. |
+| `zIndex`                   | `number`                              | —             | The z-index of the calendar dropdown.                                                                                                                   |
+| `onChange`                 | `((value: string) => void)`           | —             | Called when the user commits a date selection. Receives the selected date as a `"YYYY-MM-DD"` string, or an empty string when the selection is cleared. |
+| `onFocus`                  | `(() => void)`                        | —             | Called when the input receives focus.                                                                                                                   |
+| `onBlur`                   | `(() => void)`                        | —             | Called when focus leaves both the input and the calendar dropdown.                                                                                      |
+| `onYearMonthDisplayChange` | `((value: YearMonthDisplay) => void)` | —             | Called when the visible month or year in the calendar changes.                                                                                          |
+| `minDate`                  | `string`                              | —             | The minimum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                                                                               |
+| `maxDate`                  | `string`                              | —             | The maximum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                                                                               |
+| `disabledDates`            | `string[]`                            | —             | Dates to disable in `YYYY-MM-DD` format. Example: `["2023-04-30"]`                                                                                      |
+| `allowDisabledSelection`   | `boolean`                             | —             | Specifies if dates normally disabled by `minDate`, `maxDate` and `disabledDates` are still selectable                                                   |
+| `showActiveMonthDaysOnly`  | `boolean`                             | —             | Specifies if the calendar should display only dates for the selected month                                                                              |
+| `label`                    | `FormLabelProps \| string`            | —             | Label rendered above the input. Accepts a plain string or a `FormLabelProps` object to provide additional configuration.                                |
+| `errorMessage`             | `string \| React.ReactNode`           | —             | Inline error text rendered below the input.                                                                                                             |
+| `layoutType`               | `FormElementLayoutType`               | —             | Controls whether the container uses flex layout or a responsive column grid.                                                                            |
+| `xxlCols`                  | `ColSpan`                             | —             | Column span at the `xxl` breakpoint.                                                                                                                    |
+| `xlCols`                   | `ColSpan`                             | —             | Column span at the `xl` breakpoint.                                                                                                                     |
+| `lgCols`                   | `ColSpan`                             | —             | Column span at the `lg` breakpoint.                                                                                                                     |
+| `mdCols`                   | `ColSpan`                             | —             | Column span at the `md` breakpoint.                                                                                                                     |
+| `smCols`                   | `ColSpan`                             | —             | Column span at the `sm` breakpoint.                                                                                                                     |
+| `xsCols`                   | `ColSpan`                             | —             | Column span at the `xs` breakpoint.                                                                                                                     |
+| `xxsCols`                  | `ColSpan`                             | —             | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set.        |
+
+## Rules
+
+-   Always supply a `label` so the field is accessible.
+-   Pass `value` and `onChange` together for controlled usage; `onChange` receives a `YYYY-MM-DD` string.
+-   Use `minDate`/`maxDate` to constrain selectable dates to valid business ranges.
+-   Use `disabledDates` for known blackout dates (e.g. public holidays).
+-   Set `errorMessage` rather than `error` alone so users understand what is wrong.
+-   Use `withButton` (default `true`) to require explicit confirmation before the value is committed.
+-   Use `readOnly` on review or summary screens where the value should be visible but not editable.
+-   Specify `dropdownRootNode` if the component is inside a scrollable container to prevent the calendar from clipping.
+-   Date strings use `YYYY-MM-DD` format throughout (value, minDate, maxDate, disabledDates, onChange return).
+
+## Anti-patterns
+
+-   Do not use a plain text input for date collection — the picker enforces valid date formats automatically.
+-   Do not set `allowDisabledSelection` unless there is a specific UX reason to allow out-of-range dates.
+-   Do not rely on `error` prop alone without an `errorMessage`; users need descriptive feedback.
+-   Do not use for date-range selection — use `Form.DateRangeInput` instead.