twico-ui 1.11.0 → 1.12.0

package/dist/index.d.cts

@@ -205,6 +205,18 @@ type Sx = React.CSSProperties & {
   [selector: string]: React.CSSProperties[keyof React.CSSProperties] | string | number | Sx | undefined;
 };
 
+/**
+ * Props mixin for the components that accept the {@link Sx} escape hatch (#221). The sx-capable
+ * set is exactly the primitives that render a **single styleable root element**: `Box`, `Stack`,
+ * `Grid`, `Container` (layout), `Text`, `Heading` (typography), and `Card`. Multi-element
+ * composites (Input, Select, Combobox, MultiSelect, Dialog, …) intentionally omit `sx` because a
+ * single style target is ambiguous there — they would need an explicit per-slot API. See docs/sx.md.
+ */
+interface WithSx {
+  /** Style escape hatch: flat CSS goes inline (wins over the base style); nested selectors/at-rules compile to a scoped stylesheet. See {@link Sx}. */
+  sx?: Sx;
+}
+
 // ── Polymorphic component type kit ────────────────────────────────────────────
 // Powers the `as`-driven primitives (Box, Stack, Grid, Container, Text, Heading).
 // Passing `as="a"` narrows the accepted props to that element's attributes (href,
@@ -1505,6 +1517,8 @@ interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "o
   alpha?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
+  /** Control size. @default "md" */
+  size?: "sm" | "md" | "lg";
   onChange?: (hex: string) => void;
 }
 
@@ -1745,6 +1759,9 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  This prop is the initial state — when enabled, users can hide/show the column from the toolbar's
    *  **Columns** panel ("Row number"). @default false */
   rowNumbers?: boolean;
+  /** Restrict the toolbar quick-search to these column `field`s (client mode); defaults to every
+   *  visible column. Mirrors `runDatatableQuery`'s `options.searchFields`. */
+  searchFields?: string[];
   /**
    * Actions shown in the toolbar when one or more rows are selected (requires
    * `checkboxSelection`). Each handler receives the selected keys, the resolved
@@ -1919,8 +1936,12 @@ interface DatatableQuery {
 }
 
 interface DatatableColumn<T = any> {
-  /** Row object key (also the sort/filter key). */
+  /** Row object key (also the default sort/filter/search/group/export key). */
   field: string;
+  /** Derive the column's value from the whole row (nested/computed) — drives sort, filter,
+   *  quick-search, grouping, aggregation, the default cell render, and export. Falls back to
+   *  `row[field]` when omitted. Inline edits still write to the raw `field`. */
+  valueGetter?: (row: T) => unknown;
   /** Header label. @default field ("Actions" for actions columns) */
   headerName?: string;
   /** Data type. "actions" renders per-row action buttons via getActions. @default "string" */
@@ -2018,6 +2039,161 @@ declare function runDatatableQuery<T = any>(
   options?: { columns?: DatatableColumn<T>[]; searchFields?: string[] }
 ): { rows: T[]; total: number; filtered: T[] };
 
+/** A single sort clause — the field to sort on and the direction. */
+interface CardGridSort {
+  field: string;
+  dir: "asc" | "desc";
+}
+
+/** A normalized filter clause (same shape Datatable emits/consumes). */
+interface CardGridFilter {
+  field: string;
+  op: string;
+  value: unknown;
+}
+
+/** The query object emitted to `onServerChange` — identical to Datatable's server query (minus columns). */
+interface CardGridQuery {
+  page: number;
+  pageSize: number;
+  sort: CardGridSort | null;
+  filters: CardGridFilter[];
+  quickFilter: string;
+}
+
+/** An entry for the built-in sort control. */
+interface CardGridSortOption {
+  field: string;
+  label?: React.ReactNode;
+  /** Compare numerically instead of lexically. */
+  type?: "number" | "string";
+}
+
+/**
+ * Paginated card grid — the card analogue of Datatable's `serverMode`. Turns
+ * page/sort/filter/search into a query and renders one card per row via `renderCard`,
+ * with built-in pagination, loading, and empty states. In client mode it applies the
+ * query locally with Datatable's exact semantics; in `serverMode` it emits the query
+ * and consumes `{ rows, rowCount }`, so a page can toggle table/card views on one model.
+ *
+ * @startingPoint section="Data display" subtitle="Server-mode card grid" viewport="900x520"
+ */
+interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /** The rows: the full set in client mode, or the current page in `serverMode`. */
+  rows?: Row[];
+  /** Render one card for a row. Required. */
+  renderCard: (row: Row, index: number) => React.ReactNode;
+  /** Stable key per row: a field name or an accessor. @default "id" */
+  rowKey?: string | ((row: Row) => React.Key);
+  /** Min card width for the responsive auto-fill grid (Grid `minChildWidth`). @default "18rem" */
+  minChildWidth?: string | number;
+  /** Fixed column count (responsive object allowed); overrides `minChildWidth` when set. */
+  columns?: number | Record<string, number>;
+  /** Grid gap on the token scale. @default 4 */
+  gap?: number | string;
+  /** Cards per page (0 disables pagination). @default 12 */
+  pageSize?: number;
+  /** Options for the "per page" selector. @default [12, 24, 48, 96] */
+  pageSizeOptions?: number[];
+  /** Controlled 0-based page. */
+  page?: number;
+  /** Initial 0-based page when uncontrolled. @default 0 */
+  defaultPage?: number;
+  onPageChange?: (page: number) => void;
+  onPageSizeChange?: (pageSize: number) => void;
+  /** Show the "per page" selector in the footer. @default true */
+  showPageSize?: boolean;
+  /** Emit a query and consume `rows`/`rowCount`/`loading` instead of filtering locally. @default false */
+  serverMode?: boolean;
+  /** Total row count for pagination in `serverMode`. */
+  rowCount?: number;
+  /** Show the loading overlay (and dim the grid). @default false */
+  loading?: boolean;
+  /** Called (debounced) with the query whenever page/sort/filter/search changes. */
+  onServerChange?: (query: CardGridQuery) => void;
+  /** External filter clauses (e.g. from a FilterBar) applied in client mode / passed through in server mode. @default [] */
+  filters?: CardGridFilter[];
+  /** Controlled quick-search string. */
+  quickFilter?: string;
+  /** Initial quick-search string when uncontrolled. @default "" */
+  defaultQuickFilter?: string;
+  onQuickFilterChange?: (value: string) => void;
+  /** Render a built-in search box in the toolbar. @default false */
+  searchable?: boolean;
+  /** Fields scanned by quick search in client mode (defaults to the first row's keys). */
+  searchFields?: string[];
+  searchPlaceholder?: string;
+  /** Controlled sort clause. */
+  sort?: CardGridSort | null;
+  /** Initial sort clause when uncontrolled. @default null */
+  defaultSort?: CardGridSort | null;
+  onSortChange?: (sort: CardGridSort | null) => void;
+  /** Fields offered by the built-in sort control (renders it when provided). */
+  sortOptions?: CardGridSortOption[];
+  /** Extra node rendered in the toolbar row (before the sort control). */
+  toolbar?: React.ReactNode;
+  /** Shown when there are no rows and not loading. @default "No results." */
+  emptyState?: React.ReactNode;
+  /** Optional heading above the grid. */
+  label?: React.ReactNode;
+}
+
+declare function CardGrid<Row = any>(props: CardGridProps<Row>): React.JSX.Element;
+
+/** The classification of a paired row. */
+type DiffOp = "added" | "removed" | "modified" | "moved" | "unchanged";
+
+/** A column definition for DiffTable. */
+interface DiffTableColumn<Row = any> {
+  /** Row property this column reads (also its React key). */
+  field: string;
+  /** Header label; defaults to `field`. */
+  headerName?: React.ReactNode;
+  /** Custom value accessor; defaults to `row[field]`. */
+  valueGetter?: (row: Row) => unknown;
+  /** Format a value for display; defaults to `String(value)`. */
+  valueFormatter?: (value: any) => React.ReactNode;
+  /** Per-column equality override (return true when the two values are equal). */
+  compare?: (a: any, b: any) => boolean;
+}
+
+/**
+ * Row + field-level comparison of two datasets. Pairs rows from `from` and `to`
+ * on `rowKey`, classifies each **added / removed / modified / moved**, and renders
+ * modified rows as per-cell `before → after` (strikethrough old, accented new). Shows
+ * an op badge per row, a `+N ~M -K` summary, and an "only changed" toggle.
+ *
+ * @startingPoint section="Data display" subtitle="Compare two datasets" viewport="900x420"
+ */
+interface DiffTableProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /** The "before" rows (version A). */
+  from?: Row[];
+  /** The "after" rows (version B). */
+  to?: Row[];
+  /** Stable business key per row, used to pair A↔B. Defaults to `row.id`. */
+  rowKey?: (row: Row) => React.Key;
+  /** Columns to compare and render. */
+  columns?: DiffTableColumn<Row>[];
+  /** Hide unchanged rows (the toggle's initial state). @default true */
+  onlyChanged?: boolean;
+  /** Render the "only changed" toggle. @default true */
+  showToggle?: boolean;
+  /** Render the +added ~modified -removed summary badges. @default true */
+  showSummary?: boolean;
+  /** Classify same-value rows whose position changed as "moved" (minimal LIS-based set). @default true */
+  moveDetection?: boolean;
+  /** Global equality override for all fields (return true when equal). Falls back to `===` then JSON compare. */
+  compare?: (a: any, b: any, field: string) => boolean;
+  /** Shown when there are no rows to display. @default "No differences." */
+  emptyState?: React.ReactNode;
+  /** Label for the "only changed" toggle. @default "Only changed" */
+  toggleLabel?: React.ReactNode;
+  /** Optional heading above the table. */
+  label?: React.ReactNode;
+}
+
+declare function DiffTable<Row = any>(props: DiffTableProps<Row>): 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.
@@ -2042,9 +2218,13 @@ interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   min?: Date;
   /** Latest selectable date. */
   max?: Date;
+  /** Predicate to disable arbitrary dates (return true to disable). Composes with `min`/`max`. */
+  disabledDate?: (date: Date) => boolean;
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
+  /** Control size. @default "md" */
+  size?: "sm" | "md" | "lg";
   /** Show a clear (×) button when a date is set. @default true */
   clearable?: boolean;
   /** Render the trigger as a typeable text input with a trailing calendar toggle; typed text commits via `parse` on Enter/blur. @default false */
@@ -2087,8 +2267,11 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   /** Uncontrolled initial range. @default { start: null, end: null } */
   defaultValue?: DateRange;
   placeholder?: string;
-  /** Show the quick-preset column. @default true */
-  presets?: boolean;
+  /** Quick-preset column: `true` for the built-in rolling-day presets (Last 7/14/30/90), `false` to
+   *  hide it, or a custom array of `{ label, range }` where `range` is a `DateRange` or a
+   *  `() => DateRange` resolved at click time (for calendar-aligned presets like This month / YTD).
+   *  @default true */
+  presets?: boolean | Array<{ label: string; range: DateRange | (() => DateRange) }>;
   /** BCP-47 locale for month/weekday names + date formatting (Intl). Omit for the runtime default. @default undefined */
   locale?: string;
   /** First day of week: 0 = Sunday … 6 = Saturday. @default 0 */
@@ -2103,6 +2286,12 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
+  /** Control size. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Show a clear (×) button when a range is set; clicking it resets both endpoints. @default true */
+  clearable?: boolean;
+  /** Custom display formatter for the range (defaults to a localized "start – end"). With `editable`, keep it compatible with `parse` so the text round-trips. */
+  format?: (range: DateRange) => string;
   /** Render the trigger as a typeable input accepting "start – end"; typed text commits via `parse` on Enter/blur. @default false */
   editable?: boolean;
   /** Parse one side of the typed range into a Date (used when `editable`). Return a `Date` to accept, `null`/invalid to reject. Defaults to a lenient `Date.parse`. */
@@ -2112,6 +2301,267 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
 
 declare function DateRangePicker(props: DateRangePickerProps): React.JSX.Element;
 
+/**
+ * Time-of-day picker with a column-spinner popover — scrollable hour/minute
+ * (optional second) columns plus an AM/PM column in 12-hour mode. Emits a `Date`
+ * (date part from `referenceDate`/the current value, time part from the selection)
+ * so it composes with DatePicker into a DateTimePicker. Min/max bound the
+ * time-of-day; clearable value, optional typed entry, custom formatting.
+ *
+ * @startingPoint section="Inputs" subtitle="Time-of-day picker" viewport="700x120"
+ */
+interface TimePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Field label rendered above the control. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — turns the field red and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk to the label). @default false */
+  required?: boolean;
+  /** Controlled selected time as a Date (or null). */
+  value?: Date | null;
+  /** Uncontrolled initial time. @default null */
+  defaultValue?: Date | null;
+  placeholder?: string;
+  /** Earliest selectable time-of-day (only H:M:S are compared). */
+  min?: Date;
+  /** Latest selectable time-of-day (only H:M:S are compared). */
+  max?: Date;
+  /** Increment (minutes) for the minute column. @default 5 */
+  minuteStep?: number;
+  /** Increment (seconds) for the second column (when `granularity="second"`). @default 5 */
+  secondStep?: number;
+  /** Which columns show: hour only, hour+minute, or hour+minute+second. @default "minute" */
+  granularity?: "hour" | "minute" | "second";
+  /** 24-hour columns or 12-hour columns with an AM/PM column. @default 24 */
+  hourCycle?: 12 | 24;
+  /** Date whose Y/M/D is used for the emitted Date when no value is set yet. @default today */
+  referenceDate?: Date;
+  disabled?: boolean;
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: Tone;
+  /** Control size. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Show a clear (×) button when a time is set. @default true */
+  clearable?: boolean;
+  /** Render the trigger as a typeable text input with a trailing toggle; typed text commits via `parse` on Enter/blur. @default false */
+  editable?: boolean;
+  /** Parse typed text into a Date (used when `editable`). Return a `Date` to commit, `null`/invalid to revert. Defaults to an `HH:MM[:SS] [am/pm]` matcher. */
+  parse?: (text: string) => Date | null;
+  /** Custom display formatter (defaults to a localized time honoring `hourCycle`/`granularity`). */
+  format?: (date: Date) => string;
+  /** BCP-47 locale for time formatting (Intl). Omit for the runtime default. @default undefined */
+  locale?: string;
+  onChange?: (date: Date | null) => void;
+}
+
+declare function TimePicker(props: TimePickerProps): React.JSX.Element;
+
+/**
+ * Combined date + time picker over a single `Date` value. Composes DatePicker
+ * (calendar popover) and TimePicker (column spinner) side by side; picking a date
+ * keeps the current time and vice-versa. `min`/`max` bound the date; the time is free.
+ *
+ * @startingPoint section="Inputs" subtitle="Date + time picker" viewport="700x140"
+ */
+interface DateTimePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** Field label rendered above the pair. */
+  label?: React.ReactNode;
+  /** Helper text shown below when there is no error. */
+  hint?: React.ReactNode;
+  /** Error message — recolors both controls and replaces the hint. */
+  error?: React.ReactNode;
+  /** Marks the field required (adds an asterisk to the label). @default false */
+  required?: boolean;
+  /** Controlled selected date-time (or null). */
+  value?: Date | null;
+  /** Uncontrolled initial date-time. @default null */
+  defaultValue?: Date | null;
+  disabled?: boolean;
+  /** Color intent for the focus/open accent on both controls. @default "primary" */
+  tone?: Tone;
+  /** Control size for both. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Show a clear (×) button on the date control (clears the whole value). @default true */
+  clearable?: boolean;
+  /** Earliest selectable date. */
+  min?: Date;
+  /** Latest selectable date. */
+  max?: Date;
+  /** Predicate to disable arbitrary dates (return true to disable). */
+  disabledDate?: (date: Date) => boolean;
+  /** Increment (minutes) for the minute column. @default 5 */
+  minuteStep?: number;
+  /** Increment (seconds) for the second column (when `granularity="second"`). @default 5 */
+  secondStep?: number;
+  /** Time granularity: hour only, hour+minute, or hour+minute+second. @default "minute" */
+  granularity?: "hour" | "minute" | "second";
+  /** 24-hour or 12-hour (AM/PM) time columns. @default 24 */
+  hourCycle?: 12 | 24;
+  /** BCP-47 locale for names + formatting (Intl). @default undefined */
+  locale?: string;
+  /** First day of week: 0 = Sunday … 6 = Saturday. @default 0 */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** Custom formatter for the date control's display. */
+  dateFormat?: (date: Date) => string;
+  /** Custom formatter for the time control's display. */
+  timeFormat?: (date: Date) => string;
+  /** Placeholder for the date control. @default "Select date" */
+  datePlaceholder?: string;
+  /** Placeholder for the time control. @default "Time" */
+  timePlaceholder?: string;
+  onChange?: (date: Date | null) => void;
+}
+
+declare function DateTimePicker(props: DateTimePickerProps): 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.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
+  label?: React.ReactNode;
+  hint?: React.ReactNode;
+  error?: React.ReactNode;
+  required?: boolean;
+  /** Control height preset, matching Select/Combobox. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Color intent for the focus/open accent. @default "primary" */
+  tone?: Tone;
+  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[];
+  /** Called with the full array of selected values (empty array when none/cleared). */
+  onChange?: (values: string[]) => void;
+  /** Show a clear-all (×) affix when at least one value is selected. @default false */
+  clearable?: boolean;
+  disabled?: boolean;
+  /** Open the menu upward instead of down (e.g. near a viewport bottom). @default "bottom" */
+  placement?: "bottom" | "top";
+  /** Render the dropdown in a portal (position:fixed on document.body) so it is never clipped by a
+   *  scrolling/overflow-hidden ancestor; auto-flips up near the viewport bottom. Set false to render
+   *  inline. @default true */
+  portal?: boolean;
+  /** Minimum popover width in px when portaled (useful when the control is narrow). @default 0 */
+  minWidth?: number;
+  /** Show a loading row instead of the option list / empty state. @default false */
+  loading?: boolean;
+  /** Text shown when no options match. @default "No results found" */
+  emptyText?: string;
+  /** Fires with the raw typed query — drive a debounced remote fetch (pair with `loading` and
+   *  `filter={false}` so server-ranked results aren't re-filtered locally). */
+  onInputChange?: (query: string) => void;
+  /** `false` shows `options` as-is (server-ranked passthrough); a function replaces the default
+   *  label/description matcher. Omit for the built-in local filter. */
+  filter?: boolean | ((option: MultiSelectOption, query: string) => boolean);
+  /** Name for hidden form fields (one per selected value) for native form submission. */
+  name?: string;
+  /** Cap the number of selectable values; once reached, unselected options become disabled. */
+  max?: number;
+  /** Collapse chips after N into a "+K more" pill. */
+  maxTagCount?: number;
+  /** Virtualize the option list — render only the visible slice (plus `overscan`) for long lists. @default false */
+  virtualized?: boolean;
+  /** Extra option rows rendered above/below the viewport when `virtualized`, to smooth fast scrolling. @default 8 */
+  overscan?: number;
+  /** Composed with the field's open-on-focus behavior — your handler runs first. */
+  onFocus?: React.FocusEventHandler<HTMLInputElement>;
+  /** Composed with the field's keyboard navigation (Arrows/Enter/Escape/Backspace) — your handler runs first; call `event.preventDefault()` to suppress it. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+}
+
+/** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
+type MultiSelectOption = Option;
+
+/** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
+type MultiSelectGroup = OptionGroup;
+
+declare function MultiSelect(props: MultiSelectProps): React.JSX.Element;
+
+/** The kinds of filter control a field can render. */
+type FilterFieldType = "multiselect" | "daterange" | "search" | "text" | "number" | "boolean" | "select";
+
+/** A per-field value map keyed by `field`. Shape depends on the field's `type`. */
+type FilterValues = Record<string, any>;
+
+/** One field in the filter schema. */
+interface FilterField {
+  /** Data field key (also the React key and the clause `field`). */
+  field: string;
+  /** Visible label; defaults to `field`. */
+  label?: React.ReactNode;
+  /** Which control to render. */
+  type: FilterFieldType;
+  /** Options for `multiselect`/`select`. A function receives the current values for dependent/cascading options. */
+  options?: Array<string | MultiSelectOption | MultiSelectGroup | Option> | ((values: FilterValues) => any[]);
+  /** Placeholder for the control. */
+  placeholder?: React.ReactNode;
+  /** Operator emitted in the clause (overrides the per-type default, e.g. `text`→"contains", `number`→"="). */
+  op?: string;
+  /** Disable just this field. */
+  disabled?: boolean;
+  /** Enable type-to-filter for a `select` field. */
+  searchable?: boolean;
+  /** Portal the `select` popover (escape clipping ancestors). */
+  portal?: boolean;
+  /** Labels for a `boolean` field's three states. */
+  anyLabel?: React.ReactNode;
+  trueLabel?: React.ReactNode;
+  falseLabel?: React.ReactNode;
+}
+
+/** A normalized filter clause emitted to `onChange`. */
+interface FilterClause {
+  field: string;
+  op: string;
+  value: unknown;
+}
+
+/**
+ * Schema-driven faceted filter bar. Renders a row of controls from a `fields`
+ * schema (multi-select, date-range, search/text, number, boolean, select), and
+ * emits a **normalized clause list** `[{ field, op, value }]` (`isAnyOf`, `>=`/`<`,
+ * `contains`, `=`). Optional per-field clear ✕ and a "Clear all (N)" action; options
+ * can be a function of the current values for dependent/cascading facets.
+ *
+ * @startingPoint section="Inputs" subtitle="Schema-driven filter bar" viewport="900x160"
+ */
+interface FilterBarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+  /** The filter schema — one entry per facet. */
+  fields: FilterField[];
+  /** Controlled clause list (the same shape emitted by `onChange`). */
+  value?: FilterClause[];
+  /** Uncontrolled initial clause list. @default [] */
+  defaultValue?: FilterClause[];
+  /** Fires with the normalized clause list whenever any field changes. */
+  onChange?: (clauses: FilterClause[]) => void;
+  /** Also fires with the raw per-field value map (convenience for rehydrating controls). */
+  onValuesChange?: (values: FilterValues) => void;
+  /** Render a "Clear all (N)" action. @default false */
+  showClearAll?: boolean;
+  /** Label for the clear-all button. @default "Clear all" */
+  clearAllLabel?: React.ReactNode;
+  /** Show a per-field clear ✕ next to each active field's label. @default true */
+  showFieldClear?: boolean;
+  /** Control size for every field. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Accent tone forwarded to the date-range control. @default "primary" */
+  tone?: Tone;
+  /** Disable the whole bar. @default false */
+  disabled?: boolean;
+}
+
+declare function FilterBar(props: FilterBarProps): React.JSX.Element;
+
 /**
  * Modal dialog with scrim, pop-in animation, Esc-to-close, and backdrop close.
  * Render conditionally and drive with `open` + `onClose`.
@@ -2250,6 +2700,8 @@ interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   /** Allow selecting multiple files. @default false */
   multiple?: boolean;
   disabled?: boolean;
+  /** Control size — scales the dropzone padding. @default "md" */
+  size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
   /** Field label rendered above the dropzone. */
@@ -2416,71 +2868,6 @@ interface ListProps extends React.HTMLAttributes<HTMLUListElement> {
 
 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.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> {
-  label?: React.ReactNode;
-  hint?: React.ReactNode;
-  error?: React.ReactNode;
-  required?: boolean;
-  /** Control height preset, matching Select/Combobox. @default "md" */
-  size?: "sm" | "md" | "lg";
-  /** Color intent for the focus/open accent. @default "primary" */
-  tone?: Tone;
-  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[];
-  /** Called with the full array of selected values (empty array when none/cleared). */
-  onChange?: (values: string[]) => void;
-  /** Show a clear-all (×) affix when at least one value is selected. @default false */
-  clearable?: boolean;
-  disabled?: boolean;
-  /** Open the menu upward instead of down (e.g. near a viewport bottom). @default "bottom" */
-  placement?: "bottom" | "top";
-  /** Render the dropdown in a portal (position:fixed on document.body) so it is never clipped by a
-   *  scrolling/overflow-hidden ancestor; auto-flips up near the viewport bottom. Set false to render
-   *  inline. @default true */
-  portal?: boolean;
-  /** Minimum popover width in px when portaled (useful when the control is narrow). @default 0 */
-  minWidth?: number;
-  /** Show a loading row instead of the option list / empty state. @default false */
-  loading?: boolean;
-  /** Text shown when no options match. @default "No results found" */
-  emptyText?: string;
-  /** Name for hidden form fields (one per selected value) for native form submission. */
-  name?: string;
-  /** Cap the number of selectable values; once reached, unselected options become disabled. */
-  max?: number;
-  /** Collapse chips after N into a "+K more" pill. */
-  maxTagCount?: number;
-  /** Virtualize the option list — render only the visible slice (plus `overscan`) for long lists. @default false */
-  virtualized?: boolean;
-  /** Extra option rows rendered above/below the viewport when `virtualized`, to smooth fast scrolling. @default 8 */
-  overscan?: number;
-  /** Composed with the field's open-on-focus behavior — your handler runs first. */
-  onFocus?: React.FocusEventHandler<HTMLInputElement>;
-  /** Composed with the field's keyboard navigation (Arrows/Enter/Escape/Backspace) — your handler runs first; call `event.preventDefault()` to suppress it. */
-  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
-}
-
-/** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
-type MultiSelectOption = Option;
-
-/** Alias of the shared {@link OptionGroup} type (kept for backward-compatible imports). */
-type MultiSelectGroup = OptionGroup;
-
-declare function MultiSelect(props: MultiSelectProps): React.JSX.Element;
-
 interface NavbarLink {
   label: React.ReactNode;
   href?: string;
@@ -2870,6 +3257,8 @@ interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChan
   defaultValue?: number | [number, number];
   /** Force dual-thumb range mode even without a tuple value (defaults the range to [min, max]). @default false */
   range?: boolean;
+  /** Control size — scales the track, rail, and thumb. @default "md" */
+  size?: "sm" | "md" | "lg";
   /** @default 0 */
   min?: number;
   /** @default 100 */
@@ -2904,10 +3293,10 @@ declare function Slider(props: SliderProps): React.JSX.Element;
 interface SpinnerProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** @default "md" */
   size?: "sm" | "md" | "lg" | "xl";
-  /** Color. Wins over `tone` when both are set. @default "current" — inherits currentColor (visible inside buttons, themed). */
-  color?: "current" | Tone | "white";
-  /** Color. @deprecated since 1.4, removed in 2.0 — use `color`. @default "current" — inherits currentColor (visible inside buttons, themed). */
+  /** Colour intent; wins over `color` when both are set. @default "current" — inherits currentColor (visible inside buttons, themed). */
   tone?: "current" | Tone | "white";
+  /** Colour intent. @deprecated removed in 2.0 — use `tone` (matches every other tone-driven component). @default "current" */
+  color?: "current" | Tone | "white";
   /** Accessible label. @default "Loading" */
   label?: string;
 }
@@ -3424,8 +3813,18 @@ interface GridOwnProps {
   rowGap?: number | string;
   /** Column gap — falls back to `gap`. */
   columnGap?: number | string;
+  /** Aligns each cell's content on the block (row) axis → `align-items`. */
   align?: React.CSSProperties["alignItems"];
+  /**
+   * Aligns each cell's content on the inline (column) axis → `justify-items`. Prefer the
+   * explicit `justifyItems`; this stays as its backward-compatible alias.
+   *
+   * ⚠️ On **Grid** `justify` = `justify-items` (per-cell), but on **Stack** `justify` =
+   * `justify-content` (distribution). For content distribution on a Grid, use `justifyContent`.
+   */
   justify?: React.CSSProperties["justifyItems"];
+  /** Aligns each cell's content on the inline axis → `justify-items` (the explicit name for `justify`; wins over it). */
+  justifyItems?: React.CSSProperties["justifyItems"];
   /** Distribute the grid's rows within extra block space. */
   alignContent?: React.CSSProperties["alignContent"];
   /** Distribute the grid's columns within extra inline space. */
@@ -3449,7 +3848,14 @@ interface StackOwnProps {
   direction?: "row" | "column" | "row-reverse" | "column-reverse";
   /** Gap as a spacing-scale step (number) or any CSS length. @default 4 */
   gap?: number | string;
+  /** Aligns children on the cross axis → `align-items`. */
   align?: React.CSSProperties["alignItems"];
+  /**
+   * Distributes children on the main axis → `justify-content` (e.g. `"space-between"`).
+   *
+   * ⚠️ Note the divergence: on **Grid** `justify` = `justify-items` (per-cell), not
+   * `justify-content` — flex has no `justify-items`, so Stack's `justify` had to be content.
+   */
   justify?: React.CSSProperties["justifyContent"];
   /** Wrap children. @default false */
   wrap?: boolean;
@@ -3732,4 +4138,4 @@ declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
  */
 declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };