@arbor-education/design-system.components 0.9.0 → 0.11.0

package/.claude/component-library.md

@@ -0,0 +1,1107 @@
+# Arbor Design System — Component Library Manifest
+
+> Auto-generated reference for AI agents (Sophia, analyze-design, etc.)
+> Source: `src/components/` · Public API: `src/index.ts`
+> Last updated: 2026-04-17
+
+---
+
+## Design Tokens Overview
+
+File: `src/tokens.scss` — Auto-generated CSS custom properties on `:root`.
+
+| Category | Key tokens |
+|---|---|
+| **Spacing** | `--spacing-xsmall` (4px), `--spacing-small` (8px), `--spacing-medium` (12px), `--spacing-large` (16px), `--spacing-xlarge` (24px), `--spacing-xxlarge` (32px), `--spacing-xxxlarge` (64px) |
+| **Border radius** | `--border-radius-xsmall` (4px), `--border-radius-small` (8px), `--border-radius-large` (16px), `--border-radius-round` (99px) |
+| **Font sizes** | `--font-size-1-11` → `--font-size-8-40` (11px–40px) |
+| **Font families** | `--font-family-display: Grenette`, `--font-family-standard: Inter` |
+| **Font weights** | `--font-weight-regular` (400), `--font-weight-medium` (500), `--font-weight-semi-bold` (600), `--font-weight-bold` (700) |
+| **Brand colors** | `--color-brand-050` → `--color-brand-900` (greens; brand green = `#3cad51`) |
+| **Semantic colors** | info, caution, success, warning, destructive scales (050–900) |
+| **Grey scale** | `--color-grey-050` → `--color-grey-900` |
+| **Chart colors** | red, blue, teal, green, orange, purple, yellow (1–4 variants each) |
+| **Extended colors** | blue, teal, green, orange, purple, salmon, yellow (050/100/500/800) |
+| **Gradient ramps** | diverging and sequential ramps (050–900) |
+| **Shadow** | `--shadow-small` |
+| **Icon sizes** | `--icon-size-xsmall` (12px), `--icon-size-small` (16px), `--icon-size-medium` (24px) |
+| **Focus** | `--focus-color-focus: var(--color-brand-500)`, `--focus-border: 3px` |
+| **Avatar sizes** | `--avatar-small-size` (1.25rem), `--avatar-medium-size` (2rem), `--avatar-large-size` (3rem), `--avatar-extra-large-size` (6rem) |
+| **Control sizes** | `--size-control-xsmall` → `--size-control-xlarge` (2rem–5rem) |
+
+Component-scoped tokens follow: `--{component}-{state}-{property}` (e.g. `--button-primary-default-color-background`, `--tag-neutral-color-text`).
+
+---
+
+## Component Manifest
+
+### 0a. Badge
+
+**File:** `src/components/badge/Badge.tsx` · **Public export:** Yes
+**Also exports:** `BadgeColour`, `BadgeProps`, `BadgeSize` types
+
+**Use case:** Small coloured label/count badge for categorisation, notification counts, or status indicators.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `children` | `ReactNode` | Yes | — | Badge content |
+| `size` | `'sm' \| 'md' \| 'lg'` | No | `'md'` | Visual size |
+| `colour` | `BadgeColour` | No | — | Color variant |
+| `a11yLabel` | `string` | No | — | Accessible label (hides children from SR, shows aria-label) |
+| `className` | `string` | No | — | Additional CSS class |
+
+**`BadgeColour` / `DotColour` values:** `'purple'` · `'salmon'` · `'teal'` · `'yellow'` · `'green'` · `'orange'` · `'blue'`
+
+---
+
+### 0b. Dot
+
+**File:** `src/components/dot/Dot.tsx` · **Public export:** Yes
+**Also exports:** `DotColour` type
+
+**Use case:** Small coloured circle indicator. Used inside `Tag` (optional dot prefix) and standalone for status indicators.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `colour` | `DotColour` | Yes | — | Dot colour |
+| `label` | `string` | No | — | Accessible label; if omitted, dot is `aria-hidden` |
+
+---
+
+### 1. Avatar
+
+**File:** `src/components/avatar/Avatar.tsx` · **Public export:** Yes
+
+**Use case:** Display a user's profile picture, initials, or generic silhouette. Building block for `AvatarGroup` and `UserDropdown`.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `size` | `'small' \| 'medium' \| 'large' \| 'extra-large'` | No | `'medium'` | Visual size |
+| `src` | `string` | No | — | Image URL |
+| `alt` | `string` | No | `''` | Alt text / aria-label |
+| `initials` | `string` | No | — | Text initials if no image |
+| `className` | `string` | No | — | Additional CSS class |
+
+**Variants:** size × content mode (image → initials → placeholder SVG silhouette, in priority order)
+
+**Key features:**
+- Three rendering modes, prioritised: image → initials → placeholder SVG
+- `aria-hidden` on image; `aria-label` on initials/placeholder
+- CSS: `ds-avatar`, `ds-avatar--{size}`
+
+---
+
+### 2. AvatarGroup
+
+**File:** `src/components/avatarGroup/AvatarGroup.tsx` · **Public export:** Yes
+**Also exports:** `AvatarGroupItem`, `AvatarGroupListOrder`, `AvatarGroupOverflowCountProps`, `AvatarGroupProps` types
+
+**Use case:** Horizontal stack of user avatars with optional overflow count. Used for groups, assignments, and teams.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `items` | `readonly AvatarGroupItem[]` | Mutually exclusive with `children` | — | Flat array of avatar data |
+| `children` | `React.ReactNode` | Mutually exclusive with `items` | — | Composable `<Avatar />` children |
+| `size` | `AvatarSize` | No | — | Overrides size of all avatars |
+| `showMaxItems` | `number` | No | — | Max visible avatars before overflow |
+| `listOrder` | `'ascending' \| 'descending'` | No | `'ascending'` | Which avatars shown when truncating |
+| `label` | `string` | No | — | `aria-label` on the `<ul>` |
+| `overflowCountLabel` | `string \| ((count: number) => string)` | No | `'plus N more'` | SR label for overflow badge |
+| `presentAllUpdatesToScreenReader` | `boolean` | No | `false` | `aria-live="polite"` on overflow count |
+
+**Sub-components:** `AvatarGroup.OverflowCount`
+
+**Key features:**
+- Dual API: `items` prop array OR composable `children`
+- Group-level `size` overrides individual sizes
+- `AvatarGroupItem` type: `{ src?, alt?, initials?, size?, className? }`
+
+---
+
+### 3. Banner
+
+**File:** `src/components/banner/Banner.tsx` · **Public export:** Yes
+**Also exports:** `BANNER_LEVEL` (enum), `BannerProps` (type)
+
+**Use case:** Full-width contextual messaging strip for alerts, warnings, session notices, and errors.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `level` | `BANNER_LEVEL` | No | `BANNER_LEVEL.NEUTRAL` | Semantic level |
+| `title` | `string` | No | — | Bold heading text |
+| `text` | `string` | No | — | Body text |
+| `buttonText` | `string` | No | — | CTA button label |
+| `buttonOnClick` | `(e: React.MouseEvent<HTMLButtonElement>) => void` | No | — | CTA button handler |
+| `icon` | `IconName` | No | Auto from level | Override leading icon |
+| `hideIcon` | `boolean` | No | `false` | Suppress icon |
+
+**`BANNER_LEVEL` values:** `INFO` (blue), `NEUTRAL` (grey), `WARNING` (yellow), `DESTRUCTIVE` (red)
+
+**Default icon map:** `INFO`/`NEUTRAL` → `info`, `WARNING` → `triangle-alert`, `DESTRUCTIVE` → `circle-alert`
+
+**Key features:**
+- Built with CVA (class-variance-authority)
+- CTA rendered as `Button variant="text-link"` aligned right
+- Not dismissable by default
+
+---
+
+### 4. Button
+
+**File:** `src/components/button/Button.tsx` · **Public export:** Yes
+
+**Use case:** Primary interactive element for form submissions, action triggers, navigation, and as trigger targets for Dropdown/Tooltip.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `variant` | `ButtonVariant` | No | `'primary'` | Visual variant |
+| `size` | `'M' \| 'S'` | No | `'M'` | Size |
+| `children` | `React.ReactNode` | No | — | Button label |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+| `error` | `boolean` | No | — | Error state styling |
+| `hasHorizontalPadding` | `boolean` | No | `true` | Adds/removes horizontal padding |
+| `iconRightName` | `IconName` | No | — | Icon after text |
+| `iconRightScreenReaderText` | `string` | No | icon name | SR text for right icon |
+| `iconLeftName` | `IconName` | No | — | Icon before text |
+| `iconLeftScreenReaderText` | `string` | No | icon name | SR text for left icon |
+| `borderless` | `boolean` | No | `false` | Removes border |
+| `onClick` | `(event: React.MouseEvent<HTMLButtonElement>, ...otherArgs: unknown[]) => void` | No | — | Click handler |
+
+**`ButtonVariant` values:** `'primary'` · `'secondary'` · `'tertiary'` · `'primary-destructive'` · `'secondary-destructive'` · `'text-link'` · `'dropdown'`
+
+**Key features:**
+- `forwardRef` — ref forwarded to `<button>`
+- Icon-only mode auto-applied when no `children` but icons are set
+- Does NOT set HTML `type` attribute (caller responsibility)
+- `'dropdown'` variant used internally by SelectDropdown, ColourPickerDropdown, etc.
+
+---
+
+### 5. Card
+
+**File:** `src/components/card/Card.tsx` · **Public export:** Yes
+
+**Use case:** Navigational or informational content block for module selection, settings pages, or pick-from-a-list UIs.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `title` | `string` | No | — | Card heading |
+| `paragraph` | `string` | No | — | Descriptive text |
+| `icon` | `IconName` | No | — | Leading icon |
+| `iconColor` | `string` | No | — | Icon color override |
+| `iconScreenReaderText` | `string` | No | — | SR text for icon |
+| `tagText` | `string` | No | — | Tag label inside card |
+| `tagColor` | `TagColor` | No | — | Tag color |
+| `onClick` | `(e: React.MouseEvent<HTMLElement>) => void` | No | — | Makes card clickable |
+| `disabled` | `boolean` | No | — | Disables interaction |
+
+**Variants:** clickable (chevron + arrow icons, cursor pointer) / static / disabled
+
+**Key features:**
+- Renders as `<article>`
+- Clickable cards get `tabIndex={0}` for keyboard access
+- `aria-label="Card"` hardcoded — consider overriding via `...rest`
+
+---
+
+### 6. Combobox
+
+**File:** `src/components/combobox/Combobox.tsx` · **Public export:** Yes
+**Also exports:** `ComboboxProps`, `ComboboxOption`, `ComboboxAriaInvalid`, `ComboboxCreateResult`, `ComboboxSearchFn`, `ComboboxSearchType` types
+
+**Use case:** Searchable, filterable, optionally multi-select dropdown. Supports async search, option grouping, chip tags, create-new, and custom renderers.
+
+**`ComboboxOption` shape:** `{ value: string, label: string, tagLabel?: string, iconName?: IconName, disabled?: boolean, group?: string }`
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `options` | `ComboboxOption[]` | Yes | — | List of options |
+| `multiple` | `boolean` | No | `false` | Multi-select |
+| `value` | `string[]` | No | — | Controlled selected values (array even in single mode) |
+| `defaultValue` | `string[]` | No | — | Uncontrolled initial values |
+| `onValueChange` | `(values: string[]) => void` | No | — | Selection change callback |
+| `onSearch` | `(query: string) => void` | No | — | Async search callback; enables async mode |
+| `searchType` | `'prefix' \| 'substring' \| fn` | No | `'prefix'` | Built-in filter strategy |
+| `highlightStringMatches` | `boolean` | No | `false` | Highlights matched text in options |
+| `allowCreate` | `boolean` | No | `false` | Shows "Create X" row, calls `onCreateNew` |
+| `onCreateNew` | `(input: string) => ComboboxCreateResult` | No | — | Create callback |
+| `onDeleteCreated` | `(value: string) => void` | No | — | Delete created option callback |
+| `placeholder` | `string` | No | `'Select...'` | Placeholder text |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+| `dropdownOnFocus` | `boolean` | No | `true` | Open dropdown on focus |
+| `triggerVariant` | `'input' \| 'button'` | No | `'input'` | `'input'` = inline text trigger; `'button'` = button opens dropdown with search inside |
+| `selectedValueDisplay` | `'tags' \| 'text'` | No | `'tags'` | `'tags'` = removable chip tags; `'text'` = plain text |
+| `showDropdownTrigger` | `boolean` | No | `true` | Show/hide the chevron button |
+| `triggerEndContent` | `ReactNode` | No | — | Custom content at end of trigger |
+| `showSelectionCountBadge` | `boolean` | No | auto | Shows count badge (auto-enabled for button+multiple) |
+| `selectionCountA11yLabel` | `string \| ((count: number) => string)` | No | — | SR label for badge count |
+| `loading` | `boolean` | No | `false` | Loading state in listbox |
+| `hasError` | `boolean` | No | `false` | Error state |
+| `showClearAll` | `boolean` | No | `false` | Show "Clear all" below trigger when items selected |
+| `clearAllLabel` | `string` | No | `'Clear all'` | Label for clear button |
+| `renderOption` | `(option, selected) => ReactNode` | No | — | Custom option renderer |
+| `getTagLabel` | `(option) => string` | No | — | Custom tag label getter |
+| `id`, `aria-describedby`, `aria-invalid`, `aria-label` | — | No | — | Standard ARIA props |
+
+**Sub-components:** `Combobox.Trigger`, `Combobox.ButtonTrigger`, `Combobox.Listbox` (advanced composition)
+
+**Key features:**
+- Options with the same `group` string are visually grouped under a heading
+- Radix Popover rendered into `PopupParentContext`
+- Keyboard-navigable: arrow keys, Enter to select, Escape to close, Backspace to remove tags
+
+---
+
+### 6b. DatePicker
+
+**File:** `src/components/datePicker/DatePicker.tsx` · **Public export:** Yes
+
+**Use case:** Date selection via combined text input (free-type) and calendar popover for forms, filters, and settings.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `value` | `Date` | No | — | Controlled selected date |
+| `defaultValue` | `Date` | No | — | Uncontrolled initial date |
+| `onChange` | `(newDate?: Date) => void` | No | — | Called when date changes or is cleared |
+| `displayFormat` | `DateDisplayFormat` | No | `'default'` | Display format (e.g. 'dmy', 'mdy') |
+| `placeholder` | `string` | No | Format-derived | Placeholder text |
+| `id` | `string` | No | — | Applied to text input |
+| `hasError` | `boolean` | No | — | Error state |
+| `aria-describedby` | `string` | No | — | ARIA description |
+| `aria-invalid` | `boolean` | No | — | ARIA invalid |
+
+**Key features:**
+- Dual input: type directly OR open calendar via icon button
+- Powered by `react-day-picker`
+- Calendar popup uses Radix `Popover` rendered into `PopupParentContext`
+- Month/year navigation in calendar header
+- `onChange` called with `undefined` when date is cleared
+
+---
+
+### 7. Dropdown
+
+**File:** `src/components/dropdown/Dropdown.tsx` · **Public export:** Yes
+
+**Use case:** General-purpose contextual menu or action panel. Foundation for `SelectDropdown`, `ColourPickerDropdown`, `UserDropdown`, `BulkActionsDropdown`, `TableSettingsDropdown`.
+
+**Compound components:**
+
+| Sub-component | Description |
+|---|---|
+| `Dropdown.Trigger` | Wraps trigger element with `asChild` |
+| `Dropdown.Content` | Portal + content panel |
+| `Dropdown.Item` | Standard menu item |
+| `Dropdown.SelectItem` | Checkbox-style selectable item |
+| `Dropdown.Separator` | Visual divider |
+| `Dropdown.Group` | Groups items together |
+
+**`Dropdown.Content` key props:** `portalProps`, `contentProps` (align defaults `'start'`), `className`
+
+**`Dropdown.SelectItem` key props:** `selected` (required), `onSelectChange` (required), `closeAfterSelection` (default `true`)
+
+**Key features:**
+- Built on Radix UI `DropdownMenu` primitives
+- Portal rendered into `PopupParentContext` ref
+- `modal={false}` by default — no body scroll lock
+- `closeAfterSelection={false}` for multi-select UIs
+
+---
+
+### 8. EditableText
+
+**File:** `src/components/editableText/EditableText.tsx` · **Public export:** Yes
+
+**Use case:** Inline editable text — click to edit, Enter/blur to save, Escape to cancel. Suitable for table cell names, titles, any occasionally-edited label.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `text` | `string` | Yes | — | Current text value |
+| `onEditSave` | `(newText: string) => void` | Yes | — | Called when editing is committed |
+| `isEditing` | `boolean` | No | `false` | Controlled editing state |
+| `multiline` | `boolean` | No | `false` | Use `TextArea` instead of `TextInput` |
+
+**Key features:**
+- Toggle between display (button + pencil icon) and edit (TextInput/TextArea)
+- `autoFocus` on input when entering edit mode
+- Enter saves (single-line); Escape cancels and restores value
+- `isEditing` prop allows programmatic control
+
+---
+
+### 9. FormField
+
+**File:** `src/components/formField/FormField.tsx` · **Public export:** No (internal)
+
+**Use case:** Complete form field wrapper combining label, description, input, error text, and helper link. The preferred way to render any form input with consistent layout and accessibility wiring.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `label` | `string` | No | — | Field label |
+| `id` | `string` | No | — | Associates label and input |
+| `inputType` | `'text' \| 'textarea' \| 'number' \| 'colourPicker' \| 'selectDropdown' \| 'datePicker'` | No | `'text'` | Which input to render |
+| `inputProps` | Varies by `inputType` | No | — | Props forwarded to the input |
+| `fieldDescription` | `ReactNode` | No | — | Descriptive text below label |
+| `helperLinkText` | `string` | No | — | Helper link label |
+| `helperLinkUrl` | `string` | No | — | Helper link URL |
+| `errorText` | `string` | No | — | Error message |
+
+**Key features:**
+- Auto-wires `aria-describedby` to description and error IDs
+- Sets `hasError` and `aria-invalid` on inner input when `errorText` present
+- Error icon: `triangle-alert`; helper link icon: `arrow-up-right`
+
+---
+
+### 10. Fieldset
+
+**File:** `src/components/formField/fieldset/Fieldset.tsx` · **Public export:** Yes
+
+**Use case:** Groups related form controls (checkboxes, radios) with semantic `<fieldset>/<legend>`.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `legend` | `string` | No | — | Renders `<legend>` |
+| `children` | `ReactNode` | No | — | Form controls |
+| `...rest` | `HTMLProps<HTMLFieldSetElement>` | No | — | Native fieldset attributes (incl. `disabled`) |
+
+**Key features:**
+- Native `disabled` disables all child inputs in one prop
+- Used internally by `CheckboxGroup` and `RadioButtonGroup`
+
+---
+
+### 11. TextInput
+
+**File:** `src/components/formField/inputs/text/TextInput.tsx` · **Public export:** Yes
+
+**Use case:** Standard single-line text input for forms. Used by `FormField`, `DatePicker`, `EditableText`, `InlineTextCellRenderer`.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `size` | `'M' \| 'S'` | No | `'M'` | Input height |
+| `hasError` | `boolean` | No | — | Error state styling |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+
+---
+
+### 12. TextArea
+
+**File:** `src/components/formField/inputs/textArea/TextArea.tsx` · **Public export:** Yes
+
+**Use case:** Multi-line text input that auto-grows to fit content.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `hasError` | `boolean` | No | — | Error state |
+| `autoSize` | `boolean` | No | `true` | Auto-grows height |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+
+**Key features:**
+- `autoSize` sets explicit `height` from `scrollHeight` on each change — grows down, never scrolls internally
+
+---
+
+### 13. NumberInput
+
+**File:** `src/components/formField/inputs/number/NumberInput.tsx` · **Public export:** Yes
+
+**Use case:** Numeric input with +/− spinner buttons. Uses `Decimal.js` for precise arithmetic.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `hasError` | `boolean` | No | — | Error state |
+| `disableSpinners` | `boolean` | No | `false` | Hide increment/decrement buttons |
+| `step` | `number` | No | `1` | Spinner step size |
+| `min` | `number` | No | `-Infinity` | Minimum value |
+| `max` | `number` | No | `Infinity` | Maximum value |
+
+**Key features:**
+- Renders as `type="text"` with `inputMode="numeric"` (avoids browser native spinner styling)
+- Clamps value to `min`/`max` on blur and spinner click
+
+---
+
+### 14. CheckboxInput
+
+**File:** `src/components/formField/inputs/checkbox/CheckboxInput.tsx` · **Public export:** Yes (exported from index.ts line 24)
+
+**Use case:** Single styled checkbox with optional inline label. Used standalone or via `CheckboxGroup`.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `checked` | `boolean` | No | `false` | Checked state |
+| `indeterminate` | `boolean` | No | `false` | Indeterminate state |
+| `label` | `string` | No | — | Inline label text |
+| `disabled` | `boolean` | No | — | Disabled state |
+
+**Key features:**
+- Real `<input type="checkbox">` visually hidden; custom `<span>` visible
+- `indeterminate` set via DOM API; `aria-checked="mixed"` when indeterminate
+- Icons: `check` (checked), `minus` (indeterminate)
+
+---
+
+### 15. CheckboxGroup
+
+**File:** `src/components/formField/inputs/checkbox/CheckboxGroup.tsx` · **Public export:** No (internal)
+
+**Use case:** Group of related checkboxes within a `Fieldset`. Used in `TableSettingsDropdown`.
+
+**Props:** `options: CheckboxInputProps[]` + all `FieldsetProps`
+
+---
+
+### 16. RadioButtonInput
+
+**File:** `src/components/formField/inputs/radio/RadioButtonInput.tsx` · **Public export:** Yes
+
+**Use case:** Single radio button with inline label. Combine multiple with `RadioButtonGroup`.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `label` | `string` | No | — | Inline label |
+| `hasError` | `boolean` | No | — | Error state |
+| `name` | `string` | No | — | Radio group name |
+| `value` | `string` | No | — | Radio value |
+| `checked` | `boolean` | No | `false` | Selected state |
+| `disabled` | `boolean` | No | `false` | Disabled state |
+
+**Key features:** `type` hardcoded to `"radio"`, cannot be overridden
+
+---
+
+### 17. RadioButtonGroup
+
+**File:** `src/components/formField/inputs/radio/RadioButtonGroup.tsx` · **Public export:** No (internal)
+
+**Use case:** Controlled group of radio buttons within a `Fieldset`. Used in `TableSettingsDropdown` for spacing selection.
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | Yes | Shared group name |
+| `options` | `RadioButtonInputProps[]` | Yes | Radio option configs |
+| `checkedValue` | `string` | Yes | Currently selected value |
+| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | Yes | Change handler |
+| `legend` | `string` | No | Fieldset legend |
+
+---
+
+### 18. SelectDropdown
+
+**File:** `src/components/formField/inputs/selectDropdown/SelectDropdown.tsx` · **Public export:** Yes
+
+**Use case:** Styled single or multi-select dropdown. Supports option grouping, icons, and two-line option layouts.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `options` | `SelectDropdownItemProps[]` | Yes | — | List of options |
+| `multiple` | `boolean` | No | — | Multi-select mode |
+| `placeholder` | `string` | No | `'Select'` | Placeholder text |
+| `disabled` | `boolean` | No | — | Disabled state |
+| `hasError` | `boolean` | No | — | Error state |
+| `onSelectionChange` | `(value: string[]) => void` | No | — | Selection callback |
+| `alwaysShowPlaceholder` | `boolean` | No | `false` | Always show placeholder (not selected label) |
+| `initialSelectedValues` | `string[]` | No | `[]` | Pre-selected values |
+| `open` | `boolean` | No | — | Controlled open state |
+| `onOpenChange` | `(open: boolean) => void` | No | — | Open state change handler |
+
+**`SelectDropdownItemProps`:** `{ value, label?, icon?, header?, group? }`
+
+**Key features:**
+- Groups options by `group` field with `<h3>` group headers
+- Hidden `<input type="hidden">` for form serialization
+- Trigger: `Button variant="dropdown"` with `chevron-down`
+- Multi-select: deselect by clicking again; dropdown stays open
+
+---
+
+### 19. ColourPickerDropdown
+
+**File:** `src/components/formField/inputs/colourPickerDropdown/ColourPickerDropdown.tsx` · **Public export:** Yes
+
+**Use case:** Color selection input showing a swatch + hex value. Opens a Sketch-style picker dropdown.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `value` | `string` | No | `'#3cad51'` | Current hex color |
+| `onChange` | `(value: ColorResult) => void` | No | — | Color change callback |
+| `hasError` | `boolean` | No | — | Error state |
+| `disabled` | `boolean` | No | — | Disabled state |
+
+**Key features:**
+- Built on `@uiw/react-color` `<Sketch>` — alpha channel disabled
+- Hidden `<input type="hidden">` stores hex value for form serialization
+
+---
+
+### 20. Heading
+
+**File:** `src/components/heading/Heading.tsx` · **Public export:** Yes
+
+**Use case:** Semantic heading element mapping a numeric `level` to the correct `h1`–`h4` HTML tag.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `level` | `1 \| 2 \| 3 \| 4` | No | `1` | Heading element level |
+| `children` | `ReactNode` | No | — | Content |
+
+**Sub-components:** `Heading.InnerContainer` — `<span>` for flex layout inside headings (title left, buttons right)
+
+---
+
+### 21. Icon
+
+**File:** `src/components/icon/Icon.tsx` · **Public export:** Yes
+
+**Use case:** Renders a single icon from the curated allowed-icons set. Standard icon primitive used throughout.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `IconName` | Yes | — | Icon identifier |
+| `size` | `12 \| 16 \| 24` | No | `16` | Pixel size |
+| `color` | `string` | No | `'currentColor'` | SVG color |
+| `screenReaderText` | `string` | No | — | Visually hidden SR label |
+
+**Icon library:** ~100+ icons from `lucide-react` + 5 custom: `ask-arbor`, `google`, `check-solid`, `x-solid`, `favourite-filled`
+
+**Key icons:** `search`, `settings`, `chevron-down/up/left/right`, `x`, `check`, `info`, `triangle-alert`, `circle-alert`, `circle-check`, `pencil`, `trash`, `plus`, `minus`, `date`, `user`, `users`, `arrow-right`, `arrow-left`, `log-out`, `sparkles`, `funnel`, `sorting`, `grab`, `pin`, `lock`, `lock-open`, `eye`, `eye-off`
+
+**Key features:**
+- `aria-hidden` on SVG; accessible text via `<span className="sr-only">` when `screenReaderText` provided
+- `IconName` type constrains to approved set — TypeScript errors on unknown names
+- `IconSize` is `12 | 16 | 24` only — not arbitrary values
+
+---
+
+### 22. Modal
+
+**Files:** `src/components/modal/Modal.tsx` + `src/components/modal/modalManager/ModalManager.tsx` · **Public export:** Yes (both)
+
+**Use case:**
+- `Modal`: Self-managed dialog, controlled via `open`/`closeHandler`
+- `ModalManager`: Mount once at app root; open modals imperatively via `ModalUtils` from anywhere
+
+**`Modal` props:**
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `open` | `boolean` | No | — | Controlled open state |
+| `title` | `string` | No | — | Shortcut title (renders `ModalHeader` + `ModalTitle`) |
+| `closeHandler` | `() => void` | No | — | Close callback; enables X button + Escape |
+| `hideCloseButton` | `boolean` | No | `false` | Hide the X button |
+| `children` | `ReactNode` | No | — | Modal body |
+| `portalTarget` | `HTMLElement \| null` | No | — | Custom portal target |
+
+**Sub-components:** `Modal.Header`, `Modal.Body`, `Modal.Footer`, `Modal.CloseButton`, `Modal.Title`
+
+**Imperative API (`ModalUtils`):**
+- `ModalUtils.addModal(props: ModalProps)` — open a modal
+- `ModalUtils.removeModal()` — close current modal
+- `ModalUtils.removeAllModals()` — clear all
+
+**Key features:**
+- Built on Radix UI `Dialog`
+- Sets up `PopupParentContext.Provider` — dropdowns/tooltips inside modals render at correct z-index
+- `ModalContext` provides `closeHandler` to `Modal.CloseButton` — no prop drilling
+
+---
+
+### 23. Pill
+
+**File:** `src/components/pill/Pill.tsx` · **Public export:** Yes
+
+**Use case:** Filter pills or toggle chips for filter bars where users activate/deactivate multiple categories.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `text` | `string` | Yes | — | Label text |
+| `checkbox` | `boolean` | No | — | Renders as checkbox pill |
+| `initialValue` | `boolean` | No | `false` | Initial checked/active state |
+| `onclick` | `(checked: boolean) => void` | No | — | State change callback |
+
+**Variants:** Toggle pill (active/inactive) · Checkbox pill (checked/unchecked, with embedded `CheckboxInput`)
+
+---
+
+### 24. Progress
+
+**File:** `src/components/progress/Progress.tsx` · **Public export:** Yes
+
+**Use case:** Horizontal progress bar for uploads, completion rates, loading indicators.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `value` | `number` | No | `0` | Current value |
+| `max` | `number` | No | `100` | Maximum value |
+| `indicatorClassName` | `string` | No | `''` | Class on progress bar |
+
+**Key features:**
+- Built on Radix UI `Progress`
+- Animation via `transform: translateX(-{100 - percentage}%)` on indicator
+- Provide `aria-label` via `...rest` for accessibility
+
+---
+
+### 25. SearchBar
+
+**File:** `src/components/searchBar/SearchBar.tsx` · **Public export:** Yes
+
+**Use case:** Search input that starts compact (icon/label) and expands on click. Used in `TableHeader` and space-efficient search UIs.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `searchValue` | `string` | No | — | Controlled search value |
+| `setSearchValue` | `(searchValue: string) => void` | No | — | Value change handler |
+| `placeholderText` | `string` | No | — | Text in inactive/expanded state |
+| `hoverText` | `string` | No | — | Text on hover of inactive button |
+| `alwaysOpen` | `boolean` | No | `false` | Always show expanded input |
+
+**Variants:** Collapsible (toggle on click) · `alwaysOpen` (always expanded, no clear button)
+
+---
+
+### 26. Section
+
+**File:** `src/components/section/Section.tsx` · **Public export:** Yes
+
+**Use case:** Page layout container with heading, optional action button, optionally collapsible content. Primary structural component for organising page regions.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `title` | `string` | No | — | Heading text |
+| `headingLevel` | `1 \| 2 \| 3 \| 4` | No | `1` | HTML heading level |
+| `titleIconName` | `IconName` | No | — | Icon beside title |
+| `collapsible` | `boolean` | No | `false` | Enable expand/collapse |
+| `collapsed` | `boolean` | No | `false` | Initial collapsed state |
+| `buttonText` | `string` | No | — | Action button label in header |
+| `buttonOnClick` | `MouseEventHandler<HTMLButtonElement>` | No | — | Action button handler |
+| `buttonVariant` | `ButtonVariant` | No | — | Action button variant |
+| `buttonSize` | `ButtonSize` | No | — | Action button size |
+| `children` | `ReactNode` | No | — | Section content |
+
+**Key features:**
+- Renders as `<section>` with implicit ARIA `region` role
+- Collapsible: toggle on click/Enter/Space; `aria-expanded` on toggle; chevron direction indicates state
+
+---
+
+### 27. Separator
+
+**File:** `src/components/separator/Separator.tsx` · **Public export:** Yes
+
+**Use case:** Visual divider between sections or menu items.
+
+**Props:** `orientation: 'horizontal' | 'vertical'` (default horizontal), `decorative: boolean`
+
+**Key features:**
+- Built on Radix UI `Separator`
+- `decorative={true}` sets `role="none"` for non-semantic use
+
+---
+
+### 28. Slideover
+
+**File:** `src/components/slideover/Slideover.tsx` · **Public export:** Yes
+
+**Use case:** Slide-in side panel from the right. Supports stacking multiple slideovers. Used for detail views, edit forms, and drill-down navigation.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `title` | `string` | No | — | Header title text |
+| `children` | `ReactNode` | No | — | Main content |
+| `footerContents` | `ReactNode` | No | — | Footer content |
+| `headerIcon` | `IconName` | No | — | Icon in header |
+| `centerHeaderText` | `boolean` | No | `true` | Centers header text |
+| `hideBackButton` | `boolean` | No | — | Hides "Back" button |
+
+**Key features:**
+- Renders as `<aside>`
+- "Back" button calls `SlideoverUtils.removeSlideover()` to pop the stack
+
+---
+
+### 29. SlideoverManager
+
+**File:** `src/components/slideoverManager/SlideoverManager.tsx` · **Public export:** Yes
+
+**Use case:** Mount once at app root. Manages a stack of `Slideover` components. Open/close imperatively from anywhere via `SlideoverUtils`.
+
+**`SlideoverUtils` API:**
+- `SlideoverUtils.addSlideover(config: SlideoverProps)` — push new slideover
+- `SlideoverUtils.removeSlideover()` — pop top slideover
+- `SlideoverUtils.removeAllSlideovers()` — clear entire stack
+
+**Key features:**
+- PubSub events: `SLIDEOVER.ADD_SLIDEOVER`, `SLIDEOVER.REMOVE_SLIDEOVER`, `SLIDEOVER.REMOVE_ALL_SLIDEOVERS`
+- `PopupParentContext.Provider` wraps manager — popovers inside slideovers render correctly
+- `ds-slideover-manager--active` class triggers overlay when any slideover visible
+
+---
+
+### 30. Table
+
+**File:** `src/components/table/Table.tsx` · **Public export:** Yes
+**Also exports:** `GridApiContext`, `DSDefaultColDef`, `DefaultCellRenderer`, `BooleanCellRenderer`
+
+**Use case:** Full-featured enterprise data grid wrapping AG Grid Enterprise with design system theming, search, pagination, column visibility, bulk actions, row selection, and table settings — all pre-wired.
+
+**Key props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `hasSearch` | `boolean` | `true` | Show search bar in header |
+| `headerContent` | `ReactNode` | — | Content in table header |
+| `footerContent` | `ReactNode` | — | Content in table footer |
+| `tableTheme` | `string` | — | `'tidy'` for compact theme |
+| `enableSimultaneousRangeAndRowSelection` | `boolean` | `false` | Range + row selection simultaneously |
+| `onTableSettingsChanged` | `(val: TableSettings) => void` | — | Settings change callback |
+| `...rest` | `AgGridReactProps<TData>` | — | All AG Grid React props |
+
+**`TABLE_SPACING` enum:** `XS`, `S`, `M` (default), `L`
+
+**Sub-components:**
+
+| Name | Description |
+|---|---|
+| `Table.PaginationPanel` | Full pagination UI (controls + size selector + row count) |
+| `Table.PaginationControls` | First/prev/next/last + page number input |
+| `Table.PageSizeSelector` | Dropdown to change rows per page |
+| `Table.RowCountInfo` | "Showing X of Y results" text |
+| `Table.BulkActionsDropdown` | Actions dropdown for selected rows |
+| `Table.HideColumnsDropdown` | Multi-select to toggle column visibility |
+| `Table.ButtonCellRenderer` | Renders a `Button` in a cell (ref: `dsButtonCellRenderer`) |
+| `Table.TableSettingsDropdown` | Settings dropdown (spacing, borders, cell colors) |
+
+**Auto-registered cell renderers:**
+- `dsButtonCellRenderer` → `ButtonCellRenderer`
+- `dsInlineTextCellRenderer` → `InlineTextCellRenderer` (editable text in cell)
+- `dsSelectDropdownCellRenderer` → `SelectDropdownCellRenderer` (dropdown in cell)
+- `dsBooleanCellRenderer` → `BooleanCellRenderer` (check-solid icon for `true`, x-solid for `false`, null otherwise; also exported directly as `BooleanCellRenderer`)
+
+**Auto-registered column filters:**
+- `dsBooleanFilter` → `BooleanFilter`
+- `dsTimeFilter` → `TimeFilter` (equals/before/after modes)
+
+**Key features:**
+- AG Grid Enterprise with `AllEnterpriseModule`
+- Two themes: `defaultTheme` (configurable spacing + borders) and `tidyTheme` (compact)
+- `GridApiContext` makes AG Grid API available to sub-components without prop drilling
+- `DSDefaultColDef` handles wrapped cell values (`{ value: ... }` objects) and cell color styles
+
+---
+
+### 31. Tabs
+
+**File:** `src/components/tabs/Tabs.tsx` · **Public export:** Yes
+
+**Use case:** Horizontal tab navigation bar. Purely presentational — callers manage active state and content switching.
+
+**`Tabs` props:** `children` (ReactNode — `Tabs.Item` elements), `className`, `...rest`
+
+**`Tabs.Item` props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `active` | `boolean` | `false` | Active/selected state |
+| `iconName` | `IconName` | — | Optional icon |
+| `tabElement` | `'button' \| 'link'` | `'button'` | Render as button or anchor |
+| `tabElementProps` | `ButtonHTMLAttributes \| AnchorHTMLAttributes` | — | Props for inner element |
+| `children` | `ReactNode` | — | Tab label |
+
+**Key features:**
+- `<ul role="tablist">`, `<li role="presentation">`, inner element gets `role="tab"` + `aria-selected`
+- Both `button` and `a` variants get identical ARIA attributes
+- Active tab styled with brand color underline via CSS
+
+---
+
+### 32. Tag
+
+**File:** `src/components/tag/Tag.tsx` · **Public export:** Yes
+
+**Use case:** Non-interactive label/badge for categorization, status indicators, or metadata display.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `text` | `string` | Yes | — | Tag label |
+| `color` | `TagColor` | No | `'neutral'` | Color variant |
+| `dotColour` | `DotColour` | No | — | Optional colored dot prefix |
+
+**`TagColor` values:** `'neutral'` · `'orange'` · `'blue'` · `'green'` · `'purple'` · `'teal'` · `'salmon'` · `'yellow'`
+
+**`DotColour` values:** `'purple'` · `'salmon'` · `'teal'` · `'yellow'` · `'green'` · `'orange'` · `'blue'`
+
+**Key features:**
+- Purely presentational `<span>` — no click handling
+- Color styling via tokens: `--tag-{color}-color-text` and `--tag-{color}-color-background`
+- `dotColour` renders small colored circle with `aria-label="{colour} dot"`
+
+---
+
+### 33. Toast
+
+**File:** `src/components/toast/Toast.tsx` · **Public export:** Yes
+
+**Use case:** Transient notification messages that appear and auto-dismiss. Requires `Toast.Provider` ancestor and `Toast.Viewport` inside same provider.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `variant` | `'information' \| 'danger' \| 'success' \| 'warning'` | No | `'information'` | Semantic variant |
+| `children` | `ReactNode` | No | — | Toast message content |
+| `...rest` | `RadixToast.ToastProps` | No | — | Radix props (e.g. `open`, `onOpenChange`, `duration`) |
+
+**Static members:** `Toast.Provider`, `Toast.Viewport`
+
+**Variant icon map:** `information` → `info`, `danger` → `circle-alert`, `success` → `circle-check`, `warning` → `triangle-alert`
+
+**Key features:**
+- Built on Radix UI `Toast`
+- `duration` prop controls auto-dismiss (default 5000ms)
+- Multiple toasts can be open simultaneously
+- Includes built-in close (X) button
+
+---
+
+### 34. Tooltip / TooltipWrapper
+
+**Files:** `src/components/tooltip/Tooltip.tsx`, `TooltipWrapper.tsx` · **Public export:** Yes (both)
+
+**Use case:**
+- `Tooltip`: Composable tooltip for complex cases (custom trigger/content)
+- `TooltipWrapper`: Convenience wrapper for the common single-element + text tooltip case
+
+**`Tooltip` compound components:**
+- `Tooltip.Trigger` — wraps trigger element with `asChild`
+- `Tooltip.Content` — portal + content bubble
+
+**`Tooltip.Content` key props:** `children` (required), `shouldShowArrow` (default `true`), `portalProps`, `...rest` (side, align, sideOffset, etc.)
+
+**`TooltipWrapper` props:**
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | Yes | Trigger element |
+| `tooltipContent` | `ReactNode` | Yes | Tooltip content |
+| `delayDuration` | `number` | No | Hover delay in ms (default 400) |
+| `triggerProps` | `TooltipTriggerProps` | No | Props for the trigger |
+| `contentProps` | `Omit<TooltipContentProps, 'children'>` | No | Props for content |
+
+**Key features:**
+- Built on Radix UI `Tooltip`
+- Content portal rendered into `PopupParentContext`
+- `TooltipTrigger` uses `asChild` — trigger element receives all focus/hover behaviors
+
+---
+
+### 35. UserDropdown
+
+**File:** `src/components/userDropdown/UserDropdown.tsx` · **Public export:** Yes
+**Also exports:** `UserDropdownUserInfoAction` type, logo assets: `ArborLogo`, `GovhubLogo`, `KeyLogo`, `SampeopleLogo`, `RobinLogo`, `TimetablerLogo`
+
+**Use case:** Application header user menu. Shows avatar, user name, role, linked apps, optional discovery section, and sign-out.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `user` | `UserDropdownUser` | Yes | — | User info (`name`, `subtitle?`, `avatarSrc?`, `avatarInitials?`) |
+| `onSignOut` | `() => void` | Yes | — | Sign-out callback |
+| `logoSrc` | `string` | No | — | App/org logo URL |
+| `sections` | `UserDropdownSection[]` | No | `[]` | App/action sections |
+| `discoverSection` | `{ label, apps, defaultOpen? }` | No | — | Collapsible discovery section |
+| `userInfoAction` | `UserDropdownUserInfoAction` | No | — | Action on user info row |
+| `signOutLabel` | `string` | No | — | Custom sign-out label |
+| `variant` | `'dark' \| 'light'` | No | `'dark'` | Trigger appearance |
+
+**`UserDropdownUserInfoAction`:** `{ type: 'link', onClick }` or `{ type: 'menu', items: [{ label, onClick }] }`
+
+**Key features:**
+- Built on `Dropdown` compound component
+- `discoverSection` with `defaultOpen` shows collapsible app list
+- Pre-packaged Arbor suite logo assets exported from `index.ts`
+
+---
+
+### 36. DateTimePicker
+
+**File:** `src/components/dateTimePicker/DateTimePicker.tsx` · **Public export:** Yes
+**Also exports:** `DateTimePickerProps`, `DateTimePickerDisplayFormat` types
+
+**Use case:** Combined date + time picker for forms that need a full datetime value.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `value` | `Date` | No | — | Controlled datetime |
+| `defaultValue` | `Date` | No | — | Uncontrolled initial datetime |
+| `onChange` | `(newDate?: Date) => void` | No | — | Called when datetime changes |
+| `displayFormat` | `DateTimePickerDisplayFormat` | No | `'default'` | Date display format |
+| `granularity` | `'minute' \| 'second'` | No | `'minute'` | Time precision |
+| `timeOptions` | `TimeValue[]` | No | — | If provided, renders Combobox time picker instead of native input |
+| `searchType` | `ComboboxSearchType` | No | `'prefix'` | Combobox search strategy (only when `timeOptions` provided) |
+| `highlightStringMatches` | `boolean` | No | `false` | Combobox match highlighting |
+| `placeholder` | `string` | No | — | Date input placeholder |
+| `id` | `string` | No | — | Applied to date input |
+| `hasError` | `boolean` | No | — | Error state |
+| `aria-describedby` | `string` | No | — | ARIA description |
+| `aria-invalid` | `boolean` | No | — | ARIA invalid |
+
+---
+
+### 37. TimeInput
+
+**File:** `src/components/formField/inputs/time/TimeInput.tsx` · **Public export:** Yes
+**Also exports:** `TimeInputProps`, `TimeGranularity`, `TimeValue` types
+
+**Use case:** Time input with two modes — native browser time input or searchable Combobox-driven picker.
+
+**`TimeValue` type:** Template literal `HH:MM` or `HH:MM:SS`
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `value` | `TimeValue \| ''` | No | — | Controlled time value |
+| `defaultValue` | `TimeValue \| ''` | No | `''` | Uncontrolled initial value |
+| `onValueChange` | `(value: string) => void` | No | — | Change callback |
+| `options` | `TimeValue[]` | No | — | If provided, renders Combobox instead of native input |
+| `granularity` | `'minute' \| 'second'` | No | `'minute'` | Time precision (native mode only) |
+| `hasError` | `boolean` | No | `false` | Error state |
+| `searchType` | `ComboboxSearchType` | No | `'prefix'` | Search strategy (Combobox mode) |
+| `highlightStringMatches` | `boolean` | No | `false` | Highlight matches (Combobox mode) |
+| `disabled`, `id`, `name`, `placeholder`, `aria-*` | — | No | — | Standard HTML input attributes |
+
+**Key features:**
+- Native mode: `<input type="time">` with a clock-icon button that focuses and selects hours
+- Combobox mode: renders `Combobox` with `triggerVariant="button"` and clock icon in trigger
+- `forwardRef` — ref attached in native mode only
+
+---
+
+### 38. Toggle
+
+**File:** `src/components/toggle/Toggle.tsx` · **Public export:** Yes
+
+**Use case:** On/off toggle switch (boolean input). Use in place of a checkbox where a switch metaphor is more appropriate.
+
+**Props:** All of Radix UI `Switch.SwitchProps` — key ones:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | — | Controlled on/off state |
+| `defaultChecked` | `boolean` | — | Uncontrolled initial state |
+| `onCheckedChange` | `(checked: boolean) => void` | — | State change callback |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `required` | `boolean` | — | For form validation |
+| `name` | `string` | — | Form field name |
+| `value` | `string` | `'on'` | Value submitted with form |
+
+**Key features:**
+- Radix UI `Switch.Root` + `Switch.Thumb` wrapper
+- CSS: `ds-toggle` (root), `ds-toggle__thumb` (thumb)
+- Pair with a `<label>` or `aria-label` for accessibility
+
+---
+
+### 39. Row
+
+**File:** `src/components/row/Row.tsx` · **Public export:** Yes
+**Also exports:** `RowProps` type
+
+**Use case:** Simple key/value display row for detail panels, info cards, and read-only data views.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `label` | `string` | No | — | Left label text |
+| `value` | `string` | No | — | Centre value text |
+| `note` | `string` | No | — | Additional note text |
+| `onClick` | `MouseEventHandler<HTMLDivElement>` | No | — | Makes row clickable |
+| `className` | `string` | No | — | Additional CSS class |
+
+**Key features:**
+- When `onClick` provided: `ds-row--clickable` class, `tabIndex=0`, keyboard accessible (Enter/Space), renders chevron-right + arrow-right icons on the right edge
+- NOT suitable for table rows — use for simple key/value display layouts
+
+---
+
+### 40. SingleUser
+
+**File:** `src/components/singleUser/SingleUser.tsx` · **Public export:** Yes
+**Also exports:** `SingleUserProps` type
+
+**Use case:** Display a person with their avatar and name label, e.g. in staff assignments, contact cards, or user lists.
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `label` | `string` | Yes | — | Person's name/label |
+| `size` | `AvatarSize` | No | `'small'` | Avatar size |
+| `className` | `string` | No | — | Class on outer `<span>` |
+| `avatarClassName` | `string` | No | — | Class on Avatar |
+| `...avatarProps` | `AvatarProps` | No | — | All Avatar props (`src`, `initials`, etc.) |
+
+**Key features:**
+- `forwardRef` — ref on outer `<span>`
+- Avatar has `aria-hidden` + empty `alt` — `label` provides the accessible name
+- CSS: `ds-single-user`, `ds-single-user__label`
+
+---
+
+## Utility / Infrastructure (publicly exported)
+
+| Export | File | Description |
+|---|---|---|
+| `SlideoverUtils` | `src/utils/SlideoverUtils.ts` | `addSlideover()`, `removeSlideover()`, `removeAllSlideovers()` — PubSub helpers for `SlideoverManager` |
+| `GridApiContext` | `src/components/table/GridApiContext.ts` | React context providing AG Grid `GridApi` to table sub-components |
+| `DSDefaultColDef` | `src/components/table/DSDefaultColDef.ts` | Default AG Grid `ColDef` with DS conventions |
+| `DefaultCellRenderer` | `src/components/table/cellRenderers/DefaultCellRenderer.tsx` | Standard AG Grid cell renderer |
+| `BooleanCellRenderer` | `src/components/table/cellRenderers/BooleanCellRenderer.tsx` | Shows check icon (true), x icon (false), or null — also registered as `'dsBooleanCellRenderer'` string |
+
+**Not exported but notable:**
+- `ModalUtils` — `addModal()`, `removeModal()`, `removeAllModals()` (mount `ModalManager` to use)
+- `PopupParentContext` — React context for portal container (used by Modal, Slideover, Dropdown, Tooltip, DatePicker)
+- `PubSub` — lightweight pub/subscribe for imperative modal/slideover control
+
+---
+
+## Quick-Reference Summary Table
+
+| Component | Public | Key Variants | External Lib |
+|---|---|---|---|
+| `Badge` | Yes | size: sm/md/lg; 7 colour variants; a11yLabel | — |
+| `Dot` | Yes | 7 colour variants; optional label | — |
+| `Avatar` | Yes | size: small/medium/large/extra-large; image/initials/placeholder | — |
+| `AvatarGroup` | Yes | ascending/descending; overflow count; items or children API | — |
+| `Banner` | Yes | level: info/neutral/warning/destructive | CVA |
+| `Button` | Yes | 7 variants; 2 sizes; icon-only; borderless; error | — |
+| `Card` | Yes | clickable/static/disabled; optional tag | — |
+| `DatePicker` | Yes | any date-fns format; error state | Radix Popover, react-day-picker |
+| `Dropdown` | Yes | compound: Trigger/Content/Item/SelectItem/Separator/Group | Radix DropdownMenu |
+| `EditableText` | Yes | single-line/multiline; controlled editing | — |
+| `FormField` | No | 6 inputType values; error/helper/description | — |
+| `Fieldset` | Yes | with/without legend; native disabled | — |
+| `TextInput` | Yes | size: M/S; error state | — |
+| `TextArea` | Yes | autoSize; error state | — |
+| `NumberInput` | Yes | with/without spinners; min/max/step | decimal.js |
+| `CheckboxInput` | Yes | checked/unchecked/indeterminate; disabled | — |
+| `CheckboxGroup` | No | fieldset of checkboxes | — |
+| `RadioButtonInput` | Yes | error state; inline label | — |
+| `RadioButtonGroup` | No | controlled group with legend | — |
+| `SelectDropdown` | Yes | single/multi-select; grouping; icons | Radix DropdownMenu |
+| `ColourPickerDropdown` | Yes | error state; controlled color | @uiw/react-color |
+| `Heading` | Yes | level: 1–4 (h1–h4) | — |
+| `Icon` | Yes | ~100 icons; sizes 12/16/24; custom color | lucide-react |
+| `Modal` + `ModalManager` | Yes | compound sub-components; PubSub imperative control | Radix Dialog |
+| `Pill` | Yes | toggle / checkbox modes | — |
+| `Progress` | Yes | value/max controlled | Radix Progress |
+| `SearchBar` | Yes | collapsible/always-open | — |
+| `Section` | Yes | collapsible; icon; action button; heading level | — |
+| `Separator` | Yes | horizontal/vertical; decorative/semantic | Radix Separator |
+| `Slideover` + `SlideoverManager` | Yes | slide-in panel; stack management; PubSub | — |
+| `Table` | Yes | AG Grid Enterprise; 2 themes; pagination/bulk/settings | AG Grid Enterprise |
+| `Tabs` | Yes | button/link tabs; active state; icon | — |
+| `Tag` | Yes | 8 colors; optional dot color | — |
+| `Toast` | Yes | 4 variants; Provider + Viewport required | Radix Toast |
+| `Tooltip` + `TooltipWrapper` | Yes | delay; arrow; composable or convenience API | Radix Tooltip |
+| `UserDropdown` | Yes | dark/light trigger; sections; discover; link/menu action | Radix DropdownMenu |
+| `Combobox` | Yes | single/multi; tags or text display; async search; create-new; button or input trigger | Radix Popover |
+| `DateTimePicker` | Yes | date + time combined; native or Combobox time; granularity | Radix Popover, react-day-picker |
+| `TimeInput` | Yes | native time input or Combobox-driven; minute/second granularity | — |
+| `Toggle` | Yes | on/off switch; controlled or uncontrolled | Radix Switch |
+| `Row` | Yes | clickable or static; label/value/note | — |
+| `SingleUser` | Yes | avatar + name label; size variants | — |