@cascivo/react 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -368,6 +368,45 @@ declare function Separator({
   className,
   ...props
 }: SeparatorProps): import("react").JSX.Element;
+type LogoVariant = 'mark' | 'mark-accent' | 'horizontal' | 'stacked' | 'nav';
+interface LogoProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * The logo renders the mark and, in a lockup, the wordmark — there is no slot for
+   * anything else. `never` rather than `Omit<>` because omitting a key off
+   * `HTMLAttributes` loses the `style` widening that the signals JSX augmentation
+   * applies in an adopter's project, and the spread below then fails to compile there.
+   */
+  children?: never;
+  /**
+   * `mark` and `mark-accent` render the square alone; `horizontal`, `stacked` and `nav`
+   * add the wordmark. `nav` is the only lockup permitted below 24px.
+   *
+   * @defaultValue `mark`
+   * @see the component manifest
+   */
+  variant?: LogoVariant;
+  /**
+   * Mark height in px. Clamped to a 16px floor — below that the notch closes optically.
+   *
+   * @defaultValue `18` for `nav`, `32` otherwise
+   * @see the component manifest
+   */
+  size?: number;
+}
+/**
+ * The cascivo logo: the mark on its own, or one of the three sanctioned lockups.
+ *
+ * Renders inline SVG rather than an `<img>` on purpose — `currentColor` and
+ * `--cascivo-color-accent` only resolve when the SVG is part of the document, which is
+ * what lets the logo repaint with whatever `data-theme` subtree it is dropped into.
+ */
+declare function Logo({
+  variant,
+  size,
+  className,
+  style,
+  ...props
+}: LogoProps): import("react").JSX.Element;
 interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
   /**
    * Severity tone: `default` (neutral), `info`, `success`, `warning` or `destructive`. Sets
@@ -556,6 +595,16 @@ interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
   hint?: string;
   error?: string;
   resize?: 'none' | 'vertical' | 'both';
+  /**
+   * Grow the control with its content instead of holding the fixed rows height. rows becomes
+   * the minimum and --cascivo-textarea-max-block-size (default 20lh) the ceiling. Pure CSS
+   * (field-sizing: content) — no measurement and no listener; where unsupported the fixed
+   * rows height is kept.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  autosize?: boolean;
 }
 /**
  * `forwardRef` so `ref` reaches the underlying `<textarea>` — and so it is TYPED.
@@ -1641,7 +1690,19 @@ interface OverflowMenuProps {
    */
   label?: string;
   size?: 'sm' | 'md';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * Tab-order position of the trigger. A composite widget that manages its own focus (a
+   * `DataTable` in grid keyboard mode) passes `-1` so the menu stays reachable by Enter on
+   * its cell without becoming an extra Tab stop.
+   */
+  tabIndex?: number;
   className?: string;
 }
 declare function OverflowMenu({
@@ -1652,6 +1713,7 @@ declare function OverflowMenu({
   label,
   size,
   disabled,
+  tabIndex,
   className
 }: OverflowMenuProps): import("react").JSX.Element;
 interface SearchProps {
@@ -1798,12 +1860,94 @@ interface NumberInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, '
  * incomplete, which is why the rule is a guard and not a checklist.
  */
 declare const NumberInput: import("react").ForwardRefExoticComponent<NumberInputProps & import("react").RefAttributes<HTMLInputElement>>;
+/**
+ * Per-column filtering, kept pure so the table's filter pipeline is testable without a DOM
+ * and stays O(rows) per change — never per render.
+ *
+ * Three filter shapes cover what dashboards actually ask for (the same three TanStack's
+ * column-filtering guide leads with): a substring on text, a set of allowed values on an
+ * enumerated column, and a numeric range. Values arrive from the table's own inputs or from
+ * a controlled `filters` prop, so the shape is a plain serialisable object — it round-trips
+ * through a URL or storage unchanged.
+ */
+/** The kind of filter control a column offers. */
+type ColumnFilterKind = 'text' | 'select' | 'range';
+/** The current value of one column's filter. An inactive filter is simply absent. */
+type ColumnFilterValue = {
+  kind: 'text';
+  value: string;
+} | {
+  kind: 'select';
+  values: string[];
+} | {
+  kind: 'range';
+  min?: number;
+  max?: number;
+};
+/** Active filters by column key. */
+type ColumnFilters = Record<string, ColumnFilterValue>;
+/**
+ * Column layout as data: which columns show, in what order, how wide, and which stick to
+ * an edge. Every transition the header menu and the resize handle perform is a pure
+ * function here, so the table never reasons about layout in JSX and each rule is
+ * testable on its own.
+ *
+ * The shape is deliberately a plain object of keys (`ColumnState`): it round-trips through
+ * storage or a URL, and it survives the column definitions changing underneath it — a key
+ * that no longer exists is ignored, a new column simply takes its definition position.
+ */
+/** Which edge a pinned column sticks to. */
+type PinSide = 'start' | 'end';
+/** User-adjustable column layout. All fields optional; an absent field means "as defined". */
+interface ColumnState {
+  /** Keys of hidden columns. At least one column always stays visible. */
+  hidden?: string[];
+  /** Display order of column keys; keys not listed follow in definition order. */
+  order?: string[];
+  /** Explicit widths in px, by key — what the resize handle writes. */
+  widths?: Record<string, number>;
+  /** Pinned columns by key. Pinned-start columns render first, pinned-end last. */
+  pinned?: Record<string, PinSide>;
+}
+/**
+ * Row grouping, aggregation and column-group spans as data. The table's body is a flat
+ * list either way — grouping just interleaves group rows with the leaf rows they own, so
+ * paging, the virtual window and the grid keyboard model need no notion of a tree.
+ */
+/** Built-in aggregations for `Column.aggregate`. */
+type AggregateKind = 'sum' | 'avg' | 'min' | 'max' | 'count';
+/** A band of columns under one header (`columnGroups`). */
+interface ColumnGroup {
+  header: string;
+  /** Column keys in the band. Non-adjacent keys render as separate spans. */
+  columns: string[];
+}
 interface Column<Row> {
   key: string;
   header: string;
   sortable?: boolean;
   render?: (row: Row) => ReactNode;
   align?: 'start' | 'end';
+  /**
+   * Offer a per-column filter in a row under the header: `'text'` is a substring input,
+   * `'select'` a faceted checklist of the column's distinct values with counts, `'range'` a
+   * numeric min/max pair. Filters AND together and combine with the global search; the
+   * current values are readable and controllable through the `filters` props.
+   */
+  filter?: ColumnFilterKind;
+  /**
+   * Let the user edit this column's cells in place. Each cell renders an `Editable`
+   * (click, Enter or F2 to start; Enter commits, Escape cancels) and commits through the
+   * table's `onCellEdit`. Ignored when the column has a `render` — a custom cell brings its
+   * own control — or the table has no `onCellEdit`.
+   */
+  editable?: boolean;
+  /**
+   * What a group row and the `totals` row show for this column: a built-in reduction over
+   * the numeric cell values (`'count'` counts rows), or a function of the rows for anything
+   * else — a formatted currency, a distinct count, a sparkline.
+   */
+  aggregate?: AggregateKind | ((rows: Row[]) => ReactNode);
   /**
    * Preferred column width, any CSS length (`'8rem'`, `'120px'`, `'12%'`). Set it on
    * identifier-shaped columns (ids, statuses, dates) so they stop stealing space from the
@@ -1841,10 +1985,64 @@ interface Column<Row> {
   minWidth?: string;
 }
 type SortDirection = 'asc' | 'desc';
-interface SortState {
+/** One sorted column. */
+interface SortKey {
   key: string;
   direction: SortDirection;
 }
+/**
+ * The active sort. `thenBy` lists the secondary columns that break ties, in order — set
+ * by Shift-clicking headers when `multiSort` is on, or passed directly.
+ */
+interface SortState extends SortKey {
+  thenBy?: SortKey[];
+}
+/** One entry in a row's actions menu (`rowActions`). */
+interface RowAction<Row> {
+  id: string;
+  label: string;
+  /** Activation handler; receives the row the menu belongs to. */
+  onSelect: (row: Row) => void;
+  destructive?: boolean;
+  disabled?: boolean;
+  icon?: ReactNode;
+}
+/** Everything the table needs the server to apply, when `server` is set. */
+interface TableQuery {
+  sort: SortState | undefined;
+  /** Trimmed global search text; empty when the box is blank. */
+  search: string;
+  filters: ColumnFilters;
+  /** 1-based page. */
+  page: number;
+  pageSize: number;
+}
+/**
+ * Server-driven mode: the table renders `rows` as the current page verbatim and asks the
+ * server for anything that would change them. Sort, search, per-column filters and paging
+ * all stop running on the client at once — one switch, not four.
+ */
+interface DataTableServer {
+  /** Total rows across every page; drives the pager and the range label. */
+  totalItems?: number;
+  /**
+   * Called with the full query whenever sort, search, a filter, the page or the page size
+   * changes. Not called on mount: the rows you passed for the initial render are the first
+   * page.
+   */
+  onQueryChange: (query: TableQuery) => void;
+}
+/** Which column-layout controls the table offers. All off by default. */
+interface ColumnSettings {
+  /** A "Columns" menu in the toolbar that shows and hides columns. */
+  visibility?: boolean;
+  /** A drag handle on each header's trailing edge; arrow keys nudge it, Home resets to auto. */
+  resizable?: boolean;
+  /** "Move left" / "Move right" in each column's header menu. */
+  reorderable?: boolean;
+  /** "Pin to start" / "Pin to end" in each column's header menu; pinned columns stay put while the rest scroll. */
+  pinnable?: boolean;
+}
 interface DataTableLabels {
   search?: string;
   empty?: string;
@@ -1854,6 +2052,31 @@ interface DataTableLabels {
   expandRow?: string;
   previousPage?: string;
   nextPage?: string;
+  columns?: string;
+  actions?: string;
+  noResults?: string;
+  clearFilters?: string;
+  filterColumn?: (column: string) => string;
+  min?: string;
+  max?: string;
+  all?: string;
+  columnMenu?: (column: string) => string;
+  sortAscending?: string;
+  sortDescending?: string;
+  clearSort?: string;
+  moveLeft?: string;
+  moveRight?: string;
+  pinStart?: string;
+  pinEnd?: string;
+  unpin?: string;
+  hideColumn?: string;
+  resizeColumn?: (column: string) => string;
+  /** Accessible name of an editable cell's control; receives the column header. */
+  editCell?: (column: string) => string;
+  /** Label of the `totals` row. */
+  totals?: string;
+  /** The export button. */
+  exportCsv?: string;
 }
 interface DataTableProps<Row> {
   columns: Column<Row>[];
@@ -1870,9 +2093,15 @@ interface DataTableProps<Row> {
    * @see the component manifest
    */
   searchable?: boolean;
+  /**
+   * Client-side paging, or the pager for a `server`-driven table. `page` makes the current
+   * page controlled; with `server`, `pageSize`/`page` are echoed back in every `TableQuery`.
+   */
   pagination?: {
     pageSize: number;
     pageSizeOptions?: number[];
+    page?: number;
+    onPageChange?: (page: number) => void;
   };
   selection?: {
     mode: 'single' | 'multi';
@@ -1885,6 +2114,109 @@ interface DataTableProps<Row> {
     onClick: (selectedIds: string[]) => void;
   }[];
   renderExpandedRow?: (row: Row) => ReactNode;
+  /** Per-column filter values (controlled). Columns opt in with `Column.filter`. */
+  filters?: ColumnFilters;
+  /** Initial per-column filter values (uncontrolled). */
+  defaultFilters?: ColumnFilters;
+  /** Called with the full filter map whenever any column filter changes. */
+  onFiltersChange?: (filters: ColumnFilters) => void;
+  /**
+   * Shown instead of `emptyState` when there ARE rows but the search or filters match none
+   * of them — a different message from "no data", and the moment to offer a reset.
+   */
+  noResultsState?: ReactNode;
+  /** Extra controls rendered in the toolbar, next to the search box (exports, primary actions). */
+  toolbar?: ReactNode;
+  /**
+   * Per-row actions. Returns the menu entries for a row; the table renders them as a
+   * trailing "⋯" overflow menu column, keyboard-reachable like every other cell control.
+   */
+  rowActions?: (row: Row) => RowAction<Row>[];
+  /** Column layout (controlled): hidden, order, widths, pinned. See {@link ColumnState}. */
+  columnState?: ColumnState;
+  /** Initial column layout (uncontrolled). */
+  defaultColumnState?: ColumnState;
+  /** Called with the full column layout whenever the user changes it. */
+  onColumnStateChange?: (state: ColumnState) => void;
+  /** Which column-layout controls to offer; see {@link ColumnSettings}. */
+  columnSettings?: ColumnSettings;
+  /** Hand sort, search, filters and paging to the server; see {@link DataTableServer}. */
+  server?: DataTableServer;
+  /**
+   * Allow sorting by more than one column: Shift-click a header adds it as a tie-breaker
+   * (`SortState.thenBy`); a plain click replaces the whole sort. Sorted headers show their
+   * level.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  multiSort?: boolean;
+  /**
+   * Remember the user's column layout and sort across reloads, in local storage under this
+   * key. Applies when the corresponding props are uncontrolled; a controlled `columnState`
+   * or `sort` still wins. Two tables with the same key share the preference.
+   */
+  stateKey?: string;
+  /**
+   * How the keyboard moves through the table. `'row'` keeps every control in the Tab order
+   * and lets the arrows step between them. `'grid'` is the APG data-grid pattern: the table
+   * is ONE Tab stop, the arrows move a focused cell, Home/End jump within the row,
+   * Ctrl+Home/End to the corners, PageUp/PageDown by a screenful, Enter or F2 enters the
+   * cell's control and Escape returns to the cell. Cells outside the virtualized window are
+   * scrolled to. Prefer `'grid'` for wide or editable tables, where tabbing through every
+   * control is the complaint.
+   *
+   * @defaultValue `row`
+   * @see the component manifest
+   */
+  keyboardNavigation?: 'row' | 'grid';
+  /**
+   * Commits an inline edit: the row, the edited column's key and the new text. Enables
+   * editing for every column marked `editable`; the table does not mutate `rows` itself.
+   */
+  onCellEdit?: (row: Row, key: string, value: string) => void;
+  /**
+   * Group the rows by one or more columns, in order. Each group is a collapsible row
+   * showing its value, its row count and every `aggregate` column's reduction; leaves keep
+   * the current sort inside their group. Groups appear in order of first occurrence, so
+   * sort by the grouped column to order them.
+   */
+  groupBy?: string | string[];
+  /**
+   * Show a totals row under the body with each `aggregate` column's reduction over every
+   * row that passes the search and filters (not just the page). Sticks to the bottom of
+   * the scroller.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  totals?: boolean;
+  /**
+   * Rows kept in view outside sort, search, filters, paging and the virtual window: `top`
+   * rows sit under the header (stuck there with `stickyHeader`), `bottom` rows above the
+   * totals. Rendered with the same columns as the body.
+   */
+  pinnedRows?: {
+    top?: Row[];
+    bottom?: Row[];
+  };
+  /**
+   * Bands of columns under a shared header, rendered as a row above the column headers.
+   * A band's columns should be adjacent; reordering them apart splits the band.
+   */
+  columnGroups?: ColumnGroup[];
+  /**
+   * An "Export CSV" button in the toolbar: every row passing the search and filters (all
+   * pages; with `server`, the rows given), in the current sort, visible columns as headers,
+   * raw cell values as fields (RFC 4180, UTF-8 with BOM). Pass `{ filename }` to name the
+   * file; it defaults to the `title`.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  exportable?: boolean | {
+    filename?: string;
+  };
   /**
    * Row height preset.
    *
@@ -1941,17 +2273,16 @@ interface DataTableProps<Row> {
    */
   virtualized?: boolean;
   /**
-   * Fixed row height in px, used to compute the virtualized window.
+   * Row height in px for the virtualized window.
    *
-   * @defaultValue `40`
-   * @see the component manifest
+   * Measured from the first rendered row when omitted, so the density presets stay correct
+   * — the old fixed default of 40 never matched them (rows are 36/48/60 px plus a border),
+   * and a wrong value scales the whole scrollbar. Set it only for custom-sized rows.
    */
   rowHeight?: number;
   /**
-   * Number of rows rendered in the virtualized window.
-   *
-   * @defaultValue `20`
-   * @see the component manifest
+   * Rows rendered per window. Derived from the scroller's height when omitted; set it only
+   * to render a fixed count regardless of height.
    */
   windowSize?: number;
   /**
@@ -1975,6 +2306,26 @@ declare function DataTable<Row>({
   selection,
   batchActions,
   renderExpandedRow,
+  filters,
+  defaultFilters,
+  onFiltersChange,
+  noResultsState,
+  toolbar,
+  rowActions,
+  columnState,
+  defaultColumnState,
+  onColumnStateChange,
+  columnSettings,
+  server,
+  multiSort,
+  stateKey,
+  keyboardNavigation,
+  onCellEdit,
+  groupBy,
+  totals,
+  pinnedRows,
+  columnGroups,
+  exportable,
   density,
   zebra,
   stickyHeader,
@@ -2050,6 +2401,12 @@ interface CommandMenuProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   groups: CommandGroup[];
+  /**
+   * Placeholder text shown when the field is empty.
+   *
+   * @defaultValue `Type a command or search…`
+   * @see the component manifest
+   */
   placeholder?: string;
   /**
    * Text shown when no commands match the query.
@@ -2196,22 +2553,49 @@ declare function Form<T extends Record<string, unknown>>({
   className,
   ...props
 }: FormProps<T>): import("react").JSX.Element;
+/**
+ * Option filtering, grouping and match highlighting for `Combobox`, kept pure so the list
+ * pipeline is testable without a DOM and runs once per query change rather than per render.
+ *
+ * Matching folds diacritics: a user typing `zurich` expects `Zürich`, and a filtered option
+ * list is exactly where that gap bites, because the user cannot see why their query returns
+ * nothing. Folding is done per code point so the folded string stays index-aligned with the
+ * original — that alignment is what lets `highlightSegments` mark the match on the label the
+ * user actually reads rather than on a normalised copy of it.
+ *
+ * `MultiSelect` carries the same four operations against its own option type. They are
+ * deliberately not shared: a registry component is copied into an adopter's project as a
+ * self-contained folder, so a cross-component import would make `cascivo add combobox`
+ * drag in a sibling component's files. The catalog already accepts this for the menu /
+ * context-menu navigation pair.
+ */
+/** One selectable option. A list mixing grouped and ungrouped options renders the ungrouped ones first. */
 interface ComboboxOption {
-  value: string;
   label: string;
+  value: string;
   /**
-   * When true, disables the control and removes it from the tab order.
+   * When true, the option cannot be selected and is skipped by keyboard navigation.
    *
    * @defaultValue `false`
    * @see the component manifest
    */
   disabled?: boolean;
+  /** Optional group heading this option belongs to. */
+  group?: string;
 }
 interface ComboboxLabels {
   placeholder?: string;
   empty?: string;
   clear?: string;
+  /**
+   * @deprecated Named the in-popup search input, which no longer exists — the field itself is
+   * the combobox. Ignored; removed in 2.0.
+   */
   search?: string;
+  /** Text shown in place of the empty message while `loading` is true. */
+  loading?: string;
+  /** Template for the "create" row; `{label}` is replaced with the typed text. */
+  create?: string;
 }
 interface ComboboxProps {
   /**
@@ -2240,7 +2624,9 @@ interface ComboboxProps {
    */
   clearable?: boolean;
   /**
-   * When true, shows a search/filter input.
+   * When true the field is a text input that filters the list as the user types (the APG
+   * editable combobox). When false it is a button that opens the list, and type-to-select
+   * jumps to a matching option (the APG select-only combobox).
    *
    * @defaultValue `true`
    * @see the component manifest
@@ -2260,7 +2646,49 @@ interface ComboboxProps {
   hint?: string;
   error?: string;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * When true, the list reports itself as busy and shows a loading row instead of the empty
+   * message.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  loading?: boolean;
+  /** Called with the search text on every keystroke. Pair it with `filter={() => true}` for a server-driven list. */
+  onSearchChange?: (query: string) => void;
+  /** Replaces the built-in diacritic-insensitive matcher. */
+  filter?: (option: ComboboxOption, query: string) => boolean;
+  /**
+   * When true, offers the current search text as a new option.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  creatable?: boolean;
+  /** Called with the typed label when the user picks the "create" row. */
+  onCreate?: (label: string) => void;
+  /** Submitted with a surrounding form — a hidden input carrying the selected value. */
+  name?: string;
+  /** Marks the control as required for assistive technology. */
+  required?: boolean;
+  /** Controlled open state of the listbox. */
+  open?: boolean;
+  /**
+   * The initial open state when uncontrolled.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  defaultOpen?: boolean;
+  /** Called when the listbox opens or closes. */
+  onOpenChange?: (open: boolean) => void;
   labels?: ComboboxLabels;
   className?: string;
   id?: string;
@@ -2278,6 +2706,16 @@ declare function Combobox({
   error,
   size,
   disabled,
+  loading,
+  onSearchChange,
+  filter,
+  creatable,
+  onCreate,
+  name,
+  required,
+  open,
+  defaultOpen,
+  onOpenChange,
   labels,
   className,
   id,
@@ -2290,6 +2728,8 @@ interface DatePickerLabels {
   previousMonth?: string;
   nextMonth?: string;
   clear?: string;
+  open?: string;
+  today?: string;
 }
 interface DatePickerProps {
   /**
@@ -2311,6 +2751,8 @@ interface DatePickerProps {
   onValueChange?: (value: string | undefined) => void;
   min?: string;
   max?: string;
+  /** Rejects individual dates the bounds allow — holidays, weekends, taken slots. */
+  disabledDate?: (date: Date) => boolean;
   /**
    * Shows a clear button
    *
@@ -2345,6 +2787,30 @@ interface DatePickerProps {
    * @see the component manifest
    */
   disabled?: boolean;
+  /**
+   * When true, the field accepts a typed date as well as one picked from the calendar.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
+  typeable?: boolean;
+  /** Formatting options for the displayed date. Defaults to the locale's numeric form. */
+  format?: Intl.DateTimeFormatOptions;
+  /**
+   * When true, the calendar offers a button that jumps to the current month.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  showToday?: boolean;
+  /** Submitted with a surrounding form — a hidden input carrying the ISO value. */
+  name?: string;
+  /** Marks the control as required for assistive technology. */
+  required?: boolean;
+  /** Controlled open state of the calendar popup. */
+  open?: boolean;
+  /** Called when the popup opens or closes. */
+  onOpenChange?: (open: boolean) => void;
   labels?: DatePickerLabels;
   className?: string;
   id?: string;
@@ -2355,6 +2821,7 @@ declare function DatePicker({
   onValueChange,
   min,
   max,
+  disabledDate,
   clearable,
   label,
   ariaLabel,
@@ -2362,6 +2829,13 @@ declare function DatePicker({
   error,
   size,
   disabled,
+  typeable,
+  format,
+  showToday,
+  name,
+  required,
+  open,
+  onOpenChange,
   labels,
   className,
   id,
@@ -2793,16 +3267,29 @@ interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
  * incomplete, which is why the rule is a guard and not a checklist.
  */
 declare const PasswordInput: import("react").ForwardRefExoticComponent<PasswordInputProps & import("react").RefAttributes<HTMLInputElement>>;
+/**
+ * Option filtering, grouping and match highlighting, kept pure so the list pipeline is
+ * testable without a DOM and runs once per query change rather than per render.
+ *
+ * Matching folds diacritics because a German user typing `zurich` expects `Zürich`, and an
+ * option list is exactly where that gap bites: the user cannot see why their query returns
+ * nothing. Folding is done per code point so the folded string stays index-aligned with the
+ * original — that alignment is what lets `highlightSegments` mark the match on the label the
+ * user actually reads rather than on a normalised copy of it.
+ */
+/** One selectable option. `group` is optional; a list mixing grouped and ungrouped options renders the ungrouped ones first. */
 interface MultiSelectOption {
   label: string;
   value: string;
   /**
-   * When true, disables the control and removes it from the tab order.
+   * When true, the option cannot be selected and is skipped by keyboard navigation.
    *
    * @defaultValue `false`
    * @see the component manifest
    */
   disabled?: boolean;
+  /** Optional group heading this option belongs to. */
+  group?: string;
 }
 interface MultiSelectLabels {
   label?: string;
@@ -2810,23 +3297,155 @@ interface MultiSelectLabels {
   selected?: (count: number) => string;
   search?: string;
   noResults?: string;
+  /** Text shown in place of the no-results message while `loading` is true. */
+  loading?: string;
+  clear?: string;
+  remove?: string;
+  /** Text on the select-all row while nothing is selected. */
+  selectAll?: string;
+  clearAll?: string;
+  create?: string;
 }
-interface MultiSelectProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+interface MultiSelectProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  /**
+   * Wired automatically by a wrapping `Field` — its label id. Forwarded to the focusable
+   * control so the Field's label names it.
+   */
+  'aria-labelledby'?: string;
+  /**
+   * Wired automatically by a wrapping `Field` — the ids of its hint/error text. **Merged**
+   * with this component's own `hint`/`error` ids rather than replacing them, so both are
+   * announced.
+   */
+  'aria-describedby'?: string;
+  /** Wired automatically by a wrapping `Field` when it is in an error state. */
+  'aria-invalid'?: boolean;
   options: MultiSelectOption[];
-  value: string[];
-  onValueChange: (v: string[]) => void;
+  /** The controlled value. Omit it and pass `defaultValue` to let the component own the selection. */
+  value?: string[];
+  /**
+   * The initial value when uncontrolled.
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
+  defaultValue?: string[];
+  /** Called with the new value when it changes. */
+  onValueChange?: (value: string[]) => void;
   placeholder?: string;
+  /** Visible field label. */
+  label?: string;
+  /**
+   * Invisible accessible name, for when a visible element outside this component already
+   * labels it and `label` would render that text a second time.
+   *
+   * `label` on this component is **visible**. `IconButton.label` and `Sparkline.label` are
+   * invisible names, so an adopter arriving with that prior writes `label` here and gets the
+   * text twice (2026-08-22 report item 13). Both props are listed side by side, each saying
+   * which it is.
+   */
+  ariaLabel?: string;
+  hint?: string;
+  error?: string;
+  /**
+   * How the trigger summarises the selection: a count, or one removable chip per value.
+   *
+   * @defaultValue `'count'`
+   * @see the component manifest
+   */
+  display?: 'count' | 'chips';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * When true, shows a control that clears every selected value.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  clearable?: boolean;
+  /**
+   * When true, shows a row that selects or clears every enabled option at once.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  selectAll?: boolean;
+  /** Maximum number of values that may be selected. Further options become unselectable once reached. */
+  max?: number;
+  /**
+   * When true, offers the current search text as a new option.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  creatable?: boolean;
+  /** Called with the typed label when the user picks the "create" row. */
+  onCreate?: (label: string) => void;
+  /**
+   * When true, the list reports itself as busy and shows a loading row instead of the
+   * no-results message.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  loading?: boolean;
+  /** Called with the search text on every keystroke. Pair it with `filter={() => true}` for a server-driven list. */
+  onSearchChange?: (query: string) => void;
+  /** Replaces the built-in diacritic-insensitive matcher. */
+  filter?: (option: MultiSelectOption, query: string) => boolean;
+  /**
+   * When true, shows the search field. The list is keyboard-navigable either way.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
+  searchable?: boolean;
+  /**
+   * Field height.
+   *
+   * @defaultValue `'md'`
+   * @see the component manifest
+   */
+  size?: 'sm' | 'md' | 'lg';
+  /** Submitted with a surrounding form — one hidden input per selected value. */
+  name?: string;
   labels?: MultiSelectLabels;
+  id?: string;
 }
 declare function MultiSelect({
   options,
   value,
+  defaultValue,
   onValueChange,
   placeholder,
+  label,
+  ariaLabel,
+  hint,
+  error,
+  display,
   disabled,
+  clearable,
+  selectAll,
+  max,
+  creatable,
+  onCreate,
+  loading,
+  onSearchChange,
+  filter,
+  searchable,
+  size,
+  name,
   labels,
   className,
+  id,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
   ...props
 }: MultiSelectProps): import("react").JSX.Element;
 interface TagsInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
@@ -2925,6 +3544,12 @@ interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'on
   value: string;
   onValueChange: (v: string) => void;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 declare function SegmentedControl({
@@ -3042,9 +3667,11 @@ declare function Editable({
   onCancel,
   className,
   id,
+  'aria-label': ariaLabel,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   'aria-invalid': ariaInvalid,
+  tabIndex,
   ...props
 }: EditableProps): import("react").JSX.Element;
 interface RadioCardGroupProps {
@@ -4008,6 +4635,12 @@ interface ToggleGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChang
    */
   orientation?: 'horizontal' | 'vertical';
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 declare const ToggleGroup: import("react").ForwardRefExoticComponent<ToggleGroupProps & import("react").RefAttributes<HTMLDivElement>>;
@@ -4167,6 +4800,12 @@ interface MenuButtonProps {
   items: MenuButtonItem[];
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Disables the trigger
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   align?: 'start' | 'end';
   labels?: {
@@ -4294,13 +4933,34 @@ interface TreeNode {
   label: ReactNode;
   icon?: ReactNode;
   children?: TreeNode[];
+  /**
+   * When true, the node cannot be selected and is skipped by keyboard navigation and
+   * type-to-select.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  disabled?: boolean;
+  /**
+   * Plain-text form of `label`, for type-to-select when the label is JSX.
+   *
+   * Typeahead matched `typeof label === 'string'`, so it silently did nothing for any node
+   * rendering an icon beside its text — the common case.
+   */
+  textValue?: string;
 }
 interface TreeViewProps {
   items: TreeNode[];
   selectionMode?: 'single' | 'multi';
   selected?: string | string[];
   defaultSelected?: string | string[];
+  /**
+   * @deprecated Use `onValueChange`. The catalog names a value-carrying handler
+   * `onValueChange`; `onSelectChange` appears on this component alone. Still honoured.
+   */
   onSelectChange?: (selected: string | string[]) => void;
+  /** Called with the new selection. */
+  onValueChange?: (selected: string | string[]) => void;
   expanded?: string[];
   defaultExpanded?: string[];
   onExpandedChange?: (expanded: string[]) => void;
@@ -4326,6 +4986,7 @@ declare function TreeView({
   selected,
   defaultSelected,
   onSelectChange,
+  onValueChange,
   expanded,
   defaultExpanded,
   onExpandedChange,
@@ -4554,6 +5215,8 @@ declare function ItemActions({
 interface CalendarLabels {
   previousMonth?: string;
   nextMonth?: string;
+  today?: string;
+  weekNumber?: string;
 }
 interface CalendarProps {
   value?: Date | null;
@@ -4572,6 +5235,15 @@ interface CalendarProps {
   size?: 'sm' | 'md' | 'lg';
   labels?: CalendarLabels;
   className?: string;
+  /**
+   * Accessible name for the grid. Defaults to the visible month label.
+   *
+   * Calendar has no visible label slot — the month heading is its own — so `label` and
+   * `ariaLabel` are aliases for the same invisible name. `ariaLabel` wins if both are given.
+   */
+  ariaLabel?: string;
+  /** Alias for `ariaLabel`. See the note there. */
+  label?: string;
   /** Highlight predicate for range previews (date-range-picker). */
   isInRange?: (date: Date) => boolean;
   /** Range endpoint markers for styling. */
@@ -4595,6 +5267,20 @@ interface CalendarProps {
    * @see the component manifest
    */
   hideNav?: boolean;
+  /**
+   * When true, shows a button that jumps the view to the current month and focuses today.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  showToday?: boolean;
+  /**
+   * When true, prefixes each row with its ISO-8601 week number.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  showWeekNumbers?: boolean;
 }
 declare function Calendar({
   value,
@@ -4607,6 +5293,8 @@ declare function Calendar({
   size,
   labels,
   className,
+  ariaLabel,
+  label,
   isInRange,
   isRangeStart,
   isRangeEnd,
@@ -4614,7 +5302,9 @@ declare function Calendar({
   month,
   year,
   onViewChange,
-  hideNav
+  hideNav,
+  showToday,
+  showWeekNumbers
 }: CalendarProps): import("react").JSX.Element;
 interface DateRange {
   start: Date;
@@ -4675,17 +5365,18 @@ declare function DateRangePicker({
   labels,
   className
 }: DateRangePickerProps): import("react").JSX.Element;
+/** The output formats an adopter can ask for. */
+type ColorFormat = 'hex' | 'rgb' | 'hsl';
 interface ColorPickerLabels {
   hue?: string;
-  /**
-   * When true, enables alpha (opacity) selection.
-   *
-   * @defaultValue `true`
-   * @see the component manifest
-   */
+  /** Accessible name for the alpha slider. */
   alpha?: string;
   colorArea?: string;
+  saturation?: string;
+  brightness?: string;
   eyedropper?: string;
+  presets?: string;
+  hex?: string;
 }
 interface ColorPickerProps {
   /**
@@ -4712,7 +5403,21 @@ interface ColorPickerProps {
   defaultValue?: string;
   onValueChange?: (value: string) => void;
   presets?: string[];
+  /**
+   * When true, enables alpha (opacity) selection.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   alpha?: boolean;
+  /**
+   * Notation for the emitted value. Alpha is included whenever `alpha` is on, so the width
+   * of the emitted string is stable.
+   *
+   * @defaultValue `'hex'`
+   * @see the component manifest
+   */
+  format?: ColorFormat;
   label?: string;
   /**
    * Invisible accessible name, for when a visible element outside this component already
@@ -4731,23 +5436,27 @@ interface ColorPickerProps {
    * @see the component manifest
    */
   disabled?: boolean;
+  /** Submitted with a surrounding form — a hidden input carrying the current value. */
+  name?: string;
   size?: 'sm' | 'md' | 'lg';
   className?: string;
   labels?: ColorPickerLabels;
 }
 declare function ColorPicker({
+  id,
   value,
   defaultValue,
   onValueChange,
   presets,
   alpha,
+  format,
   label,
   ariaLabel,
   disabled,
+  name,
   size,
   className,
   labels,
-  id,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   'aria-invalid': ariaInvalid
@@ -4756,6 +5465,8 @@ interface CarouselLabels {
   region?: string;
   previous?: string;
   next?: string;
+  play?: string;
+  pause?: string;
 }
 interface CarouselProps {
   children?: ReactNode;
@@ -4776,6 +5487,14 @@ interface CarouselProps {
    * @see the component manifest
    */
   loop?: boolean;
+  /**
+   * Milliseconds between automatic advances. Omit or set 0 to leave rotation off.
+   *
+   * Auto-rotation pauses on hover, on focus within the carousel, while the tab is hidden and
+   * under `prefers-reduced-motion`, and always renders a play/pause control — APG requires
+   * one for any carousel that rotates on its own.
+   */
+  autoplay?: number;
   className?: string;
   labels?: CarouselLabels;
 }
@@ -4786,6 +5505,7 @@ declare function Carousel({
   defaultIndex,
   onIndexChange,
   loop,
+  autoplay,
   className,
   labels
 }: CarouselProps): import("react").JSX.Element;
@@ -5186,6 +5906,10 @@ interface NativeSelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>
  * A styled native `<select>` — keeps the platform's open/close, keyboard, and form behavior, and
  * layers on a custom chevron and focus/invalid rings via CSS only. No JS interactivity, so no
  * signals: the browser owns all state. Distinct from the custom-rendered `Select` listbox.
+ *
+ * Where `appearance: base-select` is supported the dropdown surface is themed from
+ * `[data-theme]` too, matching `Dropdown` — see the `@supports` block in the stylesheet. It is
+ * progressive enhancement: elsewhere the OS draws the option list, exactly as before.
  */
 /**
  * `forwardRef` so `ref` reaches the underlying `<select>` — and so it is TYPED. See
@@ -5676,12 +6400,22 @@ interface GridProps extends HTMLAttributes<HTMLDivElement> {
   align?: GridAlign;
   /** Inline-axis alignment of items within their cells (`justify-items`). Defaults to `stretch`. */
   justify?: GridAlign;
+  /**
+   * Align the internal bands of adjacent children via CSS subgrid — every CardHeader in a
+   * row shares one row track, every CardContent the next, every CardFooter the last. Where
+   * subgrid is unsupported the grid renders as it does without this prop.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  alignRows?: boolean;
 }
 declare function Grid({
   cols,
   gap,
   align,
   justify,
+  alignRows,
   className,
   style,
   children,
@@ -5856,6 +6590,7 @@ export {
   ActionSheet,
   ActionSheetAction,
   ActionSheetProps,
+  type AggregateKind,
   Alert,
   AlertDialog,
   AlertDialogLabels,
@@ -5917,15 +6652,19 @@ export {
   CodeSnippetProps,
   Collapsible,
   CollapsibleProps,
+  type ColorFormat,
   ColorPicker,
   ColorPickerLabels,
   ColorPickerProps,
   Column,
+  type ColumnGroup,
+  ColumnSettings,
+  type ColumnState,
   Columns,
   ColumnsProps,
   Combobox,
   ComboboxLabels,
-  ComboboxOption,
+  type ComboboxOption,
   ComboboxProps,
   CommandAction,
   CommandGroup,
@@ -5953,6 +6692,7 @@ export {
   DataTable,
   DataTableLabels,
   DataTableProps,
+  DataTableServer,
   DatePicker,
   DatePickerLabels,
   DatePickerProps,
@@ -6072,6 +6812,9 @@ export {
   LogViewer,
   LogViewerLabels,
   LogViewerProps,
+  Logo,
+  LogoProps,
+  LogoVariant,
   type Machine,
   type MachineConfig,
   Menu,
@@ -6093,7 +6836,7 @@ export {
   ModalProps,
   MultiSelect,
   MultiSelectLabels,
-  MultiSelectOption,
+  type MultiSelectOption,
   MultiSelectProps,
   NativeSelect,
   NativeSelectOption,
@@ -6119,6 +6862,7 @@ export {
   PasswordInput,
   PasswordInputLabels,
   PasswordInputProps,
+  type PinSide,
   Popover,
   PopoverContent,
   PopoverContentProps,
@@ -6167,6 +6911,7 @@ export {
   Resizable,
   ResizableProps,
   Responsive,
+  RowAction,
   ScrollArea,
   ScrollAreaProps,
   Search,
@@ -6209,6 +6954,7 @@ export {
   Slot,
   type SlotProps,
   SortDirection,
+  SortKey,
   SortState,
   Spacer,
   SpacerProps,
@@ -6243,6 +6989,7 @@ export {
   SwitcherEntry,
   SwitcherLink,
   SwitcherProps,
+  TableQuery,
   Tabs,
   TabsContent,
   TabsContentProps,