@toclocoinc/lattice-grid 1.18.1 → 1.20.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.18.1, type declarations
+ * Lattice Grid 1.20.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -1303,6 +1303,92 @@ export interface GridConfig {
     gap?: number;
   };
 
+  /**
+   * Present rows as a gallery of tiles (§7.12).
+   *
+   * The tiled card layout with a size-driven column count: tiles as wide as
+   * `tileWidth` allows, as many across as the container holds, laid out by the
+   * same 2-D virtualisation the grid already runs. `true` draws a tile per row
+   * generated from the columns; an object sizes them or supplies a template.
+   * Presentation only — sort, filter, group and the data pipeline are unchanged.
+   */
+  gallery?: boolean | {
+    /** The tile layout. Generated from the columns when omitted. */
+    template?: string;
+    /** How wide a tile aims to be; the count across follows the container. 240 by default. */
+    tileWidth?: number;
+    /** How tall a tile is. 180 by default. */
+    tileHeight?: number;
+    /** A fixed number of tiles on a line, instead of `tileWidth`. Does not reflow. */
+    cardsPerRow?: number;
+    /** Space between tiles, in pixels. 8 by default. */
+    gap?: number;
+    /** A class of your own on every tile, alongside the grid's. */
+    className?: string;
+    /** The layer's role. `list` by default; `listbox` for a selectable set. */
+    role?: string;
+    /** Each tile's role. `listitem` by default. */
+    itemRole?: string;
+  };
+
+  /**
+   * Present each row as a record card — a form of label/value pairs (§7.11).
+   *
+   * For a screen where reading one record matters more than comparing many.
+   * `true` draws a card per row generated from the columns, each column a
+   * labelled line in display order, showing the same text the table shows. An
+   * object supplies a template or sizes the card. A card list underneath, so it
+   * inherits the virtualisation and every interaction a card carries.
+   * Presentation only — sort, filter, group and the data pipeline are unchanged.
+   */
+  recordCard?: boolean | {
+    /** The card layout. Generated from the columns as label/value pairs when omitted. */
+    template?: string;
+    /** How tall a card is. 200 by default; a form needs room per field. */
+    cardHeight?: number;
+    /** A class of your own on every card, alongside the grid's. */
+    className?: string;
+    /** The layer's role. `list` by default. */
+    role?: string;
+    /** Each card's role. `listitem` by default. */
+    itemRole?: string;
+  };
+
+  /**
+   * Present rows as a board — a kanban of grouped lanes of cards (§7.14).
+   *
+   * The top-level group becomes a lane and every leaf under it becomes a card
+   * stacked in that lane: a pipeline by stage, a task list by status, a backlog
+   * by owner. `true` draws a card per row generated from the columns; an object
+   * sizes the lanes and cards or supplies a template. Group the grid to give the
+   * board its lanes; an ungrouped board is a single lane of every card.
+   *
+   * A card is drawn through the same code the other card presentations use, so a
+   * board card is still a row: it clicks, selects and drags through the grid's
+   * own handlers, masks protected columns, and shows the same text the table
+   * shows. Both axes are virtualised — the lanes across and the cards down each —
+   * so a board of many long lanes renders only what is on screen. Presentation
+   * only: sort, filter, group and the data pipeline are unchanged.
+   */
+  board?: boolean | {
+    /** The card layout. Generated from the columns as a tile when omitted. */
+    template?: string;
+    /** How wide a lane is, in pixels. 280 by default. */
+    laneWidth?: number;
+    /** How tall a card is, in pixels. 120 by default. */
+    cardHeight?: number;
+    /** Space between lanes, in pixels. 16 by default. */
+    laneGap?: number;
+    /** Space around a card within its lane, in pixels. 8 by default. */
+    gap?: number;
+    /** A class of your own on every card, alongside the grid's. */
+    className?: string;
+    /** The board's role. `list` by default; `listbox` for a selectable set. */
+    role?: string;
+    /** Each card's role. `listitem` by default. */
+    itemRole?: string;
+  };
+
   /**
    * Present rows as cards when the grid's container is too narrow to be a
    * table honestly, a phone, or a narrow panel on a wide screen.
@@ -1477,11 +1563,17 @@ export interface GridConfig {
   hostFilter?: { active(): boolean; passes(row: Row): boolean };
   /** Anything of yours, passed untouched to renderers, editors and sources. */
   context?: unknown;
-  /** Row count above which a column distribution is computed in a Worker. */
+  /**
+   * Row count above which eligible work is computed in a Worker: column
+   * distributions, and a portable sort (a built-in collation with no custom
+   * comparator). Below it, everything runs on the main thread.
+   */
   workerThreshold?: number;
   /**
-   * Compute column distributions off the main thread. Sorting, filtering and
-   * grouping run on the main thread; see the reference for why.
+   * Compute eligible work off the main thread: column distributions, and a
+   * portable sort above {@link GridConfig.workerThreshold} (a re-sort recomputes
+   * off-thread while the grid keeps showing the prior order, then swaps to the
+   * new one when it lands). Filtering and grouping still run on the main thread.
    */
   useWorker?: boolean;
   /** Where to load the worker kernel from, when hosting it yourself. */
@@ -1833,6 +1925,15 @@ export interface ColumnState {
   groupTotal?: TotalName | null;
   /** The grand-total override, when one differs from `total`. */
   grandTotal?: TotalName | null;
+  /**
+   * The column's runtime decoration (BACKLOG-0000723), present only when the
+   * column carries one, so a `columns.decorate()` survives a saved view and
+   * participates in undo/redo. Absent means "not recorded"; an explicit `null`
+   * on an undo patch clears a decoration back to plain text.
+   */
+  decoration?: DecorationName | DecorationSpec | null;
+  /** The variant set alongside the decoration, when one is present. */
+  variant?: VariantSpec | null;
 }
 
 export interface GridState {
@@ -2121,6 +2222,13 @@ export interface StatisticsApi {
   reduce(colId: string, fn: string): unknown;
   /** Everything worth knowing about one column, in one pass each. */
   profile(colId: string): ColumnProfile | null;
+  /**
+   * Which columns differ most between the filtered subset and the whole
+   * population it was drawn from, ranked by effect size — never by a p-value.
+   * The measure is stated per column; a numeric and a categorical column are put
+   * on one bounded scale so they rank against each other.
+   */
+  subsetVsPopulation(opts?: { columns?: string[] }): SubsetComparison;
   /** Pearson's correlation between two columns. */
   correlation(a: string, b: string): number | null;
   /** Covariance, a correlation before the scales are divided out. */
@@ -2170,6 +2278,57 @@ export interface StatisticsApi {
   keyOf(data: unknown): string | null;
   /** Which reductions can be maintained against a change, and which rescan. */
   readonly maintenance: Readonly<Record<string, 'maintained' | 'rescan'>>;
+  /**
+   * The approximate tier: kernels a sketch maintains in constant time per tick,
+   * keyed by kernel name, each carrying the sketch that backs it and the error
+   * bound that sketch is verified to meet.
+   */
+  readonly approximate: Readonly<Record<string, ApproximateEntry>>;
+  /**
+   * The honest tier for one kernel across both the exact and approximate maps:
+   * its exact tier and, when one exists, the approximate alternative and bound.
+   */
+  maintenanceTier(fn: string): MaintenanceTier;
+}
+
+/** How an approximate reduction's error bound holds, and what it measures. */
+export interface ErrorBound {
+  /** `deterministic` every run, `probabilistic` in expectation, `exact` to float rounding. */
+  kind: 'deterministic' | 'probabilistic' | 'exact';
+  /** What the number measures. `rank` is a fraction of the rank, for quantiles. */
+  metric: 'absolute' | 'relative' | 'rank' | 'none';
+  /** The bound itself, in the unit `metric` names. */
+  value: number;
+  /** A one-line human reading of the guarantee. */
+  statement: string;
+}
+
+/** One entry of the approximate maintenance tier. */
+export interface ApproximateEntry {
+  /** The sketch that backs this kernel: `HyperLogLog`, `KLL`, `SpaceSaving`. */
+  sketch: string;
+  /** The error bound the sketch is verified to meet. */
+  bound: ErrorBound;
+}
+
+/** The maintenance label for one kernel across both tiers. */
+export interface MaintenanceTier {
+  /** The kernel name. */
+  stat: string;
+  /** Its exact tier, or null when it is not an exact kernel. */
+  exact: 'maintained' | 'rescan' | null;
+  /** The approximate alternative and bound, or null when none exists. */
+  approximate: ApproximateEntry | null;
+}
+
+/** The window a windowed aggregate was computed over. */
+export interface WindowSpec {
+  /** Which window: last N ticks, last N ms, or the session. */
+  kind: 'count' | 'time' | 'session';
+  /** The size: N ticks, N ms, or the session duration in ms. */
+  span: number;
+  /** How many values actually fell inside the window. */
+  size: number;
 }
 
 export type ShadowKind =
@@ -2272,6 +2431,49 @@ export interface HistogramBin {
   count: number;
 }
 
+/** How one column differs between the filtered subset and its population. */
+export interface ColumnDifference {
+  /** The column id. */
+  column: string;
+  /** The column's display name, or its id. */
+  name: string;
+  /**
+   * The effect size reported for this column's family: the standardized mean
+   * difference for a numeric column, the total variation of the category mix for
+   * a categorical one. Never a p-value.
+   */
+  measure: 'standardizedMeanDifference' | 'categoricalTotalVariation';
+  /** The effect size in its own terms, or null when it has no scale here. */
+  magnitude: number | null;
+  /**
+   * The total variation distance between subset and population, 0 to 1 — the
+   * common scale both families reduce to, and what the ranking sorts by.
+   */
+  distance: number;
+  /** +1 when the subset sits above the population, −1 below, 0 for a mix. */
+  direction: number;
+  /** How many rows the subset comparison stood on. */
+  subsetN: number;
+  /** How many rows the population comparison stood on. */
+  populationN: number;
+  /** False when the subset is too small to read the difference from. */
+  reliable: boolean;
+}
+
+/** The subset-vs-population ranking (BACKLOG-0000653). */
+export interface SubsetComparison {
+  /** Every compared column, largest difference first. */
+  ranked: ColumnDifference[];
+  /** How many rows the filtered subset holds. */
+  subsetN: number;
+  /** How many rows the whole population holds. */
+  populationN: number;
+  /** Whether a filter is actually narrowing the set. */
+  filtered: boolean;
+  /** The measure each family reports, and the common scale, named for a legend. */
+  measures: { numeric: string; categorical: string; common: string };
+}
+
 export interface FormattingApi {
   list(scope?: FormattingScope): FormattingRule[];
   all(): Record<FormattingScope, FormattingRule[]>;
@@ -2436,10 +2638,41 @@ export interface CsvExportOptions {
   download?: boolean;
 }
 
+/** A conditional-formatting rule's rendering, returned by `cellStyle`. */
+export interface ExcelCellStyle {
+  bold?: boolean;
+  italic?: boolean;
+  /** Font colour as 6- or 8-digit hex/ARGB, e.g. 'FFFF0000'. `color` is an alias. */
+  colour?: string;
+  color?: string;
+  /** Solid fill colour as 6- or 8-digit hex/ARGB. */
+  fill?: string;
+}
+
+/** A cell border, per edge. `true` means a thin line; a string names the style. */
+export interface ExcelBorderSpec {
+  left?: boolean | string;
+  right?: boolean | string;
+  top?: boolean | string;
+  bottom?: boolean | string;
+}
+
 export interface ExcelExportOptions extends Omit<CsvExportOptions, 'delimiter' | 'quote' | 'lineEnding'> {
   sheetName?: string;
   freezePanes?: boolean;
   variantFills?: boolean;
+  /**
+   * Draw cell borders on the data grid. `false` (default) is borderless; `true`
+   * draws a thin box; a string names the line style; an object picks edges.
+   */
+  borders?: boolean | string | ExcelBorderSpec;
+  /**
+   * What to do with grid-hidden columns. `'omit'` (default) drops them;
+   * `'hidden'` keeps them as Excel-hidden columns for round-trip fidelity.
+   */
+  hiddenColumns?: 'omit' | 'hidden';
+  /** Explicit merged body ranges in A1 form, e.g. ['A3:A4']. */
+  merges?: string[];
   onProgress?: (p: { written: number; total: number }) => void;
 }