@toclocoinc/lattice-grid 1.1.0

package/lattice-grid.d.ts

@@ -0,0 +1,1232 @@
+/*!
+ * Lattice Grid 1.1.0 — type declarations
+ * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
+ * https://latticegrid.dev
+ */
+/**
+ * Lattice Grid — public type declarations.
+ * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
+ *
+ * These declarations describe the public API of the vanilla-JavaScript
+ * implementation. They are shipped for consumer tooling only; nothing in the
+ * build pipeline reads them.
+ */
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+export type TypeName =
+  | 'text' | 'number' | 'boolean' | 'date' | 'dateString' | 'object' | 'lookup'
+  | (string & {});
+
+export type Align = 'start' | 'center' | 'end';
+export type Density = 'compact' | 'comfortable';
+export type Theme = 'light' | 'dark' | (string & {});
+export type ColumnRef = string;
+export type Comparator = (
+  a: unknown, b: unknown, rowA?: Row, rowB?: Row, descending?: boolean,
+) => number;
+
+export interface CellStyle { [cssProperty: string]: string | number | null | undefined }
+
+// ---------------------------------------------------------------------------
+// Rows
+// ---------------------------------------------------------------------------
+
+export interface Row {
+  key: string;
+  data: unknown | null;
+  level: number;
+  parent: Row | null;
+  children?: Row[];
+  filteredChildren?: Row[];
+  sortedChildren?: Row[];
+  group: boolean;
+  expanded: boolean;
+  leafCount: number;
+  totals?: Record<string, unknown>;
+  detail?: boolean;
+  master?: boolean;
+  height: number;
+  index: number | null;
+  selected: boolean | 'partial';
+  /** Physical index into the ColumnStore. Null for synthetic rows. */
+  physical?: number | null;
+  /** Group rows only: the column id this level groups on, and the group value. */
+  groupColumn?: string;
+  groupValue?: unknown;
+  /** Stable path of group keys from root to this row. */
+  groupPath?: string[];
+  hasChildren?: boolean;
+}
+
+export interface RowChange {
+  add?: unknown[];
+  at?: number;
+  update?: unknown[];
+  remove?: unknown[] | string[];
+}
+
+export interface ChangeResult {
+  added: Row[];
+  updated: Row[];
+  removed: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Parameter bags handed to user callbacks
+// ---------------------------------------------------------------------------
+
+export interface ValueParams {
+  value: unknown;
+  data: unknown;
+  row: Row;
+  column: Column;
+  colId: string;
+  grid: Grid;
+  context: unknown;
+}
+
+export interface CellParams extends ValueParams {
+  text: string;
+  index: number;
+  props?: Record<string, unknown>;
+}
+
+export interface FormatParams extends ValueParams { locale: string }
+export interface ParseParams { text: string; value: unknown; data: unknown; row: Row; column: Column; grid: Grid; context: unknown }
+export interface ApplyParams { value: unknown; oldValue: unknown; data: unknown; row: Row; column: Column; grid: Grid; context: unknown }
+export interface KeyParams extends ValueParams {}
+export interface ValidateParams extends ApplyParams {}
+export interface SpanParams extends CellParams {}
+export interface ValueContext { data: unknown; row: Row; column: Column; grid: Grid; context: unknown }
+export type DepValues = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Formatting (spec 8.5)
+// ---------------------------------------------------------------------------
+
+export interface NumberFormat {
+  type?: 'number';
+  style?: 'decimal' | 'currency' | 'percent';
+  currency?: string;
+  currencyDisplay?: 'symbol' | 'code' | 'name' | 'narrowSymbol';
+  decimals?: number;
+  minDecimals?: number;
+  maxDecimals?: number;
+  thousandsSeparator?: boolean | string;
+  decimalSeparator?: string;
+  notation?: 'standard' | 'compact' | 'scientific';
+  negative?: 'minus' | 'parentheses' | 'suffix';
+  negativeClass?: string;
+  prefix?: string;
+  suffix?: string;
+  zeroDisplay?: string;
+  nullDisplay?: string;
+  locale?: string;
+  scale?: number;
+}
+
+export interface DateFormat {
+  type: 'date';
+  pattern?: string;
+  dateStyle?: 'short' | 'medium' | 'long' | 'full';
+  timeStyle?: 'short' | 'medium' | 'long';
+  timeZone?: string;
+  relative?: boolean | { threshold?: number };
+  nullDisplay?: string;
+  locale?: string;
+}
+
+export interface BooleanFormat {
+  type: 'boolean';
+  display?: 'checkbox' | 'switch' | 'text' | 'icon';
+  trueLabel?: string;
+  falseLabel?: string;
+  nullLabel?: string;
+  trueIcon?: string;
+  falseIcon?: string;
+}
+
+export interface TextFormat {
+  type: 'text';
+  transform?: 'none' | 'upper' | 'lower' | 'title';
+  truncate?: number | { chars: number; ellipsis?: string };
+  nullDisplay?: string;
+  emptyDisplay?: string;
+}
+
+export type FormatSpec = NumberFormat | DateFormat | BooleanFormat | TextFormat;
+
+// ---------------------------------------------------------------------------
+// Data types (spec 8.2)
+// ---------------------------------------------------------------------------
+
+export interface DataType {
+  base: 'text' | 'number' | 'boolean' | 'date' | 'dateString' | 'object';
+  extends?: TypeName;
+  matches?: (value: unknown) => boolean;
+  format?: (p: FormatParams) => string;
+  parse?: (p: ParseParams) => unknown;
+  compare?: Comparator;
+  defaults?: {
+    filter?: FilterName;
+    editor?: EditorName;
+    total?: TotalName;
+    align?: Align;
+  };
+  storage?: 'float64' | 'int32' | 'bitset' | 'dictionary' | 'object';
+  excel?: string;
+  toClipboard?: (v: unknown) => string;
+  fromClipboard?: (s: string) => unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Lookups (spec 8.3)
+// ---------------------------------------------------------------------------
+
+export interface Option {
+  id: unknown;
+  label: string;
+  disabled?: boolean;
+  variant?: VariantName;
+  icon?: string;
+  group?: string;
+}
+
+export interface LookupSpec {
+  options?: Option[] | (() => Option[] | Promise<Option[]>);
+  valueKey?: string;
+  labelKey?: string;
+  groupKey?: string;
+  multiple?: boolean;
+  allowCustom?: boolean;
+  unknownLabel?: string | ((v: unknown) => string);
+  search?: (query: string, signal: AbortSignal) => Promise<Option[]>;
+  sortBy?: 'label' | 'value' | 'optionOrder' | 'count';
+  separator?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Decoration and variants (spec 8.7)
+// ---------------------------------------------------------------------------
+
+export type DecorationName = 'plain' | 'fill' | 'pill' | 'dot' | 'bar' | 'heat' | 'icon';
+export type VariantName = 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'accent' | 'none' | (string & {});
+
+export interface DecorationSpec {
+  type: DecorationName;
+  size?: 'sm' | 'md' | 'lg';
+  shape?: 'pill' | 'rounded' | 'square';
+  outline?: boolean;
+  edge?: boolean;
+  position?: 'start' | 'end';
+  name?: string | Record<string, string>;
+  min?: number;
+  max?: number;
+  origin?: number;
+  showValue?: boolean;
+  track?: boolean;
+  ramp?: string;
+  midpoint?: number;
+}
+
+export interface VariantWhen { op: Operator; value?: unknown; use: VariantName }
+
+export type VariantSpec =
+  | VariantName
+  | { map: Record<string, VariantName>; default?: VariantName }
+  | { when: VariantWhen[]; default?: VariantName }
+  | ((p: CellParams) => VariantName);
+
+export interface VariantDefinition {
+  light: { fill: string; text: string; border: string };
+  dark: { fill: string; text: string; border: string };
+}
+
+// ---------------------------------------------------------------------------
+// Renderers, editors, filters
+// ---------------------------------------------------------------------------
+
+export interface Renderer {
+  init(p: CellParams): void;
+  element(): HTMLElement;
+  refresh?(p: CellParams): boolean;
+  attached?(): void;
+  destroy?(): void;
+}
+export type RendererCtor = new () => Renderer;
+export type RenderFn = (p: CellParams) => string | HTMLElement;
+
+export interface Editor {
+  init(p: EditorParams): void;
+  element(): HTMLElement;
+  value(): unknown;
+  attached?(): void;
+  cancelBeforeStart?(): boolean;
+  cancelOnClose?(): boolean;
+  popup?: boolean;
+  destroy?(): void;
+}
+export type EditorCtor = new () => Editor;
+export type EditorName = 'text' | 'textarea' | 'number' | 'date' | 'checkbox' | 'select' | 'multiSelect' | (string & {});
+
+export interface EditorParams extends CellParams {
+  stop(cancel?: boolean): void;
+  key?: string;
+  charPress?: string;
+}
+
+export interface Filter {
+  init(p: FilterParams): void;
+  active(): boolean;
+  passes(p: { row: Row; data: unknown }): boolean;
+  get(): unknown;
+  set(state: unknown): void;
+  element(): HTMLElement;
+  onRowsChanged?(): void;
+}
+export type FilterCtor = new () => Filter;
+export type FilterName = 'text' | 'number' | 'date' | 'boolean' | 'set' | 'multi' | 'none' | (string & {});
+
+export interface FilterParams {
+  column: Column;
+  colId: string;
+  grid: Grid;
+  context: unknown;
+  props?: Record<string, unknown>;
+  changed(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Totals
+// ---------------------------------------------------------------------------
+
+export type TotalName = 'sum' | 'min' | 'max' | 'avg' | 'count' | 'first' | 'last' | 'countValues' | (string & {});
+export type TotalFn = (values: unknown[], ctx: { row: Row; column: Column; grid: Grid; context: unknown }) => unknown;
+
+// ---------------------------------------------------------------------------
+// Columns (spec 8.1)
+// ---------------------------------------------------------------------------
+
+export interface ColumnValueSpec {
+  compute?: (deps: DepValues, ctx: ValueContext) => unknown;
+  deps?: string[] | '*';
+  pure?: boolean;
+  format?: (p: FormatParams) => string;
+  apply?: (p: ApplyParams) => boolean;
+  parse?: (p: ParseParams) => unknown;
+  key?: (p: KeyParams) => string;
+  compare?: Comparator;
+  quickFilterText?: (p: ValueParams) => string;
+}
+
+export interface ColumnCellSpec {
+  decoration?: DecorationName | DecorationSpec;
+  variant?: VariantSpec;
+  template?: string;
+  render?: string | RenderFn | RendererCtor;
+  props?: Record<string, unknown>;
+  css?: (p: CellParams) => CellStyle;
+  class?: string | string[] | ((p: CellParams) => string | string[]);
+  classWhen?: Record<string, string | ((p: CellParams) => boolean)>;
+  style?: CellStyle | ((p: CellParams) => CellStyle);
+  tooltip?: string | ((p: CellParams) => string);
+  align?: Align;
+  wrap?: boolean;
+  autoHeight?: boolean;
+  flash?: boolean;
+  spanColumns?: (p: SpanParams) => number;
+  spanRows?: (p: SpanParams) => number;
+}
+
+export interface ColumnEditSpec {
+  enabled?: boolean | ((p: CellParams) => boolean);
+  editor?: string | EditorCtor;
+  props?: Record<string, unknown>;
+  popup?: boolean;
+  validate?: (p: ValidateParams) => true | string;
+}
+
+export interface ColumnSortSpec {
+  enabled?: boolean;
+  direction?: 'asc' | 'desc' | null;
+  order?: number;
+  nullsFirst?: boolean;
+}
+
+export interface ColumnFilterSpec {
+  enabled?: boolean;
+  type?: FilterName | FilterCtor;
+  props?: Record<string, unknown>;
+}
+
+export interface ColumnLayoutSpec {
+  width?: number;
+  min?: number;
+  max?: number;
+  flex?: number;
+  pin?: 'start' | 'end' | null;
+  hidden?: boolean;
+  resizable?: boolean;
+  movable?: boolean;
+  lockVisible?: boolean;
+  lockPosition?: boolean | 'start' | 'end';
+}
+
+export interface ColumnHeaderSpec {
+  template?: string;
+  render?: string | RendererCtor;
+  props?: Record<string, unknown>;
+  class?: string | string[];
+  tooltip?: string;
+  align?: Align;
+}
+
+export interface ColumnExportSpec {
+  lookup?: 'label' | 'value' | 'columns';
+  csv?: boolean;
+  excel?: boolean;
+}
+
+export interface Column {
+  id?: string;
+  field?: string;
+  title?: string;
+  type?: TypeName | false;
+  preset?: string | string[];
+  format?: FormatSpec | string;
+  lookup?: LookupSpec;
+  value?: ColumnValueSpec;
+  cell?: ColumnCellSpec | string;
+  edit?: ColumnEditSpec | boolean | string;
+  sort?: ColumnSortSpec | boolean;
+  filter?: ColumnFilterSpec | boolean | FilterName;
+  group?: { enabled?: boolean; index?: number; explode?: boolean } | boolean;
+  pivot?: { enabled?: boolean; index?: number } | boolean;
+  total?: TotalName | TotalFn;
+  layout?: ColumnLayoutSpec | number;
+  header?: ColumnHeaderSpec | string;
+  export?: ColumnExportSpec;
+  allowGroup?: boolean;
+  allowPivot?: boolean;
+  allowTotal?: boolean;
+  nullable?: boolean;
+}
+
+export interface ColumnGroup {
+  id?: string;
+  title: string;
+  columns: (Column | ColumnGroup)[];
+  collapsible?: boolean;
+  openByDefault?: boolean;
+  showWhen?: 'open' | 'closed' | 'always';
+  marryChildren?: boolean;
+  header?: { render?: string | RendererCtor; props?: Record<string, unknown>; class?: string | string[] };
+}
+
+/** A column after presets, type defaults and grid defaults are folded in. */
+export interface ResolvedColumn {
+  id: string;
+  field: string | null;
+  title: string;
+  type: TypeName;
+  dataType: DataType;
+  nullable: boolean;
+  align: Align;
+  value: Required<Pick<ColumnValueSpec, 'pure'>> & ColumnValueSpec;
+  cell: ColumnCellSpec;
+  edit: ColumnEditSpec;
+  sort: ColumnSortSpec;
+  filter: ColumnFilterSpec;
+  group: { enabled: boolean; index: number; explode: boolean };
+  pivot: { enabled: boolean; index: number };
+  total: TotalName | TotalFn | null;
+  layout: ColumnLayoutSpec;
+  header: ColumnHeaderSpec;
+  export: ColumnExportSpec;
+  lookup: LookupSpec | null;
+  allowGroup: boolean;
+  allowPivot: boolean;
+  allowTotal: boolean;
+  /** Compiled display-text producer. */
+  formatValue(value: unknown, row?: Row, data?: unknown): string;
+  /** Resolve the value for a row, through the computed-value graph. */
+  getValue(data: unknown, row?: Row): unknown;
+  def: Column;
+}
+
+// ---------------------------------------------------------------------------
+// Filter wire format (spec 9.3)
+// ---------------------------------------------------------------------------
+
+export type Operator =
+  | 'eq' | 'ne'
+  | 'lt' | 'lte' | 'gt' | 'gte'
+  | 'between' | 'notBetween'
+  | 'in' | 'notIn'
+  | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'matches'
+  | 'blank' | 'notBlank'
+  | 'containsAny' | 'containsAll' | 'containsNone';
+
+export interface Condition {
+  col: string;
+  type?: TypeName;
+  op: Operator;
+  value?: unknown;
+  bounds?: '[]' | '[)' | '(]' | '()';
+  caseSensitive?: boolean;
+  meta?: Record<string, unknown>;
+}
+
+export interface FilterGroup {
+  op: 'and' | 'or' | 'not';
+  conditions: FilterSet[];
+}
+
+export type FilterSet = FilterGroup | Condition | null;
+
+export interface SortEntry {
+  col: string;
+  dir: 'asc' | 'desc';
+  nullsFirst?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Sources (spec 4)
+// ---------------------------------------------------------------------------
+
+export interface ReloadOptions { keepExpanded?: boolean; keepSelection?: boolean }
+
+export interface Source {
+  readonly mode: 'memory' | 'paged' | 'remote' | 'stream';
+  count(): number;
+  at(index: number): Row | undefined;
+  byKey(key: string): Row | undefined;
+  loaded(index: number): boolean;
+  hint(start: number, end: number): void;
+  apply(change: RowChange): ChangeResult;
+  reload(opts?: ReloadOptions): void;
+  destroy?(): void;
+}
+
+export interface MemorySourceConfig { mode: 'memory'; columnarBelow?: number }
+
+export interface PagedSourceConfig {
+  mode: 'paged';
+  pageSize?: number;
+  maxCachedPages?: number;
+  fetch(req: {
+    range: { start: number; end: number };
+    sort: SortEntry[];
+    filters: FilterSet;
+    quick?: string;
+    context: unknown;
+    signal: AbortSignal;
+  }): Promise<{ rows: unknown[]; total?: number }>;
+}
+
+export interface RemoteRequest {
+  protocol: 1;
+  range: { start: number; end: number };
+  groupPath: string[];
+  groupBy: ColumnRef[];
+  totals: ColumnRef[];
+  pivotBy: ColumnRef[];
+  pivotMode: boolean;
+  filters: FilterSet;
+  quick?: string;
+  sort: SortEntry[];
+  context: unknown;
+  signal: AbortSignal;
+}
+
+export interface RemoteResult {
+  rows: unknown[];
+  count?: number;
+  pivotFields?: string[];
+}
+
+export interface RemoteSourceConfig {
+  mode: 'remote';
+  pageSize?: number;
+  maxCachedPages?: number;
+  fetch(req: RemoteRequest): Promise<RemoteResult>;
+}
+
+export interface Chunk {
+  rows: unknown[];
+  progress?: { loaded: number; estimated?: number };
+  done?: boolean;
+}
+
+export interface StreamSourceConfig {
+  mode: 'stream';
+  open(req: {
+    sort: SortEntry[];
+    filters: FilterSet;
+    quick?: string;
+    context: unknown;
+    signal: AbortSignal;
+  }): AsyncIterable<Chunk>;
+  promoteToMemoryBelow?: number;
+  coalesceMs?: number;
+}
+
+export type SourceConfig =
+  | MemorySourceConfig | PagedSourceConfig | RemoteSourceConfig | StreamSourceConfig;
+
+// ---------------------------------------------------------------------------
+// Grid configuration (spec 18.1)
+// ---------------------------------------------------------------------------
+
+export interface TreeConfig {
+  path?: (row: unknown) => string[];
+  parentKey?: string | ((row: unknown) => unknown);
+  orphans?: 'root' | string;
+  hasChildren?: (row: unknown) => boolean;
+  loadChildren?: (row: Row, signal: AbortSignal) => Promise<unknown[]>;
+}
+
+export interface DetailConfig {
+  enabled?: boolean;
+  render?: string | RendererCtor;
+  config?: GridConfig;
+  rows?: (row: Row) => unknown[] | Promise<unknown[]>;
+  height?: number | 'auto' | ((row: Row) => number);
+  cacheLimit?: number;
+  isMaster?: (row: unknown) => boolean;
+}
+
+export interface SelectionConfig {
+  mode?: 'none' | 'single' | 'multiple';
+  checkbox?: boolean;
+  headerCheckbox?: boolean;
+  groupSelectsChildren?: boolean;
+  groupSelectsFiltered?: boolean;
+  ranges?: boolean;
+  fillHandle?: boolean;
+  fill?: (p: { source: unknown[]; target: { row: Row; column: ResolvedColumn }[]; direction: string }) => unknown[];
+}
+
+export interface EditConfig {
+  enabled?: boolean;
+  mode?: 'cell' | 'row';
+  start?: 'single' | 'double' | 'key';
+  enterMovesDown?: boolean;
+  undoDepth?: number;
+}
+
+export interface PaginationConfig {
+  enabled?: boolean;
+  pageSize?: number;
+  pageSizes?: number[];
+}
+
+export interface GridConfig {
+  columns?: (Column | ColumnGroup)[];
+  columnGroups?: ColumnGroup[];
+  rows?: unknown[];
+  rowKey?: string | ((row: unknown) => string);
+  source?: SourceConfig;
+  columnDefaults?: Column;
+  columnPresets?: Record<string, Column>;
+  dataTypes?: Record<string, DataType>;
+  components?: Record<string, RendererCtor | EditorCtor | FilterCtor>;
+  pipes?: Record<string, (value: unknown, ...args: string[]) => string>;
+  totalFns?: Record<string, TotalFn>;
+  variants?: Record<string, VariantDefinition>;
+  tree?: TreeConfig;
+  detail?: DetailConfig;
+  selection?: SelectionConfig | 'single' | 'multiple' | 'none';
+  edit?: EditConfig | boolean;
+  pagination?: PaginationConfig | boolean;
+  locale?: string;
+  /**
+   * IANA zone every date column formats in, e.g. 'Europe/London' or 'UTC'.
+   * Omit to use each viewer's own zone. A column's own `format.timeZone` wins.
+   */
+  timeZone?: string;
+  theme?: Theme;
+  density?: Density;
+  rowHeight?: number | ((row: Row) => number);
+  headerHeight?: number;
+  overscan?: number;
+  autoHeight?: boolean | 'visible';
+  state?: GridState;
+  licence?: string;
+  maximise?: boolean;
+  allowUnsafeTemplates?: boolean;
+  hostFilter?: { active(): boolean; passes(row: Row): boolean };
+  context?: unknown;
+  workerThreshold?: number;
+  useWorker?: boolean;
+  workerUrl?: string;
+  sharedMemory?: boolean;
+  groupFooter?: boolean;
+  /**
+   * Where the grand total goes. `'bottom'` pins it below the rows; omitted
+   * leaves it inline with the data. Only the string is recognised — `true`
+   * does nothing.
+   */
+  grandTotalRow?: 'bottom';
+  totalFilteredOnly?: boolean;
+  totalOnlyChangedColumns?: boolean;
+  showTotalInHeader?: boolean;
+  columnVirtualisationAbove?: number;
+  statusBar?: boolean | { panels?: string[] };
+  /**
+   * The cell right-click menu. A function supplies custom items; `false`
+   * suppresses it entirely, which is what a read-only grid wants — the default
+   * menu offers Paste, Clear and Fill down.
+   */
+  contextMenu?: boolean | ((p: CellParams) => MenuItem[]);
+  /** The header's 3-dot menu. `false` suppresses it. Default true. */
+  columnMenu?: boolean;
+  /**
+   * Flash a cell when its value changes. `true` takes the defaults; an object
+   * names a colour, a duration in milliseconds, or both.
+   */
+  highlightOnChange?: boolean | string | {
+    colour?: string;
+    color?: string;
+    /** Milliseconds. `0` leaves the highlight until it is cleared. */
+    duration?: number;
+    enabled?: boolean;
+  };
+  /** A class, or classes, for every row. Re-evaluated on each repaint. */
+  rowClass?: string | string[] | ((p: RowStyleParams) => string | string[]);
+  /** Inline styles for every row. Camel-case or hyphenated property names. */
+  rowStyle?: CellStyle | ((p: RowStyleParams) => CellStyle);
+  toolPanel?: boolean | {
+    /** Built-in names: `columns`, `filters`, `views`, `quick`. */
+    panels?: string[];
+    openPanel?: string;
+    /** Which edge to dock against. `left` is the icon rail; default `right`. */
+    side?: 'left' | 'right';
+    /** Icon-only tabs. Defaults to true for `side: 'left'`, false otherwise. */
+    icons?: boolean;
+    /**
+     * Rail action buttons: `undo`, `redo`, `export`, `restore`. Defaults to all
+     * four on the left rail and none on the right; `false` drops them.
+     */
+    actions?: false | ('undo' | 'redo' | 'export' | 'restore')[];
+    /** File name for the export action, without the extension. */
+    exportName?: string;
+  };
+  quickFilterText?: string;
+  /**
+   * Per-column read/write/hidden policy (§8.1). A usability control, not a
+   * security boundary — hidden data is still resident in the store. Enforce the
+   * same policy server-side with `permittedColumns` / `permittedExport`.
+   */
+  permissions?: PermissionPolicy;
+  /** Prior state for diff and audit mode (§12). */
+  diff?: { snapshot?: unknown[] | Map<string, unknown>; strictNull?: boolean; addedColumns?: 'unchanged' | 'changed' };
+  /** Saved views (§15): a storage adapter and any pre-loaded views. */
+  views?: { storage?: { read(): unknown[]; write(views: unknown[]): void }; saved?: unknown[] };
+  /** The undo toolbar. `element` mounts it into the host's own chrome. */
+  historyBar?: boolean | { element?: HTMLElement; timeline?: boolean };
+  /**
+   * The AI skill layer. The grid makes no network call of its own: `ask` is the
+   * host's, and owns the model, the key and the privacy decision.
+   */
+  ai?: {
+    ask(p: { prompt: string; schema: unknown; context?: unknown }): Promise<unknown>;
+    schemaOptions?: object;
+    context?: unknown;
+    element?: HTMLElement;
+    placeholder?: string;
+  };
+  pivot?: { enabled?: boolean; groupTotals?: 'before' | 'after' | false; maxColumns?: number; separator?: string };
+}
+
+/**
+ * The four corners of read × write. `writeOnly` is a secret: the column is
+ * present and editable, its value never shown, exported, copied or searched.
+ */
+export type PermissionLevel = 'hidden' | 'read' | 'writeOnly' | 'write';
+
+export type PermissionPolicy =
+  | PermissionLevel
+  | Record<string, PermissionLevel>
+  | { field?: string; id?: string; permission: PermissionLevel }[]
+  | ((column: ResolvedColumn, params: { colId: string; context?: unknown; grid?: unknown }) => PermissionLevel | undefined)
+  | {
+      default?: PermissionLevel;
+      columns?: Record<string, PermissionLevel>;
+      resolve?(column: ResolvedColumn, params: { colId: string; context?: unknown }): PermissionLevel | undefined;
+    };
+
+export interface MenuItem {
+  name?: string;
+  icon?: string;
+  shortcut?: string;
+  action?: () => void;
+  disabled?: boolean;
+  separator?: boolean;
+  children?: MenuItem[];
+}
+
+// ---------------------------------------------------------------------------
+// State (spec 15)
+// ---------------------------------------------------------------------------
+
+export interface ColumnState {
+  id: string;
+  width?: number;
+  flex?: number;
+  hidden?: boolean;
+  pin?: 'start' | 'end' | null;
+  sort?: 'asc' | 'desc' | null;
+  sortIndex?: number | null;
+  groupIndex?: number | null;
+  pivotIndex?: number | null;
+  total?: TotalName | null;
+}
+
+export interface GridState {
+  version: number;
+  columns?: ColumnState[];
+  columnOrder?: string[];
+  filters?: FilterSet;
+  quick?: string;
+  sort?: SortEntry[];
+  group?: string[];
+  pivot?: { enabled: boolean; columns: string[] };
+  expanded?: string[];
+  selection?: string[];
+  scroll?: { top: number; left: number };
+  pagination?: { page: number; pageSize: number };
+}
+
+export interface StateApplyReport {
+  applied: string[];
+  skipped: { key: string; reason: string }[];
+}
+
+// ---------------------------------------------------------------------------
+// Events (spec 18.4)
+// ---------------------------------------------------------------------------
+
+export type EventName =
+  | 'ready' | 'destroy' | 'render:first' | 'model:changed' | 'rows:changed' | 'rows:queued'
+  | 'cell:changed' | 'cell:clicked' | 'cell:dblclicked' | 'cell:contextmenu'
+  | 'cell:edit:start' | 'cell:edit:end' | 'row:edit:start' | 'row:edit:end'
+  | 'row:clicked' | 'row:dblclicked' | 'group:toggled'
+  | 'sort:changed' | 'filter:changed'
+  | 'column:moved' | 'column:resized' | 'column:visible' | 'column:pinned'
+  | 'column:grouped' | 'column:pivoted'
+  | 'selection:changed' | 'range:changed'
+  | 'page:changed' | 'scroll' | 'scroll:end' | 'size:changed'
+  | 'state:changed' | 'stream:chunk' | 'stream:end' | 'source:error'
+  | '*';
+
+export interface GridEvent {
+  type: string;
+  origin: 'api' | 'user' | 'init';
+  grid: Grid;
+  [key: string]: unknown;
+}
+
+export type EventHandler = (e: GridEvent) => void;
+export type Unsubscribe = () => void;
+
+// ---------------------------------------------------------------------------
+// Modules and licensing (spec 2, 3.3)
+// ---------------------------------------------------------------------------
+
+export interface GridModule {
+  name: string;
+  version?: string;
+  install(ctx: ModuleContext): void;
+  uninstall?(ctx: ModuleContext): void;
+}
+
+export interface ModuleContext {
+  registry: Registry;
+  grid?: Grid;
+}
+
+export interface Registry {
+  modules(): GridModule[];
+  has(name: string): boolean;
+  renderer(name: string): RendererCtor | RenderFn | undefined;
+  editor(name: string): EditorCtor | undefined;
+  filter(name: string): FilterCtor | undefined;
+  dataType(name: string): DataType | undefined;
+  totalFn(name: string): TotalFn | undefined;
+  pipe(name: string): ((v: unknown, ...a: string[]) => string) | undefined;
+  register(kind: string, name: string, impl: unknown): void;
+}
+
+export interface LicenceInfo {
+  valid: boolean;
+  product?: string;
+  issuedTo?: string;
+  expires?: string;
+  reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Export options (spec 14)
+// ---------------------------------------------------------------------------
+
+export interface CsvExportOptions {
+  delimiter?: string;
+  quote?: string;
+  lineEnding?: string;
+  headers?: boolean;
+  columns?: string[];
+  rows?: 'visible' | 'all' | 'selected';
+  fileName?: string;
+  processCell?: (p: CellParams) => string;
+  download?: boolean;
+}
+
+export interface ExcelExportOptions extends Omit<CsvExportOptions, 'delimiter' | 'quote' | 'lineEnding'> {
+  sheetName?: string;
+  freezePanes?: boolean;
+  variantFills?: boolean;
+  onProgress?: (p: { written: number; total: number }) => void;
+}
+
+export interface ClipboardOptions {
+  headers?: boolean;
+  rows?: 'visible' | 'all' | 'selected' | 'range';
+}
+
+// ---------------------------------------------------------------------------
+// Grid API (spec 18.3)
+// ---------------------------------------------------------------------------
+
+export interface RowsApi {
+  /** Replace the data. Sort, filters, grouping and column layout are kept. */
+  load(rows: unknown[]): void;
+  apply(change: RowChange): ChangeResult;
+  queue(change: RowChange): Promise<ChangeResult>;
+  get(index: number): Row | undefined;
+  byKey(key: string): Row | undefined;
+  count(): number;
+  /** Rows in the source before filtering; under pagination, across every page. */
+  totalCount(): number;
+  data(): unknown[];
+  forEach(fn: (row: Row, index: number) => void): void;
+  value(key: string, colId: string): unknown;
+  text(key: string, colId: string): string;
+  values(key: string): Record<string, unknown>;
+  refresh(opts?: { rows?: string[]; columns?: string[]; force?: boolean }): void;
+  expand(key: string, deep?: boolean): void;
+  collapse(key: string): void;
+  expandAll(): void;
+  collapseAll(): void;
+}
+
+export interface ColumnsApi {
+  get(id: string): ResolvedColumn | undefined;
+  all(): ResolvedColumn[];
+  visible(): ResolvedColumn[];
+  state(): ColumnState[];
+  apply(state: ColumnState[]): void;
+  show(ids: string | string[]): void;
+  hide(ids: string | string[]): void;
+  move(id: string, to: number): void;
+  pin(id: string, side: 'start' | 'end' | null): void;
+  resize(id: string, px: number): void;
+  autoSize(ids?: string | string[]): void;
+  fit(): void;
+  group(ids: string | string[]): void;
+  pivot(ids: string | string[]): void;
+  totals(ids: string | string[]): void;
+}
+
+export interface SelectionApi {
+  rows(): Row[];
+  keys(): string[];
+  set(keys: string[]): void;
+  all(): void;
+  clear(): void;
+  cells(): { key: string; colId: string }[];
+  ranges(): CellRange[];
+  setRange(range: CellRange): void;
+}
+
+export interface CellRange {
+  startRow: number;
+  endRow: number;
+  columns: string[];
+}
+
+export interface FiltersApi {
+  get(): FilterSet;
+  set(filters: FilterSet): void;
+  clear(): void;
+  quick(text: string): void;
+}
+
+export interface SortApi {
+  get(): SortEntry[];
+  set(entries: SortEntry[]): void;
+  clear(): void;
+}
+
+export interface EditApi {
+  start(key: string, colId: string): void;
+  stop(cancel?: boolean): void;
+  undo(): void;
+  redo(): void;
+}
+
+export interface ScrollApi {
+  toRow(index: number, align?: 'start' | 'center' | 'end' | 'auto'): void;
+  toColumn(id: string): void;
+  position(): { top: number; left: number };
+}
+
+export interface ExportApi {
+  csv(opts?: CsvExportOptions): string | Promise<Blob>;
+  excel(opts?: ExcelExportOptions): Promise<Blob>;
+  clipboard(opts?: ClipboardOptions): Promise<void>;
+  print(): void;
+}
+
+export interface SavedView {
+  id: string;
+  name: string;
+  description: string;
+  shared: boolean;
+  isDefault: boolean;
+  /** Supplied in `config.views.saved`: listed apart, and not renamable or deletable. */
+  builtin: boolean;
+  createdAt: number;
+  updatedAt: number;
+  /** A partial `GridState`; only the sections it names are applied. */
+  state: GridState;
+}
+
+export interface ViewStorage {
+  /** Load the user's views. Called at construction and by `views.reload()`. */
+  read(): SavedView[];
+  /**
+   * Mirror the views somewhere synchronous — `localStorage`, an in-memory
+   * cache. For a server, listen for `view:saved` / `view:removed` and do the
+   * write yourself: the grid does not make network calls and does not want to
+   * know whether yours succeeded.
+   */
+  write(views: SavedView[], change: ViewChange): void;
+}
+
+export interface ViewChange {
+  reason: 'save' | 'update' | 'rename' | 'remove' | 'default' | 'import' | 'seed' | 'replace';
+  /** The view the change concerns; null for a bulk replace. */
+  view: SavedView | null;
+}
+
+export interface RowStyleParams {
+  row: Row;
+  key: string;
+  index: number;
+  data: unknown;
+  grid: Grid;
+  context: unknown;
+}
+
+export interface HighlightApi {
+  /** Highlight a cell (`{key, colId}`), a row (`{key}`) or a column (`{colId}`). */
+  (target: { key?: string; colId?: string } | string,
+    opts?: { colour?: string; color?: string; duration?: number }): boolean;
+  /** Clear one target, or every highlight when called with nothing. */
+  clear(target?: { key?: string; colId?: string } | string): boolean;
+  list(): { scope: string; key: string | null; colId: string | null; colour: string; duration: number }[];
+  colourFor(key: string, colId: string): string | null;
+}
+
+export interface StateApi {
+  get(): GridState;
+  apply(state: GridState, opts?: { skip?: (keyof GridState)[] }): StateApplyReport;
+  /** The state the grid started in, captured once after `config.state`. */
+  baseline(): GridState | null;
+  /** Put the grid back the way it started, as one undoable step. */
+  reset(): StateApplyReport | null;
+  /** Whether anything has changed since construction. */
+  modified(): boolean;
+}
+
+export interface OverlayApi {
+  show(kind: 'loading' | 'empty' | (string & {}), message?: string): void;
+  hide(): void;
+}
+
+export interface HistoryEntry {
+  label: string;
+  kind: string;
+  [key: string]: unknown;
+}
+
+export interface HistoryApi {
+  undo(): HistoryEntry | null;
+  redo(): HistoryEntry | null;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  /** What undo or redo would apply next, for labelling a button. */
+  peek(direction?: 'undo' | 'redo'): HistoryEntry | null;
+  list(): HistoryEntry[];
+  /** Group everything `fn` does into one undoable step. */
+  transaction(label: string, fn: () => void): HistoryEntry | null;
+  clear(): void;
+}
+
+export interface ViewsApi {
+  list(): SavedView[];
+  get(id: string): SavedView | undefined;
+  readonly activeId: string | null;
+  save(name: string, opts?: { id?: string; overwrite?: boolean }): SavedView;
+  apply(id: string): SavedView | null;
+  rename(id: string, name: string): SavedView | null;
+  duplicate(id: string, name?: string): SavedView | null;
+  remove(id: string): boolean;
+  /** Mark the view applied on load; null clears it. */
+  setDefault(id: string | null): SavedView | null;
+  defaultView(): SavedView | null;
+  /** What applying the view would change, without applying it. */
+  diff(id: string): Record<string, unknown> | null;
+  export(id: string): string;
+  import(json: string): SavedView;
+  /** Re-read from storage, after another tab or the server changed it. */
+  reload(): void;
+}
+
+export interface DiffApi {
+  readonly enabled: boolean;
+  /** Set the baseline every row is compared against. */
+  setSnapshot(rows: unknown[] | null): void;
+  clear(): void;
+  summary(): { added: number; removed: number; changed: number; unchanged: number };
+  statusOf(key: string): 'added' | 'removed' | 'changed' | 'unchanged';
+  cellStatus(key: string, colId: string): 'changed' | 'unchanged';
+  isChanged(key: string, colId?: string): boolean;
+  changedColumns(key: string): string[];
+  /** The value a cell held in the baseline. */
+  before(key: string, colId: string): unknown;
+  beforeRow(key: string): unknown;
+  removedKeys(): string[];
+  removedRows(): unknown[];
+  report(): Record<string, unknown>;
+}
+
+export type PermissionLevel = 'hidden' | 'read' | 'write' | 'writeOnly';
+
+export interface PermissionsApi {
+  levelOf(column: string | ResolvedColumn): PermissionLevel;
+  isHidden(column: string | ResolvedColumn): boolean;
+  isReadable(column: string | ResolvedColumn): boolean;
+  isEditable(column: string | ResolvedColumn): boolean;
+  /** True only at `writeOnly`: writable, never shown or exported. */
+  isSecret(column: string | ResolvedColumn): boolean;
+  isExportable(column: string | ResolvedColumn): boolean;
+  levels(): Record<string, PermissionLevel>;
+  /** Change the context permissions are evaluated against, and re-evaluate. */
+  setContext(context: unknown): void;
+  invalidate(): void;
+}
+
+export interface AiApi {
+  /** A machine-readable description of the grid, for a model's context. */
+  schema(opts?: { maxColumns?: number; maxRows?: number }): Record<string, unknown>;
+  /** The same schema as a tool definition. */
+  tool(opts?: { maxColumns?: number; maxRows?: number }): Record<string, unknown>;
+  prompt(text: string, opts?: Record<string, unknown>): string;
+  buildPrompt(text: string, opts?: Record<string, unknown>): string;
+  /** Parse what the model returned into a plan. */
+  plan(reply: string | Record<string, unknown>, opts?: Record<string, unknown>): Record<string, unknown>;
+  /** Run a plan as one undoable step. */
+  apply(plan: Record<string, unknown>): Record<string, unknown>;
+}
+
+export interface LicenceApi {
+  set(key: string): LicenceInfo;
+  info(): LicenceInfo;
+  state(): 'licensed' | 'localhost' | 'trial';
+  watermark(): boolean;
+  /** Settles when the licence check finishes. */
+  readonly ready: Promise<LicenceInfo>;
+}
+
+export interface PaginationApi {
+  get(): { page: number; pageSize: number; total: number; pageCount: number };
+  set(next: { page?: number; pageSize?: number }): void;
+  applyPage(next: { page?: number; pageSize?: number }): void;
+}
+
+/**
+ * Fills the browser window with the grid and puts it back. Present on grids
+ * created with `createGrid` unless `maximise: false`; never on a headless grid,
+ * which has no window to fill.
+ */
+export interface MaximiseApi {
+  enter(): boolean;
+  exit(): boolean;
+  toggle(): boolean;
+  active(): boolean;
+}
+
+export interface Grid {
+  readonly rows: RowsApi;
+  readonly columns: ColumnsApi;
+  readonly selection: SelectionApi;
+  readonly filters: FiltersApi;
+  readonly sort: SortApi;
+  readonly edit: EditApi;
+  readonly scroll: ScrollApi;
+  readonly export: ExportApi;
+  readonly state: StateApi;
+  readonly overlay: OverlayApi;
+  readonly history: HistoryApi;
+  readonly views: ViewsApi;
+  readonly diff: DiffApi;
+  readonly permissions: PermissionsApi;
+  readonly ai: AiApi;
+  readonly licence: LicenceApi;
+  readonly pagination: PaginationApi;
+  readonly highlight: HighlightApi;
+  readonly maximise?: MaximiseApi;
+  readonly element: HTMLElement | null;
+  readonly destroyed: boolean;
+  /** False until the first render has been laid out. */
+  readonly ready: boolean;
+
+  /** The resolved configuration, as one object. */
+  config(): GridConfig;
+  get<K extends keyof GridConfig>(key: K): GridConfig[K];
+  set<K extends keyof GridConfig>(key: K, value: GridConfig[K]): void;
+  setAll(values: Partial<GridConfig>): void;
+
+  on(event: EventName, handler: EventHandler): Unsubscribe;
+  once(event: EventName, handler: EventHandler): Unsubscribe;
+  off(event: EventName, handler: EventHandler): void;
+  emit(event: string, payload?: Record<string, unknown>): void;
+
+  getVersion(): string;
+  destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Entry points
+// ---------------------------------------------------------------------------
+
+export function createGrid(element: HTMLElement, config?: GridConfig): Grid;
+export function createHeadlessGrid(config?: GridConfig): Grid;
+export function registerModules(modules: GridModule[], opts?: { licence?: string }): void;
+export function setLicence(licence: string): LicenceInfo;
+export function version(): string;
+
+export const LatticeGrid: {
+  createGrid: typeof createGrid;
+  createHeadlessGrid: typeof createHeadlessGrid;
+  registerModules: typeof registerModules;
+  setLicence: typeof setLicence;
+  version: typeof version;
+};
+
+export default LatticeGrid;