twico-ui 0.1.0 → 1.0.0

package/dist/index.d.cts

@@ -1,1501 +1,2189 @@
 import * as React from 'react';
 
-/**
- * Vertically stacked, expandable disclosure panels with smooth height animation.
- *
- * @startingPoint section="Navigation" subtitle="Expandable disclosure panels" viewport="700x300"
- */
-interface AccordionProps extends React.HTMLAttributes<HTMLDivElement> {
-  items: AccordionItem[];
-  /** Allow multiple panels open at once. @default false */
-  multiple?: boolean;
-  /** Values open on first render. */
-  defaultOpen?: string[];
-}
-
-interface AccordionItem {
-  value: string;
-  label: React.ReactNode;
-  content: React.ReactNode;
-  icon?: React.ReactNode;
-}
-
+/**
+ * Vertically stacked, expandable disclosure panels with smooth height animation.
+ *
+ * @startingPoint section="Navigation" subtitle="Expandable disclosure panels" viewport="700x300"
+ */
+interface AccordionProps extends React.HTMLAttributes<HTMLDivElement> {
+  items: AccordionItem[];
+  /** Allow multiple panels open at once. @default false */
+  multiple?: boolean;
+  /** Values open on first render. */
+  defaultOpen?: string[];
+  /** Controlled open panel values; pair with `onOpenChange`. */
+  open?: string[];
+  /** Called with the next open values whenever a panel is toggled. */
+  onOpenChange?: (values: string[]) => void;
+}
+
+interface AccordionItem {
+  value: string;
+  label: React.ReactNode;
+  content: React.ReactNode;
+  icon?: React.ReactNode;
+}
+
 declare function Accordion(props: AccordionProps): React.JSX.Element;
 
-/**
- * Inline message banner with semantic tones, optional title, icon, and dismiss.
- */
-interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** @default "info" */
-  tone?: "info" | "success" | "warning" | "danger";
-  /** Bold heading line. */
-  title?: React.ReactNode;
-  /** Override the default tone icon. */
-  icon?: React.ReactNode;
-  /** Show a close button and handle dismissal. */
-  onClose?: () => void;
-  children?: React.ReactNode;
-}
-
+/**
+ * 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";
+  /** Fill style. @default "soft" */
+  variant?: "soft" | "solid" | "outline";
+  /** Bold heading line. */
+  title?: React.ReactNode;
+  /** Override the default tone icon. */
+  icon?: React.ReactNode;
+  /** Show a close button and handle dismissal. */
+  onClose?: () => void;
+  children?: React.ReactNode;
+}
+
 declare function Alert(props: AlertProps): React.JSX.Element;
 
-/**
- * User avatar — image with graceful fallback to initials, optional status dot.
- */
-interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** Image URL. Falls back to initials on error or when absent. */
-  src?: string;
-  /** Full name — used for initials and the accessible label. */
-  name?: string;
-  /** @default "md" */
-  size?: "xs" | "sm" | "md" | "lg" | "xl";
-  /** Rounded-square instead of circle. */
-  square?: boolean;
-  /** Presence indicator. */
-  status?: "online" | "busy" | "away" | "offline";
-  /** Adds a brand ring around the avatar. */
-  ring?: boolean;
-}
-
+/**
+ * User avatar — image with graceful fallback to initials, optional status dot.
+ */
+interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Image URL. Falls back to initials on error or when absent. */
+  src?: string;
+  /** Full name — used for initials and the accessible label. */
+  name?: string;
+  /** @default "md" */
+  size?: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Rounded-square instead of circle. */
+  square?: boolean;
+  /** Presence indicator. */
+  status?: "online" | "busy" | "away" | "offline";
+  /** Adds a brand ring around the avatar. */
+  ring?: boolean;
+}
+
 declare function Avatar(props: AvatarProps): React.JSX.Element;
 
-interface MenuItemDef {
-  /** Item label (also used for a heading when `heading` is true). */
-  label?: React.ReactNode;
-  /** Leading icon. */
-  icon?: React.ReactNode;
-  /** Click handler — menu closes after it runs. */
-  onClick?: () => void;
-  /** Right-aligned shortcut hint (mono). */
-  shortcut?: string;
-  /** Render in danger color. */
-  danger?: boolean;
-  disabled?: boolean;
-  /** Render a divider line (ignores other fields). */
-  separator?: boolean;
-  /** Render as an uppercase section heading. */
-  heading?: boolean;
-}
-
-/**
- * Dropdown menu. Provide a `trigger` element and an `items` array. Renders in a
- * portal (never clipped), auto-flips near the viewport edge, supports an optional
- * rich `header`, and is keyboard-navigable (↑/↓, Enter, Esc). Closes on outside
- * click, Esc, or item selection.
- *
- * @startingPoint section="Overlay" subtitle="Dropdown menu with headings & shortcuts" viewport="700x360"
- */
-interface MenuProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** Clickable trigger (e.g. a Button or IconButton). */
-  trigger: React.ReactNode;
-  items: MenuItemDef[];
-  /** Horizontal alignment to the trigger. @default "start" */
-  align?: "start" | "end";
-  /** Optional rich header node rendered above the items (e.g. user info). */
-  header?: React.ReactNode;
-  /** Fixed menu width in px (defaults to max(200, trigger width)). */
-  width?: number;
-}
-
+interface MenuItemDef {
+  /** Item label (also used for a heading when `heading` is true). */
+  label?: React.ReactNode;
+  /** Leading icon. */
+  icon?: React.ReactNode;
+  /** Click handler — menu closes after it runs. */
+  onClick?: () => void;
+  /** Right-aligned shortcut hint (mono). */
+  shortcut?: string;
+  /** Render in danger color. */
+  danger?: boolean;
+  disabled?: boolean;
+  /** Render a divider line (ignores other fields). */
+  separator?: boolean;
+  /** Render as an uppercase section heading. */
+  heading?: boolean;
+}
+
+/**
+ * Dropdown menu. Provide a `trigger` element and an `items` array. Renders in a
+ * portal (never clipped), auto-flips near the viewport edge, supports an optional
+ * rich `header`, and is keyboard-navigable (↑/↓, Home/End, Enter/Space, Esc).
+ * Closes on outside click, Esc, or item selection.
+ *
+ * @startingPoint section="Overlay" subtitle="Dropdown menu with headings & shortcuts" viewport="700x360"
+ */
+interface MenuProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Clickable trigger (e.g. a Button or IconButton). */
+  trigger: React.ReactNode;
+  items: MenuItemDef[];
+  /** Horizontal alignment to the trigger. @default "start" */
+  align?: "start" | "end";
+  /** Optional rich header node rendered above the items (e.g. user info). */
+  header?: React.ReactNode;
+  /** Fixed menu width in px (defaults to max(200, trigger width)). */
+  width?: number;
+  /** Open on first render in uncontrolled mode. @default false */
+  defaultOpen?: boolean;
+  /** Controlled open state — pair with `onOpenChange`. Omit for internal (uncontrolled) state. */
+  open?: boolean;
+  /** Called with the requested open state on trigger click, item select, Esc, or outside click. */
+  onOpenChange?: (open: boolean) => void;
+}
+
 declare function Menu(props: MenuProps): React.JSX.Element;
 
-/**
- * Avatar that opens a dropdown menu of account options — the classic user menu.
- * Shows the user's avatar (optionally with name/email), and a portaled menu with
- * a rich header (avatar + name + email) above the items.
- *
- * @startingPoint section="Data display" subtitle="Avatar account menu" viewport="700x320"
- */
-interface AvatarMenuProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "title"> {
-  /** User's full name (drives initials + header). */
-  name?: string;
-  /** Avatar image URL. */
-  src?: string;
-  /** Email shown in the header (and trigger when `showName`). */
-  email?: string;
-  /** Subtitle override for the header/trigger (defaults to `email`). */
-  subtitle?: React.ReactNode;
-  /** Presence dot. */
-  status?: "online" | "busy" | "away" | "offline";
-  /** Trigger avatar size. @default "sm" */
-  size?: "xs" | "sm" | "md" | "lg" | "xl";
-  /** Menu items (same shape as Menu's items). */
-  items: MenuItemDef[];
-  /** Show name/email next to the avatar in the trigger. @default false */
-  showName?: boolean;
-  /** Show a chevron in the trigger (defaults to `showName`). */
-  showChevron?: boolean;
-  /** Menu alignment to the trigger. @default "end" */
-  align?: "start" | "end";
-}
-
+/**
+ * Avatar that opens a dropdown menu of account options — the classic user menu.
+ * Shows the user's avatar (optionally with name/email), and a portaled menu with
+ * a rich header (avatar + name + email) above the items.
+ *
+ * @startingPoint section="Data display" subtitle="Avatar account menu" viewport="700x320"
+ */
+interface AvatarMenuProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "title"> {
+  /** User's full name (drives initials + header). */
+  name?: string;
+  /** Avatar image URL. */
+  src?: string;
+  /** Email shown in the header (and trigger when `showName`). */
+  email?: string;
+  /** Subtitle override for the header/trigger (defaults to `email`). */
+  subtitle?: React.ReactNode;
+  /** Presence dot. */
+  status?: "online" | "busy" | "away" | "offline";
+  /** Trigger avatar size. @default "sm" */
+  size?: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Menu items (same shape as Menu's items). */
+  items: MenuItemDef[];
+  /** Show name/email next to the avatar in the trigger. @default false */
+  showName?: boolean;
+  /** Show a chevron in the trigger (defaults to `showName`). */
+  showChevron?: boolean;
+  /** Menu alignment to the trigger. @default "end" */
+  align?: "start" | "end";
+}
+
 declare function AvatarMenu(props: AvatarMenuProps): React.JSX.Element;
 
-/**
- * Small status label / count. Six tones × three variants.
- */
-interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** Semantic color. @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
-  /** Fill style. @default "soft" */
-  variant?: "soft" | "solid" | "outline";
-  /** @default "md" */
-  size?: "md" | "lg";
-  /** Show a leading status dot. */
-  dot?: boolean;
-  children?: React.ReactNode;
-}
-
+/**
+ * Small status label / count. Six tones × three variants.
+ */
+interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Semantic color. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Fill style. @default "soft" */
+  variant?: "soft" | "solid" | "outline";
+  /** Size scale. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Show a leading status dot. */
+  dot?: boolean;
+  children?: React.ReactNode;
+}
+
 declare function Badge(props: BadgeProps): React.JSX.Element;
 
-interface BreadcrumbItem {
-  /** Visible label. */
-  label: React.ReactNode;
-  /** Link target (omit on the last/current item). */
-  href?: string;
-  /** Optional leading icon. */
-  icon?: React.ReactNode;
-  /** Click handler (for SPA navigation). */
-  onClick?: (e: React.MouseEvent) => void;
-}
-
-/**
- * Breadcrumb trail showing the path to the current page. Supports leading icons
- * per item and collapsing the middle into a “…” that expands on click.
- *
- * @startingPoint section="Navigation" subtitle="Breadcrumb trail" viewport="700x80"
- */
-interface BreadcrumbProps extends React.HTMLAttributes<HTMLElement> {
-  /** Ordered trail; the last item renders as the current page. */
-  items: BreadcrumbItem[];
-  /** Custom separator node (defaults to a chevron). */
-  separator?: React.ReactNode;
-  /** Collapse to first + last items past this count (0 = never). @default 0 */
-  maxItems?: number;
-}
-
+interface BreadcrumbItem {
+  /** Visible label. */
+  label: React.ReactNode;
+  /** Link target (omit on the last/current item). */
+  href?: string;
+  /** Optional leading icon. */
+  icon?: React.ReactNode;
+  /** Click handler (for SPA navigation). */
+  onClick?: (e: React.MouseEvent) => void;
+}
+
+/**
+ * Breadcrumb trail showing the path to the current page. Supports leading icons
+ * per item and collapsing the middle into a “…” that expands on click.
+ *
+ * @startingPoint section="Navigation" subtitle="Breadcrumb trail" viewport="700x80"
+ */
+interface BreadcrumbProps extends React.HTMLAttributes<HTMLElement> {
+  /** Ordered trail; the last item renders as the current page. */
+  items: BreadcrumbItem[];
+  /** Custom separator node (defaults to a chevron). */
+  separator?: React.ReactNode;
+  /** Collapse to first + last items past this count (0 = never). @default 0 */
+  maxItems?: number;
+}
+
 declare function Breadcrumb(props: BreadcrumbProps): React.JSX.Element;
 
-/**
- * Primary action button with solid / soft / outline / ghost / danger variants,
- * three sizes, loading state, icons, and a click ripple.
- *
- * @startingPoint section="Buttons" subtitle="Action button with ripple + variants" viewport="700x200"
- */
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  /** Visual style. @default "solid" */
-  variant?: "solid" | "soft" | "outline" | "ghost" | "danger";
-  /** Control size. @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** Icon node rendered before the label. */
-  leftIcon?: React.ReactNode;
-  /** Icon node rendered after the label. */
-  rightIcon?: React.ReactNode;
-  /** Show a spinner and block interaction. @default false */
-  loading?: boolean;
-  /** Stretch to fill the container width. @default false */
-  fullWidth?: boolean;
-  /** Render as a different element (e.g. "a"). @default "button" */
-  as?: "button" | "a";
-  children?: React.ReactNode;
-}
-
+/**
+ * Primary action button with a solid / soft / outline / ghost **variant** (fill style) crossed with a
+ * **tone** (primary / danger color), four sizes, loading state, icons, and a click ripple. A danger
+ * button is `tone="danger"` with any variant (e.g. `<Button tone="danger">`, `<Button variant="soft"
+ * tone="danger">`) — danger is no longer a variant value.
+ *
+ * @startingPoint section="Buttons" subtitle="Action button with ripple + variants" viewport="700x200"
+ */
+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";
+  /** Control size; "xs" (~26px) is smaller than "sm". @default "md" */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Icon node rendered before the label. */
+  leftIcon?: React.ReactNode;
+  /** Icon node rendered after the label. */
+  rightIcon?: React.ReactNode;
+  /** Show a spinner and block interaction. @default false */
+  loading?: boolean;
+  /** Stretch to fill the container width. @default false */
+  fullWidth?: boolean;
+  /** Render as a different element (e.g. "a"). @default "button" */
+  as?: "button" | "a";
+  /** 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;
+  children?: React.ReactNode;
+}
+
 declare function Button(props: ButtonProps): React.JSX.Element;
 
-/**
- * Surface container for grouped content. Supports header (title/subtitle),
- * body, footer, three variants, and an interactive hover-lift.
- *
- * @startingPoint section="Data display" subtitle="Content card with header & footer" viewport="700x260"
- */
-interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Bold title in the card header. */
-  title?: React.ReactNode;
-  /** Muted subtitle under the title. */
-  subtitle?: React.ReactNode;
-  /** Footer content (e.g. action buttons). */
-  footer?: React.ReactNode;
-  /** Visual style. @default "elevated" */
-  variant?: "elevated" | "outline" | "soft";
-  /** Inner padding. @default "md" */
-  padding?: "none" | "md" | "lg";
-  /** Adds a hover-lift + pointer cursor. */
-  interactive?: boolean;
-  children?: React.ReactNode;
-}
-
+/**
+ * Surface container for grouped content. Supports header (title/subtitle),
+ * body, footer, three variants, and an interactive hover-lift.
+ *
+ * @startingPoint section="Data display" subtitle="Content card with header & footer" viewport="700x260"
+ */
+interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Bold title in the card header. */
+  title?: React.ReactNode;
+  /** Muted subtitle under the title. */
+  subtitle?: React.ReactNode;
+  /** Footer content (e.g. action buttons). */
+  footer?: React.ReactNode;
+  /** Visual style. @default "elevated" */
+  variant?: "elevated" | "outline" | "soft";
+  /** Inner padding. @default "md" */
+  padding?: "none" | "md" | "lg";
+  /** Adds a hover-lift + pointer cursor. */
+  interactive?: boolean;
+  /** Stretch to fill the parent cell (`height: 100%`) — equal-height cards in a grid/flex row. */
+  fullHeight?: boolean;
+  children?: React.ReactNode;
+}
+
 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.
- *
- * @startingPoint section="Data display" subtitle="Sliding carousel" viewport="700x320"
- */
-interface CarouselProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Show prev/next arrows. @default true */
-  showArrows?: boolean;
-  /** Show dot indicators. @default true */
-  showDots?: boolean;
-  /** Wrap around at the ends. @default true */
-  loop?: boolean;
-  /** Auto-advance slides. @default false */
-  autoPlay?: boolean;
-  /** Autoplay interval in ms. @default 4000 */
-  interval?: number;
-  /** Slides (each child is one slide). */
-  children?: React.ReactNode;
-}
-
+/**
+ * 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`.
+ *
+ * @startingPoint section="Data display" subtitle="Sliding carousel" viewport="700x320"
+ */
+interface CarouselProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Controlled active slide index — pair with `onIndexChange`. */
+  index?: number;
+  /** Initial slide index when uncontrolled. @default 0 */
+  defaultIndex?: number;
+  /** Fired when the active slide changes (arrows, dots, or autoplay): (index). */
+  onIndexChange?: (index: number) => void;
+  /** Show prev/next arrows. @default true */
+  showArrows?: boolean;
+  /** Show dot indicators. @default true */
+  showDots?: boolean;
+  /** Wrap around at the ends. @default true */
+  loop?: boolean;
+  /** Auto-advance slides. @default false */
+  autoPlay?: boolean;
+  /** Autoplay interval in ms. @default 4000 */
+  interval?: number;
+  /** 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;
-}
-
-/**
- * Lightweight, dependency-free SVG chart — bar or line, single or multi-series,
- * with grid, axes, animated entrance, tooltips, and optional legend.
- *
- * @startingPoint section="Data display" subtitle="Bar / line chart (no deps)" viewport="700x280"
- */
-interface ChartProps 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[];
-  /** Pixel height. @default 220 */
-  height?: number;
-  /** Horizontal grid lines. @default true */
-  showGrid?: boolean;
-  /** Axis labels. @default true */
-  showAxis?: boolean;
-  /** Series legend (multi-series). @default false */
-  showLegend?: boolean;
-  /** Tooltip value formatter. */
-  valueFormat?: (value: number) => string;
-}
-
+interface ChartDatum {
+  /** X-axis label. */
+  label: React.ReactNode;
+  /** One numeric field per series key (default key is "value"). */
+  [key: string]: any;
+}
+
+/**
+ * Lightweight, dependency-free SVG chart — bar or line, single or multi-series,
+ * with grid, axes, animated entrance, tooltips, and optional legend.
+ *
+ * @startingPoint section="Data display" subtitle="Bar / line chart (no deps)" viewport="700x280"
+ */
+interface ChartProps 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[];
+  /** Pixel height. @default 220 */
+  height?: number;
+  /** Horizontal grid lines. @default true */
+  showGrid?: boolean;
+  /** Axis labels. @default true */
+  showAxis?: boolean;
+  /** Series legend (multi-series). @default false */
+  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. */
+  valueFormat?: (value: number) => string;
+  /** Accessible name for the chart's `<svg role="img">`. Defaults to `"<type> chart"`. Also accepts `aria-label`. */
+  ariaLabel?: string;
+}
+
 declare function Chart(props: ChartProps): React.JSX.Element;
 
-/**
- * Checkbox with animated checkmark, label, description, and indeterminate state.
- */
-interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
-  label?: React.ReactNode;
-  description?: React.ReactNode;
-  /** Render the dash (mixed) state. */
-  indeterminate?: boolean;
-  size?: "sm" | "md";
-}
-
+/**
+ * Checkbox with animated checkmark, label, description, and indeterminate state.
+ */
+interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Error message shown below the control; tints the box red and wires `aria-invalid`/`aria-describedby`. @default undefined */
+  error?: React.ReactNode;
+  /** Render the dash (mixed) state. */
+  indeterminate?: boolean;
+  size?: "sm" | "md" | "lg";
+  /** Color intent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+}
+
 declare function Checkbox(props: CheckboxProps): React.JSX.Element;
 
-/**
- * Color picker with a saturation/value square, hue slider, hex input, and
- * preset swatches. Opens in a popover; value is a hex string.
- *
- * @startingPoint section="Inputs" subtitle="Color picker with hue + presets" viewport="700x120"
- */
-interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
-  label?: React.ReactNode;
-  /** Controlled hex value, e.g. "#6366F1". */
-  value?: string;
-  /** Uncontrolled initial hex. @default "#6366F1" */
-  defaultValue?: string;
-  /** Preset swatches (hex strings). */
-  presets?: string[];
-  onChange?: (hex: string) => void;
-}
-
+/**
+ * Color picker with a saturation/value square, hue slider, hex input, and
+ * preset swatches. Opens in a popover; value is a hex string.
+ *
+ * @startingPoint section="Inputs" subtitle="Color picker with hue + presets" viewport="700x120"
+ */
+interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — turns the field red and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk to the label). @default false */
+  required?: boolean;
+  /** Controlled hex value, e.g. "#6366F1". */
+  value?: string;
+  /** Uncontrolled initial hex. @default "#6366F1" */
+  defaultValue?: string;
+  /** Preset swatches (hex strings). */
+  presets?: string[];
+  /** 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";
+  onChange?: (hex: string) => void;
+}
+
 declare function ColorPicker(props: ColorPickerProps): React.JSX.Element;
 
-/**
- * Searchable single-select (MUI-Autocomplete style) — type directly in the
- * field to filter; the overlay shows only options. Supports grouped options
- * and two-line (title + subtitle) options.
- * Keyboard: ↑/↓ to move, Enter to select, Esc to close.
- *
- * @startingPoint section="Selects" subtitle="Searchable single-select dropdown" viewport="700x160"
- */
-interface ComboboxProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onChange" | "defaultValue"> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-  size?: "sm" | "md" | "lg";
-  /** Field placeholder. */
-  placeholder?: string;
-  /** Options — strings, {value,label,description}, or {group,options} groups. */
-  options: Array<string | ComboboxOption | ComboboxGroup>;
-  /** Controlled selected value. */
-  value?: string | null;
-  /** Uncontrolled initial value. */
-  defaultValue?: string | null;
-  onChange?: (value: string | null) => void;
-  /** Show a clear (×) affix when a value is selected. */
-  clearable?: boolean;
-  disabled?: boolean;
-}
-
-interface ComboboxOption {
-  value: string;
-  label: string;
-  /** Optional second line shown under the label. */
-  description?: string;
-}
-
-/** A group heading with its own options. */
-interface ComboboxGroup {
-  group: string;
-  options: Array<string | ComboboxOption>;
-}
-
+/**
+ * Searchable single-select (MUI-Autocomplete style) — type directly in the
+ * field to filter; the overlay shows only options. Supports grouped options
+ * and two-line (title + subtitle) options.
+ * Keyboard: ↑/↓ to move, Enter to select, Esc to close.
+ *
+ * @startingPoint section="Selects" subtitle="Searchable single-select dropdown" viewport="700x160"
+ */
+interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
+  label?: React.ReactNode;
+  hint?: React.ReactNode;
+  error?: React.ReactNode;
+  required?: boolean;
+  size?: "sm" | "md" | "lg";
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Field placeholder. */
+  placeholder?: string;
+  /** Options — strings, {value,label,description}, or {group,options} groups. */
+  options: Array<string | ComboboxOption | ComboboxGroup>;
+  /** Controlled selected value. */
+  value?: string | null;
+  /** Uncontrolled initial value. */
+  defaultValue?: string | null;
+  onChange?: (value: string | null) => void;
+  /** Show a clear (×) affix when a value is selected. */
+  clearable?: boolean;
+  disabled?: boolean;
+  /** Open the menu upward instead of down (e.g. near a viewport bottom). @default "bottom" */
+  placement?: "bottom" | "top";
+  /** Render the dropdown in a portal (position:fixed on document.body) so it is never clipped by a
+   *  scrolling/overflow-hidden ancestor; auto-flips up near the viewport bottom. Set false to render
+   *  inline. @default true */
+  portal?: boolean;
+  /** Minimum popover width in px when portaled (useful when the control is narrow). @default 0 */
+  minWidth?: number;
+  /** Composed with the field's open-on-focus behavior — your handler runs first. */
+  onFocus?: React.FocusEventHandler<HTMLInputElement>;
+  /** Composed with the field's keyboard navigation (Arrows/Enter/Escape) — your handler runs first; call `event.preventDefault()` to suppress it. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+}
+
+interface ComboboxOption {
+  value: string;
+  label: string;
+  /** Optional second line shown under the label. */
+  description?: string;
+}
+
+/** A group heading with its own options. */
+interface ComboboxGroup {
+  group: string;
+  options: Array<string | ComboboxOption>;
+}
+
 declare function Combobox(props: ComboboxProps): React.JSX.Element;
 
-interface Command {
-  /** Stable id. */
-  id?: string;
-  /** Visible label. */
-  label: string;
-  /** Secondary description line. */
-  description?: string;
-  /** Leading icon. */
-  icon?: React.ReactNode;
-  /** Right-aligned shortcut hint, e.g. "⌘K". */
-  shortcut?: string;
-  /** Group heading this command appears under. */
-  group?: string;
-  /** Extra search terms (space-separated). */
-  keywords?: string;
-  /** Invoked on Enter / click (palette closes after). */
-  onSelect?: () => void;
-}
-
-/**
- * ⌘K-style command palette — fuzzy-ish search over grouped commands with full
- * keyboard nav (↑/↓, Enter, Esc). Drive `open` yourself (e.g. on Cmd/Ctrl+K).
- */
-interface CommandPaletteProps extends React.HTMLAttributes<HTMLDivElement> {
-  open: boolean;
-  onClose?: () => void;
-  commands: Command[];
-  placeholder?: string;
-  emptyText?: string;
-}
-
+interface Command {
+  /** Stable id. */
+  id?: string;
+  /** Visible label. */
+  label: string;
+  /** Secondary description line. */
+  description?: string;
+  /** Leading icon. */
+  icon?: React.ReactNode;
+  /** Right-aligned shortcut hint, e.g. "⌘K". */
+  shortcut?: string;
+  /** Group heading this command appears under. */
+  group?: string;
+  /** Extra search terms (space-separated). */
+  keywords?: string;
+  /** Invoked on Enter / click (palette closes after). */
+  onSelect?: () => void;
+  /** Alias for `onSelect`, matching the other item-array APIs (Menu, List, Sidebar, …) — used when `onSelect` is absent. */
+  onClick?: () => void;
+}
+
+/**
+ * ⌘K-style command palette — fuzzy-ish search over grouped commands with full
+ * keyboard nav (↑/↓, Enter, Esc). Drive `open` yourself (e.g. on Cmd/Ctrl+K).
+ * While open, focus is trapped inside the palette (Tab/Shift+Tab cycle) and is
+ * restored to the previously focused element on close.
+ */
+interface CommandPaletteProps extends React.HTMLAttributes<HTMLDivElement> {
+  open: boolean;
+  onClose?: () => void;
+  commands: Command[];
+  placeholder?: string;
+  emptyText?: string;
+}
+
 declare function CommandPalette(props: CommandPaletteProps): React.JSX.Element | null;
 
-/**
- * Currency input with a fixed currency defined in code. Shows the symbol as a
- * prefix and the currency code as a suffix, and enforces decimal precision
- * (e.g. precision 2 accepts 2.25 but not 2.259).
- *
- * @startingPoint section="Inputs" subtitle="Currency input with symbol + code" viewport="700x140"
- */
-interface CurrencyProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-  size?: "sm" | "md" | "lg";
-  /** 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). */
-  precision?: number;
-  /** Override the displayed prefix symbol. */
-  symbol?: string;
-  /** Override the displayed suffix code. */
-  code?: string;
-  /** Controlled string value. */
-  value?: string | number;
-  /** Uncontrolled initial value. */
-  defaultValue?: string | number;
-  /** Native change handler (receives the event). */
-  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
-  /** Convenience callback with the parsed numeric value and the formatted string. */
-  onValueChange?: (value: number | null, formatted: string) => void;
-}
-
+/**
+ * Currency input with a fixed currency defined in code. Shows the symbol as a
+ * prefix and the currency code as a suffix, and enforces decimal precision
+ * (e.g. precision 2 accepts 2.25 but not 2.259).
+ *
+ * @startingPoint section="Inputs" subtitle="Currency input with symbol + code" viewport="700x140"
+ */
+interface CurrencyProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
+  label?: React.ReactNode;
+  /** Helper text below the field; linked to the input via aria-describedby. */
+  hint?: React.ReactNode;
+  /** Error text below the field; sets aria-invalid and is linked via aria-describedby (takes precedence over hint). */
+  error?: React.ReactNode;
+  /** Intercepted to render the label asterisk, and forwarded to the native input as `required`. @default false */
+  required?: boolean;
+  size?: "sm" | "md" | "lg";
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** 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). */
+  precision?: number;
+  /** Override the displayed prefix symbol. */
+  symbol?: string;
+  /** Override the displayed suffix code. */
+  code?: string;
+  /** Controlled string value. */
+  value?: string | number;
+  /** Uncontrolled initial value. */
+  defaultValue?: string | number;
+  /** Native change handler (receives the event); fires alongside onValueChange. */
+  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  /** Convenience callback with the parsed numeric value and the formatted string. */
+  onValueChange?: (value: number | null, formatted: string) => void;
+}
+
 declare function Currency(props: CurrencyProps): React.JSX.Element;
 
-interface CurrencyOption { value: string; label: string; }
-
-/**
- * Currency input where the USER selects the currency from a dropdown. The chosen
- * currency drives the prefix symbol, the suffix code, and the enforced decimal
- * precision.
- *
- * @startingPoint section="Inputs" subtitle="Currency input with selectable currency" viewport="700x140"
- */
-interface CurrencyFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-  size?: "sm" | "md" | "lg";
-  /** Controlled selected currency code. */
-  currency?: string;
-  /** Uncontrolled initial currency code. @default "USD" */
-  defaultCurrency?: string;
-  /** Called when the user picks a different currency. */
-  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. */
-  value?: string | number;
-  /** Uncontrolled initial amount. */
-  defaultValue?: string | number;
-  /** Callback with the parsed number, formatted string, and active currency code. */
-  onValueChange?: (value: number | null, formatted: string, currency: string) => void;
-}
-
+interface CurrencyOption { value: string; label: string; }
+
+/**
+ * Currency input where the USER selects the currency from a dropdown. The chosen
+ * currency drives the prefix symbol, the suffix code, and the enforced decimal
+ * precision.
+ *
+ * @startingPoint section="Inputs" subtitle="Currency input with selectable currency" viewport="700x140"
+ */
+interface CurrencyFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
+  label?: React.ReactNode;
+  /** Helper text below the field; linked to the input via aria-describedby. */
+  hint?: React.ReactNode;
+  /** Error text below the field; sets aria-invalid and is linked via aria-describedby (takes precedence over hint). */
+  error?: React.ReactNode;
+  /** Intercepted to render the label asterisk, and forwarded to the native input as `required`. @default false */
+  required?: boolean;
+  size?: "sm" | "md" | "lg";
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Controlled selected currency code. */
+  currency?: string;
+  /** Uncontrolled initial currency code. @default "USD" */
+  defaultCurrency?: string;
+  /** Called when the user picks a different currency. */
+  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. */
+  value?: string | number;
+  /** Uncontrolled initial amount. */
+  defaultValue?: string | number;
+  /** Native change handler (receives the event); fires alongside onValueChange, matching Currency. */
+  onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  /** Callback with the parsed number, formatted string, and active currency code. */
+  onValueChange?: (value: number | null, formatted: string, currency: string) => void;
+}
+
 declare function CurrencyField(props: CurrencyFieldProps): React.JSX.Element;
 
-/**
- * Advanced data table (Material UI Data Grid Premium style): sortable, filterable
- * (per-column operators + quick search), hideable (with a searchable column list),
- * and pinnable (left/right, sticky) columns, drag-to-reorder and drag-to-resize
- * columns, a column-management + filter toolbar, density control, CSV export,
- * an optional aggregation/summary footer, optional checkbox selection with a
- * batch-action toolbar, an actions column (per-row icon buttons + overflow menu),
- * page-number pagination with a configurable rows-per-page selector, a skeleton
- * loading state, and an optional server-side mode (sort/filter/paginate on the
- * backend — only the current page is loaded). Filter controls and the pager are
- * built from the Twico Select, Input, and Pagination components.
- *
- * @startingPoint section="Data display" subtitle="MUI-style sortable/filterable/pinnable data table" viewport="900x460"
- */
-interface DatatableProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "rows"> {
-  /** Column definitions. */
-  columns: DatatableColumn[];
-  /** Row objects. In server mode, only the current page's rows. */
-  rows: any[];
-  /** 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;
-  /** Render a leading checkbox-selection column. @default false */
-  checkboxSelection?: boolean;
-  /**
-   * Actions shown in the toolbar when one or more rows are selected (requires
-   * `checkboxSelection`). Each handler receives the selected keys, the resolved
-   * selected row objects, and a `clearSelection()` callback.
-   */
-  batchActions?: DatatableBatchAction[];
-  /** Row height preset. @default "standard" */
-  density?: "compact" | "standard" | "comfortable";
-  /** Initial rows per page. 0 disables pagination. @default 10 */
-  pageSize?: number;
-  /** Options shown in the rows-per-page selector. @default [5, 10, 25, 50] */
-  pageSizeOptions?: number[];
-  /** Max height of the scroll area in px (header/footer stay fixed). @default 440 */
-  height?: number;
-  /**
-   * Enable server-side data. When true, the table does NOT sort/filter/paginate
-   * the `rows` you pass (they are treated as the already-fetched current page);
-   * instead it calls `onServerChange` whenever the query changes so you can fetch
-   * the right slice. Provide `rowCount` for correct page counts. @default false
-   */
-  serverMode?: boolean;
-  /** Total row count on the server (required for pagination in server mode). */
-  rowCount?: number;
-  /** Server-mode callback fired (debounced) whenever the query changes. */
-  onServerChange?: (state: DatatableQuery) => void;
-  /** Show the Export toolbar button (split button: click = CSV, chevron = format menu). @default true */
-  showExport?: boolean;
-  /** Filename (without extension) for exports (CSV / Excel / TSV / JSON). @default "export" */
-  exportFilename?: string;
-  /** Server-mode precomputed aggregation. Per field, either a scalar/node (used as-is) or a per-function map
-   *  `{ sum, avg, min, max, count }` so the footer honors whichever function the user picks in the panel. */
-  aggregationValues?: Record<string, React.ReactNode | Partial<Record<"sum" | "avg" | "min" | "max" | "count", React.ReactNode>>> | null;
-  /** Disable drag-to-reorder of columns. @default false */
-  disableColumnReorder?: boolean;
-  /** Disable drag-to-resize of columns. @default false */
-  disableColumnResize?: boolean;
-  /** 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;
-  /** Controlled-rows callback: receives the full next rows array after an edit (client mode). */
-  onRowsChange?: (rows: any[]) => 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. */
-  onBatchUpdate?: (changedRows: any[], 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;
-  /** Fired when a cell is clicked in "cell" selection mode: (value, row, field). */
-  onCellClick?: (value: any, row: any, field: string) => void;
-  /** Fired when the active cell changes: ({ key, field } | null). */
-  onActiveCellChange?: (cell: { key: string | number; field: string } | null) => void;
-  /** Initial “show totals row” state. Aggregation is OFF by default and is configured at runtime from the toolbar **Aggregation** panel (pick columns + function); a column's `aggregation` prop just seeds the initial choice. @default false */
-  showAggregation?: boolean;
-  /** Accessible label for the grid (role="grid"). @default "Data table" */
-  ariaLabel?: string;
-  /** Initial row-grouping fields (collapsible groups with subtotals). Users can also group via a column's ⋮ menu. @default [] */
-  rowGrouping?: string[];
-  /** Enable row pinning — adds "Pin to top/bottom" to each row's actions menu; pinned rows stay sticky above/below the scroll body. @default false */
-  rowPinning?: boolean;
-  /** Enable drag-to-reorder of rows (whole row is draggable). Persists via `onRowOrderChange`. Disabled while sorting or grouping. @default false */
-  rowReorder?: boolean;
-  /** Enable drag-to-resize row height (handle on the row's bottom edge). @default false */
-  rowResize?: boolean;
-  /** Called with the new array of row keys after a drag-reorder. */
-  onRowOrderChange?: (keys: Array<string | number>) => void;
-  /** Initial pivot model (seeds the toolbar **Pivot** panel, which the user can edit live): aggregate `values` across `rows` (row groups) × `columns` (nested column groups). */
-  pivot?: {
-    rows: string[];
-    columns?: string[];
-    values: Array<{ field: string; agg?: "sum" | "avg" | "min" | "max" | "count"; label?: string; valueFormatter?: (v: any) => React.ReactNode }>;
-  } | null;
-  /** Start in pivot view. @default false */
-  pivotMode?: boolean;
-}
-
-/** Query state reported by a server-mode Datatable. */
-interface DatatableQuery {
-  /** Zero-based page index. */
-  page: number;
-  /** Current rows per page. */
-  pageSize: number;
-  /** Active sort, or null. */
-  sort: { field: string; dir: "asc" | "desc" } | null;
-  /** Active column filters. */
-  filters: Array<{ field: string; op: string; value: string }>;
-  /** Quick-search text. */
-  quickFilter: string;
-}
-
-interface DatatableColumn {
-  /** Row object key (also the sort/filter key). */
-  field: string;
-  /** Header label. @default field */
-  headerName?: string;
-  /** Data type. "actions" renders per-row action buttons via getActions. @default "string" */
-  type?: "string" | "number" | "actions";
-  /** Column width in px. @default 160 (110 for actions) */
-  width?: number;
-  /** Allow sorting this column. @default true */
-  sortable?: boolean;
-  /** Allow filtering this column. @default true */
-  filterable?: boolean;
-  /** Allow hiding this column. @default true */
-  hideable?: boolean;
-  /** Allow pinning this column. @default true */
-  pinnable?: boolean;
-  /** Allow grouping rows by this column (via the ⋮ menu). @default true for non-number, non-actions columns */
-  groupable?: boolean;
-  /** Pin this column on first render. */
-  pinned?: "left" | "right";
-  /** 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);
-  /** 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;
-  /** 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. */
-  editType?: "text" | "number" | "select";
-  /** Hide the column header ⋮ menu. @default true for actions columns, else false */
-  disableColumnMenu?: boolean;
-  /** 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;
-  /** Fully custom cell renderer (badges, avatars, etc.). */
-  renderCell?: (value: any, row: any) => React.ReactNode;
-  /** For type:"actions" — returns the row's action items. */
-  getActions?: (row: any) => DatatableRowAction[];
-}
-
-/** A per-row action in an actions column. */
-interface DatatableRowAction {
-  /** 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;
-  /** Place in the ⋮ overflow menu instead of inline. @default false */
-  showInMenu?: boolean;
-  /** Render in danger color. */
-  danger?: boolean;
-  disabled?: boolean;
-}
-
-/** A batch action shown in the selection toolbar. */
-interface DatatableBatchAction {
-  /** Button label. */
-  label: string;
-  /** Leading icon node. */
-  icon?: React.ReactNode;
-  /** Handler: (selectedKeys, selectedRows, clearSelection). */
-  onClick?: (keys: Array<string | number>, rows: any[], clearSelection: () => void) => void;
-  /** Render in danger color. */
-  danger?: boolean;
-  disabled?: boolean;
-}
-
+/**
+ * Advanced data table (Material UI Data Grid Premium style): sortable, filterable
+ * (per-column operators + quick search), hideable (with a searchable column list),
+ * and pinnable (left/right, sticky) columns, drag-to-reorder and drag-to-resize
+ * columns, a column-management + filter toolbar, density control, CSV export,
+ * an optional aggregation/summary footer, optional checkbox selection with a
+ * batch-action toolbar, an actions column (per-row icon buttons + overflow menu),
+ * page-number pagination with a configurable rows-per-page selector, a skeleton
+ * loading state, and an optional server-side mode (sort/filter/paginate on the
+ * backend — only the current page is loaded). Filter controls and the pager are
+ * built from the Twico Select, Input, and Pagination components.
+ *
+ * @startingPoint section="Data display" subtitle="MUI-style sortable/filterable/pinnable data table" viewport="900x460"
+ */
+interface DatatableProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "rows"> {
+  /** Column definitions. */
+  columns: DatatableColumn[];
+  /** Row objects. In server mode, only the current page's rows. */
+  rows: any[];
+  /** 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;
+  /** 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
+   *  the current sorted/filtered order and continues across pages (page 2 starts where page 1 ended;
+   *  in server mode it uses the current page × pageSize). Sits after the checkbox column, sticky-left.
+   *  This prop is the initial state — when enabled, users can hide/show the column from the toolbar's
+   *  **Columns** panel ("Row number"). @default false */
+  rowNumbers?: boolean;
+  /**
+   * Actions shown in the toolbar when one or more rows are selected (requires
+   * `checkboxSelection`). Each handler receives the selected keys, the resolved
+   * selected row objects, and a `clearSelection()` callback.
+   *
+   * Server-mode caveat: the resolved `selectedRows` argument can only include rows
+   * on the currently loaded page (the table never holds off-page rows). For
+   * cross-page selections, use the complete `selectedKeys` array and re-fetch the
+   * full row objects server-side rather than relying on `selectedRows`.
+   */
+  batchActions?: DatatableBatchAction[];
+  /** Row height preset. The toolbar density button cycles it locally; changing this prop re-applies it. @default "standard" */
+  density?: "compact" | "standard" | "comfortable";
+  /** Initial rows per page. 0 disables pagination. @default 10 */
+  pageSize?: number;
+  /** Options shown in the rows-per-page selector. @default [5, 10, 25, 50] */
+  pageSizeOptions?: number[];
+  /** Max height of the scroll area in px (header/footer stay fixed). @default 440 */
+  height?: number;
+  /**
+   * Enable server-side data. When true, the table does NOT sort/filter/paginate
+   * the `rows` you pass (they are treated as the already-fetched current page);
+   * instead it calls `onServerChange` whenever the query changes so you can fetch
+   * the right slice. Provide `rowCount` for correct page counts. @default false
+   */
+  serverMode?: boolean;
+  /** Total row count on the server (required for pagination in server mode). */
+  rowCount?: number;
+  /** Server-mode callback fired (debounced) whenever the query changes. */
+  onServerChange?: (state: DatatableQuery) => void;
+  /** Show the Export toolbar button (split button: click = CSV, chevron = format menu). @default true */
+  showExport?: boolean;
+  /** Filename (without extension) for exports (CSV / Excel). @default "export" */
+  exportFilename?: string;
+  /** Server-mode precomputed aggregation. Per field, either a scalar/node (used as-is) or a per-function map
+   *  `{ sum, avg, min, max, count }` so the footer honors whichever function the user picks in the panel. */
+  aggregationValues?: Record<string, React.ReactNode | Partial<Record<"sum" | "avg" | "min" | "max" | "count", React.ReactNode>>> | null;
+  /** Disable column reordering. When enabled (the default), columns can be reordered by dragging
+   *  the header label, or via the header column menu's "Move left" / "Move right" items (a keyboard-
+   *  accessible alternative; the move is announced through a visually-hidden live region). Both paths
+   *  rearrange only the movable, unpinned columns and leave pinned/actions columns in place.
+   *  @default false */
+  disableColumnReorder?: boolean;
+  /** Disable column resizing. When enabled (the default off), drag a header's right edge to resize a
+   *  column, or **double-click** that edge to auto-fit the column to its widest visible content
+   *  (header + rendered cells), Excel-style. @default false */
+  disableColumnResize?: boolean;
+  /** 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;
+  /** Controlled-rows callback: receives the full next rows array after an edit (client mode). */
+  onRowsChange?: (rows: any[]) => 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;
+  /** 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;
+  /** Fired when a cell is clicked in "cell" selection mode: (value, row, field). */
+  onCellClick?: (value: any, row: any, field: string) => void;
+  /** Fired when the active cell changes: ({ key, field } | null). */
+  onActiveCellChange?: (cell: { key: string | number; field: string } | null) => void;
+  /** “Show totals row” state (changing the prop re-applies it; the user can also toggle it in the toolbar **Aggregation** panel). Aggregation is configured at runtime from that panel (pick columns + function); a column's `aggregation` prop just seeds the initial choice. @default false */
+  showAggregation?: boolean;
+  /** Accessible label for the grid (role="grid"). A standard `aria-label` prop takes precedence. @default "Data table" */
+  ariaLabel?: string;
+  /** Row-grouping fields (collapsible groups with subtotals). Changing the prop re-applies it; users can also group via a column's ⋮ menu. @default [] */
+  rowGrouping?: string[];
+  /** Enable row pinning — adds "Pin to top/bottom" to each row's actions menu; pinned rows stay sticky above/below the scroll body. @default false */
+  rowPinning?: boolean;
+  /** Enable reorder of rows: the whole row is mouse-draggable, and a focusable drag handle supports
+   *  keyboard reorder (Enter/Space grabs, ArrowUp/ArrowDown move, Enter/Space drops, Escape cancels;
+   *  changes are announced via a visually-hidden live region). Persists via `onRowOrderChange`.
+   *  Disabled while sorting or grouping. @default false */
+  rowReorder?: boolean;
+  /** Enable drag-to-resize row height (handle on the row's bottom edge). @default false */
+  rowResize?: boolean;
+  /** Called with the new array of row keys after a drag-reorder. */
+  onRowOrderChange?: (keys: Array<string | number>) => void;
+  /** Initial pivot model (seeds the toolbar **Pivot** panel, which the user can edit live): aggregate `values` across `rows` (row groups) × `columns` (nested column groups). */
+  pivot?: {
+    rows: string[];
+    columns?: string[];
+    values: Array<{ field: string; agg?: "sum" | "avg" | "min" | "max" | "count"; label?: string; valueFormatter?: (v: any) => React.ReactNode }>;
+  } | null;
+  /** Start in pivot view. @default false */
+  pivotMode?: boolean;
+  /**
+   * Opt into row virtualization (windowing): render only the rows near the viewport for large
+   * datasets. Active only when pagination is effectively off (`pageSize={0}`) **and** row grouping
+   * is **not** active; otherwise it is ignored and the table renders normally. Pair with a fixed
+   * `height` so there is a scroll viewport to window against. **Rows may differ in height** — tall
+   * `renderCell` content, `wrapText` columns, or a drag-resized row all work: each rendered row is
+   * measured and cached by key, so the scrollbar and spacing stay accurate. Selection and inline
+   * edit keep working because they key off the row id, not its rendered index. @default false
+   */
+  virtualized?: boolean;
+  /** Extra rows rendered above and below the visible window (smoother fast scrolling) when `virtualized`. @default 8 */
+  overscan?: number;
+  /** Estimated row height in px, used only for rows not yet measured (they refine to their real height once scrolled into view). Defaults to the density preset (compact 36 / standard 44 / comfortable 56). Set this to your typical row height for the best first-paint estimate. */
+  rowHeight?: number;
+}
+
+/** Query state reported by a server-mode Datatable. */
+interface DatatableQuery {
+  /** Zero-based page index. */
+  page: number;
+  /** Current rows per page. */
+  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[] }>;
+  /** Quick-search text. */
+  quickFilter: string;
+}
+
+interface DatatableColumn {
+  /** Row object key (also the sort/filter key). */
+  field: string;
+  /** Header label. @default field ("Actions" for actions columns) */
+  headerName?: string;
+  /** Data type. "actions" renders per-row action buttons via getActions. @default "string" */
+  type?: "string" | "number" | "actions";
+  /** Column width in px. @default 160 (120 for actions) */
+  width?: number;
+  /** Cell alignment; currently affects the actions column's button justification. @default "right" for number/actions columns, else "left" */
+  align?: "left" | "right";
+  /** Allow sorting this column. @default true */
+  sortable?: boolean;
+  /** Allow filtering this column. @default true */
+  filterable?: boolean;
+  /** Allow hiding this column. @default true */
+  hideable?: boolean;
+  /** Allow pinning this column. @default true */
+  pinnable?: boolean;
+  /** Allow grouping rows by this column (via the ⋮ menu). @default true for non-number, non-actions columns */
+  groupable?: boolean;
+  /** Pin this column on first render. */
+  pinned?: "left" | "right";
+  /** 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);
+  /** 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;
+  /** 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. */
+  editType?: "text" | "number" | "select";
+  /** Hide the column header ⋮ menu. @default false */
+  disableColumnMenu?: boolean;
+  /** Start with this column's cell text wrapped onto multiple lines (the row grows down) instead of
+   *  clipped to one line. Users can also toggle it live from the column ⋮ menu ("Wrap text"). @default false */
+  wrapText?: boolean;
+  /** 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;
+  /** Fully custom cell renderer (badges, avatars, etc.). */
+  renderCell?: (value: any, row: any) => React.ReactNode;
+  /** For type:"actions" — returns the row's action items. */
+  getActions?: (row: any) => DatatableRowAction[];
+}
+
+/** A per-row action in an actions column. */
+interface DatatableRowAction {
+  /** 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;
+  /** Place in the ⋮ overflow menu instead of inline. @default false */
+  showInMenu?: boolean;
+  /** Render in danger color. */
+  danger?: boolean;
+  disabled?: boolean;
+}
+
+/** A batch action shown in the selection toolbar. */
+interface DatatableBatchAction {
+  /** Button label. */
+  label: string;
+  /** Leading icon node. */
+  icon?: React.ReactNode;
+  /** Handler: (selectedKeys, selectedRows, clearSelection). */
+  onClick?: (keys: Array<string | number>, rows: any[], clearSelection: () => void) => void;
+  /** Render in danger color. */
+  danger?: boolean;
+  disabled?: boolean;
+}
+
 declare function Datatable(props: DatatableProps): React.JSX.Element;
 
-/**
- * Date picker with a calendar popover — month/year navigation, a month grid,
- * today highlight, min/max bounds, clearable value, and custom formatting.
- *
- * @startingPoint section="Inputs" subtitle="Calendar date picker" viewport="700x120"
- */
-interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
-  label?: React.ReactNode;
-  /** Controlled selected date (or null). */
-  value?: Date | null;
-  /** Uncontrolled initial date. @default null */
-  defaultValue?: Date | null;
-  placeholder?: string;
-  /** Earliest selectable date. */
-  min?: Date;
-  /** Latest selectable date. */
-  max?: Date;
-  disabled?: boolean;
-  /** Show a clear (×) button when a date is set. @default true */
-  clearable?: boolean;
-  /** Custom display formatter (defaults to a localized medium date). */
-  format?: (date: Date) => string;
-  /** First day of week: 0 = Sunday, 1 = Monday. @default 0 */
-  weekStartsOn?: 0 | 1;
-  onChange?: (date: Date | null) => void;
-}
-
+/**
+ * Apply a `DatatableQuery` (the object a `serverMode` grid passes to
+ * `onServerChange`) to a plain array of rows — quick search, per-column filters,
+ * sort, and paging — with the same operator semantics the grid uses in client
+ * mode. Use it to back a `serverMode` Datatable from any data source (or a fake
+ * backend in tests) and get identical results. Pass `columns` so number columns
+ * sort/compare numerically and quick-search scans the intended fields.
+ *
+ * @returns `rows` (the current page), `total` (filtered count, for `rowCount`),
+ *  and `filtered` (the full filtered+sorted set before paging — handy for
+ *  computing server-side aggregation totals).
+ */
+declare function runDatatableQuery<T = any>(
+  rows: T[],
+  query: DatatableQuery,
+  options?: { columns?: DatatableColumn[]; searchFields?: string[] }
+): { rows: T[]; total: number; filtered: T[] };
+
+/**
+ * Date picker with a calendar popover — month/year navigation, a month grid,
+ * today highlight, min/max bounds, clearable value, and custom formatting.
+ *
+ * @startingPoint section="Inputs" subtitle="Calendar date picker" viewport="700x120"
+ */
+interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — turns the field red and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk to the label). @default false */
+  required?: boolean;
+  /** Controlled selected date (or null). */
+  value?: Date | null;
+  /** Uncontrolled initial date. @default null */
+  defaultValue?: Date | null;
+  placeholder?: string;
+  /** Earliest selectable date. */
+  min?: Date;
+  /** Latest selectable date. */
+  max?: Date;
+  disabled?: boolean;
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Show a clear (×) button when a date is set. @default true */
+  clearable?: boolean;
+  /** Custom display formatter (defaults to a localized medium date). */
+  format?: (date: Date) => string;
+  /** BCP-47 locale for month/weekday names + date formatting (Intl). Omit for the runtime default. @default undefined */
+  locale?: string;
+  /** First day of week: 0 = Sunday … 6 = Saturday. @default 0 */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  onChange?: (date: Date | null) => void;
+}
+
 declare function DatePicker(props: DatePickerProps): React.JSX.Element;
 
-interface DateRange {
-  start: Date | null;
-  end: Date | null;
-}
-
-/**
- * Date-range picker — calendar with click-start/click-end selection, in-range
- * highlighting, hover preview, and quick presets (Last 7/14/30/90 days).
- *
- * @startingPoint section="Inputs" subtitle="Date range picker with presets" viewport="700x120"
- */
-interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
-  label?: React.ReactNode;
-  /** Controlled range. */
-  value?: DateRange;
-  /** Uncontrolled initial range. @default { start: null, end: null } */
-  defaultValue?: DateRange;
-  placeholder?: string;
-  /** Show the quick-preset column. @default true */
-  presets?: boolean;
-  /** First day of week: 0 = Sunday, 1 = Monday. @default 0 */
-  weekStartsOn?: 0 | 1;
-  onChange?: (range: DateRange) => void;
-}
-
+interface DateRange {
+  start: Date | null;
+  end: Date | null;
+}
+
+/**
+ * Date-range picker — calendar with click-start/click-end selection, in-range
+ * highlighting, hover preview, and quick presets (Last 7/14/30/90 days).
+ *
+ * @startingPoint section="Inputs" subtitle="Date range picker with presets" viewport="700x120"
+ */
+interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — turns the field red and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk to the label). @default false */
+  required?: boolean;
+  /** Controlled range. */
+  value?: DateRange;
+  /** Uncontrolled initial range. @default { start: null, end: null } */
+  defaultValue?: DateRange;
+  placeholder?: string;
+  /** Show the quick-preset column. @default true */
+  presets?: boolean;
+  /** BCP-47 locale for month/weekday names + date formatting (Intl). Omit for the runtime default. @default undefined */
+  locale?: string;
+  /** First day of week: 0 = Sunday … 6 = Saturday. @default 0 */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** 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";
+  onChange?: (range: DateRange) => void;
+}
+
 declare function DateRangePicker(props: DateRangePickerProps): React.JSX.Element;
 
-/**
- * Modal dialog with scrim, pop-in animation, Esc-to-close, and backdrop close.
- * Render conditionally and drive with `open` + `onClose`.
- */
-interface DialogProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Whether the dialog is visible. */
-  open: boolean;
-  /** Called on close (Esc, backdrop, close button). */
-  onClose?: () => void;
-  title?: React.ReactNode;
-  description?: React.ReactNode;
-  /** Footer content, typically action buttons (right-aligned). */
-  footer?: React.ReactNode;
-  /** @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** Close when the backdrop is clicked. @default true */
-  closeOnBackdrop?: boolean;
-  children?: React.ReactNode;
-}
-
+/**
+ * Modal dialog with scrim, pop-in animation, Esc-to-close, and backdrop close.
+ * Render conditionally and drive with `open` + `onClose`.
+ */
+interface DialogProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Whether the dialog is visible. */
+  open: boolean;
+  /** Called on close (Esc, backdrop, close button). */
+  onClose?: () => void;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Footer content, typically action buttons (right-aligned). */
+  footer?: React.ReactNode;
+  /** `"full"` is a near-fullscreen panel (fills the viewport minus a small margin). @default "md" */
+  size?: "sm" | "md" | "lg" | "full";
+  /** Keep the header + footer fixed and scroll only the body (for long content). @default false */
+  scrollBody?: boolean;
+  /** Close when the backdrop is clicked. @default true */
+  closeOnBackdrop?: boolean;
+  children?: React.ReactNode;
+}
+
 declare function Dialog(props: DialogProps): React.JSX.Element | null;
 
-/**
- * Thin rule that separates content. Horizontal or vertical; can carry a centered
- * (or left/right-aligned) label.
- */
-interface DividerProps extends React.HTMLAttributes<HTMLElement> {
-  /** @default "horizontal" */
-  orientation?: "horizontal" | "vertical";
-  /** Indent the start of a horizontal rule. */
-  inset?: boolean;
-  /** Label alignment when children are provided. @default "center" */
-  align?: "left" | "center" | "right";
-  /** Optional label text rendered in the middle of the rule. */
-  children?: React.ReactNode;
-}
-
+/**
+ * Thin rule that separates content. Horizontal or vertical; can carry a centered
+ * (or left/right-aligned) label.
+ */
+interface DividerProps extends React.HTMLAttributes<HTMLElement> {
+  /** @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Indent the start of a horizontal rule. */
+  inset?: boolean;
+  /** Label alignment when children are provided — logical, so it mirrors under RTL.
+   *  (`"left"`/`"right"` are still accepted as aliases for `"start"`/`"end"`.) @default "center" */
+  align?: "start" | "center" | "end" | "left" | "right";
+  /** Optional label text rendered in the middle of the rule. */
+  children?: React.ReactNode;
+}
+
 declare function Divider(props: DividerProps): React.JSX.Element;
 
-/**
- * Slide-in panel anchored to any screen edge, with scrim, Esc-to-close, and a
- * header/body/footer layout. Drive with `open` + `onClose`.
- */
-interface DrawerProps extends React.HTMLAttributes<HTMLDivElement> {
-  open: boolean;
-  onClose?: () => void;
-  /** Edge the panel slides from. @default "right" */
-  side?: "left" | "right" | "top" | "bottom";
-  title?: React.ReactNode;
-  description?: React.ReactNode;
-  /** Footer content, typically action buttons (right-aligned). */
-  footer?: React.ReactNode;
-  /** Panel width (left/right) or height (top/bottom) — number (px) or CSS value. */
-  size?: number | string;
-  /** Close when the backdrop is clicked. @default true */
-  closeOnBackdrop?: boolean;
-  children?: React.ReactNode;
-}
-
+/**
+ * Slide-in panel anchored to any screen edge, with scrim, Esc-to-close, and a
+ * header/body/footer layout. Drive with `open` + `onClose`.
+ */
+interface DrawerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  open: boolean;
+  onClose?: () => void;
+  /** Edge the panel slides from. `left`/`right`/`top`/`bottom` are physical; `start`/`end`
+   *  are logical (inline-start/inline-end) and mirror under `dir="rtl"`. @default "right" */
+  side?: "left" | "right" | "top" | "bottom" | "start" | "end";
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Footer content, typically action buttons (right-aligned). */
+  footer?: React.ReactNode;
+  /** Panel width for `side="left"`/`"right"` — preset "sm" (320px) / "md" (380px) / "lg" (480px), a number (px), or a CSS length. Ignored for top/bottom. @default "md" */
+  width?: "sm" | "md" | "lg" | number | string;
+  /** Panel height for `side="top"`/`"bottom"` — preset "sm" / "md" / "lg", a number (px), or a CSS length. Ignored for left/right. @default "md" */
+  height?: "sm" | "md" | "lg" | number | string;
+  /** Close when the backdrop is clicked. @default true */
+  closeOnBackdrop?: boolean;
+  children?: React.ReactNode;
+}
+
 declare function Drawer(props: DrawerProps): React.JSX.Element | null;
 
-/**
- * Empty / zero-data placeholder — icon, title, description, and call-to-action.
- *
- * @startingPoint section="Feedback" subtitle="Empty / zero-data state" viewport="700x300"
- */
-interface EmptyStateProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Illustrative icon shown in a tinted tile. */
-  icon?: React.ReactNode;
-  title?: React.ReactNode;
-  description?: React.ReactNode;
-  /** Action buttons row. */
-  actions?: React.ReactNode;
-  /** Add a dashed border (good for drop targets / placeholders). @default false */
-  bordered?: boolean;
-}
-
+/**
+ * Empty / zero-data placeholder — icon, title, description, and call-to-action.
+ *
+ * @startingPoint section="Feedback" subtitle="Empty / zero-data state" viewport="700x300"
+ */
+interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Illustrative icon shown in a tinted tile. */
+  icon?: React.ReactNode;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Action buttons row. */
+  actions?: React.ReactNode;
+  /** Add a dashed border (good for drop targets / placeholders). @deprecated Use `border`. @default false */
+  bordered?: boolean;
+  /** Add a dashed border (good for drop targets / placeholders); preferred alias for `bordered`. @default false */
+  border?: boolean;
+}
+
 declare function EmptyState(props: EmptyStateProps): React.JSX.Element;
 
-/**
- * Drag-and-drop file upload (dropzone) with a click-to-browse fallback and a
- * removable selected-file list. Controlled via `value` (File[]) + `onChange`,
- * or uncontrolled.
- *
- * @startingPoint section="Inputs" subtitle="Drag & drop file upload" viewport="700x320"
- */
-interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
-  /** Accepted file types (input accept string, e.g. "image/*,.pdf"). */
-  accept?: string;
-  /** Allow selecting multiple files. @default false */
-  multiple?: boolean;
-  disabled?: boolean;
-  /** Hint line under the prompt (defaults to the accept types). */
-  hint?: React.ReactNode;
-  /** Controlled list of selected files. */
-  value?: File[];
-  onChange?: (files: File[]) => void;
-}
-
+/**
+ * Shared form-field chrome (label, hint, error, required asterisk) that wraps ANY control.
+ *
+ * `Field` is layout-only: it renders the label + your `children` + a single hint/error line,
+ * reusing the exact `.twc-field` markup Input/Select inline so every field looks identical.
+ * Wiring the control to the messages stays the consumer's job — point your control's
+ * `aria-describedby` at the exposed hint/error id (`` `${id}-desc` ``) and set `aria-invalid`
+ * when `error` is present. `error` replaces `hint` when both are given (error wins).
+ *
+ * @example
+ * <Field label="Email" hint="We never share it." htmlFor="email" id="email-field">
+ *   <input id="email" aria-describedby="email-field-desc" />
+ * </Field>
+ */
+interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — replaces the hint and renders in the danger color. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk after the label). @default false */
+  required?: boolean;
+  /** Id of the control the `<label>` should bind to (sets the label's `htmlFor`). */
+  htmlFor?: string;
+  /** Spacing scale, reserved for parity with Input/Select; exposed via `data-size`. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Base id; the hint/error element gets `` `${id}-desc` `` for your `aria-describedby`. Auto-generated via `React.useId` when omitted. */
+  id?: string;
+  /** Extra class names appended to the `.twc-field` root. */
+  className?: string;
+  /** The control(s) the field wraps. */
+  children?: React.ReactNode;
+}
+
+declare function Field(props: FieldProps): React.JSX.Element;
+
+/**
+ * Drag-and-drop file upload (dropzone) with a click-to-browse fallback and a
+ * removable selected-file list. Controlled via `value` (File[]) + `onChange`,
+ * or uncontrolled.
+ *
+ * @startingPoint section="Inputs" subtitle="Drag & drop file upload" viewport="700x320"
+ */
+interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Accepted file types (input accept string, e.g. "image/*,.pdf"). */
+  accept?: string;
+  /** Allow selecting multiple files. @default false */
+  multiple?: boolean;
+  disabled?: boolean;
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Field label rendered above the dropzone. */
+  label?: React.ReactNode;
+  /** Hint line under the prompt (defaults to the accept types). */
+  hint?: React.ReactNode;
+  /** Error message shown below the dropzone — turns the border red (sets `aria-invalid`). */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk to the label). @default false */
+  required?: boolean;
+  /** Controlled list of selected files. */
+  value?: File[];
+  /** Uncontrolled initial file list. @default [] */
+  defaultValue?: File[];
+  onChange?: (files: File[]) => void;
+}
+
 declare function FileUpload(props: FileUploadProps): React.JSX.Element;
 
-/**
- * Square (or circular) button for a single icon. Always provide an aria-label.
- *
- * @startingPoint section="Buttons" subtitle="Icon-only button" viewport="700x120"
- */
-interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  /** The icon node to render (e.g. a Lucide SVG). */
-  icon?: React.ReactNode;
-  /** Visual style. @default "ghost" */
-  variant?: "solid" | "soft" | "outline" | "ghost";
-  /** Control size. @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** Fully rounded (circular). @default false */
-  round?: boolean;
-  /** Accessible label — required for icon-only buttons. */
-  "aria-label": string;
-}
-
+/**
+ * Square (or circular) button for a single icon. Always provide an aria-label.
+ *
+ * @startingPoint section="Buttons" subtitle="Icon-only button" viewport="700x120"
+ */
+interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** The icon node to render (e.g. a Lucide SVG). */
+  icon?: React.ReactNode;
+  /** Fill style (same axes as Button). @default "ghost" */
+  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";
+  /** Control size; "xs" (~26px) is smaller than "sm". @default "md" */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Fully rounded (circular). @default false */
+  round?: boolean;
+  /** Accessible label — required for icon-only buttons. */
+  "aria-label": string;
+}
+
 declare function IconButton(props: IconButtonProps): React.JSX.Element;
 
-/**
- * Text input with optional label, hint, error state, and inline icons.
- *
- * @startingPoint section="Inputs" subtitle="Labeled text input with validation" viewport="700x140"
- */
-interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
-  /** Field label rendered above the control. */
-  label?: React.ReactNode;
-  /** Helper text shown below when there is no error. */
-  hint?: React.ReactNode;
-  /** Error message — turns the field red and replaces the hint. */
-  error?: React.ReactNode;
-  /** Marks the field required (adds an asterisk). */
-  required?: boolean;
-  /** Control size. @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** 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
-   *  shows a built-in reveal/hide eye toggle; providing `rightIcon` replaces it. */
-  rightIcon?: React.ReactNode;
-}
-
+/**
+ * Text input with optional label, hint, error state, and inline icons.
+ *
+ * @startingPoint section="Inputs" subtitle="Labeled text input with validation" viewport="700x140"
+ */
+interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — turns the field red and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk and forwards to the native input). */
+  required?: boolean;
+  /** Control size. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** 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
+   *  shows a built-in reveal/hide eye toggle; providing `rightIcon` replaces it. */
+  rightIcon?: React.ReactNode;
+}
+
 declare function Input(props: InputProps): React.JSX.Element;
 
-interface KanbanColumn {
-  /** Unique column id (matches a card's `column`). */
-  id: string;
-  /** Column heading. */
-  title: React.ReactNode;
-  /** Dot color for the heading. */
-  color?: string;
-}
-
-interface KanbanCard {
-  id: string;
-  /** Which column the card is in. */
-  column: string;
-  title?: React.ReactNode;
-  description?: React.ReactNode;
-  /** Small uppercase tag chips. */
-  tags?: React.ReactNode[];
-  /** Footer node (e.g. an Avatar / due date). */
-  footer?: React.ReactNode;
-  [key: string]: any;
-}
-
-/**
- * Drag-and-drop Kanban board — columns of cards you can drag between columns.
- * Controlled via `cards` + `onCardMove`, or uncontrolled. Supply `renderCard`
- * for custom card content.
- *
- * @startingPoint section="Data display" subtitle="Drag-and-drop Kanban board" viewport="900x420"
- */
-interface KanbanProps extends React.HTMLAttributes<HTMLDivElement> {
-  columns: KanbanColumn[];
-  cards: KanbanCard[];
-  /** Fired when a card is dropped in a new column: (cardId, toColumn, nextCards). */
-  onCardMove?: (cardId: string, toColumn: string, nextCards: KanbanCard[]) => void;
-  /** Custom card renderer. */
-  renderCard?: (card: KanbanCard) => React.ReactNode;
-}
-
+interface KanbanColumn {
+  /** Unique column id (matches a card's `column`). */
+  id: string;
+  /** Column heading. */
+  title: React.ReactNode;
+  /** Dot color for the heading. */
+  color?: string;
+}
+
+interface KanbanCard {
+  id: string;
+  /** Which column the card is in. */
+  column: string;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Small uppercase tag chips. */
+  tags?: React.ReactNode[];
+  /** Footer node (e.g. an Avatar / due date). */
+  footer?: React.ReactNode;
+  [key: string]: any;
+}
+
+/**
+ * Drag-and-drop Kanban board — columns of cards you can drag between columns.
+ * Controlled via `cards` + `onCardMove`, or uncontrolled via `defaultCards`.
+ * Cards can also be moved with the keyboard: Enter/Space grabs a card, the
+ * left/right arrow keys choose a column, Enter drops, Escape cancels. Supply
+ * `renderCard` for custom card content.
+ *
+ * @startingPoint section="Data display" subtitle="Drag-and-drop Kanban board" viewport="900x420"
+ */
+interface KanbanProps extends React.HTMLAttributes<HTMLDivElement> {
+  columns: KanbanColumn[];
+  /** Controlled cards — pair with `onCardMove` to apply moves yourself. */
+  cards?: KanbanCard[];
+  /** Initial cards when uncontrolled (the board applies moves internally). */
+  defaultCards?: KanbanCard[];
+  /** Fired when a card is dropped in a new column: (cardId, toColumn, nextCards). */
+  onCardMove?: (cardId: string, toColumn: string, nextCards: KanbanCard[]) => void;
+  /** Custom card renderer. */
+  renderCard?: (card: KanbanCard) => React.ReactNode;
+}
+
 declare function Kanban(props: KanbanProps): React.JSX.Element;
 
-interface ListItemData {
-  /** Primary text. */
-  title: React.ReactNode;
-  /** Secondary text under the title. */
-  description?: React.ReactNode;
-  /** Leading node (icon / avatar). */
-  leading?: React.ReactNode;
-  /** Trailing node (badge, meta, chevron, switch). */
-  trailing?: React.ReactNode;
-  /** Makes the row a button. */
-  onClick?: (e: React.MouseEvent) => void;
-  /** Makes the row a link. */
-  href?: string;
-  /** Highlight as selected. */
-  active?: boolean;
-}
-
-/**
- * Vertical list of rows with leading/trailing slots, title + description, and
- * optional interactivity (button or link rows).
- *
- * @startingPoint section="Data display" subtitle="List rows with lead/trail slots" viewport="700x300"
- */
-interface ListProps extends React.HTMLAttributes<HTMLUListElement> {
-  items: ListItemData[];
-  /** Drop the card chrome (borderless, transparent). @default false */
-  plain?: boolean;
-}
-
+interface ListItemData {
+  /** Primary text. */
+  title: React.ReactNode;
+  /** Secondary text under the title. */
+  description?: React.ReactNode;
+  /** Leading node (icon / avatar). */
+  leading?: React.ReactNode;
+  /** Trailing node (badge, meta, chevron, switch). */
+  trailing?: React.ReactNode;
+  /** Makes the row a button. */
+  onClick?: (e: React.MouseEvent) => void;
+  /** Makes the row a link. */
+  href?: string;
+  /** Highlight as selected. */
+  active?: boolean;
+}
+
+/**
+ * Vertical list of rows with leading/trailing slots, title + description, and
+ * optional interactivity (button or link rows).
+ *
+ * @startingPoint section="Data display" subtitle="List rows with lead/trail slots" viewport="700x300"
+ */
+interface ListProps extends React.HTMLAttributes<HTMLUListElement> {
+  items: ListItemData[];
+  /** Drop the card chrome (borderless, transparent). @default false */
+  plain?: boolean;
+}
+
 declare function List(props: ListProps): React.JSX.Element;
 
-/**
- * Multi-select (MUI-Autocomplete style) — type directly among the chips to
- * filter; the overlay shows checkable options only. Supports grouped options
- * and two-line (title + subtitle) options. Backspace on empty input removes
- * the last chip.
- *
- * @startingPoint section="Selects" subtitle="Multi-select with chips & inline search" viewport="700x180"
- */
-interface MultiSelectProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-  placeholder?: string;
-  /** Options — strings, {value,label,description}, or {group,options} groups. */
-  options: Array<string | MultiSelectOption | MultiSelectGroup>;
-  /** Controlled selected values. */
-  value?: string[];
-  /** Uncontrolled initial values. */
-  defaultValue?: string[];
-  onChange?: (values: string[]) => void;
-  disabled?: boolean;
-}
-
-interface MultiSelectOption {
-  value: string;
-  label: string;
-  /** Optional second line shown under the label. */
-  description?: string;
-}
-
-/** A group heading with its own options. */
-interface MultiSelectGroup {
-  group: string;
-  options: Array<string | MultiSelectOption>;
-}
-
+/**
+ * Multi-select (MUI-Autocomplete style) — type directly among the chips to
+ * filter; the overlay shows checkable options only. Supports grouped options
+ * and two-line (title + subtitle) options. Backspace on empty input removes
+ * the last chip.
+ *
+ * @startingPoint section="Selects" subtitle="Multi-select with chips & inline search" viewport="700x180"
+ */
+interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
+  label?: React.ReactNode;
+  hint?: React.ReactNode;
+  error?: React.ReactNode;
+  required?: boolean;
+  /** 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";
+  placeholder?: string;
+  /** Options — strings, {value,label,description}, or {group,options} groups. */
+  options: Array<string | MultiSelectOption | MultiSelectGroup>;
+  /** Controlled selected values. */
+  value?: string[];
+  /** Uncontrolled initial values. */
+  defaultValue?: string[];
+  onChange?: (values: string[]) => void;
+  /** Show a clear-all (×) affix when at least one value is selected. @default false */
+  clearable?: boolean;
+  disabled?: boolean;
+  /** Open the menu upward instead of down (e.g. near a viewport bottom). @default "bottom" */
+  placement?: "bottom" | "top";
+  /** Render the dropdown in a portal (position:fixed on document.body) so it is never clipped by a
+   *  scrolling/overflow-hidden ancestor; auto-flips up near the viewport bottom. Set false to render
+   *  inline. @default true */
+  portal?: boolean;
+  /** Minimum popover width in px when portaled (useful when the control is narrow). @default 0 */
+  minWidth?: number;
+  /** Composed with the field's open-on-focus behavior — your handler runs first. */
+  onFocus?: React.FocusEventHandler<HTMLInputElement>;
+  /** Composed with the field's keyboard navigation (Arrows/Enter/Escape/Backspace) — your handler runs first; call `event.preventDefault()` to suppress it. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+}
+
+interface MultiSelectOption {
+  value: string;
+  label: string;
+  /** Optional second line shown under the label. */
+  description?: string;
+}
+
+/** A group heading with its own options. */
+interface MultiSelectGroup {
+  group: string;
+  options: Array<string | MultiSelectOption>;
+}
+
 declare function MultiSelect(props: MultiSelectProps): React.JSX.Element;
 
-interface NavbarLink {
-  label: React.ReactNode;
-  href?: string;
-  icon?: React.ReactNode;
-  active?: boolean;
-  onClick?: (e: React.MouseEvent) => void;
-}
-
-/**
- * Top application bar — brand, inline nav links (hidden on small screens), and
- * a right-aligned actions slot. Sticky + translucent by default.
- *
- * @startingPoint section="Layout" subtitle="Top app bar / navbar" viewport="900x80"
- */
-interface NavbarProps extends React.HTMLAttributes<HTMLElement> {
-  /** Brand/logo node at the left. */
-  brand?: React.ReactNode;
-  /** Center nav links. */
-  links?: NavbarLink[];
-  /** Right-aligned actions (buttons, avatar, etc.). */
-  actions?: React.ReactNode;
-  /** Stick to the top with a translucent blur. @default true */
-  sticky?: boolean;
-  /** Hamburger handler shown on small screens. */
-  onMenuClick?: () => void;
-}
-
+interface NavbarLink {
+  label: React.ReactNode;
+  href?: string;
+  icon?: React.ReactNode;
+  active?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+}
+
+/**
+ * Top application bar — brand, inline nav links (hidden on small screens), and
+ * a right-aligned actions slot. Sticky + translucent by default.
+ *
+ * @startingPoint section="Layout" subtitle="Top app bar / navbar" viewport="900x80"
+ */
+interface NavbarProps extends React.HTMLAttributes<HTMLElement> {
+  /** Brand/logo node at the left. */
+  brand?: React.ReactNode;
+  /** If set, the brand becomes a link to this URL (sanitized). Otherwise the brand is a
+   *  plain, non-navigating element unless `onBrandClick` is given. */
+  brandHref?: string;
+  /** Click handler for the brand; renders it as a button when `brandHref` is not set. */
+  onBrandClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  /** Center nav links. */
+  links?: NavbarLink[];
+  /** Right-aligned actions (buttons, avatar, etc.). */
+  actions?: React.ReactNode;
+  /** Stick to the top with a translucent blur. @default true */
+  sticky?: boolean;
+  /** Hamburger handler shown on small screens. */
+  onMenuClick?: () => void;
+}
+
 declare function Navbar(props: NavbarProps): React.JSX.Element;
 
-/**
- * Page navigation with first/last, prev/next, and smart ellipsis truncation.
- */
-interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, "onChange"> {
-  /** Current 1-based page. @default 1 */
-  page?: number;
-  /** Total number of pages. */
-  total: number;
-  /** Called with the new page when the user navigates. */
-  onChange?: (page: number) => void;
-  /** Page numbers shown on each side of the current page. @default 1 */
-  siblings?: number;
-  /** Page numbers always shown at each end (first/last). @default 1 */
-  boundaries?: number;
-  /** @default "md" */
-  size?: "sm" | "md";
-  /** Show a "Go to" page input for jumping directly to a page. @default false */
-  showJumper?: boolean;
-  /** Label before the jump input. @default "Go to" */
-  jumperLabel?: React.ReactNode;
-}
-
+/**
+ * Page navigation with first/last, prev/next, and smart ellipsis truncation.
+ */
+interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, "onChange"> {
+  /** Controlled current 1-based page; when omitted the component manages its own page. */
+  page?: number;
+  /** Initial 1-based page when uncontrolled (no `page` prop). @default 1 */
+  defaultPage?: number;
+  /** Total number of pages. */
+  total: number;
+  /** Called with the new page when the user navigates. */
+  onChange?: (page: number) => void;
+  /** Page numbers shown on each side of the current page. @default 1 */
+  siblings?: number;
+  /** Page numbers always shown at each end (first/last). @default 1 */
+  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 */
+  showJumper?: boolean;
+  /** Show a "Go to" page input for jumping directly to a page; preferred alias for `showJumper`. @default false */
+  showPageJumper?: boolean;
+  /** Label before the jump input. @default "Go to" */
+  jumperLabel?: React.ReactNode;
+}
+
 declare function Pagination(props: PaginationProps): React.JSX.Element;
 
-/**
- * Click-triggered floating panel anchored to a trigger element. Renders in a
- * portal (never clipped), auto-flips near the viewport edge, closes on
- * outside-click / Esc. Use for rich content; for plain text use Tooltip.
- */
-interface PopoverProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** The clickable trigger element. */
-  trigger: React.ReactNode;
-  /** Optional bold title inside the panel. */
-  title?: React.ReactNode;
-  /** Side to open toward. @default "bottom" */
-  placement?: "top" | "bottom" | "left" | "right";
-  /** Cross-axis alignment for top/bottom. @default "center" */
-  align?: "start" | "center" | "end";
-  /** Panel width in px. @default 240 */
-  width?: number;
-  /** Panel content. */
-  children?: React.ReactNode;
-}
-
+/**
+ * Click-triggered floating panel anchored to a trigger element. Renders in a
+ * portal (never clipped), auto-flips near the viewport edge, closes on
+ * outside-click / Esc. Use for rich content; for plain text use Tooltip.
+ */
+interface PopoverProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** The clickable trigger element. */
+  trigger: React.ReactNode;
+  /** Optional bold title inside the panel. */
+  title?: React.ReactNode;
+  /** Side to open toward. @default "bottom" */
+  placement?: "top" | "bottom" | "left" | "right";
+  /** Cross-axis alignment for top/bottom. @default "center" */
+  align?: "start" | "center" | "end";
+  /** Panel width in px. @default 240 */
+  width?: number;
+  /** Panel content. */
+  children?: React.ReactNode;
+  /** Open on first render in uncontrolled mode. @default false */
+  defaultOpen?: boolean;
+  /** Controlled open state — pair with `onOpenChange`. Omit for internal (uncontrolled) state. */
+  open?: boolean;
+  /** Called with the requested open state on trigger click, Esc, or outside click. */
+  onOpenChange?: (open: boolean) => void;
+}
+
 declare function Popover(props: PopoverProps): React.JSX.Element;
 
-/**
- * Linear progress bar — determinate or indeterminate, with semantic tones.
- */
-interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Current value. @default 0 */
-  value?: number;
-  /** Maximum value. @default 100 */
-  max?: number;
-  /** @default "primary" */
-  tone?: "primary" | "success" | "warning" | "danger";
-  /** @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** Animate as an indeterminate bar (ignores value). */
-  indeterminate?: boolean;
-  /** Show a percentage label above the bar. */
-  showLabel?: boolean;
-}
-
+/**
+ * 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.
+ */
+interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Current value. @default 0 */
+  value?: number;
+  /** Maximum value. @default 100 */
+  max?: number;
+  /** @default "primary" */
+  tone?: "primary" | "info" | "success" | "warning" | "danger";
+  /** @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Animate as an indeterminate bar (ignores value). */
+  indeterminate?: boolean;
+  /** Show a percentage label above the bar. */
+  showLabel?: boolean;
+}
+
 declare function Progress(props: ProgressProps): React.JSX.Element;
 
-/**
- * Radio button with label and description. Group several with the same `name`.
- */
-interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
-  label?: React.ReactNode;
-  description?: React.ReactNode;
-  size?: "sm" | "md";
-}
-
+/**
+ * Radio button with label and description. Group several with the same `name`.
+ */
+interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Error message shown below the control; tints the dot red and wires `aria-invalid`/`aria-describedby`. @default undefined */
+  error?: React.ReactNode;
+  size?: "sm" | "md" | "lg";
+  /** Color intent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+}
+
 declare function Radio(props: RadioProps): React.JSX.Element;
 
-/**
- * Star rating — interactive (click/hover) or read-only display.
- *
- * @startingPoint section="Inputs" subtitle="Star rating" viewport="700x90"
- */
-interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue" | "color"> {
-  /** Controlled value (0…count). */
-  value?: number;
-  /** Uncontrolled initial value. @default 0 */
-  defaultValue?: number;
-  /** Number of stars. @default 5 */
-  count?: number;
-  /** @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** Filled-star color (defaults to the warning/amber token). */
-  color?: string;
-  /** Display only, no interaction. @default false */
-  readOnly?: boolean;
-  /** Show the numeric value beside the stars. @default false */
-  showValue?: boolean;
-  onChange?: (value: number) => void;
-}
-
+/**
+ * Star rating — interactive (click/hover) or read-only display.
+ *
+ * @startingPoint section="Inputs" subtitle="Star rating" viewport="700x90"
+ */
+interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue" | "color"> {
+  /** Controlled value (0…count). */
+  value?: number;
+  /** Uncontrolled initial value. @default 0 */
+  defaultValue?: number;
+  /** Number of stars. @default 5 */
+  count?: number;
+  /** @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Color intent for filled stars. @default "warning" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Explicit filled-star color; overrides `tone` when set. */
+  color?: string;
+  /** Display only, no interaction. @default false */
+  readOnly?: boolean;
+  /** Disable all interaction and dim the control. @default false */
+  disabled?: boolean;
+  /** Show the numeric value beside the stars. @default false */
+  showValue?: boolean;
+  onChange?: (value: number) => void;
+}
+
 declare function Rating(props: RatingProps): React.JSX.Element;
 
-/**
- * Custom select with a rounded popover (no native browser dropdown). Supports
- * grouped options and two-line (title + subtitle) options. Keyboard navigable.
- *
- * @startingPoint section="Selects" subtitle="Custom select with grouped options" viewport="700x160"
- */
-interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onChange" | "defaultValue"> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-  size?: "sm" | "md" | "lg";
-  placeholder?: string;
-  /** Placeholder for the in-popover search box. @default "Search…" */
-  searchPlaceholder?: string;
-  /** Show a search box inside the dropdown to filter options. Omit to auto-enable when there are >5 options. */
-  searchable?: boolean;
-  /** Options — strings, {value,label,description}, or {group,options} groups. */
-  options: Array<string | SelectOption | SelectGroup>;
-  /** Controlled selected value. */
-  value?: string | null;
-  /** Uncontrolled initial value. */
-  defaultValue?: string | null;
-  onChange?: (value: string) => void;
-  disabled?: boolean;
-  /** Open the menu upward instead of down (e.g. near a viewport bottom). @default "bottom" */
-  placement?: "bottom" | "top";
-  /** Render the dropdown in a portal (position:fixed on document.body) so it is never clipped by a
-   *  scrolling/overflow-hidden ancestor; auto-flips up near the viewport bottom. @default false */
-  portal?: boolean;
-  /** Minimum popover width in px when portaled (useful when the trigger is narrow). @default 0 */
-  minWidth?: number;
-}
-
-interface SelectOption {
-  value: string;
-  label: string;
-  /** Optional second line shown under the label. */
-  description?: string;
-}
-
-/** A group heading with its own options. */
-interface SelectGroup {
-  group: string;
-  options: Array<string | SelectOption>;
-}
-
+/**
+ * Custom select with a rounded popover (no native browser dropdown). Supports
+ * grouped options and two-line (title + subtitle) options. Keyboard navigable.
+ *
+ * @startingPoint section="Selects" subtitle="Custom select with grouped options" viewport="700x160"
+ */
+interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onChange" | "defaultValue"> {
+  label?: React.ReactNode;
+  hint?: React.ReactNode;
+  error?: React.ReactNode;
+  required?: boolean;
+  size?: "sm" | "md" | "lg";
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  placeholder?: string;
+  /** Placeholder for the in-popover search box. @default "Search…" */
+  searchPlaceholder?: string;
+  /** Show a search box inside the dropdown to filter options. Omit to auto-enable when there are >5 options. */
+  searchable?: boolean;
+  /** Options — strings, {value,label,description}, or {group,options} groups. */
+  options: Array<string | SelectOption | SelectGroup>;
+  /** Controlled selected value. */
+  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; Delete/Backspace on the closed trigger also clears. @default false */
+  clearable?: boolean;
+  disabled?: boolean;
+  /** Composed with the trigger's open/close toggle — your handler runs first; call `event.preventDefault()` to keep the menu from toggling. */
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+  /** Composed with the trigger's keyboard navigation (Enter/Space/Arrows/Escape) — your handler runs first; call `event.preventDefault()` to suppress it. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLButtonElement>;
+  /** Open the menu upward instead of down (e.g. near a viewport bottom). @default "bottom" */
+  placement?: "bottom" | "top";
+  /** Render the dropdown in a portal (position:fixed on document.body) so it is never clipped by a
+   *  scrolling/overflow-hidden ancestor; auto-flips up near the viewport bottom. Set false to render
+   *  inline. @default true */
+  portal?: boolean;
+  /** Minimum popover width in px when portaled (useful when the trigger is narrow). @default 0 */
+  minWidth?: number;
+}
+
+interface SelectOption {
+  value: string;
+  label: string;
+  /** Optional second line shown under the label. */
+  description?: string;
+}
+
+/** A group heading with its own options. */
+interface SelectGroup {
+  group: string;
+  options: Array<string | SelectOption>;
+}
+
 declare function Select(props: SelectProps): React.JSX.Element;
 
-interface SidebarItem {
-  /** Item label. */
-  label?: React.ReactNode;
-  /** Leading icon (shown in collapsed mode too). */
-  icon?: React.ReactNode;
-  href?: string;
-  active?: boolean;
-  onClick?: (e: React.MouseEvent) => void;
-  /** Trailing count badge. */
-  badge?: React.ReactNode;
-  /** Render as an uppercase section heading instead of a link. */
-  section?: React.ReactNode;
-}
-
-/**
- * Collapsible side navigation — brand header, grouped nav items with icons and
- * badges, an optional footer, and a collapse toggle (icon-only when collapsed).
- *
- * @startingPoint section="Layout" subtitle="Collapsible side navigation" viewport="280x520"
- */
-interface SidebarProps extends React.HTMLAttributes<HTMLElement> {
-  brand?: React.ReactNode;
-  items: SidebarItem[];
-  /** Content pinned above the collapse toggle (e.g. a user row). */
-  footer?: React.ReactNode;
-  /** Controlled collapsed state. */
-  collapsed?: boolean;
-  /** Uncontrolled initial collapsed state. @default false */
-  defaultCollapsed?: boolean;
-  /** Show the collapse toggle. @default true */
-  collapsible?: boolean;
-  onCollapsedChange?: (collapsed: boolean) => void;
-}
-
+interface SidebarItem {
+  /** Item label. */
+  label?: React.ReactNode;
+  /** Leading icon (shown in collapsed mode too). */
+  icon?: React.ReactNode;
+  href?: string;
+  active?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+  /** Trailing count badge. */
+  badge?: React.ReactNode;
+  /** Render as an uppercase section heading instead of a link. */
+  section?: React.ReactNode;
+}
+
+/**
+ * Collapsible side navigation — brand header, grouped nav items with icons and
+ * badges, an optional footer, and a collapse toggle (icon-only when collapsed).
+ *
+ * @startingPoint section="Layout" subtitle="Collapsible side navigation" viewport="280x520"
+ */
+interface SidebarProps extends React.HTMLAttributes<HTMLElement> {
+  brand?: React.ReactNode;
+  items: SidebarItem[];
+  /** Content pinned above the collapse toggle (e.g. a user row). */
+  footer?: React.ReactNode;
+  /** Controlled collapsed state. */
+  collapsed?: boolean;
+  /** Uncontrolled initial collapsed state. @default false */
+  defaultCollapsed?: boolean;
+  /** Show the collapse toggle. @default true */
+  collapsible?: boolean;
+  onCollapsedChange?: (collapsed: boolean) => void;
+}
+
 declare function Sidebar(props: SidebarProps): React.JSX.Element;
 
-/**
- * Shimmering placeholder shown while content loads.
- */
-interface SkeletonProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** Shape. @default "text" */
-  variant?: "text" | "circle" | "rect";
-  /** CSS width (e.g. "120px", "60%"). */
-  width?: string | number;
-  /** CSS height. */
-  height?: string | number;
-  /** For text variant: number of lines (last is shortened). @default 1 */
-  lines?: number;
-}
-
+/**
+ * Shimmering placeholder shown while content loads.
+ */
+interface SkeletonProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Shape preset: "text" line(s), "circle" (1:1 aspect, full radius), or "rect" block (--radius-md). @default "text" */
+  variant?: "text" | "circle" | "rect";
+  /** CSS width (e.g. "120px", "60%"). */
+  width?: string | number;
+  /** CSS height. */
+  height?: string | number;
+  /** For text variant: number of lines (last is shortened). @default 1 */
+  lines?: number;
+}
+
 declare function Skeleton(props: SkeletonProps): React.JSX.Element;
 
-/**
- * Range slider with a filled track, draggable thumb, value bubble, optional
- * ticks, and full keyboard support (arrows / Home / End).
- *
- * @startingPoint section="Inputs" subtitle="Range slider with value bubble" viewport="700x110"
- */
-interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
-  /** Label shown above the track. */
-  label?: React.ReactNode;
-  /** Controlled value. */
-  value?: number;
-  /** Uncontrolled initial value. @default 0 */
-  defaultValue?: number;
-  /** @default 0 */
-  min?: number;
-  /** @default 100 */
-  max?: number;
-  /** @default 1 */
-  step?: number;
-  disabled?: boolean;
-  /** Show the current value at the top-right. @default true */
-  showValue?: boolean;
-  /** Render step ticks along the rail. @default false */
-  showTicks?: boolean;
-  /** Format the displayed value (label + bubble). */
-  formatValue?: (value: number) => React.ReactNode;
-  onChange?: (value: number) => void;
-}
-
+/**
+ * Range slider with a filled track, draggable thumb, value bubble, optional
+ * ticks, and full keyboard support (arrows / Home / End).
+ *
+ * @startingPoint section="Inputs" subtitle="Range slider with value bubble" viewport="700x110"
+ */
+interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Label shown above the track. */
+  label?: React.ReactNode;
+  /** Helper text shown below the track when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message shown below the track — turns it red (sets `aria-invalid`) and replaces the hint. */
+  error?: React.ReactNode;
+  /** Controlled value. */
+  value?: number;
+  /** Uncontrolled initial value. @default 0 */
+  defaultValue?: number;
+  /** @default 0 */
+  min?: number;
+  /** @default 100 */
+  max?: number;
+  /** @default 1 */
+  step?: number;
+  disabled?: boolean;
+  /** Show the current value at the top-right. @default true */
+  showValue?: boolean;
+  /** Render step ticks along the rail. @default false */
+  showTicks?: boolean;
+  /** Color intent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Format the displayed value (label + bubble). */
+  formatValue?: (value: number) => React.ReactNode;
+  onChange?: (value: number) => void;
+}
+
 declare function Slider(props: SliderProps): React.JSX.Element;
 
-/**
- * Indeterminate loading spinner.
- */
-interface SpinnerProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** @default "md" */
-  size?: "sm" | "md" | "lg" | "xl";
-  /** @default "primary" — use "white" on colored backgrounds. */
-  tone?: "primary" | "neutral" | "white";
-  /** Accessible label. @default "Loading" */
-  label?: string;
-}
-
+/**
+ * Indeterminate loading spinner.
+ */
+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";
+  /** Accessible label. @default "Loading" */
+  label?: string;
+}
+
 declare function Spinner(props: SpinnerProps): React.JSX.Element;
 
-/**
- * KPI / metric card — label, big value, optional icon, trend delta, and help text.
- *
- * @startingPoint section="Data display" subtitle="KPI / metric card" viewport="700x160"
- */
-interface StatProps extends React.HTMLAttributes<HTMLDivElement> {
-  label: React.ReactNode;
-  value: React.ReactNode;
-  /** Icon shown top-right in a tinted tile. */
-  icon?: React.ReactNode;
-  /** Trend value, e.g. "+12.5%" or "-3%". */
-  delta?: React.ReactNode;
-  /** Force the trend direction/color; otherwise inferred from a leading "-". */
-  deltaDirection?: "up" | "down" | "flat";
-  /** Muted text after the delta, e.g. "vs last month". */
-  helpText?: React.ReactNode;
-  /** Drop the card chrome (no border/background/padding). @default false */
-  plain?: boolean;
-}
-
+/**
+ * KPI / metric card — label, big value, optional icon, trend delta, and help text.
+ *
+ * @startingPoint section="Data display" subtitle="KPI / metric card" viewport="700x160"
+ */
+interface StatProps extends React.HTMLAttributes<HTMLDivElement> {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  /** Icon shown top-right in a tinted tile. */
+  icon?: React.ReactNode;
+  /** Trend value, e.g. "+12.5%" or "-3%". */
+  delta?: React.ReactNode;
+  /** Force the trend direction/color; otherwise inferred from a leading "-". */
+  deltaDirection?: "up" | "down" | "flat";
+  /** Muted text after the delta, e.g. "vs last month". */
+  helpText?: React.ReactNode;
+  /** Drop the card chrome (no border/background/padding). @default false */
+  plain?: boolean;
+}
+
 declare function Stat(props: StatProps): React.JSX.Element;
 
-interface Step {
-  /** Step title. */
-  title: React.ReactNode;
-  /** Optional sub-label under the title. */
-  description?: React.ReactNode;
-  /** Custom indicator content (defaults to the step number). */
-  icon?: React.ReactNode;
-  /** Mark this step as errored (red indicator). */
-  error?: boolean;
-}
-
-/**
- * Multi-step progress indicator. Steps before `active` show a check, the active
- * step is ringed, later steps are muted; horizontal or vertical.
- *
- * @startingPoint section="Navigation" subtitle="Multi-step progress" viewport="700x140"
- */
-interface StepperProps extends React.HTMLAttributes<HTMLDivElement> {
-  steps: Step[];
-  /** Index of the current step. @default 0 */
-  active?: number;
-  /** @default "horizontal" */
-  orientation?: "horizontal" | "vertical";
-  /** Allow clicking completed/active steps. @default false */
-  clickable?: boolean;
-  /** Fired when a clickable step is clicked. */
-  onStepClick?: (index: number) => void;
-}
-
+interface Step {
+  /** Step title. */
+  title: React.ReactNode;
+  /** Optional sub-label under the title. */
+  description?: React.ReactNode;
+  /** Custom indicator content (defaults to the step number). */
+  icon?: React.ReactNode;
+  /** Mark this step as errored (red indicator). */
+  error?: boolean;
+}
+
+/**
+ * Multi-step progress indicator. Steps before `active` show a check, the active
+ * step is ringed, later steps are muted; horizontal or vertical.
+ *
+ * @startingPoint section="Navigation" subtitle="Multi-step progress" viewport="700x140"
+ */
+interface StepperProps extends React.HTMLAttributes<HTMLDivElement> {
+  steps: Step[];
+  /** Controlled index of the current step (pair with `onStepClick`). */
+  active?: number;
+  /** Uncontrolled initial step index; the Stepper then tracks clicks itself. @default 0 */
+  defaultActive?: number;
+  /** @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Color intent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** Allow clicking completed/active steps. @default false */
+  clickable?: boolean;
+  /** Fired when a clickable step is clicked. */
+  onStepClick?: (index: number) => void;
+}
+
 declare function Stepper(props: StepperProps): React.JSX.Element;
 
-/**
- * Toggle switch with a springy thumb. Use for instant on/off settings.
- *
- * @startingPoint section="Toggles" subtitle="On/off toggle switch" viewport="700x120"
- */
-interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
-  label?: React.ReactNode;
-  description?: React.ReactNode;
-  size?: "sm" | "md";
-}
-
+/**
+ * Toggle switch with a springy thumb. Use for instant on/off settings.
+ *
+ * @startingPoint section="Toggles" subtitle="On/off toggle switch" viewport="700x120"
+ */
+interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+  /** Error message shown below the control; tints the track red and wires `aria-invalid`/`aria-describedby`. @default undefined */
+  error?: React.ReactNode;
+  size?: "sm" | "md" | "lg";
+  /** Color intent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+}
+
 declare function Switch(props: SwitchProps): React.JSX.Element;
 
-/**
- * Data table with sticky-styled header, hover/striped rows, client-side
- * sorting, custom cell renderers, and row selection highlight.
- *
- * @startingPoint section="Data display" subtitle="Sortable data table" viewport="700x320"
- */
-interface TableProps<T = any> extends React.HTMLAttributes<HTMLDivElement> {
-  columns: TableColumn<T>[];
-  data: T[];
-  /** Row hover highlight. @default true */
-  hover?: boolean;
-  /** Zebra striping. @default false */
-  striped?: boolean;
-  /** @default "md" */
-  size?: "sm" | "md";
-  /** Enable click-to-sort headers. @default false */
-  sortable?: boolean;
-  /** Returns a stable key per row. */
-  rowKey?: (row: T, index: number) => string | number;
-  /** Keys of rows to highlight as selected. */
-  selectedKeys?: Array<string | number>;
-}
-
-interface TableColumn<T = any> {
-  /** Object key in each row + sort key. */
-  key: string;
-  /** Header label. */
-  header: React.ReactNode;
-  /** Cell alignment. @default "left" */
-  align?: "left" | "center" | "right";
-  /** Fixed column width (CSS value). */
-  width?: string;
-  /** Disable sorting for this column when the table is sortable. */
-  sortable?: boolean;
-  /** Custom cell renderer. */
-  render?: (value: any, row: T, index: number) => React.ReactNode;
-}
-
+/** Sort state: the sorted column field (null = unsorted) and direction. */
+interface TableSort {
+  /** Column field being sorted, or null for no sort. */
+  field: string | null;
+  /** Sort direction. */
+  dir: "asc" | "desc";
+}
+
+/**
+ * Data table with sticky-styled header, hover/striped rows, client-side
+ * sorting, custom cell renderers, and row selection highlight. Sorting is
+ * controlled via `sort` + `onSortChange`, or uncontrolled via `defaultSort`.
+ * A truly pinned header (`stickyHeader`) keeps thead visible while the body
+ * scrolls — pair it with `maxHeight` to give the table its own scroll area.
+ * Uses the same vocabulary as `Datatable` (`rows`, `field`, `headerName`,
+ * `renderCell`) so columns/data move between the two without renaming.
+ *
+ * @startingPoint section="Data display" subtitle="Sortable data table" viewport="700x320"
+ */
+interface TableProps<T = any> extends React.HTMLAttributes<HTMLDivElement> {
+  columns: TableColumn<T>[];
+  /** Row objects. */
+  rows?: T[];
+  /** Row hover highlight. @default true */
+  hover?: boolean;
+  /** Zebra striping. @default false */
+  striped?: boolean;
+  /** @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Enable click-to-sort headers. @default false */
+  sortable?: boolean;
+  /** Controlled sort state — pair with `onSortChange` (null = unsorted). */
+  sort?: TableSort | null;
+  /** Initial sort when uncontrolled. @default { field: null, dir: "asc" } */
+  defaultSort?: TableSort;
+  /** Fired when a sortable header is clicked with the next sort state: (sort). */
+  onSortChange?: (sort: TableSort) => void;
+  /** Returns a stable key per row. */
+  rowKey?: (row: T, index: number) => string | number;
+  /** Keys of rows to highlight as selected. */
+  selectedKeys?: Array<string | number>;
+  /** Pin the header to the top while the body scrolls (use with `maxHeight` or a scroll container). @default false */
+  stickyHeader?: boolean;
+  /** Cap the table height and give it its own vertical scroll area (CSS length or number of px). */
+  maxHeight?: number | string;
+}
+
+interface TableColumn<T = any> {
+  /** Object key in each row + sort key. */
+  field: string;
+  /** Header label. */
+  headerName?: React.ReactNode;
+  /** Cell alignment. @default "left" */
+  align?: "left" | "center" | "right";
+  /** Fixed column width (CSS value). */
+  width?: string;
+  /** Disable sorting for this column when the table is sortable. */
+  sortable?: boolean;
+  /** Custom cell renderer: (value, row, index). */
+  renderCell?: (value: any, row: T, index: number) => React.ReactNode;
+}
+
 declare function Table<T = any>(props: TableProps<T>): React.JSX.Element;
 
-/**
- * Tabbed navigation with a sliding active indicator. Line or pill variant.
- * Controlled (`value` + `onChange`) or uncontrolled (`defaultValue`).
- *
- * @startingPoint section="Navigation" subtitle="Tabs with sliding indicator" viewport="700x220"
- */
-interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
-  items: TabItem[];
-  value?: string;
-  defaultValue?: string;
-  onChange?: (value: string) => void;
-  /** @default "line" */
-  variant?: "line" | "pill";
-}
-
-interface TabItem {
-  /** Unique value / id. */
-  value: string;
-  /** Tab label. */
-  label: React.ReactNode;
-  /** Optional leading icon. */
-  icon?: React.ReactNode;
-  /** Optional count pill. */
-  count?: number;
-  /** Panel content rendered when active (omit for nav-only tabs). */
-  content?: React.ReactNode;
-}
-
+/**
+ * Tabbed navigation with a sliding active indicator. Line or pill variant.
+ * Controlled (`value` + `onChange`) or uncontrolled (`defaultValue`).
+ *
+ * @startingPoint section="Navigation" subtitle="Tabs with sliding indicator" viewport="700x220"
+ */
+interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+  items: TabItem[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  /** @default "line" */
+  variant?: "line" | "pill";
+  /** Color intent. @default "primary" */
+  tone?: "primary" | "success" | "warning" | "danger" | "info" | "neutral";
+  /** 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";
+}
+
+interface TabItem {
+  /** Unique value / id. */
+  value: string;
+  /** Tab label. */
+  label: React.ReactNode;
+  /** Optional leading icon. */
+  icon?: React.ReactNode;
+  /** Optional count pill. */
+  count?: number;
+  /** Panel content rendered when active (omit for nav-only tabs). */
+  content?: React.ReactNode;
+}
+
 declare function Tabs(props: TabsProps): React.JSX.Element;
 
-/**
- * Removable chip for filters, selected items, and keywords.
- */
-interface TagProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** Show a remove (×) button and handle its click. */
-  onRemove?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-  /** Optional leading icon. */
-  leftIcon?: React.ReactNode;
-  children?: React.ReactNode;
-}
-
+/**
+ * Removable chip for filters, selected items, and keywords.
+ */
+interface TagProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Show a remove (×) button and handle its click. */
+  onRemove?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+  /** 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";
+  children?: React.ReactNode;
+}
+
 declare function Tag(props: TagProps): React.JSX.Element;
 
-/**
- * Multi-line text input with label, hint, and error state.
- */
-interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-}
-
+/**
+ * Multi-line text input with label, hint, and error state.
+ */
+interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — turns the field red and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk and forwards to the native textarea). */
+  required?: boolean;
+  /** 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";
+}
+
 declare function Textarea(props: TextareaProps): React.JSX.Element;
 
-interface TimelineItem {
-  /** Event title. */
-  title: React.ReactNode;
-  /** Muted timestamp shown to the right of the title. */
-  time?: React.ReactNode;
-  /** Supporting description. */
-  description?: React.ReactNode;
-  /** Icon inside the node dot. */
-  icon?: React.ReactNode;
-  /** Node color. */
-  tone?: "primary" | "success" | "warning" | "danger";
-}
-
-/**
- * Vertical timeline of events — node dots connected by a rail, each with title,
- * time, and description.
- *
- * @startingPoint section="Data display" subtitle="Vertical event timeline" viewport="700x340"
- */
-interface TimelineProps extends React.HTMLAttributes<HTMLUListElement> {
-  items: TimelineItem[];
-}
-
+interface TimelineItem {
+  /** Event title. */
+  title: React.ReactNode;
+  /** Muted timestamp shown to the right of the title. */
+  time?: React.ReactNode;
+  /** Supporting description. */
+  description?: React.ReactNode;
+  /** Icon inside the node dot. */
+  icon?: React.ReactNode;
+  /** Node color. */
+  tone?: "primary" | "info" | "success" | "warning" | "danger";
+}
+
+/**
+ * Vertical timeline of events — node dots connected by a rail, each with title,
+ * time, and description.
+ *
+ * @startingPoint section="Data display" subtitle="Vertical event timeline" viewport="700x340"
+ */
+interface TimelineProps extends React.HTMLAttributes<HTMLUListElement> {
+  items: TimelineItem[];
+}
+
 declare function Timeline(props: TimelineProps): React.JSX.Element;
 
-/**
- * Transient notification card. Render inside a <ToastViewport> and manage a
- * list in state (push on action, remove on close / timeout).
- */
-interface ToastProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** @default "default" */
-  tone?: "default" | "success" | "warning" | "danger" | "info";
-  /** Bold heading. */
-  title?: React.ReactNode;
-  /** Override the tone icon. */
-  icon?: React.ReactNode;
-  /** Show close button + handle dismissal. */
-  onClose?: () => void;
-  children?: React.ReactNode;
-}
-
-declare function Toast(props: ToastProps): React.JSX.Element;
-
-interface ToastViewportProps extends React.HTMLAttributes<HTMLDivElement> {
-  children?: React.ReactNode;
-}
-
-/** Fixed bottom-right stack container for toasts. */
+/**
+ * Transient notification card. Render inside a <ToastViewport> and manage a
+ * list in state (push on action, remove on close / timeout).
+ */
+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";
+  /** Bold heading. */
+  title?: React.ReactNode;
+  /** Override the tone icon. */
+  icon?: React.ReactNode;
+  /** Show close button + handle dismissal. */
+  onClose?: () => void;
+  /** Auto-dismiss after this many ms (paused on hover/focus). `0`/`Infinity` keeps it open. @default 4500 */
+  duration?: number;
+  children?: React.ReactNode;
+}
+
+declare function Toast(props: ToastProps): React.JSX.Element;
+
+interface ToastViewportProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Cap how many toasts are shown at once (keeps the most recent). */
+  limit?: number;
+  children?: React.ReactNode;
+}
+
+/** Fixed bottom-right stack container for toasts. */
 declare function ToastViewport(props: ToastViewportProps): React.JSX.Element;
 
-/**
- * Hover/focus tooltip. Wraps a single trigger element.
- */
-interface TooltipProps extends React.HTMLAttributes<HTMLSpanElement> {
-  /** Tooltip text/content. */
-  label: React.ReactNode;
-  /** @default "top" */
-  placement?: "top" | "bottom" | "left" | "right";
-  /** Open delay in ms. @default 120 */
-  delay?: number;
-  /** The trigger element. */
-  children: React.ReactNode;
-}
-
+/** A single toast's options when pushed imperatively. */
+interface ToastOptions {
+  /** @default "default" */
+  tone?: "default" | "neutral" | "success" | "warning" | "danger" | "info";
+  /** Bold heading. */
+  title?: React.ReactNode;
+  /** Body/description content. */
+  description?: React.ReactNode;
+  /** Override the tone icon. */
+  icon?: React.ReactNode;
+  /** Auto-dismiss after this many ms (overrides the provider default); 0/Infinity keeps it open. */
+  duration?: number;
+}
+
+/** Tone helper signature: pass a title (or a full options object) + optional options. */
+type ToastFn = (titleOrOptions: React.ReactNode | ToastOptions, options?: ToastOptions) => number;
+
+/** Imperative toast API returned by useToast(). */
+interface ToastApi {
+  /** Push a toast; returns its id. */
+  toast: ((options: ToastOptions) => number) & {
+    success: ToastFn;
+    warning: ToastFn;
+    danger: ToastFn;
+    /** Alias of `danger`. */
+    error: ToastFn;
+    info: ToastFn;
+    /** Default (neutral) tone. */
+    show: ToastFn;
+  };
+  /** Dismiss a toast by id. */
+  dismiss: (id: number) => void;
+  /** Remove every toast. */
+  clear: () => void;
+  /** The current toast list. */
+  toasts: Array<{ id: number } & ToastOptions & { children?: React.ReactNode }>;
+}
+
+/** Access the imperative toast API. Must be under a <ToastProvider>. */
+declare function useToast(): ToastApi;
+
+interface ToastProviderProps {
+  children?: React.ReactNode;
+  /** Max toasts shown at once (most recent kept). @default 4 */
+  limit?: number;
+  /** Default auto-dismiss duration in ms for toasts that don't set their own. @default 4500 */
+  duration?: number;
+}
+
+/** Holds the toast list + renders a ToastViewport; exposes the API via useToast(). */
+declare function ToastProvider(props: ToastProviderProps): React.JSX.Element;
+
+/**
+ * Hover/focus tooltip. Wraps a single trigger element. The tooltip is linked to the
+ * trigger via aria-describedby while shown, is aria-hidden when closed, and Escape
+ * dismisses it (WCAG 1.4.13).
+ */
+interface TooltipProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Tooltip text/content. */
+  label: React.ReactNode;
+  /** @default "top" */
+  placement?: "top" | "bottom" | "left" | "right";
+  /** Open delay in ms. @default 120 */
+  delay?: number;
+  /** The trigger element; receives aria-describedby while shown (non-element children are wrapped in a span). */
+  children: React.ReactNode;
+}
+
 declare function Tooltip(props: TooltipProps): React.JSX.Element;
 
-interface TreeNode {
-  /** Unique id. */
-  id: string;
-  /** Row label. */
-  label: React.ReactNode;
-  /** Leading icon. */
-  icon?: React.ReactNode;
-  /** Trailing meta (count, etc.). */
-  badge?: React.ReactNode;
-  /** Child nodes (presence makes the row expandable). */
-  children?: TreeNode[];
-}
-
-/**
- * Hierarchical tree with expand/collapse carets, indentation, icons, and a
- * selected row. Good for file explorers and nested navigation.
- *
- * @startingPoint section="Navigation" subtitle="Hierarchical tree view" viewport="700x340"
- */
-interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
-  data: TreeNode[];
-  /** Node ids expanded on first render. */
-  defaultExpanded?: string[];
-  /** Controlled selected node id. */
-  selectedId?: string | null;
-  /** Fired with the node when a row is clicked. */
-  onSelect?: (node: TreeNode) => void;
-}
-
+interface TreeNode {
+  /** Unique id. */
+  id: string;
+  /** Row label. */
+  label: React.ReactNode;
+  /** Leading icon. */
+  icon?: React.ReactNode;
+  /** Trailing meta (count, etc.). */
+  badge?: React.ReactNode;
+  /** Child nodes (presence makes the row expandable). */
+  children?: TreeNode[];
+}
+
+/**
+ * Hierarchical tree with expand/collapse carets, indentation, icons, and a
+ * selected row. Good for file explorers and nested navigation.
+ *
+ * @startingPoint section="Navigation" subtitle="Hierarchical tree view" viewport="700x340"
+ */
+interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Tree nodes. @default [] */
+  items?: TreeNode[];
+  /** Node ids expanded on first render (uncontrolled). */
+  defaultExpanded?: string[];
+  /** Controlled expanded node ids (pair with `onExpandedChange`). */
+  expanded?: string[];
+  /** Fired with the next expanded ids whenever a row expands or collapses. */
+  onExpandedChange?: (ids: string[]) => void;
+  /** Selected node id on first render (uncontrolled). */
+  defaultSelectedId?: string | null;
+  /** Controlled selected node id (pair with `onSelect`). */
+  selectedId?: string | null;
+  /** Fired when a row is clicked, id first (with the full node as the second argument). */
+  onSelect?: (id: string, node: TreeNode) => void;
+}
+
 declare function TreeView(props: TreeViewProps): React.JSX.Element;
 
-export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, 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, FileUpload, type FileUploadProps, 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, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastProps, ToastViewport, type ToastViewportProps, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps };
+/** 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;
+  /** 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;
+  /** Padding (all / x / y / individual) — spacing step (number) or CSS length. */
+  p?: number | string;
+  px?: number | string;
+  py?: number | string;
+  pt?: number | string;
+  pr?: number | string;
+  pb?: number | string;
+  pl?: number | string;
+  /** Margin (all / x / y / individual) — spacing step (number) or CSS length. */
+  m?: number | string;
+  mx?: number | string;
+  my?: number | string;
+  mt?: number | string;
+  mr?: number | string;
+  mb?: number | string;
+  ml?: number | string;
+  /** Background: a surface token name ("surface" | "surface-raised" | "surface-sunken" | "bg"), a bare custom property ("--my-token", wrapped in var()), or any plain CSS background value (e.g. "#fff", "linear-gradient(...)") used as-is. */
+  bg?: "surface" | "surface-raised" | "surface-sunken" | "bg" | string;
+  /** Add a 1px token border. @default false */
+  border?: boolean;
+  /** Border radius token suffix (e.g. "md", "lg", "2xl", "full"). */
+  radius?: string;
+  /** Box-shadow token suffix (e.g. "sm", "lg", "xl"). */
+  shadow?: string;
+}
+
+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;
+  /** 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;
+  /** Max width: a named size (sm 640 / md 768 / lg 1024 / xl 1280 / full) or any CSS length. @default "lg" */
+  size?: "sm" | "md" | "lg" | "xl" | "full" | string;
+  /** Apply horizontal padding. @default true */
+  padded?: boolean;
+}
+
+declare function Container(props: ContainerProps): React.JSX.Element;
+
+/** 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;
+  /** 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;
+  /** 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?: number | string;
+  align?: React.CSSProperties["alignItems"];
+  justify?: React.CSSProperties["justifyItems"];
+}
+
+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;
+  /** 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;
+  /** @default "column" */
+  direction?: "row" | "column" | "row-reverse" | "column-reverse";
+  /** Gap as a spacing-scale step (number) or any CSS length. @default 4 */
+  gap?: number | string;
+  align?: React.CSSProperties["alignItems"];
+  justify?: React.CSSProperties["justifyContent"];
+  /** Wrap children. @default false */
+  wrap?: boolean;
+  /** Use inline-flex instead of flex. @default false */
+  inline?: boolean;
+}
+
+declare function Stack(props: StackProps): React.JSX.Element;
+
+/** Inline code with mono font and a subtle token-styled surface. */
+interface CodeProps extends React.HTMLAttributes<HTMLElement> {
+  /** Element/tag to render. @default "code" */
+  as?: keyof React.JSX.IntrinsicElements;
+  /** 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;
+}
+
+declare function Code(props: CodeProps): React.JSX.Element;
+
+/** Heading (h1–h6) with token typography. `level` sets the tag and default 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;
+  /** 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;
+  /** 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;
+  align?: React.CSSProperties["textAlign"];
+}
+
+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;
+  /** 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;
+  /** 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";
+  /** Font-weight token suffix (e.g. "medium", "semibold", "bold"). */
+  weight?: "medium" | "semibold" | "bold" | string;
+  align?: React.CSSProperties["textAlign"];
+}
+
+declare function Text(props: TextProps): React.JSX.Element;
+
+/** SSR-safe `useLayoutEffect` (falls back to `useEffect` on the server). */
+declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;
+
+/** `true` once the component has mounted on the client — for SSR-safe rendering. */
+declare function useMounted(): boolean;
+
+/** The value from the previous render. */
+declare function usePrevious<T>(value: T): T | undefined;
+
+/** Boolean state with a stable toggle. `toggle()` flips; `toggle(true)` sets. */
+declare function useToggle(
+  initial?: boolean
+): [boolean, (next?: boolean) => void, React.Dispatch<React.SetStateAction<boolean>>];
+
+/** Open/close state for dialogs, drawers, menus, popovers. */
+declare function useDisclosure(initial?: boolean): {
+  open: boolean;
+  onOpen: () => void;
+  onClose: () => void;
+  onToggle: () => void;
+  setOpen: React.Dispatch<React.SetStateAction<boolean>>;
+};
+
+/** Controlled/uncontrolled state — the pattern every form component needs. */
+declare function useControllableState<T>(options?: {
+  value?: T;
+  defaultValue?: T;
+  onChange?: (value: T) => void;
+}): [T, (next: T | ((prev: T) => T)) => void];
+
+/** Reactively match a media query (SSR-safe). */
+declare function useMediaQuery(query: string): boolean;
+
+/** `true` when the user requests reduced motion. */
+declare function usePrefersReducedMotion(): boolean;
+
+interface UseColorSchemeOptions {
+  /** localStorage key. @default "twico-theme" */
+  storageKey?: string;
+  /** "class" toggles `.dark`; any other string is set as an attribute. @default "class" */
+  attribute?: string;
+  /** Element to theme. @default document.documentElement */
+  element?: HTMLElement | null;
+  /** Disable CSS transitions during the switch so the UI re-themes instantly. @default true */
+  disableTransitionsOnChange?: boolean;
+}
+
+/** Light/dark theme state synced to `<html>` and persisted to localStorage. */
+declare function useColorScheme(options?: UseColorSchemeOptions): {
+  theme: "light" | "dark";
+  setTheme: (theme: "light" | "dark") => void;
+  toggle: () => void;
+  isDark: boolean;
+};
+
+/** Attach an event listener (window by default, or a ref/element) with cleanup. */
+declare function useEventListener(
+  eventName: string,
+  handler: (event: any) => void,
+  element?: React.RefObject<any> | 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>,
+  handler: (event: Event) => void,
+  events?: string[]
+): void;
+
+interface UseKeyPressOptions {
+  ctrl?: boolean;
+  meta?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+  preventDefault?: boolean;
+}
+
+/** Run `handler` on a keydown matching `key`, with optional modifier requirements. */
+declare function useKeyPress(
+  key: string | string[],
+  handler: (event: KeyboardEvent) => void,
+  options?: UseKeyPressOptions
+): void;
+
+/** State persisted to localStorage (JSON-serialized), SSR-safe. */
+declare function useLocalStorage<T>(
+  key: string,
+  initialValue: T
+): [T, (value: T | ((prev: T) => T)) => void];
+
+/** Copy text to the clipboard with a `copied` flag that auto-resets. */
+declare function useCopyToClipboard(timeout?: number): {
+  copied: boolean;
+  copy: (text: string) => Promise<boolean>;
+};
+
+/** Debounce a value — updates only after `delay` ms of no change. */
+declare function useDebouncedValue<T>(value: T, delay?: number): T;
+
+/** A debounced version of a callback. */
+declare function useDebouncedCallback<A extends any[]>(
+  callback: (...args: A) => void,
+  delay?: number
+): (...args: A) => void;
+
+/** Run `callback` every `delay` ms; pass `delay = null` to pause. */
+declare function useInterval(callback: () => void, delay: number | null): void;
+
+/** Run `callback` once after `delay` ms; pass `delay = null` to cancel. */
+declare function useTimeout(callback: () => void, delay: number | null): void;
+
+/** The current window dimensions (0×0 on the server). */
+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;
+
+/** The latest IntersectionObserver entry for the element referenced by `ref`. */
+declare function useIntersectionObserver<T extends HTMLElement = HTMLElement>(
+  ref: React.RefObject<T>,
+  options?: IntersectionObserverInit
+): IntersectionObserverEntry | null;
+
+/** Lock body scroll while `locked` is true — for modals/drawers. */
+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, 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 };