@toclocoinc/lattice-grid 1.31.1 → 1.33.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.31.1, type declarations
+ * Lattice Grid 1.33.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -5863,9 +5863,244 @@ declare module 'lattice-grid/modules/charts' {
   export function resolveScheme(spec?: object): object;
   export function schemeNames(): string[];
   export function setDefaultScheme(name: string): void;
+  /**
+   * The definition an extension chart type registers (BACKLOG-0000886). `draw`
+   * receives the base drawing context — `plot`, `bound`, `groups`, `scheme`,
+   * `typography`, `fontSize`, `labels`, `grid`, `spec`, `doc` — plus
+   * `ctx.helpers`, the base's own toolkit of primitives (element factory, scales,
+   * axes, mark pool, distribution kernels), and appends its marks to the layer
+   * groups. `bind` optionally supplies the bound data (default: the by-series
+   * binder); `freeform` lays the chart out without axis gutters; `labelled`
+   * declares that `labels` applies.
+   */
+  interface ChartTypeDefinition {
+    draw: (ctx: object) => object;
+    bind?: (grid: Grid, spec: ChartSpec) => object;
+    freeform?: boolean;
+    labelled?: boolean;
+  }
+  /**
+   * Register an extension chart type so `createChart({ type })` can draw it
+   * (BACKLOG-0000886). Extension types ship as their own opt-in modules, so the
+   * base charts bundle does not grow for a type a caller never imports — you pay
+   * only for the charts you use.
+   */
+  export function registerChartType(name: string, def: ChartTypeDefinition): void;
+  /** Every registered extension chart-type name, in registration order. */
+  export function registeredChartTypes(): string[];
   export { Chart };
 }
 
+declare module 'lattice-grid/modules/chart-ridgeline' {
+  /**
+   * The ridgeline (joy plot) extension chart type (BACKLOG-0000886). Importing
+   * this module registers `ridgeline` with the base charts module; the base
+   * bundle does not include it unless a caller imports it. Draws one
+   * kernel-density ridge per category (`x`), stacked and overlapping, over the
+   * distribution of a measure (`y`); `spec.overlap` sets the vertical overlap.
+   */
+  export function drawRidgeline(ctx: object): object;
+  export default drawRidgeline;
+}
+
+declare module 'lattice-grid/modules/chart-calendar' {
+  /**
+   * The calendar-heatmap extension chart type (BACKLOG-0000886). Importing this
+   * module registers `calendar`. Draws value-by-day as a GitHub-style grid: `x`
+   * is a date column, `y` the measure summed per day.
+   */
+  export function drawCalendar(ctx: object): object;
+  export default drawCalendar;
+}
+
+declare module 'lattice-grid/modules/chart-splom' {
+  /**
+   * The scatter-plot-matrix (SPLOM) extension chart type (BACKLOG-0000886).
+   * Importing this module registers `splom`. Crosses every pair of the numeric
+   * `columns` (2–6) as a matrix of scatters, naming each variable on the
+   * diagonal.
+   */
+  export function drawSplom(ctx: object): object;
+  /** The SPLOM binding: reads the numeric `columns` off the grid's visible rows. */
+  export function bindSplom(grid: Grid, spec: object): object;
+  export default drawSplom;
+}
+
+declare module 'lattice-grid/modules/chart-hexbin' {
+  /**
+   * The hexbin / 2D-density extension chart type (BACKLOG-0000886). Importing
+   * this module registers `hexbin`. Bins `x`/`y` points into hexagons shaded by
+   * count, so a large scatter reads as a density field rather than overplotting.
+   */
+  export function drawHexbin(ctx: object): object;
+  /** The hexbin binding: reads the numeric `x` and `y` columns off the grid's rows. */
+  export function bindHexbin(grid: Grid, spec: object): object;
+  export default drawHexbin;
+}
+
+declare module 'lattice-grid/modules/chart-roc' {
+  /**
+   * The ROC / PR / calibration extension chart type (BACKLOG-0000886). Importing
+   * this module registers `roc`. `spec.curve` chooses `'roc'` (default, with the
+   * chance diagonal and AUC), `'pr'`, or `'calibration'`; `label` is the outcome
+   * column (positive when truthy or equal to `spec.positive`), `score` the model
+   * score.
+   */
+  export function drawRoc(ctx: object): object;
+  /** The ROC binding: reads the outcome and score off the grid's rows. */
+  export function bindRoc(grid: Grid, spec: object): object;
+  export default drawRoc;
+}
+
+declare module 'lattice-grid/modules/chart-fan' {
+  /**
+   * The fan / forecast extension chart type (BACKLOG-0000886). Importing this
+   * module registers `fan`. Draws `y` (history) as a solid line, `forecast` as a
+   * dashed continuation, and the `lower`/`upper` interval as a widening band.
+   */
+  export function drawFan(ctx: object): object;
+  /** The fan binding: reads the history, forecast and interval columns in row order. */
+  export function bindFan(grid: Grid, spec: object): object;
+  export default drawFan;
+}
+
+declare module 'lattice-grid/modules/chart-decomposition' {
+  /**
+   * The seasonal-decomposition panel extension chart type (BACKLOG-0000886),
+   * companion to the `tsTrend`/`tsSeasonal`/`tsResidual` shadow columns.
+   * Importing this module registers `decomposition`. Draws a stacked panel per
+   * named component column (`observed`/`trend`/`seasonal`/`residual`) sharing one
+   * x axis.
+   */
+  export function drawDecomposition(ctx: object): object;
+  /** The decomposition binding: reads the named component columns in row order. */
+  export function bindDecomposition(grid: Grid, spec: object): object;
+  export default drawDecomposition;
+}
+
+declare module 'lattice-grid/modules/chart-slope' {
+  /**
+   * The slope-chart extension type (BACKLOG-0000886). Importing this module
+   * registers `slope`. One line per `series` connecting its `y` across the `x`
+   * periods — before/after comparison read from the slopes.
+   */
+  export function drawSlope(ctx: object): object;
+  export default drawSlope;
+}
+
+declare module 'lattice-grid/modules/chart-dumbbell' {
+  /**
+   * The dumbbell / connected-dot extension type (BACKLOG-0000886). Importing
+   * this module registers `dumbbell`. Two dots (`start`, `end`) joined by a bar
+   * per `x` category — the gap is the bar's length.
+   */
+  export function drawDumbbell(ctx: object): object;
+  /** The dumbbell binding: reads the category and its two numeric columns. */
+  export function bindDumbbell(grid: Grid, spec: object): object;
+  export default drawDumbbell;
+}
+
+declare module 'lattice-grid/modules/chart-bump' {
+  /**
+   * The bump-chart extension type (BACKLOG-0000886). Importing this module
+   * registers `bump`. One line per `series` plotted by its rank of `y` within
+   * each `x` period — rank-over-time, where crossings are the story.
+   */
+  export function drawBump(ctx: object): object;
+  export default drawBump;
+}
+
+declare module 'lattice-grid/modules/chart-diverging' {
+  /**
+   * The diverging-bar extension type (BACKLOG-0000886). Importing this module
+   * registers `diverging`. Horizontal bars growing left/right from a central
+   * zero over a signed `y`, on a symmetric scale.
+   */
+  export function drawDiverging(ctx: object): object;
+  export default drawDiverging;
+}
+
+declare module 'lattice-grid/modules/chart-parallel' {
+  /**
+   * The parallel-coordinates extension type (BACKLOG-0000886). Importing this
+   * module registers `parallel`. One polyline per row across the numeric
+   * `columns`, each a vertical axis with its own scale; `spec.colourBy` colours
+   * by a category.
+   */
+  export function drawParallel(ctx: object): object;
+  /** The parallel-coordinates binding: reads the dimension columns off the rows. */
+  export function bindParallel(grid: Grid, spec: object): object;
+  export default drawParallel;
+}
+
+declare module 'lattice-grid/modules/chart-icicle' {
+  /**
+   * The icicle extension type (BACKLOG-0000886). Importing this module registers
+   * `icicle`. A hierarchy (the grid's group tree) as nested rectangles in rows,
+   * sized by `y`; drills like the built-in hierarchical types.
+   */
+  export function drawIcicle(ctx: object): object;
+  export default drawIcicle;
+}
+
+declare module 'lattice-grid/modules/chart-waffle' {
+  /**
+   * The waffle / dot-matrix extension type (BACKLOG-0000886). Importing this
+   * module registers `waffle`. Proportion as counted squares (default 100), one
+   * colour per `x` category sized by `y`.
+   */
+  export function drawWaffle(ctx: object): object;
+  export default drawWaffle;
+}
+
+declare module 'lattice-grid/modules/chart-alluvial' {
+  /**
+   * The alluvial extension type (BACKLOG-0000886). Importing this module
+   * registers `alluvial`. Ribbons from `source` categories to `target`
+   * categories sized by `value` — categorical flow between two dimensions.
+   */
+  export function drawAlluvial(ctx: object): object;
+  /** The alluvial binding: aggregates source→target flows off the grid's rows. */
+  export function bindAlluvial(grid: Grid, spec: object): object;
+  export default drawAlluvial;
+}
+
+declare module 'lattice-grid/modules/chart-arc' {
+  /**
+   * The arc-diagram extension type (BACKLOG-0000886). Importing this module
+   * registers `arc`. Nodes on a baseline with `source`→`target` relationships as
+   * semicircular arcs, thickness by `value`.
+   */
+  export function drawArc(ctx: object): object;
+  /** The arc-diagram binding: collects nodes and edges off the grid's rows. */
+  export function bindArc(grid: Grid, spec: object): object;
+  export default drawArc;
+}
+
+declare module 'lattice-grid/modules/chart-bubblemap' {
+  /**
+   * The symbol / bubble-map extension type (BACKLOG-0000886). Importing this
+   * module registers `bubblemap`. Points placed by `lon`/`lat`, each a bubble
+   * with a square-root radius from `size`; needs no outlines and fetches nothing.
+   */
+  export function drawBubbleMap(ctx: object): object;
+  /** The bubble-map binding: reads the coordinate and size columns off the rows. */
+  export function bindBubbleMap(grid: Grid, spec: object): object;
+  export default drawBubbleMap;
+}
+
+declare module 'lattice-grid/modules/chart-hexmap' {
+  /**
+   * The hexbin-map extension type (BACKLOG-0000886). Importing this module
+   * registers `hexmap`. `lon`/`lat` points binned into hexagons shaded by count,
+   * so a geographic density reads without overplotting or outlines.
+   */
+  export function drawHexMap(ctx: object): object;
+  /** The hexbin-map binding: reads the coordinate columns off the grid's rows. */
+  export function bindHexMap(grid: Grid, spec: object): object;
+  export default drawHexMap;
+}
+
 declare module 'lattice-grid/modules/react' {
   /**
    * Build the React component.
@@ -5961,6 +6196,19 @@ declare module 'lattice-grid/modules/data-router' {
   /** A predicate: a property value (`row[key] === value`) or a `fn(row)`. */
   type RoutePredicate = unknown | ((row: RouterRecord) => boolean);
 
+  /**
+   * Per-route reshaping options (v3, BACKLOG-0000887): `transform` maps/renames/
+   * derives each row before the grid sees it; `filter` gives the grid only the
+   * rows it admits; `sort` (a comparator or `{ key, dir }`) orders what the grid
+   * receives. `rowKey` overrides the router default. All optional.
+   */
+  interface RouteOptions {
+    rowKey?: (string | ((row: RouterRecord) => unknown));
+    transform?: (row: RouterRecord) => RouterRecord;
+    filter?: (row: RouterRecord) => boolean;
+    sort?: (((a: RouterRecord, b: RouterRecord) => number) | { key: string; dir?: 'asc' | 'desc' });
+  }
+
   /**
    * A cross-grid selection relation (v2, BACKLOG-0000880): a key map (target
    * rows whose `to` value is among the selected source rows' `from` values — an
@@ -5980,10 +6228,10 @@ declare module 'lattice-grid/modules/data-router' {
    * update or remove in place by `rowKey`, preserving selection and scroll.
    */
   interface DataRouter {
-    /** Attach a grid behind a predicate; `rowKey` overrides the router default. */
-    attach(grid: unknown, predicate: RoutePredicate, opts?: { rowKey?: (string | ((row: RouterRecord) => unknown)) }): DataRouter;
+    /** Attach a grid behind a predicate; `opts` may reshape/filter/sort the route (v3). */
+    attach(grid: unknown, predicate: RoutePredicate, opts?: RouteOptions): DataRouter;
     /** Attach the "rest" sink for records no explicit route matched. */
-    attachDefault(grid: unknown, opts?: { rowKey?: (string | ((row: RouterRecord) => unknown)) }): DataRouter;
+    attachDefault(grid: unknown, opts?: RouteOptions): DataRouter;
     /** Detach a grid; the host still owns and destroys it. */
     detach(grid: unknown): DataRouter;
     /** Apply a full snapshot as a keyed diff per grid; returns per-route counts. */
@@ -6136,3 +6384,115 @@ declare module 'lattice-grid/modules/devtools' {
   export const CONSOLE_ACTIVATION: string;
   export default createDevtools;
 }
+
+declare module 'lattice-grid/modules/mock-socket' {
+  /** One record on a feed: any object. Its partition comes from a property and its identity from `rowKey`. */
+  type FeedRow = Record<string, unknown>;
+
+  /** One change in a delta batch, in the shape the data router applies. */
+  interface FeedChange { op: 'upsert' | 'delete'; row: FeedRow }
+
+  /**
+   * A message on the wire. A snapshot carries the full opening set; a delta
+   * carries the changes since. The reader parses `event.data` and switches on
+   * `kind`, exactly as against a real feed that framed its messages the same way.
+   */
+  interface FeedMessage {
+    kind: 'snapshot' | 'delta';
+    /** Present on a snapshot: the full opening set of rows. */
+    rows?: FeedRow[];
+    /** Present on a delta: the changes to apply. */
+    changes?: FeedChange[];
+  }
+
+  /** A feed: any iterator that yields a snapshot first, then deltas forever. */
+  type Feed = Iterator<FeedMessage>;
+
+  /**
+   * A serverless stand-in for a live `WebSocket`. It presents the same surface
+   * as the browser's `WebSocket` — `readyState` and the state constants,
+   * `onopen`/`onmessage`/`onclose`/`onerror`, `addEventListener`, `send` and
+   * `close` — so the code that reads it does not change when it is swapped for a
+   * real socket. It opens after a short delay, emits the feed's first value as a
+   * snapshot, then pumps one value per tick as a delta.
+   */
+  export class MockWebSocket {
+    static readonly CONNECTING: 0;
+    static readonly OPEN: 1;
+    static readonly CLOSING: 2;
+    static readonly CLOSED: 3;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    readyState: number;
+    url: string;
+    onopen: ((event: { type: string }) => void) | null;
+    onmessage: ((event: { type: string; data: string }) => void) | null;
+    onclose: ((event: { type: string; code: number; reason: string; wasClean: boolean }) => void) | null;
+    onerror: ((event: { type: string; error: unknown }) => void) | null;
+    /**
+     * @param init the feed and its timing: `feed` (snapshot first, then deltas);
+     *   `rate` ms between deltas (default 1000); `jitter` random plus-or-minus ms
+     *   per gap (default 0); `seed` for that jitter (default 1); `snapshotDelay`
+     *   ms before opening (default 60); `pauseWhenHidden` stops while the tab is
+     *   hidden (default true); `url` a cosmetic address.
+     */
+    constructor(init: {
+      feed: Feed;
+      rate?: number;
+      jitter?: number;
+      seed?: number;
+      snapshotDelay?: number;
+      pauseWhenHidden?: boolean;
+      url?: string;
+    });
+    addEventListener(type: string, fn: (event: unknown) => void): void;
+    removeEventListener(type: string, fn: (event: unknown) => void): void;
+    /** A real socket sends upstream; here it is accepted and ignored. */
+    send(data?: unknown): void;
+    /** Stop the feed until `resume()`; the socket stays open (a demo/test affordance). */
+    pause(): void;
+    /** Resume a paused feed. */
+    resume(): void;
+    /** Close the socket, stop the feed and emit a clean `close`. */
+    close(): void;
+  }
+
+  /**
+   * mulberry32: a small seeded pseudo-random generator, so a custom feed can be
+   * seeded the same way the shipped ones are. The same seed yields the same
+   * sequence of values in `[0, 1)`.
+   */
+  export function rng(seed: number): () => number;
+
+  /**
+   * A mixed operations feed — orders, shipments and incidents across three
+   * regions plus a throughput rollup — the Data Router tutorial partitions
+   * across several grids and a chart from one source. Yields a snapshot, then
+   * deltas forever. Seedable for a repeatable stream.
+   */
+  export function opsFeed(options?: {
+    seed?: number;
+    orders?: number;
+    shipments?: number;
+    incidents?: number;
+    batch?: number;
+  }): Generator<FeedMessage>;
+
+  /**
+   * A market-data feed: instruments whose prices random-walk each tick, each
+   * record carrying `type: 'price'`, `symbol`, `last`, `chg` and a bid/ask. The
+   * price/random-walk feed behind the trading-terminal tutorial. Yields a
+   * snapshot, then deltas forever. Seedable for a repeatable stream.
+   */
+  export function priceFeed(options?: {
+    seed?: number;
+    symbols?: { symbol: string; last: number }[];
+    move?: number;
+    batch?: number;
+    spread?: number;
+  }): Generator<FeedMessage>;
+
+  export default MockWebSocket;
+}