twico-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1501 @@
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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";
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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";
+}
+
+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;
+}
+
+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>;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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>;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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";
+}
+
+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;
+}
+
+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>;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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";
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+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[];
+}
+
+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. */
+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;
+}
+
+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;
+}
+
+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 };