@toclocoinc/lattice-grid 1.52.0 → 1.54.0

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.52.0, type declarations
+ * Lattice Grid 1.54.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -8715,14 +8715,17 @@ declare module 'lattice-grid/modules/kpi' {
     value: unknown;
     formatted: string;
     /**
-     * The tile's semantic band, or `unknown` when the panel holds no rows at
-     * all. `unknown` is decided from data presence before any threshold is
+     * The tile's semantic band, or `unknown` when the tile measured nothing.
+     * `unknown` is decided from data presence before any threshold is
      * consulted: an aggregation over nothing returns the identity of its
      * operation (`sum` and `count` return 0), and 0 is a number a threshold
-     * grades, so without it an empty panel would report as a healthy one. A
-     * tile whose `filter` matches none of the rows the panel *does* hold has
-     * measured a real zero and is banded normally. `null` means the tile has no
-     * thresholds or bands configured.
+     * grades, so without it an empty panel would report as a healthy one.
+     *
+     * Two things make a tile `unknown`: the panel holds no rows at all, or the
+     * tile's `field` names no column on the bound grid, so it never read a cell
+     * to reduce over. A tile whose `filter` matches none of the rows the panel
+     * *does* hold is neither — it has measured a real zero and is banded
+     * normally. `null` means the tile has no thresholds or bands configured.
      */
     status: 'good' | 'warn' | 'critical' | 'unknown' | null;
     target?: number;
@@ -8746,6 +8749,14 @@ declare module 'lattice-grid/modules/kpi' {
     rows?: KPIRow[];
     grid?: unknown;
     rowKey?: string | ((row: KPIRow) => unknown);
+    /**
+     * Extra columns of the bound `grid` to project onto the rows a tile `filter`
+     * sees, beyond the fields the tiles themselves declare. A grid-bound panel
+     * hands a filter a projection, not a whole grid row, so a filter over a
+     * column no tile names would otherwise read `undefined` and report a
+     * confident zero. Ignored on a panel over a plain `rows` array.
+     */
+    fields?: string[];
     tiles?: KPITile[];
     columns?: number;
     ariaLabel?: string;
@@ -9318,3 +9329,321 @@ declare module 'lattice-grid/modules/tabs' {
   export function createTabs(el: HTMLElement, config: TabsConfig): Tabs;
   export default createTabs;
 }
+
+declare module 'lattice-grid/modules/layout' {
+  /**
+   * One window on the cell grid.
+   *
+   * Deliberately **not** named `WindowSpec`: that name is already taken by the
+   * rolling-statistics window (`{ kind: 'count'|'time'|'session', span, size }`)
+   * and reusing it would put `kind: 'session'` next to a dashboard pane.
+   */
+  interface LayoutWindow {
+    /** A stable, unique id. Required. */
+    id: string;
+    /** The 1-based column the window starts in. Auto-placed when omitted. */
+    xPos?: number;
+    /** The 1-based row the window starts in. Auto-placed when omitted. */
+    yPos?: number;
+    /** How many columns it spans (default 1). */
+    xSize?: number;
+    /** How many rows it spans (default 1). */
+    ySize?: number;
+    /** The title shown in the chrome bar, and the name every control takes. */
+    title?: string;
+    /** Whether to draw the title bar (default `true`). */
+    chrome?: boolean;
+    /** Whether to offer a close button (default `false`). */
+    closable?: boolean;
+    /** Whether the window can be moved by drag or keyboard (default `false`). */
+    movable?: boolean;
+    /** Whether the window can be resized by drag or keyboard (default `false`). */
+    resizable?: boolean;
+    /**
+     * Whether to offer a maximise control in the chrome (default `false`).
+     *
+     * Maximising fills the **layout host**, not the browser window, and hides
+     * every other window for the duration. Escape restores it, unless a payload
+     * has already claimed the key.
+     */
+    maximisable?: boolean;
+    /**
+     * Whether to offer a minimise control in the chrome (default `false`).
+     *
+     * A window with `chrome: false` cannot be minimised whatever this says:
+     * there would be nothing left on screen to restore it with.
+     */
+    minimisable?: boolean;
+    /** Padding inside the window; the layout's `padding` (default `'5px'`) otherwise. */
+    padding?: number | string;
+    /** The `id` given to the payload container (default `` `${id}-body` ``). */
+    payloadId?: string;
+    /** The window's accessible name, when the title alone is not enough context. */
+    ariaLabel?: string;
+  }
+
+  /**
+   * The three capabilities a layout-level default and `setInteractive()` cover.
+   *
+   * These are the layout **defaults**, not the per-window resolution: a window
+   * that declared `movable: false` stays pinned whatever these say.
+   *
+   * Three values, not two. `undefined` means no layout-level default is in force
+   * and each window's own flag decides; `true` unlocks everything that did not
+   * opt out; `false` is an active lock. Reporting `undefined` as `false` would
+   * read correctly and round-trip wrongly, so it is reported as it is.
+   */
+  interface LayoutInteractive {
+    movable: boolean | undefined;
+    resizable: boolean | undefined;
+    closable: boolean | undefined;
+  }
+
+  /** The plain, JSON-safe arrangement `getLayout()` returns and `setLayout()` takes. */
+  interface LayoutSnapshot {
+    columns: number;
+    rows: number;
+    windows: { id: string; xPos: number; yPos: number; xSize: number; ySize: number }[];
+  }
+
+  /** A cell placement, as carried on the move and resize events. */
+  interface LayoutPlacement {
+    xPos: number;
+    yPos: number;
+    xSize: number;
+    ySize: number;
+  }
+
+  /** The payload of `window:moved`, `beforeWindowMove`, `beforeWindowResize`. */
+  interface LayoutMoveEvent {
+    id: string;
+    from: LayoutPlacement;
+    /** Where the window was asked to go. */
+    to: LayoutPlacement;
+    /** Where it actually ended up, which under `compact: 'vertical'` may differ. */
+    landed?: LayoutPlacement;
+    origin?: 'api' | 'user' | 'init';
+    reason?: string | null;
+    /** Cancel the action (only meaningful on a `before*` event). */
+    preventDefault?: (reason?: string) => void;
+    defaultPrevented?: boolean;
+  }
+
+  /**
+   * The payload of `window:resized` — the measured **content box** of the
+   * payload container, not a cell count. Emitted when the container genuinely
+   * changes size, including on the opening frame; never with a zero box.
+   */
+  interface LayoutResizeEvent {
+    id: string;
+    payloadId: string;
+    /** The payload container itself, so a host can act on it directly. */
+    payload: HTMLElement;
+    width: number;
+    height: number;
+    xPos: number;
+    yPos: number;
+    xSize: number;
+    ySize: number;
+  }
+
+  /** The payload of `window:closed` and `beforeWindowClose`. */
+  interface LayoutCloseEvent {
+    id: string;
+    payloadId: string;
+    /** The payload container, handed back so the host can destroy what it mounted. */
+    payload?: HTMLElement;
+    origin?: 'api' | 'user';
+    reason?: string | null;
+    preventDefault?: (reason?: string) => void;
+    defaultPrevented?: boolean;
+  }
+
+  /** The payload of `layout:changed`: the whole arrangement, plus what moved it. */
+  interface LayoutChangedEvent extends LayoutSnapshot {
+    cause: string;
+  }
+
+  /** Dashboard layout configuration. */
+  interface LayoutConfig {
+    /** Cell columns across the mounted element (default 12). */
+    columns?: number;
+    /** Cell rows down the mounted element (default 6). */
+    rows?: number;
+    /** Horizontal overflow (default `'static'`). */
+    overflowX?: 'static' | 'scroll';
+    /** Vertical overflow (default `'static'`). */
+    overflowY?: 'static' | 'scroll';
+    /** Fixed column track size, used only when `overflowX` is `'scroll'` (default `'240px'`). */
+    columnWidth?: number | string;
+    /** Fixed row track size, used only when `overflowY` is `'scroll'` (default `'160px'`). */
+    rowHeight?: number | string;
+    /** The gap between cells (default `'8px'`). */
+    gap?: number | string;
+    /** The default padding inside a window (default `'5px'`). */
+    padding?: number | string;
+    /** Rearrangement (default `'vertical'`): push displaced windows down, then pull up. */
+    compact?: 'vertical' | 'none';
+    /**
+     * The default `movable` for every window that does not declare its own
+     * (default `false`). This states a default, so `false` takes nothing away
+     * from a window that declared `movable: true`; `setInteractive(false)` is
+     * the active lock that does.
+     */
+    movable?: boolean;
+    /** The default `resizable` for windows that declare none (default `false`); see `movable`. */
+    resizable?: boolean;
+    /** The default `closable` for windows that declare none (default `false`); see `movable`. */
+    closable?: boolean;
+    /**
+     * The default `maximisable` for windows that declare none (default `false`).
+     *
+     * Not touched by `setInteractive()`: a display mode neither moves nor resizes
+     * a window in the arrangement, so a locked dashboard can still be blown up
+     * to read.
+     */
+    maximisable?: boolean;
+    /** The default `minimisable` for windows that declare none (default `false`); see `maximisable`. */
+    minimisable?: boolean;
+    /** The windows, in mount order. */
+    windows?: LayoutWindow[];
+    /** An arrangement to apply at mount, as produced by `getLayout()`. */
+    layout?: LayoutSnapshot;
+    /** The layout region's accessible name. */
+    ariaLabel?: string;
+    /** A message catalogue, e.g. `grid.messages`; built-in English seeds otherwise. */
+    messages?: { t(key: string, params?: Record<string, unknown>): string };
+    onWindowMoved?: (event: LayoutMoveEvent) => void;
+    onWindowResized?: (event: LayoutResizeEvent) => void;
+    onWindowClosed?: (event: LayoutCloseEvent) => void;
+    onLayoutChanged?: (event: LayoutChangedEvent) => void;
+    onBeforeWindowMove?: (event: LayoutMoveEvent) => boolean | void | Promise<boolean>;
+    onBeforeWindowResize?: (event: LayoutMoveEvent) => boolean | void | Promise<boolean>;
+    onBeforeWindowClose?: (event: LayoutCloseEvent) => boolean | void | Promise<boolean>;
+    onWindowMoveCancelled?: (event: LayoutMoveEvent) => void;
+    onWindowResizeCancelled?: (event: LayoutMoveEvent) => void;
+    onWindowCloseCancelled?: (event: LayoutCloseEvent) => void;
+  }
+
+  /**
+   * A reconfigurable dashboard: a cell grid inside an element, and a set of
+   * windows on it that a user can move, resize and close by pointer or by
+   * keyboard (BACKLOG-0001108).
+   *
+   * The module is **payload-agnostic**: a window body is a container with an id,
+   * which this module creates and sizes and never reads. It tells a payload it
+   * was resized by emitting `window:resized`; it never calls into one, because it
+   * cannot know what one is.
+   */
+  interface Layout {
+    readonly el: HTMLElement;
+    /** The window ids, in mount order. */
+    windows(): string[];
+    /** The payload container for a window, or `null`. */
+    payload(id: string): HTMLElement | null;
+    /** A copy of one window's current descriptor, or `null`. */
+    window(id: string): LayoutWindow | null;
+    /** Add a window after mount; returns its payload container. */
+    add(spec: LayoutWindow): HTMLElement;
+    /** Move or resize a window, through the same before-events the drag uses. */
+    move(id: string, to: Partial<LayoutPlacement>): boolean | Promise<boolean>;
+    /** Close a window through `beforeWindowClose`; the payload is not destroyed. */
+    close(id: string): boolean | Promise<boolean>;
+    /**
+     * Blow one window up to fill the layout host, hiding the rest.
+     *
+     * It fills the **host element**, not the browser window, so there is no
+     * `position: fixed` (whose containing block is the nearest ancestor carrying
+     * a `transform` or a `contain`, which is why the same rule fills the screen
+     * on one page and lands in a 300px box on the next), no reparenting and
+     * nothing that can disturb the page around the dashboard.
+     *
+     * **Nothing moves**: no compaction runs, no placement changes, and the
+     * payload container is the same DOM node throughout. **Escape restores it**,
+     * from anywhere inside the layout, unless a payload has already claimed the
+     * key — a grid marks every Escape as handled, at two independent sites (a
+     * focused body cell and a focused header cell), so from inside a maximised
+     * grid the way back is the restore control. A minimised window is expanded first,
+     * and maximising a second window restores the first.
+     */
+    maximise(id: string): boolean;
+    /**
+     * Collapse one window to a single row: its payload is hidden and its chrome
+     * stays, carrying the control that brings it back.
+     *
+     * On screen it becomes one row and the windows below pull up into the space
+     * under `compact: 'vertical'`. In the arrangement nothing moves at all — the
+     * collapse is a projection of it — so `restore()` gives back exactly the
+     * arrangement that was there, in **any** order and with any number of other
+     * windows still collapsed.
+     *
+     * A window with `chrome: false` is refused, with a warning naming it.
+     */
+    minimise(id: string): boolean;
+    /** Leave whichever display mode a window is in; `false` when it was in none. */
+    restore(id: string): boolean;
+    /** The id of the window filling the host, or `null`. At most one. */
+    maximised(): string | null;
+    /** The ids of every currently minimised window, in mount order. */
+    minimised(): string[];
+    /**
+     * The full current arrangement.
+     *
+     * **A mode is not an arrangement**: this reports the *underlying* placement
+     * of a maximised or minimised window — where it will be when restored — never
+     * the geometry it is drawn at.
+     */
+    getLayout(): LayoutSnapshot;
+    /** Restore an arrangement; never throws on garbage. */
+    setLayout(incoming: LayoutSnapshot | LayoutWindow[]): number;
+    /** A versioned snapshot, following core's and gantt's shape. */
+    getState(): { version: number; layout: LayoutSnapshot };
+    /** Restore a `getState()` snapshot; never throws on garbage. */
+    setState(snapshot: unknown): number;
+    /**
+     * Lock or unlock the dashboard at runtime — the "Edit layout" button. A
+     * boolean sets all three capabilities; an object sets only the keys it
+     * carries. Nothing is destroyed, so every payload survives the toggle.
+     *
+     * The asymmetry is deliberate: **you can always take a capability away; you
+     * can never grant one where the developer said no.** `setInteractive(false)`
+     * locks every window, including one whose own spec says `movable: true`;
+     * `setInteractive(true)` unlocks only the windows that never opted out.
+     *
+     * `config.movable: false` and `setInteractive(false)` are deliberately not
+     * the same thing: the config states the *default* for windows that declare
+     * nothing (and `false` is already that default, so it takes nothing away from
+     * a window that opted in), while this is an *active lock*.
+     *
+     * A key carrying `undefined` is treated as absent, so
+     * `setInteractive(getInteractive())` is a no-op in every state.
+     *
+     * A locked layout is not a read-only dashboard: this module never reads or
+     * writes a payload, so a grid inside a window is made read-only with the
+     * grid's own settings.
+     */
+    setInteractive(value: boolean | Partial<LayoutInteractive>): LayoutInteractive;
+    /**
+     * The layout-level interactivity now in force, as a copy — `undefined` where
+     * no layout-level default is set, so the result round-trips through
+     * `setInteractive`.
+     */
+    getInteractive(): LayoutInteractive;
+    /** Re-measure every window and emit `window:resized` for those that changed. */
+    refresh(): number;
+    on(
+      name: 'window:moved' | 'window:resized' | 'window:closed' | 'layout:changed'
+        | 'beforeWindowMove' | 'beforeWindowResize' | 'beforeWindowClose'
+        | 'windowMove:cancelled' | 'windowResize:cancelled' | 'windowClose:cancelled'
+        | '*' | string,
+      fn: (event: any) => unknown,
+    ): () => void;
+    off(name: string, fn: (event: any) => unknown): void;
+    /** Tear the layout down; whatever the host mounted in a payload is the host's to destroy. */
+    destroy(): void;
+  }
+
+  /** Create a reconfigurable dashboard layout over a host element. */
+  export function createLayout(el: HTMLElement, config?: LayoutConfig): Layout;
+  export default createLayout;
+}