@sdaia-ds/mcp 0.0.0-stage → 3.1.1

package/knowledge/general/slideout-menu.md

@@ -0,0 +1,92 @@
+# Slideout Menu
+
+## Metadata
+- Component: Slideout Menu
+- Slug: `slideout-menu`
+- Category: General
+- Install: `npx sdaia-ui@latest add slideout-menu`
+- Import: `import { SlideoutMenu } from '@/components/ui/SlideoutMenu'`
+- Installed files: `SlideoutMenu.tsx`, `SlideoutMenu.types.ts`, `SlideoutMenu.variants.ts`, `SlideoutMenuDivider.tsx`, `SlideoutMenuSection.tsx`, `index.ts`
+- Docs: https://ds.nacew.com/components/slideoutmenu
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add slideout-menu`. It copies the source into your components folder (`components/ui/SlideoutMenu/`, under `src/` when the project has one); import it as `@/components/ui/SlideoutMenu`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the panel. Also picks the slide direction (inline-end in LTR, inline-start in RTL). Omit to inherit (LTR motion). |
+| `title?` | `string` | — | Header title (also names the dialog). Nothing is rendered when omitted. |
+| `description?` | `string` | — | Header description text. Nothing is rendered when omitted. |
+| `headerIcon?` | `ReactNode` | — | Optional header icon (rendered inside a bordered circle) |
+| `divider?` | `boolean` | true | Whether to show header dividers and section dividers |
+| `showFooter?` | `boolean` | true | Whether to show the footer. Each footer button only renders when its label is provided. |
+| `primaryButtonLabel?` | `string` | — | Primary (dark) button label. The button is not rendered when omitted. |
+| `secondaryButtonLabel?` | `string` | — | Secondary (outline) button label. The button is not rendered when omitted. |
+| `onPrimaryClick?` | `() => void` | — | Primary button click handler |
+| `onSecondaryClick?` | `() => void` | — | Secondary button click handler |
+| `onClose?` | `() => void` | — | Close handler — called by the header close button and by Escape while focus is inside the panel. Without it the header button collapses / re-expands the panel body instead. |
+| `open?` | `boolean` | true | Whether the slideout is open/visible. |
+| `modal?` | `boolean` | true | Modal dialog semantics (`aria-modal="true"`, Tab is kept inside the panel). Set `false` for a non-modal side panel that sits beside content. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+| `labels?` | `Partial<SlideoutMenuLabels>` | — | Override the built-in accessible strings (English defaults). |
+| `children?` | `ReactNode` | — | Content to render in the body |
+| `className?` | `string` | — | Additional class names for the outer container |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`, `children`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the panel. Also picks the slide direction
+(inline-end in LTR, inline-start in RTL). Omit to inherit (LTR motion).
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the slide-out panel.
+  - `'solid'` (default) — opaque panel background.
+  - `'glass'` — translucent liquid-glass material (blurred backdrop +
+    beveled edge highlight). Reads best when the panel overlays imagery
+    or color.
+
+The visual is provided by the shared `.glass-surface` utility, so it is
+theme-aware (light / dark) and identical across every component that
+exposes a `surface` prop.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-neutral)`
+- `var(--ds-color-text-default)`
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-motion-enter-duration)`
+- `var(--ds-motion-enter-easing)`
+- `var(--ds-motion-exit-duration)`
+- `var(--ds-motion-exit-easing)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-spacing-xxs)`
+- `var(--ds-text-leading-line-heights-text-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add slideout-menu` (after `npx sdaia-ui@latest init`), then import `{ SlideoutMenu }` from `@/components/ui/SlideoutMenu`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/stepper.md

@@ -0,0 +1,42 @@
+# Stepper
+
+## Metadata
+- Component: Stepper
+- Slug: `stepper`
+- Category: General
+- Install: `npx sdaia-ui@latest add stepper`
+- Import: `import { Stepper } from '@/components/ui/Stepper'`
+- Installed files: `Stepper.tsx`, `Stepper.types.ts`, `Stepper.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/stepper
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add stepper`. It copies the source into your components folder (`components/ui/Stepper/`, under `src/` when the project has one); import it as `@/components/ui/Stepper`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation?` | `StepperOrientation` | 'horizontal' | Layout of the steps (Figma `Orientation`). Horizontal sits above a form; vertical fits a side panel. A horizontal stepper restacks vertically when its container is narrower than 36rem (576px). |
+| `currentStep?` | `number` | — | Number of the step the user is on (1-based, like the numbers shown). Steps before it become `completed`, it becomes `current`, later ones `upcoming`. A `status` set on a `StepperItem` always wins (e.g. `error`). |
+| `children?` | `ReactNode` | — | `StepperItem` elements, in order. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the stepper. Inherits from the document when omitted. |
+| `labels?` | `Partial<StepperItemLabels>` | — | Screen-reader status words for every step (English defaults). |
+
+Also accepts standard `<element>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the stepper. Inherits from the document when omitted.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-brand-spacing-space-4)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add stepper` (after `npx sdaia-ui@latest init`), then import `{ Stepper }` from `@/components/ui/Stepper`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/structured-list.md

@@ -0,0 +1,52 @@
+# Structured List
+
+## Metadata
+- Component: Structured List
+- Slug: `structured-list`
+- Category: General
+- Install: `npx sdaia-ui@latest add structured-list`
+- Import: `import { StructuredList } from '@/components/ui/StructuredList'`
+- Installed files: `StructuredList.tsx`, `StructuredList.types.ts`, `StructuredList.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/structuredlist
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add structured-list`. It copies the source into your components folder (`components/ui/StructuredList/`, under `src/` when the project has one); import it as `@/components/ui/StructuredList`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | `StructuredListColumn[]` | — | Array of columns, each with a header and rows |
+| `compact?` | `boolean` | false | Use compact row height (48px instead of 64px) |
+| `contained?` | `boolean` | false | Add border and rounded corners around the list |
+| `dividerRow?` | `boolean` | true | Show horizontal dividers between data rows (default: true) |
+| `dividerColumn?` | `boolean` | true | Show vertical dividers between columns (default: true) |
+| `dividerHeader?` | `boolean` | true | Show divider under the header row (default: true) |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `className?` | `string` | — | Additional class name |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `children`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-border-default)`
+- `var(--ds-color-table-text-head)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add structured-list` (after `npx sdaia-ui@latest init`), then import `{ StructuredList }` from `@/components/ui/StructuredList`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/table-bulk-actions-bar.md

@@ -0,0 +1,66 @@
+# Table Bulk Actions Bar
+
+## Metadata
+- Component: Table Bulk Actions Bar
+- Slug: `table-bulk-actions-bar`
+- Category: General
+- Install: `npx sdaia-ui@latest add table-bulk-actions-bar`
+- Import: `import { TableBulkActionsBar } from '@/components/ui/TableBulkActionsBar'`
+- Installed files: `TableBulkActionsBar.tsx`, `TableBulkActionsBar.types.ts`, `TableBulkActionsBar.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/table-bulk-actions-bar
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add table-bulk-actions-bar`. It copies the source into your components folder (`components/ui/TableBulkActionsBar/`, under `src/` when the project has one); import it as `@/components/ui/TableBulkActionsBar`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `selectedCount` | `number` | — | Number of selected rows — e.g. `selectedRowKeys.length` from the `Table`'s `onSelectionChange`. The bar is hidden while it is 0. |
+| `totalCount?` | `number` | — | Number of rows that can be selected. Drives the select-all checkbox: indeterminate while only some rows are selected, checked when all are. When omitted the checkbox shows the indeterminate (some selected) mark. |
+| `onSelectAllChange?` | `(checked: boolean) => void` | — | Called by the select-all checkbox with `true` (select every row) or `false` (clear). The checkbox renders only when this is set. |
+| `onClearSelection?` | `() => void` | — | Called by the "Clear selection" link. The link renders only when this is set (Figma boolean `Clear Selection`). |
+| `onClose?` | `() => void` | — | Called by the close (×) button, which dismisses the bar — usually by clearing the selection. The button renders only when this is set (Figma boolean `Close Button`). |
+| `actions?` | `ReactNode` | — | The bulk actions — usually up to three small `Button`s such as Approve, Export and Delete (Figma `Export Action` / `Delete Action`). Use a menu for more. Destructive actions must ask for confirmation. |
+| `returnFocusRef?` | `RefObject<HTMLElement \| null>` | — | Where keyboard focus goes when the bar hides while it holds focus (after "Clear selection", close or select-all → clear). Defaults to the first focusable element after the bar — for an inline bar, the table's select-all checkbox — so focus is never dropped on the page body. |
+| `position?` | `'inline' \| 'floating'` | 'inline' | Placement and surface (Figma `Position`). |
+| `labels?` | `Partial<TableBulkActionsBarLabels>` | — | Localised built-in strings (English defaults). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction of the bar. Inherits from the document when omitted. Figma `RTL=True` maps to `dir="rtl"`. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`, `children`.
+
+## Options (allowed values)
+- `position`: `'inline'` \| `'floating'` — Where the bar sits (Figma `Position`).
+- `inline` — above the table header, in place of the table toolbar; light
+  brand surface.
+- `floating` — raised surface with a shadow that sticks 24px above the
+  bottom of the viewport while a long table scrolls (`position: sticky`, so
+  it settles back in place at the end of the table instead of covering the
+  pagination). Place it right after the `Table`.
+- `dir`: `'ltr'` \| `'rtl'` — Text direction of the bar. Inherits from the document when omitted.
+Figma `RTL=True` maps to `dir="rtl"`.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-brand-subtle)`
+- `var(--ds-color-bg-raised)`
+- `var(--ds-color-border-brand-subtle)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-text-default)`
+- `var(--ds-radius-m)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add table-bulk-actions-bar` (after `npx sdaia-ui@latest init`), then import `{ TableBulkActionsBar }` from `@/components/ui/TableBulkActionsBar`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/table-of-content.md

@@ -0,0 +1,49 @@
+# Table of Content
+
+## Metadata
+- Component: Table of Content
+- Slug: `table-of-content`
+- Category: General
+- Install: `npx sdaia-ui@latest add table-of-content`
+- Import: `import { TableOfContent } from '@/components/ui/TableOfContent'`
+- Installed files: `TableOfContent.tsx`, `TableOfContent.types.ts`, `TableOfContent.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/table-of-content
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add table-of-content`. It copies the source into your components folder (`components/ui/TableOfContent/`, under `src/` when the project has one); import it as `@/components/ui/TableOfContent`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label?` | `ReactNode` | — | Small header label above the page name (rich content allowed). Takes precedence over `labels.heading`. |
+| `labels?` | `Partial<TableOfContentLabels>` | — | Translatable built-in strings. |
+| `pageName` | `ReactNode` | — | The current page title displayed in the header. |
+| `lists` | `TableOfContentListItem[][]` | — | Lists of TOC items (each list is a separate group). Matches Figma where multiple lists can appear stacked. |
+| `selectedId?` | `string` | — | Controlled selected item id (forwarded to every list). |
+| `defaultSelectedId?` | `string` | — | Uncontrolled initial selected item id. Defaults to the first item of the first list. |
+| `onSelectedIdChange?` | `(id: string) => void` | — | Called when an item is activated (click / Enter / Space). |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. Inherits when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. Inherits when omitted.
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-text-display)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-spacing-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+- `var(--ds-text-leading-line-heights-text-xl)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add table-of-content` (after `npx sdaia-ui@latest init`), then import `{ TableOfContent }` from `@/components/ui/TableOfContent`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/table.md

@@ -0,0 +1,113 @@
+# Table
+
+## Metadata
+- Component: Table
+- Slug: `table`
+- Category: General
+- Install: `npx sdaia-ui@latest add table`
+- Import: `import { Table } from '@/components/ui/Table'`
+- Installed files: `Table.tsx`, `Table.types.ts`, `Table.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/table
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add table`. It copies the source into your components folder (`components/ui/Table/`, under `src/` when the project has one); import it as `@/components/ui/Table`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title?` | `ReactNode` | — | Title shown in the table header band |
+| `description?` | `ReactNode` | — | Optional description shown beneath the title |
+| `headerActions?` | `ReactNode` | — | Custom slot for action content (e.g. `<Button/>`s) on the trailing side of the header |
+| `showMoreIcon?` | `boolean` | — | Shows the inline more (3-dot) icon button after the header actions |
+| `onMoreClick?` | `() => void` | — | Click handler for the more icon. If omitted the icon is not rendered |
+| `hideHeader?` | `boolean` | false | Hides the entire top header band (title/description/actions) |
+| `columns` | `TableColumn[]` | — | Column definitions |
+| `rows` | `TableRowData[]` | — | Row data |
+| `divider?` | `'none' \| 'horizontal' \| 'vertical' \| 'both'` | 'none' | Divider style between rows/columns |
+| `sortKey?` | `string` | — | Controlled sort key |
+| `sortDirection?` | `'asc' \| 'desc'` | — | Controlled sort direction |
+| `onSort?` | `(key: string, direction: TableSortDirection) => void` | — | Fired when a sortable header cell is clicked |
+| `showPagination?` | `boolean` | false | Shows the pagination footer |
+| `page?` | `number` | 1 | Current page number (1-based) |
+| `totalPages?` | `number` | 1 | Total page count |
+| `onPageChange?` | `(page: number) => void` | — | Fired when prev/next is clicked |
+| `mobile?` | `boolean` | false | Forces the mobile layout regardless of viewport |
+| `labels?` | `Partial<TableLabels>` | — | Override built-in strings (English defaults) to localize pagination, actions and selection labels. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Text direction. Inherits from the document when omitted. |
+| `selectable?` | `boolean` | false | Adds a checkbox to the first column of every row plus a select-all checkbox in its header cell (Figma: header / row cell Type=Checkbox). |
+| `selectedRowKeys?` | `TableRowKey[]` | — | Controlled selection: keys of the selected rows. |
+| `defaultSelectedRowKeys?` | `TableRowKey[]` | — | Uncontrolled initial selection. Ignored when `selectedRowKeys` is set. |
+| `onSelectionChange?` | `(selectedRowKeys: TableRowKey[], selectedRows: TableRowData[]) => void` | — | Fired when the selection changes, with the new keys and the selected rows among `rows`. |
+| `getRowKey?` | `(row: TableRowData) => TableRowKey` | defaultGetRowKey | Derives a row's selection key. |
+| `state?` | `'default' \| 'loading' \| 'empty' \| 'error'` | 'default' | Data state of the body (Figma Table State). `loading` shows skeleton rows and sets `aria-busy`; `empty` / `error` replace the rows with `emptyState` / `errorState`. Messages are announced in a polite live region. |
+| `loadingRowCount?` | `number` | 5 | Number of skeleton rows while `state="loading"`. |
+| `emptyState?` | `TableStateContent` | — | Message shown when `state="empty"` (EmptyState type No Data). |
+| `errorState?` | `TableStateContent` | — | Message shown when `state="error"` (EmptyState type Error), usually with a retry action. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `divider`: `'none'` \| `'horizontal'` \| `'vertical'` \| `'both'` — Divider style between rows/columns
+- `sortDirection`: `'asc'` \| `'desc'` — Controlled sort direction
+- `dir`: `'ltr'` \| `'rtl'` — Text direction. Inherits from the document when omitted.
+- `state`: `'default'` \| `'loading'` \| `'empty'` \| `'error'` — Data state of the table body (Figma Table State 12942:258736).
+- `default` — the rows.
+- `loading` — skeleton rows under the real header; header and pagination
+  stay so the layout does not jump.
+- `empty` — the header stays and an `EmptyState` (No Data) replaces the
+  rows, e.g. when a search or filter returns nothing.
+- `error` — the header stays and an `EmptyState` (Error) with a retry action
+  replaces the rows.
+
+## Accessibility
+Built in (SDAIA review item C7) — verified by `tests/a11y/keyboard/mouse-toggles.spec.ts` in the design system's test suite:
+- Row checkboxes and the select-all checkbox respond to a click on the box.
+- Built-in pagination and selection strings (previous / next, page X of Y, select all / row, more actions) can be translated through `labels`.
+
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-brand-primary-900)`
+- `var(--ds-brand-primary-950)`
+- `var(--ds-color-bg-emphasis-high)`
+- `var(--ds-color-bg-overlay)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-color-border-default)`
+- `var(--ds-color-border-muted)`
+- `var(--ds-color-icon-default)`
+- `var(--ds-color-icon-default-400)`
+- `var(--ds-color-icon-default-500)`
+- `var(--ds-color-primitive-neutral-700)`
+- `var(--ds-color-table-)`
+- `var(--ds-color-table-bg-header)`
+- `var(--ds-color-table-bg-row-hovered)`
+- `var(--ds-color-table-bg-row-select)`
+- `var(--ds-color-table-bg-row-selected-hovered)`
+- `var(--ds-color-table-cell-border)`
+- `var(--ds-color-table-text-body)`
+- `var(--ds-color-table-text-head)`
+- `var(--ds-color-text-paragraph)`
+- `var(--ds-color-text-paragraph-muted)`
+- `var(--ds-radius-full)`
+- `var(--ds-radius-l)`
+- `var(--ds-radius-xs)`
+- `var(--ds-spacing-2xl)`
+- `var(--ds-spacing-4xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-none)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-spacing-xs)`
+- `var(--ds-text-leading-line-heights-text-lg)`
+- `var(--ds-text-leading-line-heights-text-md)`
+- `var(--ds-text-leading-line-heights-text-sm)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add table` (after `npx sdaia-ui@latest init`), then import `{ Table }` from `@/components/ui/Table`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pass icons via `<DgaIcon data={…} className="size-icon-sm" />` from `@platformscode/icons` only — see `get_foundations` (`icon-usage`). Never emoji, Lucide, or random icons (e.g. `pizza01Stroke` for dark mode).
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/tree-view.md

@@ -0,0 +1,55 @@
+# Tree View
+
+## Metadata
+- Component: Tree View
+- Slug: `tree-view`
+- Category: General
+- Install: `npx sdaia-ui@latest add tree-view`
+- Import: `import { TreeView } from '@/components/ui/TreeView'`
+- Installed files: `TreeView.tsx`, `TreeView.types.ts`, `TreeView.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/tree-view
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add tree-view`. It copies the source into your components folder (`components/ui/TreeView/`, under `src/` when the project has one); import it as `@/components/ui/TreeView`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. Also decides which arrow key expands (Right in LTR, Left in RTL). Omit to inherit — the computed direction is used for the keys. |
+| `items` | `TreeViewNode[]` | — | Tree nodes to render. |
+| `expandedIds?` | `string[]` | — | Controlled expanded ids. |
+| `defaultExpandedIds?` | `string[]` | [] | Uncontrolled initial expanded ids. |
+| `onExpandedIdsChange?` | `(expandedIds: string[]) => void` | — | Called whenever expansion state changes. |
+| `selectedId?` | `string` | — | Controlled selected node id. |
+| `defaultSelectedId?` | `string` | — | Uncontrolled initial selected node id. |
+| `onSelectedIdChange?` | `(id: string) => void` | — | Called when a node is selected. |
+| `baseLevel?` | `TreeViewItemLevel` | 1 | Base indentation level for the first rendered row. Figma set covers levels 1–4. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. Also decides which arrow key
+expands (Right in LTR, Left in RTL). Omit to inherit — the computed
+direction is used for the keys.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-default)`
+- `var(--ds-color-border-brand)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-lg)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add tree-view` (after `npx sdaia-ui@latest init`), then import `{ TreeView }` from `@/components/ui/TreeView`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/vertical-tabs.md

@@ -0,0 +1,48 @@
+# Vertical Tabs
+
+## Metadata
+- Component: Vertical Tabs
+- Slug: `vertical-tabs`
+- Category: General
+- Install: `npx sdaia-ui@latest add vertical-tabs`
+- Import: `import { VerticalTabs } from '@/components/ui/VerticalTabs'`
+- Installed files: `VerticalTabs.tsx`, `VerticalTabs.types.ts`, `VerticalTabs.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/vertical-tabs
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add vertical-tabs`. It copies the source into your components folder (`components/ui/VerticalTabs/`, under `src/` when the project has one); import it as `@/components/ui/VerticalTabs`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `VerticalTabItem[]` | — | Tabs to render. |
+| `type?` | `'primary' \| 'neutral' \| 'line-vertical' \| 'outline'` | 'primary' | Visual type. |
+| `value?` | `string` | — | Controlled selected value. |
+| `defaultValue?` | `string` | — | Uncontrolled initial value. |
+| `onValueChange?` | `(value: string) => void` | — | Selection change callback. |
+| `disabled?` | `boolean` | false | Disable the entire tab group. |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction applied to the root. Inherits the ambient direction when omitted. |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …).
+
+## Options (allowed values)
+- `type`: `'primary'` \| `'neutral'` \| `'line-vertical'` \| `'outline'` — Container-level type. Determines both the wrapper styling and the
+inner `Tab` variant used for each item.
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction applied to the root. Inherits the ambient direction when omitted.
+
+## Accessibility
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-xs)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add vertical-tabs` (after `npx sdaia-ui@latest init`), then import `{ VerticalTabs }` from `@/components/ui/VerticalTabs`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Express the disabled state with the `disabled` prop, not custom styling.
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.

package/knowledge/general/video-player.md

@@ -0,0 +1,88 @@
+# Video Player
+
+## Metadata
+- Component: Video Player
+- Slug: `video-player`
+- Category: General
+- Install: `npx sdaia-ui@latest add video-player`
+- Import: `import { VideoPlayer } from '@/components/ui/VideoPlayer'`
+- Installed files: `VideoPlayer.tsx`, `VideoPlayer.types.ts`, `VideoPlayer.variants.ts`, `index.ts`
+- Docs: https://ds.nacew.com/components/video-player
+
+> **Hard rule:** `sdaia-ui` is a CLI, not a runtime package — NEVER run `npm install sdaia-ui` and NEVER `import … from 'sdaia-ui'`. Run `npx sdaia-ui@latest init` once per project (Tailwind CSS v4, tokens, the IBM Plex Sans Arabic font, the `@/` alias on Vite, `cn`), then `npx sdaia-ui@latest add video-player`. It copies the source into your components folder (`components/ui/VideoPlayer/`, under `src/` when the project has one); import it as `@/components/ui/VideoPlayer`. The files are yours: prefer props and composition over editing them. `npx sdaia-ui@latest update` never overwrites a file you changed: it keeps it and says it has updates; `diff` shows them and `update --force` takes them.
+
+## Props
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src?` | `string` | — | URL of the video to play. When provided, the component renders a real <video> element and drives progress / currentTime / duration from actual playback. When omitted, the component shows the poster image and relies on the controlled progress / currentTime / duration props (demo / storybook mode). |
+| `poster?` | `string` | — | Poster / thumbnail image shown before playback begins. When omitted (and there is no `src`), the player renders an empty neutral surface — there is no built-in placeholder image. |
+| `posterAlt?` | `string` | '' | Accessible alt text for the poster image. |
+| `title?` | `string` | — | Video title shown in the header while the player is in the playing state. |
+| `playing?` | `boolean` | — | Whether the player is playing (controlled). When omitted the component manages its own playing state. |
+| `defaultPlaying?` | `boolean` | false | Initial playing state when uncontrolled. Default: false. |
+| `progress?` | `number` | — | Playback progress 0–100 (controlled). When omitted the component manages its own progress internally. |
+| `defaultProgress?` | `number` | 0 | Initial progress value when uncontrolled. Default: 0. |
+| `currentTime?` | `string` | '0:00' | Current-time display string shown in the controls bar, e.g. "0:12". |
+| `duration?` | `string` | '0:00' | Total-duration display string shown in the controls bar, e.g. "2:32". |
+| `onPlay?` | `() => void` | — | Called when the user requests playback to start. |
+| `onPause?` | `() => void` | — | Called when the user requests playback to pause. |
+| `onPrevious?` | `() => void` | — | Called when the previous-track button is clicked. |
+| `onNext?` | `() => void` | — | Called when the next-track button is clicked. |
+| `onProgressChange?` | `(value: number) => void` | — | Called when the user scrubs the progress bar. Receives the new value in the range 0–100. |
+| `onVolumeClick?` | `() => void` | — | Called when the volume button is clicked. |
+| `onSettingsClick?` | `() => void` | — | Called when the settings button is clicked. |
+| `onFullscreenClick?` | `() => void` | — | Called when the fullscreen button is clicked. |
+| `onMoreClick?` | `() => void` | — | Called when the more-options (⋮) button is clicked. |
+| `labels?` | `Partial<VideoPlayerLabels>` | — | Localised copy for every control label (`aria-label` / `aria-valuetext`). Unset keys fall back to English. See . |
+| `dir?` | `'ltr' \| 'rtl'` | — | Layout direction. In `rtl` the controls bar mirrors (button groups swap sides, progress fills right-to-left, ArrowLeft seeks forward). Omit to inherit the direction from the parent. |
+| `surface?` | `'solid' \| 'glass'` | 'solid' | Surface treatment of the controls toolbar — `'solid'` (default) or `'glass'` (translucent liquid-glass material). |
+
+Also accepts standard `<div>` HTML attributes (`className`, `style`, `onClick`, `aria-*`, …) — except: `title`, `dir`.
+
+## Options (allowed values)
+- `dir`: `'ltr'` \| `'rtl'` — Layout direction. In `rtl` the controls bar mirrors (button groups swap
+sides, progress fills right-to-left, ArrowLeft seeks forward).
+Omit to inherit the direction from the parent.
+- `surface`: `'solid'` \| `'glass'` — Surface treatment of the controls toolbar (the pill wrapping the playback
+controls).
+  - `'solid'` (default) — dark semi-transparent scrim.
+  - `'glass'` — translucent liquid-glass material (blurred video backdrop +
+    beveled edge highlight).
+
+The visual is provided by the shared `.glass-surface` utility, so it is
+theme-aware (light / dark) and identical across every component that
+exposes a `surface` prop.
+
+## Deprecated props
+Do not use in new code:
+- `rtl`
+
+## Accessibility
+- Built-in strings (button names, announcements) come from `labels`; pass translated strings for Arabic or other languages.
+- Don't remove the focus ring or replace interactive elements with `div`s; keep the control keyboard-operable.
+- For contrast, keyboard patterns and RTL rules, call `get_foundations` (`accessibility`, `rtl`).
+
+## Design tokens used
+Keep these consistent (resolve values with `get_tokens`):
+- `var(--ds-color-bg-brand)`
+- `var(--ds-color-bg-emphasis-strong)`
+- `var(--ds-color-border-on-color-30)`
+- `var(--ds-color-icon-oncolor)`
+- `var(--ds-color-text-on-color)`
+- `var(--ds-motion-feedback-duration)`
+- `var(--ds-motion-feedback-easing)`
+- `var(--ds-radius-m)`
+- `var(--ds-radius-xxs)`
+- `var(--ds-spacing-3xl)`
+- `var(--ds-spacing-lg)`
+- `var(--ds-spacing-md)`
+- `var(--ds-spacing-sm)`
+- `var(--ds-spacing-xl)`
+- `var(--ds-themes-media-media-background-transparent)`
+
+## AI usage guidance
+When generating UI:
+- Install with `npx sdaia-ui@latest add video-player` (after `npx sdaia-ui@latest init`), then import `{ VideoPlayer }` from `@/components/ui/VideoPlayer`.
+- NEVER run `npm install sdaia-ui` and NEVER `import` from the `sdaia-ui` package — it is a source-copying CLI, not a component library.
+- Use only the documented option values listed under "Options".
+- Pick one theme per screen: dark is `.theme-dark` (or `.dark`) on `<html>`; style surrounding layout with DS tokens (`get_tokens`), never hardcoded colors.