twico-ui 1.4.0 → 1.5.0

package/dist/index.d.cts

@@ -15,6 +15,8 @@ interface AccordionProps extends React.HTMLAttributes<HTMLDivElement> {
   open?: string[];
   /** Called with the next open values whenever a panel is toggled. */
   onOpenChange?: (values: string[]) => void;
+  /** Heading level wrapping each trigger button (document-outline semantics). @default 3 */
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
 }
 
 interface AccordionItem {
@@ -22,16 +24,45 @@ interface AccordionItem {
   label: React.ReactNode;
   content: React.ReactNode;
   icon?: React.ReactNode;
+  /** Disable this section — its trigger can't be opened, activated, or focused. @default false */
+  disabled?: boolean;
+  /** Override the accordion's `headingLevel` for this item. */
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
 }
 
 declare function Accordion(props: AccordionProps): React.JSX.Element;
 
+// Shared, library-wide type vocabulary. Types only — no runtime. Re-exported from
+// the package root so consumers can name the same unions the components use, instead
+// of re-deriving them. See docs/tone-variant-system.md and docs/prop-conventions.md.
+
+/** The canonical six-value color/intent scale used by status & control components. */
+type Tone = "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+
+/** Action controls (Button, IconButton) — brand or destructive only. */
+type ActionTone = "primary" | "danger";
+
+/** Text roles, the full color scale, and `"inherit"` (adopt the parent color) — Text. */
+type TextTone = "default" | "muted" | "subtle" | "inherit" | Tone;
+
+/** Toast tone vocabulary — `"neutral"` is an alias of `"default"`. */
+type ToastTone = "default" | "neutral" | "success" | "warning" | "danger" | "info";
+
+/** Progress / Timeline bar tones — the scale minus `"neutral"` (no neutral bar state). */
+type BarTone = Exclude<Tone, "neutral">;
+
+/**
+ * The `as` prop of the polymorphic primitives — any intrinsic tag name (`"div"`)
+ * OR a React component (`as={Link}`), whose props then flow through `{...rest}`.
+ */
+type PolymorphicAs = React.ElementType;
+
 /**
  * Inline message banner with semantic tones, optional title, icon, and dismiss.
  */
 interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
   /** Color intent. @default "info" */
-  tone?: "info" | "success" | "warning" | "danger" | "primary" | "neutral";
+  tone?: Tone;
   /** Fill style. @default "soft" */
   variant?: "soft" | "solid" | "outline";
   /** Bold heading line. */
@@ -40,6 +71,14 @@ interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">
   icon?: React.ReactNode;
   /** Show a close button and handle dismissal. */
   onClose?: () => void;
+  /**
+   * Live-region politeness. Tone-aware default: danger/warning → `"assertive"` (role="alert"),
+   * success/info → `"polite"` (role="status"), primary/neutral → `"off"` (no live region, for
+   * static banners). Set explicitly to override. @default tone-aware
+   */
+  live?: "assertive" | "polite" | "off";
+  /** Accessible label for the dismiss button (shown only when `onClose` is set). @default "Dismiss" */
+  closeLabel?: string;
   children?: React.ReactNode;
 }
 
@@ -59,6 +98,10 @@ interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
   square?: boolean;
   /** Presence indicator. */
   status?: "online" | "busy" | "away" | "offline";
+  /** Accessible text for the presence dot, folded into the avatar's spoken name (e.g. "Jane Doe, Online"). Defaults to a capitalized `status`. */
+  statusLabel?: string;
+  /** Localized presence labels keyed by status value. */
+  statusLabels?: Partial<Record<"online" | "busy" | "away" | "offline", string>>;
   /** Adds a brand ring around the avatar. */
   ring?: boolean;
 }
@@ -77,6 +120,12 @@ interface MenuItemDef {
   /** Render in danger color. */
   danger?: boolean;
   disabled?: boolean;
+  /** Turns the item into a link: renders `<a role="menuitem" href>`. Sanitized against javascript:/data:/vbscript:. `onClick` (if also set) still fires, then the menu closes. */
+  href?: string;
+  /** Anchor target when `href` is set (e.g. "_blank"). */
+  target?: string;
+  /** Anchor rel when `href` is set — pair "_blank" with "noopener noreferrer". */
+  rel?: string;
   /** Render a divider line (ignores other fields). */
   separator?: boolean;
   /** Render as an uppercase section heading. */
@@ -107,6 +156,10 @@ interface MenuProps extends React.HTMLAttributes<HTMLSpanElement> {
   open?: boolean;
   /** Called with the requested open state on trigger click, item select, Esc, or outside click. */
   onOpenChange?: (open: boolean) => void;
+  /** Accessible name for the `role="menu"` popup. When omitted and a `header` is set, the header labels the popup. */
+  "aria-label"?: string;
+  /** Id(s) of element(s) that label the popup; overrides the header fallback. */
+  "aria-labelledby"?: string;
 }
 
 declare function Menu(props: MenuProps): React.JSX.Element;
@@ -148,7 +201,7 @@ declare function AvatarMenu(props: AvatarMenuProps): React.JSX.Element;
  */
 interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** Semantic color. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Fill style. @default "soft" */
   variant?: "soft" | "solid" | "outline";
   /** Size scale. @default "md" */
@@ -200,7 +253,7 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Fill style. @default "solid" */
   variant?: "solid" | "soft" | "outline" | "ghost";
   /** Color/intent, orthogonal to `variant`. @default "primary" */
-  tone?: "primary" | "danger";
+  tone?: ActionTone;
   /** Control size; "xs" (~26px) is smaller than "sm". @default "md" */
   size?: "xs" | "sm" | "md" | "lg";
   /** Icon node rendered before the label. */
@@ -252,8 +305,14 @@ declare function Card(props: CardProps): React.JSX.Element;
 
 /**
  * Sliding carousel — one slide per view, prev/next arrows, dot indicators,
- * optional looping and autoplay (pauses on hover). Each child is a slide.
- * Controlled via `index` + `onIndexChange`, or uncontrolled via `defaultIndex`.
+ * optional looping and autoplay. Each child is a slide. Controlled via `index` +
+ * `onIndexChange`, or uncontrolled via `defaultIndex`.
+ *
+ * Accessibility: the region is focusable and keyboard-navigable — ArrowLeft/ArrowRight
+ * step slides and Home/End jump to first/last. Autoplay pauses on hover/focus, via the
+ * pause button, and when `prefers-reduced-motion` is set (WCAG 2.2.2); a polite live
+ * region announces the active slide (silenced while auto-rotating). Give the region an
+ * accessible name with `label` (or `aria-label`/`aria-labelledby`).
  *
  * @startingPoint section="Data display" subtitle="Sliding carousel" viewport="700x320"
  */
@@ -262,44 +321,53 @@ interface CarouselProps extends React.HTMLAttributes<HTMLDivElement> {
   index?: number;
   /** Initial slide index when uncontrolled. @default 0 */
   defaultIndex?: number;
-  /** Fired when the active slide changes (arrows, dots, or autoplay): (index). */
+  /** Fired when the active slide changes (arrows, dots, keyboard, or autoplay): (index). */
   onIndexChange?: (index: number) => void;
   /** Show prev/next arrows. @default true */
   showArrows?: boolean;
   /** Show dot indicators. @default true */
   showDots?: boolean;
+  /** Show the pause/play toggle when `autoPlay` is on. @default true */
+  showPauseButton?: boolean;
   /** Wrap around at the ends. @default true */
   loop?: boolean;
-  /** Auto-advance slides. @default false */
+  /** Auto-advance slides. Suppressed under `prefers-reduced-motion`. @default false */
   autoPlay?: boolean;
   /** Autoplay interval in ms. @default 4000 */
   interval?: number;
+  /** Accessible name for the carousel region. Falls back to `aria-label`, then `"Carousel"`. */
+  label?: string;
+  /** Accessible label for the pause button (paused → shows the play label). @default "Pause" */
+  pauseLabel?: string;
+  /** Accessible label for the play button. @default "Play" */
+  playLabel?: string;
   /** Slides (each child is one slide). */
   children?: React.ReactNode;
 }
 
 declare function Carousel(props: CarouselProps): React.JSX.Element;
 
-interface ChartDatum {
-  /** X-axis label. */
-  label: React.ReactNode;
-  /** One numeric field per series key (default key is "value"). */
-  [key: string]: any;
-}
+/**
+ * A chart data point: a `label` plus one numeric field per series key `K`
+ * (default key `"value"`). `K` is normally inferred from the `series` prop.
+ */
+type ChartDatum<K extends string = "value"> = { label: React.ReactNode } & { [P in K]: number };
 
 /**
  * Lightweight, dependency-free SVG chart — bar or line, single or multi-series,
- * with grid, axes, animated entrance, tooltips, and optional legend.
+ * with grid, axes, animated entrance, tooltips, and optional legend. Generic over
+ * the series keys `K` so the data rows are type-checked (e.g.
+ * `<Chart series={["sales"]} data={[{ label, sales: 12 }]} />`).
  *
  * @startingPoint section="Data display" subtitle="Bar / line chart (no deps)" viewport="700x280"
  */
-interface ChartProps extends React.HTMLAttributes<HTMLDivElement> {
+interface ChartProps<K extends string = "value"> extends React.HTMLAttributes<HTMLDivElement> {
   /** @default "bar" */
   type?: "bar" | "line";
-  /** Data points. Each has a `label` + one numeric field per series. */
-  data: ChartDatum[];
-  /** Series field names (defaults to ["value"]). Multiple = grouped bars / multi-line. */
-  series?: string[];
+  /** Data points. Each has a `label` + one numeric field per series key. (`K` is inferred from `series`, not from `data`.) */
+  data: ChartDatum<NoInfer<K>>[];
+  /** Series field names (defaults to `["value"]`). Multiple = grouped bars / multi-line. */
+  series?: K[];
   /** Pixel height. @default 220 */
   height?: number;
   /** Horizontal grid lines. @default true */
@@ -310,13 +378,17 @@ interface ChartProps extends React.HTMLAttributes<HTMLDivElement> {
   showLegend?: boolean;
   /** Per-series colors (any CSS color), cycled when shorter than `series`. Defaults to the built-in token palette. */
   colors?: string[];
-  /** Tooltip value formatter. */
+  /** Tooltip value formatter (also formats the hidden data-table cells). */
   valueFormat?: (value: number) => string;
-  /** Accessible name for the chart's `<svg role="img">`. Defaults to `"<type> chart"`. Also accepts `aria-label`. */
+  /** Accessible name for the chart's `<svg role="img">`. Per-point values are exposed via the hidden data table, not this label. Defaults to `"<type> chart"`; also accepts `aria-label`. */
   ariaLabel?: string;
+  /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
+  tableFallback?: boolean;
+  /** Caption for the hidden data table; defaults to the chart's accessible label. */
+  caption?: React.ReactNode;
 }
 
-declare function Chart(props: ChartProps): React.JSX.Element;
+declare function Chart<K extends string = "value">(props: ChartProps<K>): React.JSX.Element;
 
 /**
  * Checkbox with animated checkmark, label, description, and indeterminate state.
@@ -330,7 +402,7 @@ interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   indeterminate?: boolean;
   size?: "sm" | "md" | "lg";
   /** Color intent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
 }
 
 declare function Checkbox(props: CheckboxProps): React.JSX.Element;
@@ -359,12 +431,32 @@ interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "o
   /** Disable all interaction (the popover cannot be opened). @default false */
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   onChange?: (hex: string) => void;
 }
 
 declare function ColorPicker(props: ColorPickerProps): React.JSX.Element;
 
+// Shared option shape for the Select family (Select, Combobox, MultiSelect). One
+// canonical pair instead of three byte-identical duplicates; the per-component names
+// (SelectOption, ComboboxOption, …) stay as structural aliases so existing imports
+// keep resolving. Types only — no runtime. CurrencyField's CurrencyOption is a
+// deliberately separate, narrower shape and is NOT unified here.
+
+/** A single selectable option. */
+interface Option {
+  value: string;
+  label: string;
+  /** Optional second line shown under the label. */
+  description?: string;
+}
+
+/** A labeled group of options (or bare string values). */
+interface OptionGroup {
+  group: string;
+  options: Array<string | Option>;
+}
+
 /**
  * Searchable single-select (MUI-Autocomplete style) — type directly in the
  * field to filter; the overlay shows only options. Supports grouped options
@@ -380,7 +472,7 @@ interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   required?: boolean;
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Field placeholder. */
   placeholder?: string;
   /** Options — strings, {value,label,description}, or {group,options} groups. */
@@ -389,6 +481,7 @@ interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   value?: string | null;
   /** Uncontrolled initial value. */
   defaultValue?: string | null;
+  /** Called with the chosen option's value, or `null` when cleared via `clearable`. */
   onChange?: (value: string | null) => void;
   /** Show a clear (×) affix when a value is selected. */
   clearable?: boolean;
@@ -407,18 +500,11 @@ interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
 }
 
-interface ComboboxOption {
-  value: string;
-  label: string;
-  /** Optional second line shown under the label. */
-  description?: string;
-}
+/** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
+type ComboboxOption = Option;
 
-/** A group heading with its own options. */
-interface ComboboxGroup {
-  group: string;
-  options: Array<string | ComboboxOption>;
-}
+/** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
+type ComboboxGroup = OptionGroup;
 
 declare function Combobox(props: ComboboxProps): React.JSX.Element;
 
@@ -476,7 +562,7 @@ interface CurrencyProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   required?: boolean;
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Currency code (key in the built-in table), e.g. "USD", "EUR", "IDR", "JPY". @default "USD" */
   currency?: string;
   /** Override the currency's decimal precision (number of digits after the decimal). */
@@ -485,13 +571,13 @@ interface CurrencyProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   symbol?: string;
   /** Override the displayed suffix code. */
   code?: string;
-  /** Controlled string value. */
+  /** Controlled value (string or number). For numeric state, read the parsed value back from `onValueChange` — NOT from the `onChange` event, whose `e.target.value` is a string. */
   value?: string | number;
   /** Uncontrolled initial value. */
   defaultValue?: string | number;
-  /** Native change handler (receives the event); fires alongside onValueChange. */
+  /** Escape hatch for the native DOM event. `e.target.value` is a **string** (the raw input the user typed), not a number — the field then clamps the displayed value to the currency precision. For controlled numeric state use `onValueChange` instead. */
   onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
-  /** Convenience callback with the parsed numeric value and the formatted string. */
+  /** Primary value callback: the parsed numeric value (`number | null`) plus the clamped, formatted display string. Use this — not `onChange` — for controlled numeric state. */
   onValueChange?: (value: number | null, formatted: string) => void;
 }
 
@@ -516,7 +602,7 @@ interface CurrencyFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputEle
   required?: boolean;
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Controlled selected currency code. */
   currency?: string;
   /** Uncontrolled initial currency code. @default "USD" */
@@ -525,13 +611,13 @@ interface CurrencyFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputEle
   onCurrencyChange?: (code: string) => void;
   /** Limit the selectable currencies (codes or {value,label}); defaults to the full built-in list. */
   currencies?: Array<string | CurrencyOption>;
-  /** Controlled amount string. */
+  /** Controlled amount (string or number). For numeric state, read the parsed value back from `onValueChange` — NOT from the `onChange` event, whose `e.target.value` is a string. */
   value?: string | number;
   /** Uncontrolled initial amount. */
   defaultValue?: string | number;
-  /** Native change handler (receives the event); fires alongside onValueChange, matching Currency. */
+  /** Escape hatch for the native DOM event. `e.target.value` is a **string** (the raw input), not a number — the field then clamps the displayed value to the currency precision. For controlled numeric state use `onValueChange`. */
   onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
-  /** Callback with the parsed number, formatted string, and active currency code. */
+  /** Primary value callback: the parsed number (`number | null`), the clamped formatted string, and the active currency code. Use this — not `onChange` — for controlled numeric state. */
   onValueChange?: (value: number | null, formatted: string, currency: string) => void;
 }
 
@@ -551,15 +637,15 @@ declare function CurrencyField(props: CurrencyFieldProps): React.JSX.Element;
  *
  * @startingPoint section="Data display" subtitle="MUI-style sortable/filterable/pinnable data table" viewport="900x460"
  */
-interface DatatableProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "rows"> {
+interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, "rows"> {
   /** Column definitions. */
-  columns: DatatableColumn[];
+  columns: DatatableColumn<T>[];
   /** Row objects. In server mode, only the current page's rows. */
-  rows: any[];
+  rows: T[];
   /** Show shimmering skeleton rows instead of data. @default false */
   loading?: boolean;
   /** Returns a stable key per row. @default (r,i) => r.id ?? i */
-  rowKey?: (row: any, index: number) => string | number;
+  rowKey?: (row: T, index: number) => string | number;
   /** Render a leading checkbox-selection column. @default false */
   checkboxSelection?: boolean;
   /** Render a leading auto-numbered row column (1, 2, 3…). The number reflects each row's position in
@@ -578,7 +664,7 @@ interface DatatableProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "row
    * cross-page selections, use the complete `selectedKeys` array and re-fetch the
    * full row objects server-side rather than relying on `selectedRows`.
    */
-  batchActions?: DatatableBatchAction[];
+  batchActions?: DatatableBatchAction<T>[];
   /** Row height preset. With `showDensity`, the toolbar density button cycles it locally; changing this prop re-applies it. @default "comfortable" */
   density?: "compact" | "standard" | "comfortable";
   /** Initial rows per page. 0 disables pagination. @default 10 */
@@ -623,23 +709,23 @@ interface DatatableProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "row
   /** Make all columns editable by default (double-click a cell to edit; per-column `editable` overrides). @default false */
   editMode?: boolean;
   /** Called when a cell edit is committed: (updatedRow, originalRow, field). */
-  onRowUpdate?: (updatedRow: any, originalRow: any, field: string) => void;
+  onRowUpdate?: (updatedRow: T, originalRow: T, field: string) => void;
   /** Controlled-rows callback: receives the full next rows array after an edit (client mode). */
-  onRowsChange?: (rows: any[]) => void;
+  onRowsChange?: (rows: T[]) => void;
   /** Fired when the built-in batch editor applies columns across selected rows:
    *  (changedRows, patch, selectedKeys). The selection-toolbar "Edit" button appears
    *  automatically when there are editable columns. Server-mode caveat: `changedRows`
    *  resolves only rows on the currently loaded page; for cross-page selections use the
    *  complete `selectedKeys` array and apply the `patch` server-side. */
-  onBatchUpdate?: (changedRows: any[], patch: Record<string, any>, selectedKeys: Array<string | number>) => void;
+  onBatchUpdate?: (changedRows: T[], patch: Record<string, any>, selectedKeys: Array<string | number>) => void;
   /** Show a "Go to" page jumper in the footer when there are more than 5 pages. @default true */
   showPageJumper?: boolean;
   /** Click-to-select mode: "row" highlights the clicked row, "cell" highlights a single cell. @default "none" */
   selectionMode?: "none" | "row" | "cell";
   /** Fired when a row is clicked in "row" selection mode: (row, key). */
-  onRowClick?: (row: any, key: string | number) => void;
+  onRowClick?: (row: T, key: string | number) => void;
   /** Fired when a cell is clicked in "cell" selection mode: (value, row, field). */
-  onCellClick?: (value: any, row: any, field: string) => void;
+  onCellClick?: (value: any, row: T, field: string) => void;
   /** Fired when the active cell changes: ({ key, field } | null). */
   onActiveCellChange?: (cell: { key: string | number; field: string } | null) => void;
   /** Show the **Aggregation** toolbar button and start with the totals row on. From that panel the user
@@ -685,6 +771,18 @@ interface DatatableProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "row
   rowHeight?: number;
 }
 
+/** String-column filter operators (Datatable server mode). */
+type DatatableStringOp = "contains" | "equals" | "startsWith" | "endsWith" | "isEmpty" | "isNotEmpty" | "isAnyOf";
+/** Number-column filter operators. */
+type DatatableNumberOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "isAnyOf";
+/** Any Datatable filter operator. */
+type DatatableFilterOp = DatatableStringOp | DatatableNumberOp;
+/** A single active filter — the value shape is discriminated by `op`. */
+type DatatableFilter =
+  | { field: string; op: "isAnyOf"; value: string[] }
+  | { field: string; op: "isEmpty" | "isNotEmpty"; value?: undefined }
+  | { field: string; op: Exclude<DatatableFilterOp, "isAnyOf" | "isEmpty" | "isNotEmpty">; value: string };
+
 /** Query state reported by a server-mode Datatable. */
 interface DatatableQuery {
   /** Zero-based page index. */
@@ -693,13 +791,16 @@ interface DatatableQuery {
   pageSize: number;
   /** Active sort, or null. */
   sort: { field: string; dir: "asc" | "desc" } | null;
-  /** Active column filters. `value` is a `string[]` when `op === "isAnyOf"` (and empty for `isEmpty`/`isNotEmpty`). */
-  filters: Array<{ field: string; op: string; value: string | string[] }>;
+  /**
+   * Active column filters. String columns emit contains/equals/startsWith/endsWith/isAnyOf/isEmpty/isNotEmpty;
+   * number columns emit =, !=, >, >=, <, <=. `value` is a `string[]` for `isAnyOf` and omitted for `isEmpty`/`isNotEmpty`.
+   */
+  filters: DatatableFilter[];
   /** Quick-search text. */
   quickFilter: string;
 }
 
-interface DatatableColumn {
+interface DatatableColumn<T = any> {
   /** Row object key (also the sort/filter key). */
   field: string;
   /** Header label. @default field ("Actions" for actions columns) */
@@ -725,11 +826,11 @@ interface DatatableColumn {
   /** Allow drag-to-resize of this column. @default true */
   resizable?: boolean;
   /** Summary-footer aggregation: a preset, or a function over the column's values. */
-  aggregation?: "sum" | "avg" | "min" | "max" | "count" | ((values: any[], rows: any[]) => React.ReactNode);
+  aggregation?: "sum" | "avg" | "min" | "max" | "count" | ((values: any[], rows: T[]) => React.ReactNode);
   /** Format an aggregation result for the footer (falls back to valueFormatter). */
   aggregationFormatter?: (value: any) => React.ReactNode;
   /** Map a row to its exported CSV value (defaults to the raw field value). */
-  exportValue?: (value: any, row: any) => string | number;
+  exportValue?: (value: any, row: T) => string | number;
   /** Make this column's cells editable (double-click to edit). Overrides the grid `editMode`. */
   editable?: boolean;
   /** Editor type. "select" (or any column with `valueOptions`) renders a dropdown; else a text/number input by column type. */
@@ -742,21 +843,21 @@ interface DatatableColumn {
   /** Distinct values for the "is any of" multi-value filter (recommended in server mode). */
   valueOptions?: Array<string | { value: string; label: string }>;
   /** Format the raw value to a string/number for display. */
-  valueFormatter?: (value: any, row: any) => React.ReactNode;
+  valueFormatter?: (value: any, row: T) => React.ReactNode;
   /** Fully custom cell renderer (badges, avatars, etc.). */
-  renderCell?: (value: any, row: any) => React.ReactNode;
+  renderCell?: (value: any, row: T) => React.ReactNode;
   /** For type:"actions" — returns the row's action items. */
-  getActions?: (row: any) => DatatableRowAction[];
+  getActions?: (row: T) => DatatableRowAction<T>[];
 }
 
 /** A per-row action in an actions column. */
-interface DatatableRowAction {
+interface DatatableRowAction<T = any> {
   /** Icon node (rendered as an icon button, or leading icon in the overflow menu). */
   icon?: React.ReactNode;
   /** Accessible label / tooltip / menu text. */
   label: string;
   /** Click handler, receives the row. */
-  onClick?: (row: any) => void;
+  onClick?: (row: T) => void;
   /** Place in the ⋮ overflow menu instead of inline. @default false */
   showInMenu?: boolean;
   /** Render in danger color. */
@@ -765,19 +866,19 @@ interface DatatableRowAction {
 }
 
 /** A batch action shown in the selection toolbar. */
-interface DatatableBatchAction {
+interface DatatableBatchAction<T = any> {
   /** Button label. */
   label: string;
   /** Leading icon node. */
   icon?: React.ReactNode;
   /** Handler: (selectedKeys, selectedRows, clearSelection). */
-  onClick?: (keys: Array<string | number>, rows: any[], clearSelection: () => void) => void;
+  onClick?: (keys: Array<string | number>, rows: T[], clearSelection: () => void) => void;
   /** Render in danger color. */
   danger?: boolean;
   disabled?: boolean;
 }
 
-declare function Datatable(props: DatatableProps): React.JSX.Element;
+declare function Datatable<T = any>(props: DatatableProps<T>): React.JSX.Element;
 
 /**
  * Apply a `DatatableQuery` (the object a `serverMode` grid passes to
@@ -794,7 +895,7 @@ declare function Datatable(props: DatatableProps): React.JSX.Element;
 declare function runDatatableQuery<T = any>(
   rows: T[],
   query: DatatableQuery,
-  options?: { columns?: DatatableColumn[]; searchFields?: string[] }
+  options?: { columns?: DatatableColumn<T>[]; searchFields?: string[] }
 ): { rows: T[]; total: number; filtered: T[] };
 
 /**
@@ -823,7 +924,7 @@ interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   max?: Date;
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Show a clear (×) button when a date is set. @default true */
   clearable?: boolean;
   /** Custom display formatter (defaults to a localized medium date). */
@@ -871,7 +972,7 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   /** Disable all interaction (the popover cannot be opened). @default false */
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   onChange?: (range: DateRange) => void;
 }
 
@@ -906,7 +1007,7 @@ declare function Dialog(props: DialogProps): React.JSX.Element | null;
  * (or left/right-aligned) label.
  */
 interface DividerProps extends React.HTMLAttributes<HTMLElement> {
-  /** @default "horizontal" */
+  /** Rule axis — applies to both the plain and the labeled variant (exposed as `aria-orientation`). @default "horizontal" */
   orientation?: "horizontal" | "vertical";
   /** Indent the start of a horizontal rule. */
   inset?: boolean;
@@ -956,7 +1057,7 @@ interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "ti
   description?: React.ReactNode;
   /** Action buttons row. */
   actions?: React.ReactNode;
-  /** Add a dashed border (good for drop targets / placeholders). @deprecated Use `border`. @default false */
+  /** Add a dashed border (good for drop targets / placeholders). @deprecated since 1.4, removed in 2.0 — use `border`. @default false */
   bordered?: boolean;
   /** Add a dashed border (good for drop targets / placeholders); preferred alias for `bordered`. @default false */
   border?: boolean;
@@ -1015,7 +1116,7 @@ interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   multiple?: boolean;
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Field label rendered above the dropzone. */
   label?: React.ReactNode;
   /** Hint line under the prompt (defaults to the accept types). */
@@ -1045,7 +1146,7 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
   variant?: "solid" | "soft" | "outline" | "ghost";
   /** Color/intent, orthogonal to `variant` (mirrors Button). A destructive icon button is
    *  `tone="danger"` with any variant. @default "primary" */
-  tone?: "primary" | "danger";
+  tone?: ActionTone;
   /** Control size; "xs" (~26px) is smaller than "sm". @default "md" */
   size?: "xs" | "sm" | "md" | "lg";
   /** Fully rounded (circular). @default false */
@@ -1073,7 +1174,7 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   /** Control size. @default "md" */
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Icon node inside the field, leading edge (prefix). */
   leftIcon?: React.ReactNode;
   /** Optional suffix icon/node inside the field, trailing edge. For `type="password"`, omitting this
@@ -1088,6 +1189,8 @@ interface KanbanColumn {
   id: string;
   /** Column heading. */
   title: React.ReactNode;
+  /** Accessible name for the column group — use when `title` is a non-string node. Falls back to a string title, then the id. */
+  ariaLabel?: string;
   /** Dot color for the heading. */
   color?: string;
 }
@@ -1098,6 +1201,8 @@ interface KanbanCard {
   column: string;
   title?: React.ReactNode;
   description?: React.ReactNode;
+  /** Accessible name for the card — use when the card content is graphical/icon-only. Falls back to a string title, then "Card". */
+  ariaLabel?: string;
   /** Small uppercase tag chips. */
   tags?: React.ReactNode[];
   /** Footer node (e.g. an Avatar / due date). */
@@ -1124,6 +1229,8 @@ interface KanbanProps extends React.HTMLAttributes<HTMLDivElement> {
   onCardMove?: (cardId: string, toColumn: string, nextCards: KanbanCard[]) => void;
   /** Custom card renderer. */
   renderCard?: (card: KanbanCard) => React.ReactNode;
+  /** Accessible name for each card — supply this when `renderCard` produces graphical/icon-only content; falls back to a string title or "Card". */
+  getCardLabel?: (card: KanbanCard) => string;
 }
 
 declare function Kanban(props: KanbanProps): React.JSX.Element;
@@ -1175,7 +1282,7 @@ interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
   /** Control height preset, matching Select/Combobox. @default "md" */
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   placeholder?: string;
   /** Options — strings, {value,label,description}, or {group,options} groups. */
   options: Array<string | MultiSelectOption | MultiSelectGroup>;
@@ -1183,6 +1290,7 @@ interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
   value?: string[];
   /** Uncontrolled initial values. */
   defaultValue?: string[];
+  /** Called with the full array of selected values (empty array when none/cleared). */
   onChange?: (values: string[]) => void;
   /** Show a clear-all (×) affix when at least one value is selected. @default false */
   clearable?: boolean;
@@ -1201,18 +1309,11 @@ interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
   onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
 }
 
-interface MultiSelectOption {
-  value: string;
-  label: string;
-  /** Optional second line shown under the label. */
-  description?: string;
-}
+/** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
+type MultiSelectOption = Option;
 
-/** A group heading with its own options. */
-interface MultiSelectGroup {
-  group: string;
-  options: Array<string | MultiSelectOption>;
-}
+/** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
+type MultiSelectGroup = OptionGroup;
 
 declare function MultiSelect(props: MultiSelectProps): React.JSX.Element;
 
@@ -1246,6 +1347,12 @@ interface NavbarProps extends React.HTMLAttributes<HTMLElement> {
   sticky?: boolean;
   /** Hamburger handler shown on small screens. */
   onMenuClick?: () => void;
+  /** Drives the hamburger's `aria-expanded` and its "Open menu"/"Close menu" accessible name. */
+  menuOpen?: boolean;
+  /** Id of the menu/drawer the hamburger controls (`aria-controls`). */
+  menuControls?: string;
+  /** Accessible name for the links `<nav>` landmark. @default "Primary" */
+  navLabel?: string;
 }
 
 declare function Navbar(props: NavbarProps): React.JSX.Element;
@@ -1268,7 +1375,7 @@ interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, "onCha
   boundaries?: number;
   /** @default "md" */
   size?: "sm" | "md" | "lg";
-  /** Show a "Go to" page input for jumping directly to a page. @deprecated Use `showPageJumper`. @default false */
+  /** Show a "Go to" page input for jumping directly to a page. @deprecated since 1.4, removed in 2.0 — use `showPageJumper`. @default false */
   showJumper?: boolean;
   /** Show a "Go to" page input for jumping directly to a page; preferred alias for `showJumper`. @default false */
   showPageJumper?: boolean;
@@ -1308,8 +1415,9 @@ declare function Popover(props: PopoverProps): React.JSX.Element;
 
 /**
  * Linear progress bar — determinate or indeterminate, with semantic tones.
- * `className` and all extra HTML attributes (`style`, `id`, handlers, …) land on the
- * root wrapper; `role="progressbar"` + `aria-value*` live on the inner track.
+ * `className` and extra HTML attributes (`style`, `id`, handlers, …) land on the root
+ * wrapper; `role="progressbar"` + `aria-value*` live on the inner track. `aria-label` /
+ * `aria-labelledby` are forwarded onto that track so they actually name the bar.
  */
 interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Current value. @default 0 */
@@ -1317,13 +1425,18 @@ interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Maximum value. @default 100 */
   max?: number;
   /** @default "primary" */
-  tone?: "primary" | "info" | "success" | "warning" | "danger";
+  tone?: BarTone;
   /** @default "md" */
   size?: "sm" | "md" | "lg";
   /** Animate as an indeterminate bar (ignores value). */
   indeterminate?: boolean;
   /** Show a percentage label above the bar. */
   showLabel?: boolean;
+  /**
+   * Visible label in the meta row that also names the progressbar (via `aria-labelledby`).
+   * @default "Progress" (only rendered when `showLabel` or `label` is set)
+   */
+  label?: React.ReactNode;
 }
 
 declare function Progress(props: ProgressProps): React.JSX.Element;
@@ -1338,7 +1451,7 @@ interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   error?: React.ReactNode;
   size?: "sm" | "md" | "lg";
   /** Color intent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
 }
 
 declare function Radio(props: RadioProps): React.JSX.Element;
@@ -1358,7 +1471,7 @@ interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChan
   /** @default "md" */
   size?: "sm" | "md" | "lg";
   /** Color intent for filled stars. @default "warning" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Explicit filled-star color; overrides `tone` when set. */
   color?: string;
   /** Display only, no interaction. @default false */
@@ -1385,7 +1498,7 @@ interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onC
   required?: boolean;
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   placeholder?: string;
   /** Placeholder for the in-popover search box. @default "Search…" */
   searchPlaceholder?: string;
@@ -1416,18 +1529,11 @@ interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onC
   minWidth?: number;
 }
 
-interface SelectOption {
-  value: string;
-  label: string;
-  /** Optional second line shown under the label. */
-  description?: string;
-}
+/** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
+type SelectOption = Option;
 
-/** A group heading with its own options. */
-interface SelectGroup {
-  group: string;
-  options: Array<string | SelectOption>;
-}
+/** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
+type SelectGroup = OptionGroup;
 
 declare function Select(props: SelectProps): React.JSX.Element;
 
@@ -1448,6 +1554,7 @@ interface SidebarItem {
 /**
  * Collapsible side navigation — brand header, grouped nav items with icons and
  * badges, an optional footer, and a collapse toggle (icon-only when collapsed).
+ * Set `overlay` for a mobile off-canvas drawer (backdrop, focus trap, Escape-to-close).
  *
  * @startingPoint section="Layout" subtitle="Collapsible side navigation" viewport="280x520"
  */
@@ -1463,12 +1570,30 @@ interface SidebarProps extends React.HTMLAttributes<HTMLElement> {
   /** Show the collapse toggle. @default true */
   collapsible?: boolean;
   onCollapsedChange?: (collapsed: boolean) => void;
+  /**
+   * Render as an off-canvas drawer instead of an in-flow rail: a fixed slide-over
+   * panel behind a dismissable backdrop, portaled to `document.body`, with a focus
+   * trap, Escape-to-close, and body-scroll lock. Drive visibility with
+   * `open`/`defaultOpen`/`onOpenChange`. For a responsive layout, render the rail on
+   * desktop and the overlay on mobile. @default false
+   */
+  overlay?: boolean;
+  /** Controlled open state of the overlay drawer (only when `overlay`). */
+  open?: boolean;
+  /** Uncontrolled initial open state of the overlay drawer. @default false */
+  defaultOpen?: boolean;
+  /** Called when the overlay drawer requests open/close (backdrop, Escape). */
+  onOpenChange?: (open: boolean) => void;
+  /** Accessible name for the inner `<nav>` landmark (and the overlay dialog). @default "Main" */
+  navLabel?: string;
 }
 
 declare function Sidebar(props: SidebarProps): React.JSX.Element;
 
 /**
- * Shimmering placeholder shown while content loads.
+ * Shimmering placeholder shown while content loads. Decorative by default — the
+ * placeholder gets `aria-hidden="true"` so screen readers skip it. Pass `label` to
+ * instead announce loading via a `role="status"` live region.
  */
 interface SkeletonProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** Shape preset: "text" line(s), "circle" (1:1 aspect, full radius), or "rect" block (--radius-md). @default "text" */
@@ -1479,6 +1604,11 @@ interface SkeletonProps extends React.HTMLAttributes<HTMLSpanElement> {
   height?: string | number;
   /** For text variant: number of lines (last is shortened). @default 1 */
   lines?: number;
+  /**
+   * When set, announces loading via `role="status"` + `aria-live="polite"` + `aria-busy="true"`
+   * plus visually-hidden text (e.g. "Loading…"); otherwise the placeholder is `aria-hidden="true"`.
+   */
+  label?: string;
 }
 
 declare function Skeleton(props: SkeletonProps): React.JSX.Element;
@@ -1512,7 +1642,7 @@ interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChan
   /** Render step ticks along the rail. @default false */
   showTicks?: boolean;
   /** Color intent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Format the displayed value (label + bubble). */
   formatValue?: (value: number) => React.ReactNode;
   onChange?: (value: number) => void;
@@ -1527,9 +1657,9 @@ interface SpinnerProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** @default "md" */
   size?: "sm" | "md" | "lg" | "xl";
   /** Color. Wins over `tone` when both are set. @default "current" — inherits currentColor (visible inside buttons, themed). */
-  color?: "current" | "primary" | "success" | "warning" | "danger" | "info" | "neutral" | "white";
-  /** Color. @deprecated Use `color` instead. @default "current" — inherits currentColor (visible inside buttons, themed). */
-  tone?: "current" | "primary" | "success" | "warning" | "danger" | "info" | "neutral" | "white";
+  color?: "current" | Tone | "white";
+  /** Color. @deprecated since 1.4, removed in 2.0 — use `color`. @default "current" — inherits currentColor (visible inside buttons, themed). */
+  tone?: "current" | Tone | "white";
   /** Accessible label. @default "Loading" */
   label?: string;
 }
@@ -1584,7 +1714,7 @@ interface StepperProps extends React.HTMLAttributes<HTMLDivElement> {
   /** @default "horizontal" */
   orientation?: "horizontal" | "vertical";
   /** Color intent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Allow clicking completed/active steps. @default false */
   clickable?: boolean;
   /** Fired when a clickable step is clicked. */
@@ -1605,7 +1735,7 @@ interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>,
   error?: React.ReactNode;
   size?: "sm" | "md" | "lg";
   /** Color intent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
 }
 
 declare function Switch(props: SwitchProps): React.JSX.Element;
@@ -1688,7 +1818,7 @@ interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange
   /** @default "line" */
   variant?: "line" | "pill";
   /** Color intent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
   /** Layout axis. Vertical stacks the tablist with the indicator on its trailing edge and the panel beside it; ArrowUp/ArrowDown navigate. @default "horizontal" */
   orientation?: "horizontal" | "vertical";
 }
@@ -1700,8 +1830,10 @@ interface TabItem {
   label: React.ReactNode;
   /** Optional leading icon. */
   icon?: React.ReactNode;
-  /** Optional count pill. */
-  count?: number;
+  /** Optional count pill (e.g. `12`, `"99+"`, `"1.2k"`, or an element). Renders whenever `count != null` — pass `undefined` to hide a `0`. */
+  count?: React.ReactNode;
+  /** Disable the tab: not selectable via click or keyboard; dimmed and `aria-disabled`. */
+  disabled?: boolean;
   /** Panel content rendered when active (omit for nav-only tabs). */
   content?: React.ReactNode;
 }
@@ -1714,12 +1846,14 @@ declare function Tabs(props: TabsProps): React.JSX.Element;
 interface TagProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** Show a remove (×) button and handle its click. */
   onRemove?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  /** Accessible label for the remove (×) button. Defaults to `Remove {children}` when children is a string, else "Remove". */
+  removeLabel?: string;
   /** Optional leading icon. */
   leftIcon?: React.ReactNode;
   /** Fill style. @default "soft" */
   variant?: "soft" | "solid" | "outline";
   /** Color intent. @default "neutral" */
-  tone?: "neutral" | "primary" | "success" | "warning" | "danger" | "info";
+  tone?: Tone;
   children?: React.ReactNode;
 }
 
@@ -1740,7 +1874,7 @@ interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement
   /** Control size — same padding steps as Input. @default "md" */
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  tone?: Tone;
 }
 
 declare function Textarea(props: TextareaProps): React.JSX.Element;
@@ -1755,7 +1889,7 @@ interface TimelineItem {
   /** Icon inside the node dot. */
   icon?: React.ReactNode;
   /** Node color. */
-  tone?: "primary" | "info" | "success" | "warning" | "danger";
+  tone?: BarTone;
 }
 
 /**
@@ -1776,7 +1910,7 @@ declare function Timeline(props: TimelineProps): React.JSX.Element;
  */
 interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
   /** Semantic tone. `"neutral"` is an alias for `"default"` (matches Badge's vocabulary). @default "default" */
-  tone?: "default" | "neutral" | "success" | "warning" | "danger" | "info";
+  tone?: ToastTone;
   /** Bold heading. */
   title?: React.ReactNode;
   /** Override the tone icon. */
@@ -1802,7 +1936,7 @@ declare function ToastViewport(props: ToastViewportProps): React.JSX.Element;
 /** A single toast's options when pushed imperatively. */
 interface ToastOptions {
   /** @default "default" */
-  tone?: "default" | "neutral" | "success" | "warning" | "danger" | "info";
+  tone?: ToastTone;
   /** Bold heading. */
   title?: React.ReactNode;
   /** Body/description content. */
@@ -1921,6 +2055,19 @@ interface AppShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "chil
   height?: string | number;
   /** Pad the scrollable content region. @default true */
   padded?: boolean;
+  /** Id for the `<main>` content region and the skip-link target. @default "twc-main" */
+  mainId?: string;
+  /** Label for the visually-hidden-until-focused skip-to-content link (the shell's first child). Pass `false`/`null` to opt out. @default "Skip to content" */
+  skipLinkLabel?: React.ReactNode | false;
+  /**
+   * Open state of the sidebar's off-canvas drawer on mobile. Providing this (or
+   * `onSidebarOpenChange`) makes the shell forward `overlay`/`open`/`onOpenChange`
+   * to the `sidebar` element, so it renders as a drawer. Respects any of those
+   * props the sidebar already sets.
+   */
+  sidebarOpen?: boolean;
+  /** Called when the sidebar drawer requests open/close (backdrop, Escape) — wire a `Navbar`'s `onMenuClick` to `() => onSidebarOpenChange(true)`. */
+  onSidebarOpenChange?: (open: boolean) => void;
 }
 
 declare function AppShell(props: AppShellProps): React.JSX.Element;
@@ -1928,7 +2075,7 @@ declare function AppShell(props: AppShellProps): React.JSX.Element;
 /** Generic, token-styled element — the building block for non-flex layout. */
 interface BoxProps extends React.HTMLAttributes<HTMLElement> {
   /** Element/tag to render. @default "div" */
-  as?: keyof React.JSX.IntrinsicElements;
+  as?: PolymorphicAs;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
@@ -1966,7 +2113,7 @@ declare function Box(props: BoxProps): React.JSX.Element;
 /** Centered, max-width content wrapper with responsive horizontal padding. */
 interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
   /** Element/tag to render. @default "div" */
-  as?: keyof React.JSX.IntrinsicElements;
+  as?: PolymorphicAs;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
@@ -1981,24 +2128,35 @@ interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
 
 declare function Container(props: ContainerProps): React.JSX.Element;
 
+/** Responsive column counts per breakpoint (base + sm/md/lg/xl at 640/768/1024/1280px). */
+type ResponsiveColumns = { base?: number; sm?: number; md?: number; lg?: number; xl?: number };
+
 /** CSS grid primitive — fixed columns or a responsive auto-fill grid. */
 interface GridProps extends React.HTMLAttributes<HTMLElement> {
   /** Element/tag to render. @default "div" */
-  as?: keyof React.JSX.IntrinsicElements;
+  as?: PolymorphicAs;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
   target?: React.HTMLAttributeAnchorTarget;
   /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
   rel?: string;
-  /** Fixed number of columns (ignored when `minChildWidth` is set). */
-  columns?: number;
+  /** Fixed column count, or a responsive object `{ base, sm, md, lg, xl }` (ignored when `minChildWidth` is set). */
+  columns?: number | ResponsiveColumns;
   /** Responsive auto-fill: minimum child width (number = px, or any CSS length). */
   minChildWidth?: number | string;
-  /** Gap as a spacing-scale step (number) or any CSS length. @default 4 */
+  /** Gap (both axes) as a spacing-scale step (number) or any CSS length. @default 4 */
   gap?: number | string;
+  /** Row gap — falls back to `gap`. */
+  rowGap?: number | string;
+  /** Column gap — falls back to `gap`. */
+  columnGap?: number | string;
   align?: React.CSSProperties["alignItems"];
   justify?: React.CSSProperties["justifyItems"];
+  /** Distribute the grid's rows within extra block space. */
+  alignContent?: React.CSSProperties["alignContent"];
+  /** Distribute the grid's columns within extra inline space. */
+  justifyContent?: React.CSSProperties["justifyContent"];
 }
 
 declare function Grid(props: GridProps): React.JSX.Element;
@@ -2006,7 +2164,7 @@ declare function Grid(props: GridProps): React.JSX.Element;
 /** Flex layout primitive — rows or columns with token-based gaps. */
 interface StackProps extends React.HTMLAttributes<HTMLElement> {
   /** Element/tag to render. @default "div" */
-  as?: keyof React.JSX.IntrinsicElements;
+  as?: PolymorphicAs;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
@@ -2023,14 +2181,38 @@ interface StackProps extends React.HTMLAttributes<HTMLElement> {
   wrap?: boolean;
   /** Use inline-flex instead of flex. @default false */
   inline?: boolean;
+  /** Padding — all sides. Spacing step (number) or any CSS length. */
+  p?: number | string;
+  /** Horizontal (inline) padding. */
+  px?: number | string;
+  /** Vertical (block) padding. */
+  py?: number | string;
+  /** Top padding (overrides `py`/`p`). */
+  pt?: number | string;
+  /** Right padding (overrides `px`/`p`). */
+  pr?: number | string;
+  /** Bottom padding (overrides `py`/`p`). */
+  pb?: number | string;
+  /** Left padding (overrides `px`/`p`). */
+  pl?: number | string;
+  /** Node rendered between each child (not before the first or after the last). Pass an orientation-appropriate `Divider`. */
+  divider?: React.ReactNode;
 }
 
 declare function Stack(props: StackProps): React.JSX.Element;
 
-/** Inline code with mono font and a subtle token-styled surface. */
+/** Inline code, or a scrollable multi-line block with an optional copy button. */
 interface CodeProps extends React.HTMLAttributes<HTMLElement> {
-  /** Element/tag to render. @default "code" */
-  as?: keyof React.JSX.IntrinsicElements;
+  /** Element/tag or component to render. @default "code" (or "pre" when `block`) */
+  as?: PolymorphicAs;
+  /** Render a scrollable multi-line `<pre>` block instead of the inline pill; defaults `as` to "pre". @default false */
+  block?: boolean;
+  /** Show a copy-to-clipboard button (typically with `block`). @default false */
+  copyable?: boolean;
+  /** Accessible label for the copy button. @default "Copy code" */
+  copyLabel?: string;
+  /** Accessible label announced after a successful copy. @default "Copied" */
+  copiedLabel?: string;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
@@ -2041,10 +2223,17 @@ interface CodeProps extends React.HTMLAttributes<HTMLElement> {
 
 declare function Code(props: CodeProps): React.JSX.Element;
 
-/** Heading (h1–h6) with token typography. `level` sets the tag and default size. */
+/** Font-size token suffixes available to `Heading` (see tokens/typography.css). */
+type HeadingSize =
+  | "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl" | "display";
+
+/**
+ * Heading (h1–h6) with token typography. `level` sets the tag/semantics; `size` sets the visual
+ * scale — the two are intentionally independent (e.g. a semantic `<h1>` at a small size).
+ */
 interface HeadingProps extends React.HTMLAttributes<HTMLElement> {
   /** Override the rendered tag (e.g. render a visual h2 as an h1). */
-  as?: keyof React.JSX.IntrinsicElements;
+  as?: PolymorphicAs;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
@@ -2053,9 +2242,15 @@ interface HeadingProps extends React.HTMLAttributes<HTMLElement> {
   rel?: string;
   /** Heading level 1–6 — sets the tag and the default size. @default 2 */
   level?: 1 | 2 | 3 | 4 | 5 | 6;
-  /** Override the font-size token suffix (e.g. "3xl"). */
-  size?: string;
+  /** Font-size token (xs…7xl or display), independent of `level`. */
+  size?: HeadingSize;
+  /** Convenience: render at the display size (`var(--text-display)`) regardless of level. @default false */
+  display?: boolean;
   align?: React.CSSProperties["textAlign"];
+  /** Single-line ellipsis truncation (adds min-width:0 so it shrinks in a flex parent). @default false */
+  truncate?: boolean;
+  /** Clamp to N lines with an ellipsis (multi-line, -webkit-line-clamp). Overrides `truncate`. */
+  lineClamp?: number;
 }
 
 declare function Heading(props: HeadingProps): React.JSX.Element;
@@ -2063,7 +2258,7 @@ declare function Heading(props: HeadingProps): React.JSX.Element;
 /** Body text with token sizes and semantic color tones. Renders <p> by default. */
 interface TextProps extends React.HTMLAttributes<HTMLElement> {
   /** Element/tag to render (e.g. "span", "p"). @default "p" */
-  as?: keyof React.JSX.IntrinsicElements;
+  as?: PolymorphicAs;
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
   href?: string;
   /** Anchor target — only used with as="a" (e.g. "_blank"). */
@@ -2072,11 +2267,15 @@ interface TextProps extends React.HTMLAttributes<HTMLElement> {
   rel?: string;
   /** Font-size token suffix. @default "base" */
   size?: "xs" | "sm" | "base" | "lg" | "xl" | string;
-  /** Semantic color tone — text roles (default/muted/subtle) plus the color intents. @default "default" */
-  tone?: "default" | "muted" | "subtle" | "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Semantic color tone — text roles (default/muted/subtle), the color intents, or `"inherit"` to adopt the parent color. @default "default" */
+  tone?: TextTone;
   /** Font-weight token suffix (e.g. "medium", "semibold", "bold"). */
   weight?: "medium" | "semibold" | "bold" | string;
   align?: React.CSSProperties["textAlign"];
+  /** Single-line ellipsis truncation (adds min-width:0 so it shrinks in a flex parent). @default false */
+  truncate?: boolean;
+  /** Clamp to N lines with an ellipsis (multi-line, -webkit-line-clamp). Overrides `truncate`. */
+  lineClamp?: number;
 }
 
 declare function Text(props: TextProps): React.JSX.Element;
@@ -2104,15 +2303,30 @@ declare function useDisclosure(initial?: boolean): {
   setOpen: React.Dispatch<React.SetStateAction<boolean>>;
 };
 
-/** Controlled/uncontrolled state — the pattern every form component needs. */
+/**
+ * Controlled/uncontrolled state — the pattern every form component needs.
+ * Returns `[value, setValue, isControlled]`; the third element reports whether a
+ * `value` prop is currently driving the state. In development it warns once if a
+ * component switches between controlled and uncontrolled.
+ */
 declare function useControllableState<T>(options?: {
   value?: T;
   defaultValue?: T;
   onChange?: (value: T) => void;
-}): [T, (next: T | ((prev: T) => T)) => void];
+}): [T, (next: T | ((prev: T) => T)) => void, boolean];
 
-/** Reactively match a media query (SSR-safe). */
-declare function useMediaQuery(query: string): boolean;
+interface UseMediaQueryOptions {
+  /** Value on the server and first client render (before the after-mount sync). @default false */
+  defaultValue?: boolean;
+  /** Read `matchMedia` eagerly in the initializer — client-only apps with no SSR. @default false */
+  initializeWithValue?: boolean;
+}
+
+/**
+ * Reactively match a media query. Returns `defaultValue` on the server and the
+ * first client render, then syncs after mount — so hydration never mismatches.
+ */
+declare function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;
 
 /** `true` when the user requests reduced motion. */
 declare function usePrefersReducedMotion(): boolean;
@@ -2140,13 +2354,13 @@ declare function useColorScheme(options?: UseColorSchemeOptions): {
 declare function useEventListener(
   eventName: string,
   handler: (event: any) => void,
-  element?: React.RefObject<any> | EventTarget | null,
+  element?: React.RefObject<any | null> | EventTarget | null,
   options?: boolean | AddEventListenerOptions
 ): void;
 
 /** Call `handler` when a pointer/touch event lands outside `ref`. */
 declare function useClickOutside<T extends HTMLElement = HTMLElement>(
-  ref: React.RefObject<T>,
+  ref: React.RefObject<T | null>,
   handler: (event: Event) => void,
   events?: string[]
 ): void;
@@ -2197,11 +2411,11 @@ declare function useTimeout(callback: () => void, delay: number | null): void;
 declare function useWindowSize(): { width: number; height: number };
 
 /** `true` while the pointer is over the element referenced by `ref`. */
-declare function useHover<T extends HTMLElement = HTMLElement>(ref: React.RefObject<T>): boolean;
+declare function useHover<T extends HTMLElement = HTMLElement>(ref: React.RefObject<T | null>): boolean;
 
 /** The latest IntersectionObserver entry for the element referenced by `ref`. */
 declare function useIntersectionObserver<T extends HTMLElement = HTMLElement>(
-  ref: React.RefObject<T>,
+  ref: React.RefObject<T | null>,
   options?: IntersectionObserverInit
 ): IntersectionObserverEntry | null;
 
@@ -2211,4 +2425,28 @@ declare function useScrollLock(locked?: boolean): void;
 /** A stable, SSR-safe unique id (optionally prefixed). */
 declare function useId(prefix?: string): string;
 
-export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, Box, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableProps, type DatatableQuery, type DatatableRowAction, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Grid, type GridProps, Heading, type HeadingProps, IconButton, type IconButtonProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, Pagination, type PaginationProps, Popover, type PopoverProps, Progress, type ProgressProps, Radio, type RadioProps, Rating, type RatingProps, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextProps, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, ToastViewport, type ToastViewportProps, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, type UseColorSchemeOptions, type UseKeyPressOptions, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+/** Options for {@link useFocusTrap}. */
+interface UseFocusTrapOptions {
+  /** Restore focus to the previously-focused element when the trap deactivates. @default true */
+  restoreFocus?: boolean;
+}
+
+/**
+ * Trap focus inside the modal region referenced by `ref`. While `active`, focus
+ * moves inside on activate, Tab/Shift+Tab cycle within it, and (by default) focus
+ * is restored to the previously-focused element on deactivate. Escape is NOT
+ * handled — that stays with the component. SSR-safe.
+ */
+declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
+  ref: React.RefObject<T | null>,
+  active?: boolean,
+  options?: UseFocusTrapOptions
+): void;
+
+/**
+ * Returns a stable `render(node)` that portals `node` to `document.body`, or `null`
+ * on the server (no document). Centralizes the overlay portal pattern.
+ */
+declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
+
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Grid, type GridProps, Heading, type HeadingProps, type HeadingSize, IconButton, type IconButtonProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, type PolymorphicAs, Popover, type PopoverProps, Progress, type ProgressProps, Radio, type RadioProps, Rating, type RatingProps, type ResponsiveColumns, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextProps, type TextTone, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };