@toclocoinc/lattice-grid 1.55.0 → 1.57.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.55.0, type declarations
+ * Lattice Grid 1.57.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -340,7 +340,8 @@ export interface Option {
   label: string;
   disabled?: boolean;
   variant?: VariantName;
-  icon?: string;
+  /** A glyph name from the icon registry (see {@link IconName}), shown before the label. */
+  icon?: IconName;
   group?: string;
 }
 
@@ -364,6 +365,32 @@ export interface LookupSpec {
 export type DecorationName = 'plain' | 'fill' | 'pill' | 'dot' | 'bar' | 'heat' | 'icon';
 export type VariantName = 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'accent' | 'none' | (string & {});
 
+/**
+ * A glyph name from the icon sprite registry (`packages/dom/src/cell/icons.js`).
+ *
+ * The union below is every built-in name, generated from `iconNames()` so an
+ * editor can autocomplete and typo-check them — see
+ * `test/icon-name-type-drift.test.js`, which fails if this list and the
+ * registry ever disagree. It is deliberately **not closed**: the registry is
+ * extensible at runtime via `registerIcon`, `registerIcons`, `config.icons` and
+ * `grid.icons`, and `(string & {})` widens the type so a custom registered name
+ * still typechecks without losing autocomplete on the built-ins. A name the
+ * registry has never heard of — built-in or custom — draws a blank glyph and
+ * warns once at runtime; it is not a type error.
+ */
+export type IconName =
+  | 'chevronRight' | 'chevronDown' | 'chevronUp' | 'chevronLeft'
+  | 'check' | 'dash' | 'close' | 'plus' | 'minus'
+  | 'info' | 'success' | 'warning' | 'danger' | 'clock' | 'lock'
+  | 'link' | 'external' | 'filter' | 'pause' | 'play' | 'chart' | 'palette'
+  | 'undo' | 'redo' | 'columns' | 'download' | 'restore' | 'spreadsheet' | 'print'
+  | 'maximise' | 'minimise' | 'views' | 'search' | 'pencil' | 'trash' | 'share'
+  | 'pin' | 'sortAsc' | 'sortDesc' | 'menu' | 'drag'
+  | 'star' | 'heart' | 'circleFilled' | 'square' | 'bolt' | 'flag'
+  | 'arrow' | 'highlight' | 'thumbUp' | 'eye' | 'eyeOff' | 'copy' | 'present'
+  | 'blank'
+  | (string & {});
+
 /** A built-in threshold icon set, mapping value bands to built-in glyphs. */
 export type IconSetName = 'trafficLights' | 'arrows' | 'trafficArrows' | 'ratings' | (string & {});
 
@@ -375,7 +402,8 @@ export type IconSetName = 'trafficLights' | 'arrows' | 'trafficArrows' | 'rating
  */
 export interface IconBand {
   min?: number;
-  icon: string;
+  /** A glyph name from the icon registry (see {@link IconName}). */
+  icon: IconName;
   label?: string;
   variant?: VariantName;
 }
@@ -387,7 +415,12 @@ export interface DecorationSpec {
   outline?: boolean;
   edge?: boolean;
   position?: 'start' | 'end';
-  name?: string | Record<string, string>;
+  /**
+   * `icon` decoration only: either a single glyph name (see {@link IconName})
+   * used for every value, or a value -> glyph name map for exact-value icons.
+   * Omit both `name` and `bands` to use `iconSet`/its default instead.
+   */
+  name?: IconName | Record<string, IconName>;
   /** icon only: a built-in threshold icon set, expanded to `bands`. */
   iconSet?: IconSetName;
   /** icon only: value bands mapped to glyphs, first match by descending `min`. */
@@ -626,7 +659,10 @@ export interface ColumnHeaderSpec {
   render?: string | RendererCtor;
   /** Props passed to `render` as `params.props`. */
   props?: Record<string, unknown>;
-  /** A class, or classes, added to the heading cell. */
+  /**
+   * A class, or classes, added to the heading cell. A string may hold several
+   * space-separated tokens (`'a b'`), each applied individually.
+   */
   class?: string | string[];
   tooltip?: string;
   align?: Align;
@@ -1354,8 +1390,9 @@ export interface DerivedSourceConfig {
    * change on the parent re-derives the whole thing. `correlation` additionally
    * scans the rows once *per pair*, so N columns cost N·(N−1)/2 passes. Use
    * `refresh` (`'idle'` is the default; `'manual'` or a debounce in ms for an
-   * expensive analysis over a live feed) — see `docs/api-detail.html` for the
-   * measured figures.
+   * expensive analysis over a live feed; under `'manual'` the host re-derives
+   * by calling `rows.load()` on the derived grid) — see `docs/api-detail.html`
+   * for the measured figures.
    *
    * Every row carries `n`, the rows the figure covered, because a derived
    * statistic travels into an export or a chart without its grid and "r = 0.98
@@ -1368,7 +1405,15 @@ export interface DerivedSourceConfig {
    */
   statistics?: DerivedStatistics;
 
-  /** When to re-derive. `idle` by default: coalesced to a frame. */
+  /**
+   * When to re-derive. `idle` by default: coalesced to a frame. A number
+   * debounces by that many milliseconds; `live` re-derives on every change.
+   * `manual` never re-derives on its own: the host triggers it by calling
+   * `rows.load()`, with no argument, on the derived grid - from a Refresh
+   * button, say. Each call re-reads `from` there and then and replaces the
+   * rows; a derived grid takes its rows from `from`, so anything passed to
+   * `load` is not used. Executed example: `docs/api-detail.html#derived-manual-refresh`.
+   */
   refresh?: 'live' | 'idle' | 'manual' | number;
 
   /**
@@ -1566,9 +1611,20 @@ export interface DetailConfig {
 }
 
 export interface SelectionConfig {
+  /** `'none'` also turns off `ranges` and `fillHandle` unless either is set explicitly alongside it. */
   mode?: 'none' | 'single' | 'multiple';
   checkbox?: boolean;
   headerCheckbox?: boolean;
+  /**
+   * Only the `checkbox` column may change row selection — a click anywhere
+   * else in the row, and Space with focus anywhere but the checkbox, leave
+   * selection untouched. Range and cell selection are unaffected either way.
+   * For a host whose row click is bound to its own action (opening a record):
+   * without this, that click also selects the row, so a later bulk action can
+   * reach rows nobody chose. Off by default. `mode: 'none'` already refuses
+   * every selection path regardless of this flag.
+   */
+  checkboxOnly?: boolean;
   groupSelectsChildren?: boolean;
   groupSelectsFiltered?: boolean;
   ranges?: boolean;
@@ -1703,8 +1759,13 @@ export interface GridConfig {
    * What identifies a row. Everything that survives a refresh (selection,
    * expansion, and edits in flight) is keyed on it, so it must be stable and
    * unique. A derived grid defaults to its own derived key.
+   *
+   * Three shapes: a field name (`'id'`, dot paths allowed); an array of field
+   * names, joined into one composite key (`['tenantId', 'circuitId']`); or a
+   * function of the row (`row => \`${row.tenantId}#${row.circuitId}\``),
+   * itself allowed to return an array to the same effect.
    */
-  rowKey?: string | ((row: unknown) => string);
+  rowKey?: string | string[] | ((row: unknown) => string | string[]);
   /** Where rows come from: memory, paged, remote, stream or derived. */
   source?: SourceConfig;
   /** How rows are ingested into the column store. */
@@ -1735,7 +1796,11 @@ export interface GridConfig {
   tree?: TreeConfig;
   /** The expandable panel beneath a row. */
   detail?: DetailConfig;
-  /** What the user may select, and how selection behaves across groups. */
+  /**
+   * What the user may select, and how selection behaves across groups.
+   * The `'none'` shorthand is `{ mode: 'none' }` and behaves identically: no
+   * row selection, and no cell ranges or fill handle either.
+   */
   selection?: SelectionConfig | 'single' | 'multiple' | 'none';
   /** Editing, and how a change is committed and validated. */
   edit?: EditConfig | boolean;
@@ -2158,7 +2223,12 @@ export interface GridConfig {
    * measured; it is about whether the ceiling applies.
    */
   autoHeight?: boolean | 'visible';
-  /** Sort, filters, grouping, widths and the rest, restored at construction. */
+  /**
+   * Sort, filters, grouping, widths and the rest, restored at construction.
+   * Takes precedence over a saved view flagged `isDefault`: when both are
+   * present, this wins outright and the default view is never applied — the
+   * active view id stays `null`.
+   */
   state?: GridState;
   /** Your licence key. Without one the grid renders in full and watermarks off localhost. */
   licence?: string;
@@ -2664,6 +2734,15 @@ export interface GridState {
   /** The banded-header tree, when the grid has one (BACKLOG-0000739). */
   columnGroups?: ColumnGroupState[];
   filters?: FilterSet;
+  /**
+   * The `where` predicates that were in force, as names only (BACKLOG-0001202).
+   * A predicate is host code: it cannot be serialised into a view or restored
+   * from one. `apply` reconciles these against what the host has registered and
+   * reports every name it cannot honour rather than restoring a view that
+   * silently shows more rows than the one that was saved. Absent when none is
+   * registered.
+   */
+  where?: string[];
   quick?: string;
   sort?: SortEntry[];
   group?: string[];
@@ -2692,6 +2771,27 @@ export interface StateApplyReport {
   skipped: { key: string; reason: string }[];
 }
 
+/**
+ * Every top-level section of a {@link GridState} bar `version` — the
+ * vocabulary `state.apply`'s `skip` list, `StateApplyReport.applied` and
+ * `StateChangedEvent.sections` all speak, derived from `GridState` itself so a
+ * new section cannot appear in one and be missing from the others.
+ */
+export type StateSection = Exclude<keyof GridState, 'version'>;
+
+/**
+ * What caused a `state:changed` (BACKLOG-0001182).
+ *
+ * `'user'` is a change to one part of the view — a sort, a filter, a column
+ * moved, resized, pinned or hidden, a grouping, a page — whether it arrived as
+ * a gesture or as the equivalent API call. `'apply'` is `state.apply()`,
+ * including the restore an undo performs and a `config.state` seed at
+ * construction. `'reset'` is `state.reset()`, and is the one a persistence
+ * layer skips: saving the reset arrangement writes the default straight back
+ * over the view the user had just abandoned.
+ */
+export type StateChangeCause = 'user' | 'apply' | 'reset';
+
 // ---------------------------------------------------------------------------
 // Conditional formatting (spec 8.12)
 // ---------------------------------------------------------------------------
@@ -4089,6 +4189,11 @@ export type EventName =
   | 'model:changed' | 'rows:changed' | 'rows:queued' | 'rows:deferred'
   | 'rows:paused' | 'rows:resumed' | 'row:received' | 'row:sent' | 'row:copied'
   | 'row:moved' | 'source:error' | 'stream:chunk' | 'stream:end' | 'stream:evicted'
+  /* The row-drag gesture as it happens (BACKLOG-0001224). Notifications only:
+   * the drop is already vetoable by `beforeRowMove` and `beforeRowReceive`, and
+   * a third veto on the same gesture would be a fourth place to look. All four
+   * fire on the grid the drag started in and carry a {@link RowDragEvent}. */
+  | 'rowDrag:started' | 'rowDrag:moved' | 'rowDrag:left' | 'rowDrag:ended'
   /* Cells and editing */
   | 'cell:changed' | 'cell:pending' | 'cell:confirmed' | 'cell:reverted' | 'cell:conflict'
   | 'cell:clicked' | 'cell:dblclicked' | 'cell:contextmenu'
@@ -4145,11 +4250,14 @@ export type EventName =
   | 'beforeEdit' | 'beforeSort' | 'beforeFilter'
   | 'beforeColumnMove' | 'beforeColumnResize' | 'beforeColumnHide'
   | 'beforeSelect' | 'beforeRowAdd' | 'beforeDelete' | 'beforeRowMove' | 'beforeGroup'
+  /* A row dropped in from another grid, on the receiving grid (BACKLOG-0001225):
+   * a {@link BeforeRowReceiveEvent}. */
+  | 'beforeRowReceive'
   /* Their cancellation notifications (past-tense, non-cancellable). */
   | 'edit:cancelled' | 'sort:cancelled' | 'filter:cancelled'
   | 'columnMove:cancelled' | 'columnResize:cancelled' | 'columnHide:cancelled'
   | 'selection:cancelled' | 'rowAdd:cancelled' | 'delete:cancelled'
-  | 'rowMove:cancelled' | 'group:cancelled'
+  | 'rowMove:cancelled' | 'group:cancelled' | 'rowReceive:cancelled'
   /* Every event at once, for logging and debugging. */
   | '*';
 
@@ -4191,6 +4299,195 @@ export interface BeforeEvent extends GridEvent {
   reason: string | null;
 }
 
+/**
+ * The `beforeRowReceive` event (BACKLOG-0001225): a row dragged from another
+ * grid is about to be inserted into this one. Fires on the **receiving** grid,
+ * before the insert, with the row under the pointer named — so a drop that
+ * means "assign this to that" can be recorded by the host and the insert
+ * stopped with `preventDefault(reason)`.
+ *
+ * A veto leaves the source grid untouched: the row stays where it was, and
+ * neither `row:sent` nor `row:copied` fires there. The source removes its row
+ * only after the target has admitted it, and a veto is a refusal to admit.
+ * The paired `rowReceive:cancelled` carries the same context plus the reason.
+ *
+ * Like every {@link BeforeEvent}, the handler may be `async`; the insert is
+ * held until it settles, and is cancelled as `'stale'` (BACKLOG-0001242) if
+ * the source row is gone by then, or if the row under the pointer is gone or
+ * has moved to a different index — `at` names a slot as "before `overKey`",
+ * and once that is no longer where `overKey`'s row sits, `at` is a stale index
+ * into a list that changed while the handler was thinking, not the slot the
+ * drop meant. `overKey: null` (the drop landed on no row) has no row to drift
+ * against and is never stale on that account.
+ */
+export interface BeforeRowReceiveEvent extends BeforeEvent {
+  /**
+   * The row about to be inserted: a shallow copy of the source row's data,
+   * and the very object that is inserted if no handler vetoes, so a change
+   * made to it here lands with the row.
+   */
+  data: Record<string, unknown>;
+  /**
+   * The display index the row would be inserted at: the index of the row
+   * under the pointer, or `rows.count()` when the drop landed on no row. When
+   * `overKey` names a row, this is guaranteed to still be that row's index at
+   * the moment the insert actually runs — an async handler that leaves the
+   * named row at a different index causes the drop to be cancelled as
+   * `'stale'` (BACKLOG-0001242) rather than inserted at this index regardless.
+   */
+  at: number;
+  /**
+   * The key of the row under the pointer when the drop happened — the row the
+   * user meant. Null when the drop landed past the last row, on empty space,
+   * on the header, or on a pinned row: there is no row to name, and a nearest
+   * guess would be wrong in a way that looks right.
+   */
+  overKey: string | null;
+  /** The grid the row is being dragged from. */
+  source: Grid;
+}
+
+/**
+ * The `rowReceive:cancelled` event (BACKLOG-0001225): a `beforeRowReceive`
+ * was vetoed, or went stale during an async handler. Nothing was inserted and
+ * the source grid is untouched.
+ */
+export interface RowReceiveCancelledEvent extends GridEvent {
+  /** The row that was not inserted, as the handler saw it. */
+  data: Record<string, unknown>;
+  /** The display index it would have taken. */
+  at: number;
+  /** The key of the row under the pointer, or null. */
+  overKey: string | null;
+  /** The grid the row would have come from; it still holds the row. */
+  source: Grid;
+  /**
+   * The reason given to `preventDefault`, `'prevented'` when none was given,
+   * or `'stale'` when the row under the pointer or the source row was gone by
+   * the time an async handler settled.
+   */
+  reason: string;
+}
+
+/**
+ * The row-drag lifecycle events (BACKLOG-0001224): `rowDrag:started`,
+ * `rowDrag:moved`, `rowDrag:left` and `rowDrag:ended`, which report a row drag
+ * *as it happens* rather than once it has settled. Before them a host got the
+ * handle the grid draws and then one settled event, with nothing in between to
+ * highlight a candidate target, drive a custom drop indicator, or react when
+ * the pointer left the grid.
+ *
+ * **All four fire on the grid the drag started in**, whether the row is being
+ * reordered within that grid or dragged into another one. A drag is one gesture
+ * with one owner, and the source grid is the only grid present for the whole of
+ * it — the pointer may cross several others, or none. `over` names whichever
+ * grid the event is about, so a single subscription can drive decoration on any
+ * of them.
+ *
+ * **Notifications, not gates.** None of these is cancellable and none carries
+ * `preventDefault`. The drop is already vetoable twice over — `beforeRowMove`
+ * for a reorder, `beforeRowReceive` for a drop into another grid — and a third
+ * veto on the same gesture would be a third place to look when a drop does not
+ * happen.
+ *
+ * **What is safe to do in a handler.** Read, measure and draw: highlight a
+ * candidate row, move an indicator, update a side panel. Do not mutate rows,
+ * columns, sort, filters or grouping from one of these. The drag resolves where
+ * it would land against the display order, so changing that order mid-gesture
+ * moves the ground under the drop; and `data` is the source row's own object
+ * rather than a copy, so writing to it edits the row that is still in the grid
+ * without announcing it. Work that changes the grid belongs in
+ * `beforeRowReceive`, which is asked before the insert, or in the settled
+ * events afterwards.
+ *
+ * **`rowDrag:moved` is coalesced to one event per animation frame**, carrying
+ * the latest pointer position of that frame, so a handler runs at the display's
+ * rate rather than the pointer's several hundred events a second. The other
+ * three fire on the transition itself.
+ *
+ * The sequence for any gesture is `rowDrag:started`, then `rowDrag:moved` and
+ * `rowDrag:left` as the pointer travels, then exactly one `rowDrag:ended` —
+ * including when the pointer is released outside every grid. No `rowDrag:moved`
+ * is delivered after `rowDrag:ended`. A press that never passes the drag
+ * threshold is a click and raises none of them; a grid destroyed mid-drag
+ * raises no `rowDrag:ended`.
+ */
+export interface RowDragEvent extends GridEvent {
+  /** The key of the row being dragged. */
+  key: string;
+  /**
+   * The dragged row's data as it stands in the source grid — that row's own
+   * object, not a copy. Null if the row has left the source during the drag.
+   */
+  data: Record<string, unknown> | null;
+  /**
+   * The grid the event is about: the grid under the pointer for
+   * `rowDrag:started`, `rowDrag:moved` and `rowDrag:ended`, and the grid just
+   * left for `rowDrag:left`. Null when the pointer is over no grid at all.
+   */
+  over: Grid | null;
+  /**
+   * Where the row would land in `over`: the display index it would take. Null
+   * when there is no candidate to report — the pointer is over no grid, over a
+   * grid that will refuse the row, or over a header; and on `rowDrag:left`,
+   * which is about a grid the pointer has already gone from.
+   */
+  at: number | null;
+  /**
+   * The key of the row under the pointer in `over`, or null where there is no
+   * row to name: past the last row, on empty space, on a header, on a pinned
+   * row, on a grid that will refuse the drop, or on `rowDrag:left`.
+   */
+  overKey: string | null;
+  /**
+   * `rowDrag:ended` only: whether the release is being acted on — a transfer
+   * the target accepts, or a same-grid reorder that is a real move and is not
+   * refused by a sort, filter or grouping. False when the row was released over
+   * no grid, over a grid that refuses it, or back where it started. What became
+   * of an acted-on drop is reported by `row:moved`, `row:sent`, `row:received`
+   * and `rowReceive:cancelled`.
+   */
+  dropped?: boolean;
+}
+
+/**
+ * The `state:changed` event (BACKLOG-0001182).
+ *
+ * Fires once per logical state change, whether it began as a user gesture or
+ * as a programmatic call, so view persistence is built on this one event
+ * rather than on the ten individual ones — `reset()` raises those too, which
+ * made a debounced save write the reset arrangement back.
+ *
+ * **Exactly one event per change.** A change that internally routes through
+ * `state.apply()` — applying a saved view, an undo, a reset — announces itself
+ * once, carrying the outermost cause rather than the inner mechanism's.
+ *
+ * A host predicate registered, replaced or removed through
+ * `filters.where(name, fn)`, and a `filters.reapply()` that re-runs one, go
+ * through the same tracked door as `sort` and `filters`: each fires this
+ * event once, `cause: 'user'`, with `'where'` in `sections` (BACKLOG-0001235).
+ */
+export interface StateChangedEvent extends GridEvent {
+  /** Why the state changed. `'reset'` is the one a save should ignore. */
+  cause: StateChangeCause;
+  /**
+   * Which sections moved, sorted and de-duplicated. For `'apply'` and
+   * `'reset'` these are the sections the report applied; for `'user'`, the
+   * sections the change touches.
+   */
+  sections: StateSection[];
+  /**
+   * The state that was applied — present for `'apply'` and `'reset'`, null for
+   * `'user'`. A full capture on every gesture would put an unsanitised copy of
+   * the state, hidden column ids and widths included, on the bus for every
+   * listener; a host calls `grid.state.get()` when it decides to write, which
+   * is permission-sanitised.
+   */
+  state: GridState | null;
+  /** What an apply could not restore; null for `'user'`. */
+  report: StateApplyReport | null;
+}
+
 export type EventHandler = (e: GridEvent) => void;
 export type Unsubscribe = () => void;
 
@@ -4489,17 +4786,84 @@ export interface CellRange {
   columns: string[];
 }
 
+/**
+ * How a `where` predicate is re-evaluated, whether `filters.clear()` may remove
+ * it, and what the source may be told about it (BACKLOG-0001202).
+ */
+export interface WhereOptions {
+  /**
+   * The columns the predicate reads, in the same spirit as `value.deps` on a
+   * computed column (§8.4.2). Declared, the verdict is cached per row and
+   * re-run only when one of these columns changes on that row. Omitted, the
+   * predicate is treated as reading the whole row and is called on every pass —
+   * never stale, and never skipped either.
+   */
+  deps?: string[];
+  /**
+   * Survive `filters.clear()`. For a predicate that is not the user's filter —
+   * row-level permissions, tenant scoping — where a "clear filters" button must
+   * never widen what the user can see.
+   */
+  pinned?: boolean;
+  /**
+   * A declarative twin of the predicate, pushed to the source while the function
+   * stays as the residual. On a pushdown engine this narrows the fetch instead
+   * of filtering a page client-side. It must be implied by the predicate: the
+   * grid ANDs both, so a twin wider than the function costs only time, while one
+   * narrower than it hides rows the function would have kept.
+   */
+  condition?: FilterSet;
+}
+
 export interface FiltersApi {
   /** The quick filter's text and match mode, for restoring a control. */
   quickState(): { text: string; mode: string };
   get(): FilterSet;
   set(filters: FilterSet): void;
+  /**
+   * Drop the condition tree, the quick filter, and every `where` predicate that
+   * was not registered `{ pinned: true }`.
+   */
   clear(): void;
   quick(text: string): void;
+  /** The names of the `where` predicates in force, in registration order. */
+  where(): string[];
+  /**
+   * Register, replace or remove a named row predicate composed with the filter
+   * set (BACKLOG-0001202).
+   *
+   * Registering *is* activating: there is no companion "a predicate is present"
+   * flag to keep in sync, which is the failure mode this replaces. Several may
+   * be in force at once under their own names, ANDed with each other and with
+   * the declarative set, and removing one leaves the rest alone. The predicate
+   * is handed the **data row**.
+   *
+   *     grid.filters.where('visibleToMe', row => row.owner === me);
+   *     grid.filters.where('rateKnown', row => rates.has(row.ccy),
+   *       { deps: ['ccy'], pinned: true });
+   *     grid.filters.where('visibleToMe', null);   // remove
+   *
+   * Only the names reach `filters.get()` and `state.get()`; the functions never
+   * do.
+   * @param name the name to register under
+   * @param predicate the predicate, or null to remove it
+   * @param opts re-evaluation, pinning, and the pushed-down twin
+   */
+  where(name: string, predicate: ((row: any) => boolean) | null, opts?: WhereOptions): void;
+  /**
+   * Re-run `where` predicates whose inputs changed where the grid could not see
+   * it — a rate table that arrived late, a permission set that refreshed. The
+   * out-of-band half of re-evaluation; `deps` is the half the grid observes for
+   * itself. Together they replace the manual "filter again" call.
+   * @param name the predicate to re-run; every one when omitted
+   * @returns whether anything was re-run
+   */
+  reapply(name?: string): boolean;
 }
 
 export interface SortApi {
   get(): SortEntry[];
+  /** Replace the sort model; an entry naming no known column is dropped with a warning. */
   set(entries: SortEntry[]): void;
   clear(): void;
 }
@@ -4743,6 +5107,11 @@ export interface SavedView {
   name: string;
   description: string;
   shared: boolean;
+  /**
+   * Applied on load when no `config.state` is given. `config.state` wins
+   * outright over this flag: with both present, the default view is never
+   * applied and the active view id stays `null`.
+   */
   isDefault: boolean;
   /** Supplied in `config.views.saved`: listed apart, and not renamable or deletable. */
   builtin: boolean;
@@ -5375,7 +5744,11 @@ export interface FindApi {
 export interface StateApi {
   get(): GridState;
   apply(state: GridState, opts?: { skip?: (keyof GridState)[] }): StateApplyReport;
-  /** The state the grid started in, captured once after `config.state`. */
+  /**
+   * The grid as configured, without `config.state` — captured once, before
+   * that seed is applied, so a view opened through `config.state` is never
+   * itself mistaken for the default `reset()` returns to.
+   */
   baseline(): GridState | null;
   /** Put the grid back the way it started, as one undoable step. */
   reset(): StateApplyReport | null;
@@ -5596,7 +5969,18 @@ export interface RailActionParams {
 export interface RailAction {
   name: string;
   title: string | (() => string);
-  icon?: string | (() => string);
+  /**
+   * A glyph name from the icon registry (see {@link IconName}) — a built-in
+   * name, or one registered with `registerIcon`/`registerIcons`,
+   * `config.icons` or `grid.icons`. A function form is re-read on every
+   * repaint, the same as `title`, so a toggle can swap its glyph with its
+   * state. When omitted, the rail tries `name` as the icon name instead (so an
+   * action named after a built-in, e.g. `'undo'`, needs no separate `icon`);
+   * an unrecognised name — from either `icon` or the `name` fallback — draws a
+   * blank glyph, and only an explicitly-given unrecognised `icon` warns once
+   * in the console.
+   */
+  icon?: IconName | (() => IconName);
   run(params: RailActionParams): void;
   enabled?(): boolean;
   /**
@@ -6357,6 +6741,28 @@ export function graphqlAdapter(options: {
 export function createGrid(element: HTMLElement, config?: GridConfig): Grid;
 export function createHeadlessGrid(config?: GridConfig): Grid;
 
+/**
+ * House-wide defaults, merged beneath every grid built afterwards.
+ *
+ * For an application with many grids that should agree on theme, density or
+ * row key. The exported factories cannot be wrapped in place — `createGrid` is
+ * exported through a getter with no setter, so assigning over it is discarded
+ * in a plain script and throws in a module — so this is the supported route.
+ *
+ * - **The per-grid config always wins.** Defaults sit *beneath* what
+ *   `createGrid`/`createHeadlessGrid` is passed; a key the grid names keeps the
+ *   grid's value, a key it omits takes the house value.
+ * - **Plain objects deep-merge; arrays and everything else replace.** A house
+ *   `views: { storage }` and a grid's `views: { local: true }` both survive;
+ *   a grid's `columns` array replaces the house one rather than extending it.
+ * - **Calling it again replaces the set, it does not accumulate.** Extend
+ *   explicitly with `defaults({ ...defaults(), density: 'compact' })`.
+ * - **Never retroactive.** Grids already built are untouched.
+ *
+ * `defaults()` reads the current set; `defaults(null)` clears it.
+ */
+export function defaults(config?: Partial<GridConfig> | null): Partial<GridConfig>;
+
 /**
  * The library version, e.g. `'1.13.1'`.
  *
@@ -6440,6 +6846,7 @@ export function version(): string;
 export const LatticeGrid: {
   createGrid: typeof createGrid;
   createHeadlessGrid: typeof createHeadlessGrid;
+  defaults: typeof defaults;
   registerModules: typeof registerModules;
   setLicence: typeof setLicence;
   version: typeof version;
@@ -7938,7 +8345,15 @@ declare module 'lattice-grid/modules/webcomponent' {
    * is disconnected.
    */
   export function defineLatticeGrid(tag?: string): void;
-  export function createLatticeGridElement(deps?: object): unknown;
+  /**
+   * Build the `<lattice-grid>` element class. The one argument is the grid
+   * factory the element creates its grid with — `createGrid`-shaped, and
+   * defaulting to it — injectable for tests. Returns the class, or `null`
+   * where `HTMLElement` is undefined (a Node import, a server-side pass).
+   */
+  export function createLatticeGridElement(
+    factory?: (element: Element, config: GridConfig) => Grid,
+  ): typeof HTMLElement | null;
   export const TAG_NAME: string;
   export const EVENT_PREFIX: string;
   export const ATTRIBUTE_CONFIG: Readonly<Record<string, unknown>>;
@@ -7960,7 +8375,14 @@ declare module 'lattice-grid/modules/htmx' {
    */
   export function createGrid(element: Element, config: GridConfig): Grid;
   export function autoInit(root?: ParentNode): Grid[];
-  export function attach(element: Element, config?: GridConfig): Grid;
+  /**
+   * Wire the htmx lifecycle events on a document: grids are built in each
+   * swapped-in fragment, released before htmx detaches one, and their view
+   * state carried across history navigation. Called once on import against
+   * the global `document`; call it again only for another document. Returns
+   * the function that removes every listener it installed.
+   */
+  export function attach(doc?: Document): () => void;
   export function initWithin(root: ParentNode): Grid[];
   export function destroyWithin(root: ParentNode): void;
   export function gridElementsWithin(root: ParentNode): Element[];
@@ -7968,9 +8390,41 @@ declare module 'lattice-grid/modules/htmx' {
   export function readTable(table: Element): { columns: Column[]; rows: unknown[] };
   export function rowsFromFragment(fragment: ParentNode): unknown[];
   export function rowsFromJson(text: string): unknown[];
-  export function ingestResponse(grid: Grid, response: unknown): void;
-  export function driveServerMode(grid: Grid, opts?: object): () => void;
-  export function driveInfiniteScroll(grid: Grid, opts?: object): () => void;
+  /**
+   * Parse a response into rows by its content type: JSON through
+   * `rowsFromJson`, anything else through `rowsFromFragment` against the
+   * columns given. The fragment arrives already parsed; this never touches
+   * `DOMParser` or `innerHTML`. Returns the rows and, when the body carried
+   * one, the total.
+   */
+  export function ingestResponse(
+    response: { contentType: string; text?: string; fragment?: ParentNode },
+    columns: { field: string }[],
+  ): { rows: unknown[]; total: number | undefined };
+  /**
+   * Drive server-side sort and filter through htmx. `trigger` is the element
+   * carrying the htmx request attributes (`hx-get`, `hx-target`,
+   * `hx-trigger="lattice:query-changed"`); the grid's query parameters are
+   * merged into that element's request and its response ingested. Returns the
+   * function that detaches everything this attached.
+   */
+  export function driveServerMode(
+    grid: Grid,
+    trigger: Element,
+    opts?: { columns?: { field: string }[] },
+  ): () => void;
+  /**
+   * Load rows in chunks as the user nears the end of what is loaded.
+   * `sentinelEl` is the element carrying `hx-get` and
+   * `hx-trigger="revealed, lattice:scroll-near-end"`; `threshold` is how many
+   * rows from the end counts as near (default 20). Returns the function that
+   * detaches everything this attached.
+   */
+  export function driveInfiniteScroll(
+    grid: Grid,
+    sentinelEl: Element,
+    opts?: { columns?: { field: string }[]; threshold?: number },
+  ): () => void;
   export function driveOobUpdates(grid: Grid, opts?: object): () => void;
   export function serialiseState(grid: Grid): string;
   export function restoreState(grid: Grid, state: string): void;
@@ -8034,7 +8488,12 @@ declare module 'lattice-grid/modules/devtools' {
     destroy(): void;
   };
   export function expose(grid: Grid, name?: string): void;
-  export const CONSOLE_ACTIVATION: string;
+  /**
+   * Whether the console entry point is compiled in. A build that replaces the
+   * activation token with `false` removes the global entirely; in every other
+   * build this is `true`.
+   */
+  export const CONSOLE_ACTIVATION: boolean;
   export default createDevtools;
 }
 
@@ -8408,8 +8867,12 @@ declare module 'lattice-grid/modules/kanban' {
     addCard?: boolean;
     /** Persist a standalone inline edit; return false or a rejected promise to revert. */
     onCardEdit?: (event: { card: KanbanCard; key: unknown; field: string; fieldPath: string; value: unknown }) => boolean | void | Promise<boolean | void>;
-    /** Create a card for a column on add-card; return the row to create (with its key), or nothing to auto-generate. */
-    onAddCard?: (columnId: string) => KanbanRow | void;
+    /**
+     * Create a card for a column on add-card; return the row to create (with
+     * its key), a Promise of that row, or nothing to auto-generate. A rejected
+     * Promise creates no card and leaves the board unchanged (BACKLOG-0001230).
+     */
+    onAddCard?: (columnId: string) => KanbanRow | Promise<KanbanRow> | void;
     /** A predicate filter over cards; only matching cards are shown. */
     filter?: (row: KanbanRow, card: KanbanCard) => boolean;
     /** Quick-filter text matched case-insensitively across card fields. */
@@ -8492,6 +8955,26 @@ declare module 'lattice-grid/modules/kanban' {
     readonly count: number;
   }
 
+  /**
+   * Named card predicates, composed with AND (BACKLOG-0001229), following the
+   * grid's `filters.where` convention (BACKLOG-0001202). Several may be
+   * registered under different names at once; each can be replaced or removed
+   * without touching the others. `setFilter(fn)` is unchanged sugar for
+   * `where(DEFAULT, fn)` / `where(DEFAULT, null)`.
+   */
+  interface KanbanFilters {
+    /** The reserved name `board.setFilter` registers/removes under. */
+    readonly DEFAULT: string;
+    /** The registered names, in registration order. */
+    where(): string[];
+    /** Register or replace the predicate under `name`. */
+    where(name: string, predicate: (row: KanbanRow, card: KanbanCard) => boolean): Kanban;
+    /** Remove whatever is registered under `name`; a no-op if nothing was. */
+    where(name: string, predicate: null): Kanban;
+    /** Re-run every named predicate (or one, by name) and re-render. */
+    reapply(name?: string): boolean;
+  }
+
   /**
    * A board instance: a kanban view of grid rows as cards grouped into columns.
    * It consumes data through the same keyed-diff `rows.apply` contract a grid
@@ -8540,9 +9023,11 @@ declare module 'lattice-grid/modules/kanban' {
     reorderLanes(order: string[]): Kanban;
     /** Move one swimlane before another (or to the end); emits `swimlane:reorder`. */
     moveLane(id: string, beforeId: string | null): Kanban;
-    /** Set a predicate filter over cards, or clear it with null. */
+    /** Named card predicates, composed with AND (BACKLOG-0001229). See {@link KanbanFilters}. */
+    filters: KanbanFilters;
+    /** Set a predicate filter over cards, or clear it with null. Sugar for `filters.where(filters.DEFAULT, fn)`. */
     setFilter(fn: ((row: KanbanRow, card: KanbanCard) => boolean) | null): Kanban;
-    /** Set the quick-filter text matched across card fields. */
+    /** Set the quick-filter text matched across card fields. Independent of every `filters.where` predicate. */
     setQuickFilter(text: string): Kanban;
     /** Distinct values of a property with card counts — the raw material for a facet control. */
     facets(property: string): { value: unknown; count: number }[];
@@ -8576,8 +9061,13 @@ declare module 'lattice-grid/modules/kanban' {
     editCard(key: unknown, name?: string): object | null;
     /** Commit an inline edit through the write-back path (grid.edit.setCells when bound); emits `card:edit`. */
     applyEdit(key: unknown, name: string, value: unknown): Promise<boolean>;
-    /** Add a card to a column and open it in inline edit; emits `card:add`. */
-    addCard(columnId: string, seed?: KanbanRow): unknown;
+    /**
+     * Add a card to a column and open it in inline edit; emits `card:add`.
+     * Returns the new key directly, or a Promise of it when `onAddCard`
+     * returns a Promise or a `beforeAdd` handler defers (BACKLOG-0001230); a
+     * rejected `onAddCard` Promise resolves this to `null` with no card added.
+     */
+    addCard(columnId: string, seed?: KanbanRow): unknown | Promise<unknown>;
     /** Serialise the restorable state: collapsed columns/lanes, order, filter, sprint/epic, selection. */
     getState(): object;
     /** Restore a state snapshot from {@link Kanban#getState}. */
@@ -8587,6 +9077,15 @@ declare module 'lattice-grid/modules/kanban' {
     /** Set (or clear with null) an error state, rendered as a host-supplied message. */
     setError(message: string | null): Kanban;
     setRows(rows: KanbanRow[]): Kanban;
+    /**
+     * Replace the board's configured column set (BACKLOG-0001228). Keeps card
+     * placement and interaction state (collapsed columns, column order, quick
+     * filter, selection) for every column id that survives; a dropped id is
+     * not specially handled — a card whose value has nowhere configured to go
+     * re-derives an ad hoc column rather than becoming `unplaced` (the same
+     * "never silently drop a card" rule an unconfigured value already gets).
+     */
+    setColumns(defs: KanbanColumnDef[]): Kanban;
     refresh(): Kanban;
     destroy(): void;
   }