@toclocoinc/lattice-grid 1.47.0 → 1.49.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.47.0, type declarations
+ * Lattice Grid 1.49.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -1145,6 +1145,41 @@ export interface StreamSourceConfig {
    * rather than what the producer sends.
    */
   maxRows?: number;
+  /**
+   * The longest a row is kept, in milliseconds — a rolling *time* window, sitting
+   * beside `maxRows` as a second, independent bound (BACKLOG-0001036). Rows older
+   * than the span are evicted through the same path, the same `evicted` counters
+   * and the same `stream:evicted` event as the count bound, so an existing
+   * readout keeps working. Set both and whichever bites first applies. Eviction
+   * continues on a low-frequency timer while the feed is idle, so "the last five
+   * minutes" keeps shrinking through a silent period rather than freezing —
+   * which is the thing `maxRows` cannot do.
+   *
+   * Retention is a *bound, not a guillotine*: rows live a little past the span
+   * before a block is dropped. Two things add to it. First the eviction slack,
+   * ten per cent of the span, exactly as `maxRows` overshoots its count, so the
+   * row permutation is rebuilt once per block rather than once per row. Second,
+   * when the feed is idle, up to one tick of the eviction timer, which runs at a
+   * quarter of the span clamped to between 50 ms and one second. So the real
+   * ceiling is roughly `span * 1.1 + tick`, and because the tick has a floor it
+   * is proportionally larger the shorter the window: negligible at a five-minute
+   * window (about 10%), around 1.25x at ten seconds, and as much as ~1.35x at
+   * three. That is the deliberate trade for an idle grid that costs no CPU.
+   *
+   * Omit for no age limit.
+   */
+  maxAge?: number;
+  /**
+   * Which clock `maxAge` reads: a column id (or dotted path), or a function of
+   * the row returning a `Date`, epoch milliseconds, or an ISO string
+   * (BACKLOG-0001036). Given, the window follows the **data's own** clock, so it
+   * means what the producer means — and inherits the producer's clock skew.
+   * Omitted, `maxAge` falls back to **arrival time**: when the row reached this
+   * source. Arrival time needs no timestamp column and cannot be skewed, but it
+   * is not event time — a row delayed in transit counts as young. A row whose
+   * time value cannot be read is never aged out.
+   */
+  ageBy?: string | ((row: unknown) => unknown);
   promoteToMemoryBelow?: number;
   coalesceMs?: number;
 }
@@ -2072,6 +2107,15 @@ export interface GridConfig {
    */
   shortcuts?: boolean;
 
+  /**
+   * The in-grid find bar (BACKLOG-0001018): Ctrl+F / Cmd+F with focus in the
+   * grid opens it; typing highlights every matching cell in place without
+   * filtering a row away; Enter and Shift+Enter step through the matches.
+   * `false` removes the bar and its shortcut; the `grid.find` API still works.
+   * Default true.
+   */
+  find?: boolean | FindConfig;
+
   /**
    * Let a user reorder rows by dragging a handle, or with
    * Alt+Shift+Up/Down.
@@ -3815,7 +3859,7 @@ export type EventName =
   /* Selection and view */
   | 'selection:changed' | 'range:changed' | 'clipboard:copy'
   | 'page:changed' | 'scroll' | 'scroll:end' | 'size:changed'
-  | 'detail:toggled' | 'toolpanel:focus' | 'highlight:changed'
+  | 'detail:toggled' | 'toolpanel:focus' | 'highlight:changed' | 'find:changed'
   /* Tree data */
   | 'tree:loading' | 'tree:loaded' | 'tree:loadFailed' | 'tree:loadAborted'
   /* State, history and views */
@@ -4322,7 +4366,10 @@ export interface ScrollApi {
   /**
    * A row key, or a display index. A key survives a sort and is usually what a
    * caller holds; resolving one scans the display order, so prefer an index
-   * when scrolling a very large grid repeatedly.
+   * when scrolling a very large grid repeatedly. The row lands fully visible in
+   * the part of the body the pinned strips (pinned rows, sticky group
+   * headings, a bottom grand total) do not cover: `end` puts it just above the
+   * bottom strip, `start` just below the top one.
    */
   toRow(row: string | number, align?: 'start' | 'center' | 'end' | 'auto'): void;
   toColumn(id: string): void;
@@ -4960,6 +5007,106 @@ export interface HighlightApi {
   colourFor(key: string, colId: string): string | null;
 }
 
+/**
+ * The in-grid find bar's settings (BACKLOG-0001018). `find: true` or an
+ * omitted key mounts the bar with these defaults; `find: false` removes the
+ * bar and its shortcut while `grid.find` keeps working programmatically.
+ */
+export interface FindConfig {
+  /**
+   * Bind Ctrl+F (Cmd+F on a Mac) while focus is in the grid. The browser's
+   * own find is untouched while focus is anywhere else on the page. Default
+   * true.
+   */
+  shortcut?: boolean;
+  /** Milliseconds of typing quiet before the bar searches. Default 120. */
+  debounce?: number;
+}
+
+/**
+ * How `grid.find(text, opts)` matches. Defaults: case-insensitive, substring,
+ * every visible column, starting from the first row. Find matches the
+ * **formatted display text** — what the cell shows, a column `format`
+ * included — never a raw value; there is no regular-expression mode.
+ */
+export interface FindQuery {
+  /** Match letter case exactly. Default false. */
+  caseSensitive?: boolean;
+  /** The whole cell text must equal the search text rather than contain it. Default false. */
+  wholeCell?: boolean;
+  /** Search only these column ids. Omitted searches every visible column. */
+  columns?: string[] | string | null;
+  /** The display index to start from: the first match at or after it becomes current. Default 0. */
+  from?: number;
+}
+
+/** One matching cell. */
+export interface FindMatch {
+  key: string;
+  colId: string;
+  /** The display index, or -1 for a row pinned to an edge. */
+  index: number;
+  /** Which sticky strip a pinned row is in; null for a body row. */
+  pinned: 'top' | 'bottom' | null;
+}
+
+/**
+ * How many matches there are and which is current. `windowed` is the honest
+ * scope flag: over a paged pushdown source only the loaded rows are searched,
+ * so `total` counts matches in `loaded` rows out of the `rows` the source
+ * reports for the whole matching set.
+ */
+export interface FindCount {
+  /** 1-based position of the current match; 0 when there is none. */
+  current: number;
+  total: number;
+  /** False while the bar's sliced scan is still running, so a partial count is never read as final. */
+  complete: boolean;
+  windowed: boolean;
+  /** Rows the search actually read; a windowed source's not-yet-fetched placeholders are not counted. */
+  loaded: number;
+  /** The rows the source reports for the whole matching set, when it can say. */
+  rows: number;
+}
+
+/** The current query and whether the bar is showing. */
+export interface FindState {
+  text: string;
+  caseSensitive: boolean;
+  wholeCell: boolean;
+  columns: string[] | null;
+  open: boolean;
+}
+
+/**
+ * In-grid find (BACKLOG-0001018): locate text and step through where it
+ * occurs without filtering anything away. Matches are a visual overlay — no
+ * row is reordered, removed or edited — and coexist with the quick filter.
+ */
+export interface FindApi {
+  /** Search now, scanning every loaded row before returning; an empty text clears. */
+  (text: string, opts?: FindQuery): FindCount;
+  /** Show the bar with focus in its input, optionally seeding the text. */
+  open(text?: string): void;
+  /** Hide the bar and clear every match. */
+  close(): void;
+  /** Clear the query and the highlights, leaving the bar as it is. */
+  clear(): void;
+  /** The next match, wrapping from the last to the first, scrolled into view and made the active cell unless an edit is open. */
+  next(): FindMatch | null;
+  /** The previous match, wrapping from the first to the last. */
+  prev(): FindMatch | null;
+  /** Make the match at a position in `matches()` current. */
+  goTo(index: number): FindMatch | null;
+  /** Every match, in display order: pinned-top rows, then the body, then pinned-bottom rows. */
+  matches(): FindMatch[];
+  count(): FindCount;
+  current(): FindMatch | null;
+  state(): FindState;
+  /** How a cell is painted: the current match, another match, or nothing. */
+  stateFor(key: string, colId: string): 'current' | 'match' | null;
+}
+
 export interface StateApi {
   get(): GridState;
   apply(state: GridState, opts?: { skip?: (keyof GridState)[] }): StateApplyReport;
@@ -5245,6 +5392,8 @@ export interface Grid {
   readonly pagination: PaginationApi;
   /** Transient emphasis on a row, column or cell. */
   readonly highlight: HighlightApi;
+  /** In-grid find: locate text without filtering, and step through the matches. */
+  readonly find: FindApi;
   /** Values hidden from view and from export. */
   readonly redaction: RedactionApi;
   /** An image of the grid as drawn, where the module is installed. */
@@ -6124,6 +6273,19 @@ export interface ChartAxis {
   every?: number;
   /** Force the category labels' rotation rather than deciding it. */
   rotate?: boolean | 'auto';
+  /**
+   * A rolling window for the axis domain (BACKLOG-0001036), in the shipped
+   * `WindowSpec` vocabulary that rolling statistics already use. Only
+   * `{ kind: 'time', span }` applies to an axis: the domain becomes the last
+   * `span` milliseconds ending **now**, so the chart keeps scrolling left while
+   * the feed is silent — the thing a count window cannot do, because with no
+   * rows arriving nothing changes. Advanced on a low-frequency clock (a quarter
+   * of the window, between 50 ms and 1 s), never per frame, and stopped when the
+   * chart is destroyed or its document is hidden. Needs a continuous x axis
+   * carrying wall-clock times; `{ kind: 'count' }` is the source's `maxRows` and
+   * is refused here rather than given a second meaning.
+   */
+  window?: Pick<WindowSpec, 'kind' | 'span'>;
 }
 
 /**