@toclocoinc/lattice-grid 1.68.0 → 1.68.2

package/modules/tabs.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, tabs module type declarations
+ * Lattice Grid 1.68.2, tabs module type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -41,6 +41,7 @@ interface TabDescriptor {
   where?: (row: unknown) => boolean;
   /** Group-by forwarded to the derived source. */
   group?: unknown;
+  /** An alias for `group`, forwarded verbatim to the derived source. */
   groupBy?: unknown;
   /** Time-bucketing forwarded to the derived source. */
   bucket?: unknown;
@@ -70,15 +71,101 @@ interface TabDescriptor {
   badgeTone?: 'good' | 'warn' | 'bad' | 'unknown' | ((count: number | null, tab: { id: string; label: string; from: string | null }) => 'good' | 'warn' | 'bad' | 'unknown' | null);
 }
 
-/** The payload every tab-change event carries. */
+/**
+ * `beforeTabChange`: a switch is about to be applied, and may be refused.
+ *
+ * Delivered through `packages/modules/shared/emitter.js`'s `emitBefore`, which
+ * builds the event from the module's action context plus `type`, the resolved
+ * `origin` and the veto surface — so every member below is always present on
+ * this event. A handler refuses the switch by calling `preventDefault(reason?)`
+ * or by returning a Promise that resolves `false`; the active tab then does not
+ * change and `tabChange:cancelled` fires carrying the reason.
+ */
 interface TabChangeEvent {
+  /** Which event this is: `beforeTabChange`. */
+  type: string;
+  /** The tab being switched to. */
   id: string;
+  /** The tab being left, or null when no tab was active. */
   previousId: string | null;
-  origin?: 'api' | 'user' | 'init';
-  reason?: string | null;
-  /** Cancel the switch (only meaningful on `beforeTabChange`). */
-  preventDefault?: (reason?: string) => void;
-  defaultPrevented?: boolean;
+  /**
+   * Who asked for the switch: `user` for a click or a keypress, `api` for
+   * `activate()`. The opening tab is activated silently, so it raises no
+   * `beforeTabChange` at all.
+   */
+  origin: 'api' | 'user';
+  /** The reason given to `preventDefault`, or null while nothing has refused the switch. */
+  reason: string | null;
+  /** True once a handler has refused the switch. */
+  defaultPrevented: boolean;
+  /** Refuse the switch; the optional reason is carried on `tabChange:cancelled`. */
+  preventDefault(reason?: string): void;
+}
+
+/**
+ * `tab:changed`: the switch happened — the target panel is revealed, its grid
+ * materialised on first activation, the badges refreshed and `aria-selected`
+ * moved. A notification, so it carries no `preventDefault`.
+ */
+interface TabChangedEvent {
+  /** Which event this is: `tab:changed`. */
+  type: string;
+  /** The tab now active. */
+  id: string;
+  /**
+   * The tab that was left, or null for the mount-time activation — which
+   * happens while the strip is being built, before a handler can subscribe.
+   */
+  previousId: string | null;
+}
+
+/**
+ * `tabChange:cancelled`: a `beforeTabChange` handler refused the switch, so the
+ * active tab did not change. A notification, so it carries no `preventDefault`.
+ */
+interface TabChangeCancelledEvent {
+  /** Which event this is: `tabChange:cancelled`. */
+  type: string;
+  /** The tab that was not switched to. */
+  id: string;
+  /** The tab that is still active, or null when none was. */
+  previousId: string | null;
+  /** Who asked for the switch that was refused. */
+  origin: 'api' | 'user';
+  /** The reason given to `preventDefault`, or `'prevented'` when none was. */
+  reason: string;
+}
+
+/**
+ * The events a tabbed grid raises.
+ *
+ * The strip's own, not a grid's: `grid.on` takes {@link EventName} and knows
+ * nothing about these, and each tab's grid keeps raising its own events itself.
+ * `on()` warns once on any other name, because a binding to an event that can
+ * never fire is a silent no-op. Each event also has a config callback
+ * (`onBeforeTabChange`, `onTabChange`, `onTabChangeCancelled`); both routes
+ * fire.
+ *
+ * Only `beforeTabChange` is cancellable — it is the one that runs before
+ * anything moves. `tab:changed` and `tabChange:cancelled` report a decision
+ * already taken and carry no `preventDefault`.
+ */
+type TabsEventName =
+  /** A switch is about to be applied; cancellable. */
+  | 'beforeTabChange'
+  /** The active tab changed: its panel is showing and its grid is mounted. */
+  | 'tab:changed'
+  /** A `beforeTabChange` handler refused the switch; the active tab did not change. */
+  | 'tabChange:cancelled';
+
+/** What a handler receives, per tabs event. */
+interface TabsEventPayloads {
+  /** The switch about to happen, with `preventDefault` to refuse it. */
+  beforeTabChange: TabChangeEvent;
+  /** The tab now active, and the one it replaced. */
+  'tab:changed': TabChangedEvent;
+  /** The switch that was refused, and why. */
+  'tabChange:cancelled': TabChangeCancelledEvent;
 }
 
 /** Tabbed-grid configuration. */
@@ -95,9 +182,19 @@ interface TabsConfig {
   ariaLabel?: string;
   /** An explicit message-catalogue override; otherwise a mounted tab's own `grid.messages` is used. */
   messages?: { t(key: string, params?: Record<string, unknown>): string };
-  onTabChange?: (event: TabChangeEvent) => void;
+  /** Called after the active tab has changed, alongside the `tab:changed` event. */
+  onTabChange?: (event: TabChangedEvent) => void;
+  /**
+   * Called before the switch. Return `false`, call `preventDefault(reason)`, or throw, to
+   * stay where you are; return a promise and the switch waits for it. Alongside the
+   * `beforeTabChange` event.
+   */
   onBeforeTabChange?: (event: TabChangeEvent) => boolean | void | Promise<boolean>;
-  onTabChangeCancelled?: (event: TabChangeEvent) => void;
+  /**
+   * Called when a switch was refused, with the reason on the payload. Alongside
+   * `tabChange:cancelled`.
+   */
+  onTabChangeCancelled?: (event: TabChangeCancelledEvent) => void;
 }
 
 /**
@@ -106,6 +203,7 @@ interface TabsConfig {
  * alive, hidden, until `destroy()`.
  */
 interface Tabs {
+  /** The element the strip was mounted on. */
   readonly el: HTMLElement;
   /** The currently active tab id. */
   readonly activeId: string;
@@ -117,8 +215,15 @@ interface Tabs {
   isMounted(id: string): boolean;
   /** Switch the active tab, gated by `beforeTabChange`. */
   activate(id: string, opts?: { origin?: 'api' | 'user' }): boolean | Promise<boolean>;
-  on(name: 'beforeTabChange' | 'tab:changed' | 'tabChange:cancelled' | string, fn: (event: TabChangeEvent) => void): () => void;
-  off(name: string, fn: (event: TabChangeEvent) => void): void;
+  /**
+   * Register an event handler; returns a function that removes it. Any other name is
+   * warned about once, because it names a binding that could never fire. What each event
+   * carries is {@link TabsEventPayloads}; the handler is declared with the widest of
+   * them, so narrow on the name inside it.
+   */
+  on(name: TabsEventName, fn: (event: TabsEventPayloads[TabsEventName]) => void): () => void;
+  /** Remove a handler registered with `on`. */
+  off(name: TabsEventName, fn: (event: TabsEventPayloads[TabsEventName]) => void): void;
   /** Tear the whole strip down; destroys every mounted tab's grid. */
   destroy(): void;
 }

package/modules/tabs.esm.min.js

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, tabs module
+ * Lattice Grid 1.68.2, tabs module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -52,12 +52,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.68.0";
+const STAMPED_VERSION="1.68.2";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.68.0";
+const VERSION="1.68.2";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){

package/modules/tabs.min.cjs

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, tabs module
+ * Lattice Grid 1.68.2, tabs module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -54,12 +54,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.68.0";
+const STAMPED_VERSION="1.68.2";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.68.0";
+const VERSION="1.68.2";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){

package/modules/tabs.min.js

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, tabs module
+ * Lattice Grid 1.68.2, tabs module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -54,12 +54,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.68.0";
+const STAMPED_VERSION="1.68.2";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.68.0";
+const VERSION="1.68.2";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){

package/modules/vue.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, vue module type declarations
+ * Lattice Grid 1.68.2, vue module type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -143,6 +143,7 @@ export type LatticeVueGridEmit = {
 
 /** What a `<LatticeGrid>` template ref exposes; `grid()` is null before mount. */
 export interface LatticeVueGridExposed {
+  /** The live grid the component built, or null before mount. */
   grid(): Grid | null;
 }
 
@@ -190,6 +191,7 @@ export type LatticeVueViewerCommonProps = LatticeVueHostProps & {
 
 /** What a viewer's template ref exposes; `instance()` is null before mount. */
 export interface LatticeVueViewerExposed<Instance = unknown> {
+  /** The live viewer the component built, or null before mount. */
   instance(): Instance | null;
 }
 
@@ -233,8 +235,17 @@ export type LatticeVueLayoutProps = Record<string, unknown> & LatticeVueViewerCo
 
 /** One tab of a `<LatticeTabs>`; a slot named for its `id` makes it Vue's. */
 export interface LatticeVueTabSpec {
+  /**
+   * The tab's identity, which also names the slot whose content Vue renders into the
+   * panel. Required, non-empty and unique.
+   */
   id: string;
+  /** The text on the tab button. Defaults to the id. */
   label?: string;
+  /**
+   * Any other prop the host wants to carry on the tab. Passed through untouched, so a
+   * Vue host can key its own state off the same object the grid holds.
+   */
   [key: string]: unknown;
 }
 

package/modules/vue.esm.min.js

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, vue module
+ * Lattice Grid 1.68.2, vue module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -52,12 +52,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.68.0";
+const STAMPED_VERSION="1.68.2";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.68.0";
+const VERSION="1.68.2";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){

package/modules/vue.min.cjs

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, vue module
+ * Lattice Grid 1.68.2, vue module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -54,12 +54,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.68.0";
+const STAMPED_VERSION="1.68.2";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.68.0";
+const VERSION="1.68.2";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){

package/modules/vue.min.js

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, vue module
+ * Lattice Grid 1.68.2, vue module
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -54,12 +54,12 @@ Object.defineProperty(__exports,"frameBatched",{enumerable:true,get:function(){r
 Object.defineProperty(__exports,"settleDebounce",{enumerable:true,get:function(){return settleDebounce;}});
 Object.defineProperty(__exports,"whenIdle",{enumerable:true,get:function(){return whenIdle;}});
 Object.defineProperty(__exports,"uid",{enumerable:true,get:function(){return uid;}});
-const STAMPED_VERSION="1.68.0";
+const STAMPED_VERSION="1.68.2";
 async function resolveVersion(){
 if(STAMPED_VERSION!=='0.0.0-source')return STAMPED_VERSION;
 return STAMPED_VERSION;
 }
-const VERSION="1.68.0";
+const VERSION="1.68.2";
 const warned=new Set();
 const WARNED_LIMIT=2000;
 function rememberWarned(key){

package/modules/webcomponent.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.68.0, webcomponent module type declarations
+ * Lattice Grid 1.68.2, webcomponent module type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -70,12 +70,34 @@ export interface LatticeViewerEventDetail<Instance = unknown> { instance: Instan
 export interface LatticeGridElement<Row = any> extends HTMLElement {
   /** Every attribute in the table above is also a property of the same name. */
   theme: string | undefined;
+  /**
+   * The row height and padding as a named step, rather than pixel by pixel. The `density`
+   * attribute.
+   */
   density: string | undefined;
+  /** The locale the grid formats and sorts in. The `locale` attribute. */
   locale: string | undefined;
+  /**
+   * Which field identifies a row. As an attribute it can only be a field name; the
+   * composite and function forms are properties.
+   */
   rowKey: string | undefined;
+  /** Row height in pixels. The `row-height` attribute, parsed as a number. */
   rowHeight: number | undefined;
+  /**
+   * Header height in pixels. The `header-height` attribute, parsed as a number; unset,
+   * the header follows the density token.
+   */
   headerHeight: number | undefined;
+  /**
+   * Let the grid grow to its rows rather than capping its height. The `auto-height`
+   * attribute is a bare boolean — present is true.
+   */
   autoHeight: boolean | undefined;
+  /**
+   * What the reader may select: `single`, `multiple` or `none`. The `selection`
+   * attribute; the full selection config goes through `config`.
+   */
   selection: string | undefined;
   /** The live grid, or null while the element is disconnected. */
   readonly grid: Grid | null;
@@ -122,64 +144,121 @@ export interface LatticeViewerElement<Instance = unknown> extends HTMLElement {
  * empty; give it `rows` for a standalone panel.
  */
 export interface LatticeKPIElement<Row = any> extends LatticeViewerElement {
+  /** The panel's tiles. A structure, so it is a property rather than an attribute. */
   tiles: unknown[];
+  /** Rows for a standalone panel. Set them and the element stops waiting for a grid. */
   rows: Row[];
+  /** How many tile columns to aim for. */
   columns: number | undefined;
+  /** Which field identifies a row, for the panel's own keyed store. */
   rowKey: string | undefined;
+  /** The default locale a clock tile formats in. */
   locale: string | undefined;
-  theme: string | undefined;
-  density: string | undefined;
-  format: unknown;
 }
 
 /** `<lattice-chart>`. Always drawn from a grid, so it waits for one. */
 export interface LatticeChartElement extends LatticeViewerElement {
+  /**
+   * A geomap's geometry: a loaded pack, `{ pack: id }`, GeoJSON, or a map of code to path
+   * data. A structure, so it is a property.
+   */
   shapes: unknown;
+  /** The column that splits the measure into one series per distinct value. */
   series: unknown;
+  /**
+   * Rows to draw instead of the grid's own filtered rows — the chart spec's `rows`,
+   * under the name the element gives it. An explicit `config: { rows }` wins.
+   */
   data: unknown;
-  formatting: unknown;
+  /** Which chart to draw. The `type` attribute. */
   type: string | undefined;
+  /** The category column. */
   x: string | undefined;
+  /** The measure column, or several for a multi-measure chart. */
   y: string | string[] | undefined;
+  /** The measure a markermap writes beside each dot and colours it by. */
   value: string | undefined;
+  /** The row-label column, for the types that name their rows. */
   label: string | undefined;
+  /** The longitude column, in degrees east, for the maps that place a row by where it is. */
   lon: string | undefined;
+  /** The latitude column, in degrees north. */
   lat: string | undefined;
+  /** Print the value beside each mark. The `labels` attribute is a bare boolean. */
   labels: boolean | undefined;
+  /** Stack the series rather than drawing them side by side — the spec's `stack`. */
   stacked: boolean | undefined;
+  /**
+   * Draw a `type="bar"` chart along y instead of x, by selecting the `horizontalBar`
+   * type. Ignored on any other chart type, whose orientation is the type's own.
+   */
   horizontal: boolean | undefined;
+  /** The colour scheme by name. */
   scheme: string | undefined;
 }
 
 /** `<lattice-kanban>`. Grid-bound like the KPI panel; give it `rows` to stand alone. */
 export interface LatticeKanbanElement<Row = any> extends LatticeViewerElement {
+  /** Rows for a standalone board. Set them and the element stops waiting for a grid. */
   rows: Row[];
+  /** The board's column definitions. */
   columns: unknown[];
+  /** The card template's field mapping — title, subtitle, labels, assignee and the rest. */
   card: unknown;
-  facets: unknown;
+  /** Which field identifies a card. */
   rowKey: string | undefined;
+  /** The row property that puts a card in a column. */
   columnProperty: string | undefined;
+  /**
+   * The row property a card's headline comes from — the shorthand for
+   * `card: { title }`, which wins where both are given.
+   */
   titleProperty: string | undefined;
+  /**
+   * Draw the two-dimensional swimlane layout. The `swimlanes` attribute is a bare
+   * boolean; name the lane property through `swimlane-property`.
+   */
   swimlanes: boolean | undefined;
 }
 
 /** `<lattice-gantt>`. */
 export interface LatticeGanttElement extends LatticeViewerElement {
+  /** The plan's tasks. A structure, so it is a property. */
   tasks: unknown[];
+  /** The links between tasks. */
   dependencies: unknown[];
+  /** The resource capacities, for over-allocation and levelling. */
   resources: unknown;
+  /** The working-time calendar: the `weekends` preset, or explicit workdays and holidays. */
   calendar: unknown;
+  /** The table panel's columns, for the split view. */
   columns: unknown;
+  /** Which field identifies a task. */
   rowKey: string | undefined;
+  /**
+   * The timeline's zoom — the shorthand for `config: { render: { zoom } }`, which wins
+   * where both are given.
+   */
   scale: string | undefined;
+  /**
+   * Cascade an edit down the dependency chain rather than only recomputing. A bare
+   * boolean attribute.
+   */
   autoSchedule: boolean | undefined;
 }
 
 /** `<lattice-layout>`. */
 export interface LatticeLayoutElement extends LatticeViewerElement {
+  /**
+   * The windows to place, each with its content and its cell. A structure, so it is a
+   * property.
+   */
   windows: unknown[];
+  /** How many columns the grid of windows has. */
   columns: number | undefined;
+  /** How many rows the grid of windows has. */
   rows: number | undefined;
+  /** Which way windows collapse into the space a closed one left. */
   compact: string | undefined;
 }
 
@@ -189,6 +268,10 @@ export interface LatticeLayoutElement extends LatticeViewerElement {
  * left to the module.
  */
 export interface LatticeTabsElement extends LatticeViewerElement {
+  /**
+   * The tab descriptors. A tab's content comes from a `<template data-tab="‹id›">` child
+   * when there is one.
+   */
   tabs: unknown[];
 }