apex-grid 3.2.0 → 3.4.0

package/internal/state-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-schema.js","sourceRoot":"","sources":["../../src/internal/state-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAwElD,MAAM,UAAU,YAAY,CAAmB,MAA8B;IAC3E,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAiB;QAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,GAAG,CAAC;QAC9C,QAAQ,EAAE,CAAC,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAa;QAC/C,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QAC9B,UAAU;QACV,cAAc,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;QAC3E,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;KAC/B,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK;QAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IACxF,OAAO,MAAM,CAAC;AAChB,CAAC;AAQD,MAAM,UAAU,cAAc,CAC5B,OAA8C;IAE9C,MAAM,GAAG,GAAwC,EAAE,CAAC;IACpD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAa,CAAC;QACnD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import type { SortingDirection } from '../operations/sort/types.js';\nimport type { GridState } from './state-snapshot.js';\nimport type { ColumnConfiguration, DataType, SelectionMode } from './types.js';\nimport { getFilterOperandsFor } from './utils.js';\n\n/**\n * A machine-readable description of what the grid is and what can be done to it:\n * the columns and their data types, the operations available per column, the\n * grid-level capabilities, and the current {@link GridState}. Produced by\n * `ApexGrid.getSchema`.\n *\n * @remarks\n * This is the contract an AI layer feeds to an LLM (as the basis of a\n * structured-output schema) and validates a returned state patch against, but it\n * is AI-agnostic: it is equally useful for building a view-editor UI or for docs.\n * It is a descriptor, not a JSON-Schema document — everything needed to *build* a\n * strict JSON Schema (or validate a `setState` patch) is here. Enterprise grids\n * populate the optional grouping / pivot / aggregation fields.\n */\nexport interface GridSchema {\n  /** Schema version, matching {@link GridState.version}. */\n  version: 1;\n  /** Per-column description, in display order. */\n  columns: ColumnSchema[];\n  /** Grid-level operation availability. */\n  capabilities: GridCapabilities;\n  /** The current restorable state, so capabilities and live values travel together. */\n  state: GridState;\n}\n\n/** Description of a single column for {@link GridSchema}. */\nexport interface ColumnSchema {\n  key: string;\n  /** Human label (`headerText`, falling back to `key`). */\n  label: string;\n  dataType: DataType;\n  /** Whether the column opts into sorting (its header sort affordance). */\n  sortable: boolean;\n  /** Whether the column opts into filtering. */\n  filterable: boolean;\n  /** Operand names valid for this column when `filterable` (e.g. `'contains'`); else empty. */\n  filterOperands: string[];\n  editable: boolean;\n  hidden: boolean;\n  /** Pin band, omitted when the column scrolls with the body. */\n  pinned?: 'start' | 'end';\n  /** Enterprise: whether the column can be row-grouped. Set by the enterprise grid. */\n  groupable?: boolean;\n  /** Enterprise: whether the column can be a pivot dimension. Set by the enterprise grid. */\n  pivotable?: boolean;\n  /** Enterprise: whether the column can be aggregated. Set by the enterprise grid. */\n  aggregatable?: boolean;\n  /** Enterprise: aggregation functions valid for this column, when `aggregatable`. */\n  aggFuncs?: string[];\n  /** Enterprise: whether the column accepts spreadsheet formulas. Set by the enterprise grid. */\n  allowFormula?: boolean;\n}\n\n/** Grid-level operation availability for {@link GridSchema}. */\nexport interface GridCapabilities {\n  sort: { directions: SortingDirection[]; multi: boolean };\n  filter: { operandsByType: Partial<Record<DataType, string[]>> };\n  pagination: boolean;\n  selection: SelectionMode | false;\n  rowPinning: boolean;\n  rowReordering: boolean;\n  /** Enterprise: whether row grouping is available. Set by the enterprise grid. */\n  grouping?: boolean;\n  /** Enterprise: whether pivoting is available. Set by the enterprise grid. */\n  pivot?: boolean;\n  /** Enterprise: aggregation availability + the supported functions. Set by the enterprise grid. */\n  aggregation?: { funcs: string[] };\n}\n\n/** Describe a single column: data type + the operations it opts into. */\nexport function columnSchema<T extends object>(column: ColumnConfiguration<T>): ColumnSchema {\n  const filterable = Boolean(column.filter);\n  const schema: ColumnSchema = {\n    key: String(column.key),\n    label: String(column.headerText ?? column.key),\n    dataType: (column.type ?? 'string') as DataType,\n    sortable: Boolean(column.sort),\n    filterable,\n    filterOperands: filterable ? Object.keys(getFilterOperandsFor(column)) : [],\n    editable: Boolean(column.editable),\n    hidden: Boolean(column.hidden),\n  };\n  if (column.pinned === 'start' || column.pinned === 'end') schema.pinned = column.pinned;\n  return schema;\n}\n\n/**\n * The filter-operand vocabulary keyed by the data types present among `columns`\n * (the global reference for `capabilities.filter`), resolved from the same\n * source the apply path trusts ({@link getFilterOperandsFor}), so the schema and\n * `setState` can never disagree about valid operands.\n */\nexport function operandsByType<T extends object>(\n  columns: ReadonlyArray<ColumnConfiguration<T>>\n): Partial<Record<DataType, string[]>> {\n  const out: Partial<Record<DataType, string[]>> = {};\n  for (const column of columns) {\n    const type = (column.type ?? 'string') as DataType;\n    if (!out[type]) out[type] = Object.keys(getFilterOperandsFor(column));\n  }\n  return out;\n}\n"]}

package/internal/state-snapshot.d.ts

@@ -0,0 +1,152 @@
+import type { FilterCriteria, FilterExpression } from '../operations/filter/types.js';
+import type { SortExpression, SortingDirection } from '../operations/sort/types.js';
+import type { ColumnConfiguration, PinPosition } from './types.js';
+/**
+ * A serializable, JSON-safe snapshot of the grid's restorable state, produced by
+ * `ApexGrid.getState` and consumed by `ApexGrid.setState`.
+ *
+ * @remarks
+ * Functions and templates are never serialized — sort comparers, filter
+ * condition functions, and cell/header/editor templates are re-bound from the
+ * live column configuration on restore. Filter conditions are captured as
+ * operand name strings (e.g. `'contains'`). Selection / expansion / tree rows
+ * are captured as {@link RowRef}s (a stable `id` when an `ApexGrid.rowId`
+ * resolver is configured, otherwise a positional `index` into `ApexGrid.data`,
+ * which round-trips within a session but not across a data reload).
+ */
+export interface GridState {
+    /** Snapshot schema version. */
+    version: 1;
+    /** Per-column layout (order, width, pinning, visibility). */
+    columns: ColumnLayoutState[];
+    /** Active sort expressions (comparer functions omitted). */
+    sort: SortStateSnapshot[];
+    /** Active per-column filter expressions (condition captured by operand name). */
+    filter: FilterStateSnapshot[];
+    /** Global quick-filter term. */
+    quickFilter: string;
+    /** Pagination position. */
+    pagination: {
+        page: number;
+        pageSize: number;
+    };
+    /** Selected rows. */
+    selection: RowRef[];
+    /** Expanded (master-detail) rows. */
+    expansion: RowRef[];
+    /** Expanded tree rows that have backing data. */
+    treeExpanded: RowRef[];
+    /** Expanded synthesized tree parents (path-keyed; already string-stable). */
+    treeExpandedKeys: string[];
+    /**
+     * Pinned rows (F4) by {@link RowRef}, per band. Optional: absent on snapshots
+     * produced before row pinning existed; `getState` always emits it (empty bands
+     * when nothing is pinned).
+     */
+    rowPinning?: {
+        top: RowRef[];
+        bottom: RowRef[];
+    };
+    /**
+     * Manual drag-reorder order (F5) as a full {@link RowRef} list, or `null` for
+     * the derived (filter → sort) order. Optional for back-compat; `getState`
+     * always emits it (`null` when no manual order is active). Mutually exclusive
+     * with `sort`: a snapshot carrying both drops `rowOrder` on restore.
+     */
+    rowOrder?: RowRef[] | null;
+    /** Per-module serialized state, keyed by module id. */
+    modules: Record<string, unknown>;
+}
+/** Layout state for a single column. Order is implied by array position. */
+export interface ColumnLayoutState {
+    key: string;
+    width?: string;
+    pinned?: PinPosition;
+    hidden?: boolean;
+}
+/** A single sort expression, stripped of its (non-serializable) comparer. */
+export interface SortStateSnapshot {
+    key: string;
+    direction: SortingDirection;
+    caseSensitive?: boolean;
+}
+/** A single filter expression with its condition captured by operand name. */
+export interface FilterStateSnapshot {
+    key: string;
+    /** Operand name, e.g. `'contains'` / `'greaterThan'` (see the `*Operands`). */
+    operand: string;
+    searchTerm?: unknown;
+    criteria?: FilterCriteria;
+    caseSensitive?: boolean;
+}
+/**
+ * A reference to a row in `ApexGrid.data`: a stable `id` (when an
+ * `ApexGrid.rowId` resolver is configured) or a positional `index`.
+ */
+export type RowRef = {
+    readonly id: string | number;
+} | {
+    readonly index: number;
+};
+/** Options for `ApexGrid.getState`. */
+export interface GetStateOptions<T extends object> {
+    /** Row-identity resolver; overrides `ApexGrid.rowId` for this call. */
+    rowId?: (row: T) => string | number;
+}
+/** Options for `ApexGrid.setState`. */
+export interface SetStateOptions<T extends object> {
+    /** Row-identity resolver; overrides `ApexGrid.rowId` for this call. */
+    rowId?: (row: T) => string | number;
+    /**
+     * Throw on the first problem instead of degrading. Off by default: `setState`
+     * applies what it can and reports the rest via {@link SetStateResult.warnings}
+     * (the right behavior for LLM-produced or persisted-and-possibly-stale input).
+     * Turn on for tests / development to fail loudly.
+     */
+    strict?: boolean;
+}
+/**
+ * The outcome of an {@link SetStateOptions} apply. `setState` never throws on
+ * malformed input (unless `strict`): it applies recognized slices, skips the
+ * rest, and records human-readable {@link warnings} for anything dropped,
+ * clamped, or unresolved.
+ */
+export interface SetStateResult {
+    /** Slice names that were present and applied (e.g. `'sort'`, `'columns'`). */
+    applied: string[];
+    /** Known slice names that were absent (left untouched). */
+    skipped: string[];
+    /** What was dropped / clamped / unresolved, one message each. */
+    warnings: string[];
+}
+/** Capture the layout-managed properties of each column, in array order. */
+export declare function serializeColumnLayout<T extends object>(columns: ReadonlyArray<ColumnConfiguration<T>>): ColumnLayoutState[];
+/**
+ * Return a new columns array reordered to match `layout`, with width / pinning /
+ * visibility applied. Column objects are shallow-cloned so non-layout
+ * properties (templates, comparers, type config) are preserved. Columns absent
+ * from `layout` are appended unchanged; layout entries with no matching column
+ * are ignored.
+ */
+export declare function applyColumnLayout<T extends object>(columns: ReadonlyArray<ColumnConfiguration<T>>, layout: ReadonlyArray<ColumnLayoutState>): ColumnConfiguration<T>[];
+export declare function serializeSort<T extends object>(expressions: ReadonlyArray<SortExpression<T>>): SortStateSnapshot[];
+export declare function serializeFilter<T extends object>(expressions: ReadonlyArray<FilterExpression<T>>): FilterStateSnapshot[];
+/**
+ * Rebuild filter expressions from a snapshot, resolving each operand name back
+ * to a live {@link FilterOperation} via the target column's operand set.
+ * Entries whose column or operand can't be resolved are dropped; `onDrop` (when
+ * given) is called with the dropped entry and a reason.
+ */
+export declare function deserializeFilter<T extends object>(snapshots: ReadonlyArray<FilterStateSnapshot>, getColumn: (key: string) => ColumnConfiguration<T> | undefined, onDrop?: (snapshot: FilterStateSnapshot, reason: string) => void): FilterExpression<T>[];
+/**
+ * Serialize a set of rows to {@link RowRef}s. With a `rowId` resolver each row
+ * is captured by id; otherwise by its positional index in `universe`
+ * (`ApexGrid.data`). Rows not found in `universe` (index mode) are skipped.
+ */
+export declare function serializeRowRefs<T extends object>(rows: ReadonlyArray<T>, universe: ReadonlyArray<T>, rowId?: (row: T) => string | number): RowRef[];
+/**
+ * Resolve {@link RowRef}s back to rows in `universe`. `id` refs require a
+ * `rowId` resolver (otherwise they're skipped); `index` refs resolve
+ * positionally. Unresolvable refs are dropped.
+ */
+export declare function resolveRowRefs<T extends object>(refs: ReadonlyArray<RowRef>, universe: ReadonlyArray<T>, rowId?: (row: T) => string | number): T[];

package/internal/state-snapshot.js

@@ -0,0 +1,115 @@
+import { getFilterOperandsFor } from './utils.js';
+export function serializeColumnLayout(columns) {
+    return columns.map((column) => ({
+        key: String(column.key),
+        width: column.width,
+        pinned: column.pinned ?? undefined,
+        hidden: column.hidden ?? undefined,
+    }));
+}
+export function applyColumnLayout(columns, layout) {
+    const byKey = new Map();
+    for (const column of columns)
+        byKey.set(String(column.key), column);
+    const used = new Set();
+    const ordered = [];
+    for (const entry of layout) {
+        const column = byKey.get(entry.key);
+        if (!column)
+            continue;
+        used.add(entry.key);
+        ordered.push({
+            ...column,
+            width: entry.width,
+            pinned: entry.pinned ?? undefined,
+            hidden: entry.hidden ?? false,
+        });
+    }
+    for (const column of columns) {
+        if (!used.has(String(column.key)))
+            ordered.push(column);
+    }
+    return ordered;
+}
+export function serializeSort(expressions) {
+    return expressions.map((expression) => ({
+        key: String(expression.key),
+        direction: expression.direction,
+        caseSensitive: expression.caseSensitive,
+    }));
+}
+export function serializeFilter(expressions) {
+    return expressions.map((expression) => {
+        const condition = expression.condition;
+        return {
+            key: String(expression.key),
+            operand: typeof condition === 'string' ? condition : condition.name,
+            searchTerm: expression.searchTerm,
+            criteria: expression.criteria,
+            caseSensitive: expression.caseSensitive,
+        };
+    });
+}
+export function deserializeFilter(snapshots, getColumn, onDrop) {
+    const expressions = [];
+    for (const snapshot of snapshots) {
+        const column = getColumn(snapshot.key);
+        if (!column) {
+            onDrop?.(snapshot, 'unknown column');
+            continue;
+        }
+        const operands = getFilterOperandsFor(column);
+        const condition = operands[snapshot.operand];
+        if (!condition) {
+            onDrop?.(snapshot, `unknown operand "${snapshot.operand}"`);
+            continue;
+        }
+        expressions.push({
+            key: snapshot.key,
+            condition,
+            searchTerm: snapshot.searchTerm,
+            criteria: snapshot.criteria,
+            caseSensitive: snapshot.caseSensitive,
+        });
+    }
+    return expressions;
+}
+export function serializeRowRefs(rows, universe, rowId) {
+    const refs = [];
+    for (const row of rows) {
+        if (rowId) {
+            refs.push({ id: rowId(row) });
+        }
+        else {
+            const index = universe.indexOf(row);
+            if (index !== -1)
+                refs.push({ index });
+        }
+    }
+    return refs;
+}
+export function resolveRowRefs(refs, universe, rowId) {
+    const out = [];
+    let byId = null;
+    for (const ref of refs) {
+        if ('id' in ref) {
+            if (!rowId)
+                continue;
+            if (!byId) {
+                byId = new Map();
+                for (const row of universe)
+                    byId.set(rowId(row), row);
+            }
+            const row = byId.get(ref.id);
+            if (row)
+                out.push(row);
+        }
+        else {
+            const row = universe[ref.index];
+            if (row)
+                out.push(row);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=state-snapshot.js.map

package/internal/state-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-snapshot.js","sourceRoot":"","sources":["../../src/internal/state-snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  FilterCriteria,\n  FilterExpression,\n  FilterOperation,\n} from '../operations/filter/types.js';\nimport type { SortExpression, SortingDirection } from '../operations/sort/types.js';\nimport type { ColumnConfiguration, Keys, PinPosition } from './types.js';\nimport { getFilterOperandsFor } from './utils.js';\n\n/**\n * A serializable, JSON-safe snapshot of the grid's restorable state, produced by\n * `ApexGrid.getState` and consumed by `ApexGrid.setState`.\n *\n * @remarks\n * Functions and templates are never serialized — sort comparers, filter\n * condition functions, and cell/header/editor templates are re-bound from the\n * live column configuration on restore. Filter conditions are captured as\n * operand name strings (e.g. `'contains'`). Selection / expansion / tree rows\n * are captured as {@link RowRef}s (a stable `id` when an `ApexGrid.rowId`\n * resolver is configured, otherwise a positional `index` into `ApexGrid.data`,\n * which round-trips within a session but not across a data reload).\n */\nexport interface GridState {\n  /** Snapshot schema version. */\n  version: 1;\n  /** Per-column layout (order, width, pinning, visibility). */\n  columns: ColumnLayoutState[];\n  /** Active sort expressions (comparer functions omitted). */\n  sort: SortStateSnapshot[];\n  /** Active per-column filter expressions (condition captured by operand name). */\n  filter: FilterStateSnapshot[];\n  /** Global quick-filter term. */\n  quickFilter: string;\n  /** Pagination position. */\n  pagination: { page: number; pageSize: number };\n  /** Selected rows. */\n  selection: RowRef[];\n  /** Expanded (master-detail) rows. */\n  expansion: RowRef[];\n  /** Expanded tree rows that have backing data. */\n  treeExpanded: RowRef[];\n  /** Expanded synthesized tree parents (path-keyed; already string-stable). */\n  treeExpandedKeys: string[];\n  /**\n   * Pinned rows (F4) by {@link RowRef}, per band. Optional: absent on snapshots\n   * produced before row pinning existed; `getState` always emits it (empty bands\n   * when nothing is pinned).\n   */\n  rowPinning?: { top: RowRef[]; bottom: RowRef[] };\n  /**\n   * Manual drag-reorder order (F5) as a full {@link RowRef} list, or `null` for\n   * the derived (filter → sort) order. Optional for back-compat; `getState`\n   * always emits it (`null` when no manual order is active). Mutually exclusive\n   * with `sort`: a snapshot carrying both drops `rowOrder` on restore.\n   */\n  rowOrder?: RowRef[] | null;\n  /** Per-module serialized state, keyed by module id. */\n  modules: Record<string, unknown>;\n}\n\n/** Layout state for a single column. Order is implied by array position. */\nexport interface ColumnLayoutState {\n  key: string;\n  width?: string;\n  pinned?: PinPosition;\n  hidden?: boolean;\n}\n\n/** A single sort expression, stripped of its (non-serializable) comparer. */\nexport interface SortStateSnapshot {\n  key: string;\n  direction: SortingDirection;\n  caseSensitive?: boolean;\n}\n\n/** A single filter expression with its condition captured by operand name. */\nexport interface FilterStateSnapshot {\n  key: string;\n  /** Operand name, e.g. `'contains'` / `'greaterThan'` (see the `*Operands`). */\n  operand: string;\n  searchTerm?: unknown;\n  criteria?: FilterCriteria;\n  caseSensitive?: boolean;\n}\n\n/**\n * A reference to a row in `ApexGrid.data`: a stable `id` (when an\n * `ApexGrid.rowId` resolver is configured) or a positional `index`.\n */\nexport type RowRef = { readonly id: string | number } | { readonly index: number };\n\n/** Options for `ApexGrid.getState`. */\nexport interface GetStateOptions<T extends object> {\n  /** Row-identity resolver; overrides `ApexGrid.rowId` for this call. */\n  rowId?: (row: T) => string | number;\n}\n\n/** Options for `ApexGrid.setState`. */\nexport interface SetStateOptions<T extends object> {\n  /** Row-identity resolver; overrides `ApexGrid.rowId` for this call. */\n  rowId?: (row: T) => string | number;\n  /**\n   * Throw on the first problem instead of degrading. Off by default: `setState`\n   * applies what it can and reports the rest via {@link SetStateResult.warnings}\n   * (the right behavior for LLM-produced or persisted-and-possibly-stale input).\n   * Turn on for tests / development to fail loudly.\n   */\n  strict?: boolean;\n}\n\n/**\n * The outcome of an {@link SetStateOptions} apply. `setState` never throws on\n * malformed input (unless `strict`): it applies recognized slices, skips the\n * rest, and records human-readable {@link warnings} for anything dropped,\n * clamped, or unresolved.\n */\nexport interface SetStateResult {\n  /** Slice names that were present and applied (e.g. `'sort'`, `'columns'`). */\n  applied: string[];\n  /** Known slice names that were absent (left untouched). */\n  skipped: string[];\n  /** What was dropped / clamped / unresolved, one message each. */\n  warnings: string[];\n}\n\n// --- columns ---------------------------------------------------------------\n\n/** Capture the layout-managed properties of each column, in array order. */\nexport function serializeColumnLayout<T extends object>(\n  columns: ReadonlyArray<ColumnConfiguration<T>>\n): ColumnLayoutState[] {\n  return columns.map((column) => ({\n    key: String(column.key),\n    width: column.width,\n    pinned: column.pinned ?? undefined,\n    hidden: column.hidden ?? undefined,\n  }));\n}\n\n/**\n * Return a new columns array reordered to match `layout`, with width / pinning /\n * visibility applied. Column objects are shallow-cloned so non-layout\n * properties (templates, comparers, type config) are preserved. Columns absent\n * from `layout` are appended unchanged; layout entries with no matching column\n * are ignored.\n */\nexport function applyColumnLayout<T extends object>(\n  columns: ReadonlyArray<ColumnConfiguration<T>>,\n  layout: ReadonlyArray<ColumnLayoutState>\n): ColumnConfiguration<T>[] {\n  const byKey = new Map<string, ColumnConfiguration<T>>();\n  for (const column of columns) byKey.set(String(column.key), column);\n\n  const used = new Set<string>();\n  const ordered: ColumnConfiguration<T>[] = [];\n  for (const entry of layout) {\n    const column = byKey.get(entry.key);\n    if (!column) continue;\n    used.add(entry.key);\n    ordered.push({\n      ...column,\n      width: entry.width,\n      pinned: entry.pinned ?? undefined,\n      hidden: entry.hidden ?? false,\n    } as ColumnConfiguration<T>);\n  }\n  for (const column of columns) {\n    if (!used.has(String(column.key))) ordered.push(column);\n  }\n  return ordered;\n}\n\n// --- sort ------------------------------------------------------------------\n\nexport function serializeSort<T extends object>(\n  expressions: ReadonlyArray<SortExpression<T>>\n): SortStateSnapshot[] {\n  return expressions.map((expression) => ({\n    key: String(expression.key),\n    direction: expression.direction,\n    caseSensitive: expression.caseSensitive,\n  }));\n}\n\n// --- filter ----------------------------------------------------------------\n\nexport function serializeFilter<T extends object>(\n  expressions: ReadonlyArray<FilterExpression<T>>\n): FilterStateSnapshot[] {\n  return expressions.map((expression) => {\n    const condition = expression.condition as FilterOperation<unknown> | string;\n    return {\n      key: String(expression.key),\n      operand: typeof condition === 'string' ? condition : condition.name,\n      searchTerm: expression.searchTerm,\n      criteria: expression.criteria,\n      caseSensitive: expression.caseSensitive,\n    };\n  });\n}\n\n/**\n * Rebuild filter expressions from a snapshot, resolving each operand name back\n * to a live {@link FilterOperation} via the target column's operand set.\n * Entries whose column or operand can't be resolved are dropped; `onDrop` (when\n * given) is called with the dropped entry and a reason.\n */\nexport function deserializeFilter<T extends object>(\n  snapshots: ReadonlyArray<FilterStateSnapshot>,\n  getColumn: (key: string) => ColumnConfiguration<T> | undefined,\n  onDrop?: (snapshot: FilterStateSnapshot, reason: string) => void\n): FilterExpression<T>[] {\n  const expressions: FilterExpression<T>[] = [];\n  for (const snapshot of snapshots) {\n    const column = getColumn(snapshot.key);\n    if (!column) {\n      onDrop?.(snapshot, 'unknown column');\n      continue;\n    }\n    const operands = getFilterOperandsFor(column) as unknown as Record<\n      string,\n      FilterOperation<unknown>\n    >;\n    const condition = operands[snapshot.operand];\n    if (!condition) {\n      onDrop?.(snapshot, `unknown operand \"${snapshot.operand}\"`);\n      continue;\n    }\n    expressions.push({\n      key: snapshot.key as Keys<T>,\n      condition,\n      searchTerm: snapshot.searchTerm,\n      criteria: snapshot.criteria,\n      caseSensitive: snapshot.caseSensitive,\n    } as unknown as FilterExpression<T>);\n  }\n  return expressions;\n}\n\n// --- row references --------------------------------------------------------\n\n/**\n * Serialize a set of rows to {@link RowRef}s. With a `rowId` resolver each row\n * is captured by id; otherwise by its positional index in `universe`\n * (`ApexGrid.data`). Rows not found in `universe` (index mode) are skipped.\n */\nexport function serializeRowRefs<T extends object>(\n  rows: ReadonlyArray<T>,\n  universe: ReadonlyArray<T>,\n  rowId?: (row: T) => string | number\n): RowRef[] {\n  const refs: RowRef[] = [];\n  for (const row of rows) {\n    if (rowId) {\n      refs.push({ id: rowId(row) });\n    } else {\n      const index = universe.indexOf(row);\n      if (index !== -1) refs.push({ index });\n    }\n  }\n  return refs;\n}\n\n/**\n * Resolve {@link RowRef}s back to rows in `universe`. `id` refs require a\n * `rowId` resolver (otherwise they're skipped); `index` refs resolve\n * positionally. Unresolvable refs are dropped.\n */\nexport function resolveRowRefs<T extends object>(\n  refs: ReadonlyArray<RowRef>,\n  universe: ReadonlyArray<T>,\n  rowId?: (row: T) => string | number\n): T[] {\n  const out: T[] = [];\n  let byId: Map<string | number, T> | null = null;\n  for (const ref of refs) {\n    if ('id' in ref) {\n      if (!rowId) continue;\n      if (!byId) {\n        byId = new Map();\n        for (const row of universe) byId.set(rowId(row), row);\n      }\n      const row = byId.get(ref.id);\n      if (row) out.push(row);\n    } else {\n      const row = universe[ref.index];\n      if (row) out.push(row);\n    }\n  }\n  return out;\n}\n"]}

package/internal/tags.d.ts

@@ -1,5 +1,6 @@
 export declare const GRID_TAG: "apex-grid";
 export declare const GRID_BODY: "apex-virtualizer";
+export declare const GRID_GROUP_HEADER_ROW_TAG: "apex-grid-group-header-row";
 export declare const GRID_HEADER_ROW_TAG: "apex-grid-header-row";
 export declare const GRID_HEADER_TAG: "apex-grid-header";
 export declare const GRID_ROW_TAG: "apex-grid-row";

package/internal/tags.js

@@ -1,5 +1,6 @@
 export const GRID_TAG = 'apex-grid';
 export const GRID_BODY = 'apex-virtualizer';
+export const GRID_GROUP_HEADER_ROW_TAG = 'apex-grid-group-header-row';
 export const GRID_HEADER_ROW_TAG = 'apex-grid-header-row';
 export const GRID_HEADER_TAG = 'apex-grid-header';
 export const GRID_ROW_TAG = 'apex-grid-row';

package/internal/tags.js.map

@@ -1 +1 @@
-{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../src/internal/tags.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAoB,CAAC;AAC7C,MAAM,CAAC,MAAM,SAAS,GAAG,kBAA2B,CAAC;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAA+B,CAAC;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,kBAA2B,CAAC;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG,eAAwB,CAAC;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAyB,CAAC;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAA0B,CAAC;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAA8B,CAAC;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAA4B,CAAC","sourcesContent":["export const GRID_TAG = 'apex-grid' as const;\nexport const GRID_BODY = 'apex-virtualizer' as const;\nexport const GRID_HEADER_ROW_TAG = 'apex-grid-header-row' as const;\nexport const GRID_HEADER_TAG = 'apex-grid-header' as const;\nexport const GRID_ROW_TAG = 'apex-grid-row' as const;\nexport const GRID_CELL_TAG = 'apex-grid-cell' as const;\nexport const GRID_FILTER_ROW_TAG = 'apex-filter-row' as const;\nexport const GRID_PAGINATOR_TAG = 'apex-grid-paginator' as const;\nexport const GRID_TOOLBAR_TAG = 'apex-grid-toolbar' as const;\n"]}
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../src/internal/tags.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAoB,CAAC;AAC7C,MAAM,CAAC,MAAM,SAAS,GAAG,kBAA2B,CAAC;AACrD,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAAqC,CAAC;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAA+B,CAAC;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,kBAA2B,CAAC;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG,eAAwB,CAAC;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAyB,CAAC;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAA0B,CAAC;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAA8B,CAAC;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAA4B,CAAC","sourcesContent":["export const GRID_TAG = 'apex-grid' as const;\nexport const GRID_BODY = 'apex-virtualizer' as const;\nexport const GRID_GROUP_HEADER_ROW_TAG = 'apex-grid-group-header-row' as const;\nexport const GRID_HEADER_ROW_TAG = 'apex-grid-header-row' as const;\nexport const GRID_HEADER_TAG = 'apex-grid-header' as const;\nexport const GRID_ROW_TAG = 'apex-grid-row' as const;\nexport const GRID_CELL_TAG = 'apex-grid-cell' as const;\nexport const GRID_FILTER_ROW_TAG = 'apex-filter-row' as const;\nexport const GRID_PAGINATOR_TAG = 'apex-grid-paginator' as const;\nexport const GRID_TOOLBAR_TAG = 'apex-grid-toolbar' as const;\n"]}

package/internal/types.d.ts

@@ -6,6 +6,23 @@ import type ApexGridRow from '../components/row.js';
 import type { SortComparer } from '../operations/sort/types.js';
 export type NavigationState = 'previous' | 'current';
 export type GridHost<T extends object> = ReactiveControllerHost & ApexGrid<T>;
+/**
+ * A custom action button contributed to the toolbar's trailing actions area.
+ *
+ * @remarks
+ * The seam derived grids use to add toolbar buttons, mirroring the export-format
+ * seam: the community grid contributes none (its {@link ApexGrid.toolbarActions}
+ * returns `[]`), and the toolbar renders one button per entry, invoking
+ * {@link ToolbarAction.run} on click.
+ */
+export interface ToolbarAction {
+    /** Stable identifier, e.g. `'create-chart'`. */
+    id: string;
+    /** Button label. */
+    label: string;
+    /** Invoked when the button is clicked. */
+    run(): void;
+}
 /**
  * Helper type for resolving keys of type T.
  */
@@ -218,6 +235,16 @@ export interface BaseColumnConfiguration<T extends object, K extends Keys<T> = K
      * Header template callback.
      */
     headerTemplate?: (params: ApexHeaderContext<T>) => TemplateResult | unknown;
+    /**
+     * The id of the {@link ColumnGroupConfiguration} this column belongs to.
+     *
+     * @remarks
+     * Columns sharing a `group` id render under a single spanning header cell in
+     * the group header row. Members must be **contiguous within one pin region**
+     * (the grid warns and skips the spanning cell otherwise). Has no effect unless
+     * {@link ApexGrid.columnGroups} defines a matching group.
+     */
+    group?: string;
     /**
      * Cell template callback.
      */
@@ -241,6 +268,33 @@ export interface BaseColumnConfiguration<T extends object, K extends Keys<T> = K
      * recommended so keyboard handoff works.
      */
     editorTemplate?: (params: ApexEditorContext<T, K>) => TemplateResult | unknown;
+    /**
+     * Allows cells in this column to hold spreadsheet-style formulas.
+     *
+     * @remarks
+     * An enterprise feature: the free core only carries this flag. With the
+     * enterprise formula module active and the column also
+     * {@link BaseColumnConfiguration.editable}, a cell whose edited text starts
+     * with `=` is parsed, stored as a formula, and its computed result becomes the
+     * cell value (so sorting, filtering, and aggregation keep working on the
+     * value). Has no effect without that module. Default `false`.
+     */
+    allowFormula?: boolean;
+    /**
+     * Declarative validators run before a candidate value is written to this
+     * column's cells.
+     *
+     * @remarks
+     * Each validator receives the candidate value and a {@link ValidatorContext}
+     * and returns an error message string (the cell is rejected) or `null` (it
+     * passes). All validators run and every message is collected, so a single
+     * failed commit can surface multiple errors. A failing commit keeps the
+     * inline editor open, marks the cell `aria-invalid`, and emits
+     * `cellValidationFailed`. Validation also covers bulk edits (paste / fill).
+     * Use the built-in factories ({@link required}, {@link min}, {@link max},
+     * {@link pattern}, {@link custom}) or supply your own function.
+     */
+    validators?: Validator<T, K>[];
     /**
      * Option list for columns with `type: 'select'`.
      *
@@ -318,6 +372,50 @@ export interface BaseColumnConfiguration<T extends object, K extends Keys<T> = K
  * See {@link BaseColumnConfiguration} for the full documentation.
  */
 export type ColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T> ? BaseColumnConfiguration<T, K> : never;
+/**
+ * Context passed to a {@link ColumnGroupConfiguration.headerTemplate}.
+ */
+export interface ApexColumnGroupContext {
+    /** The group configuration being rendered. */
+    group: ColumnGroupConfiguration;
+    /** Number of (visible) member columns the group spans. */
+    span: number;
+}
+/**
+ * Configuration for a spanning group header over a contiguous run of columns
+ * (see {@link BaseColumnConfiguration.group}).
+ */
+export interface ColumnGroupConfiguration {
+    /** Unique group id, referenced by a column's {@link BaseColumnConfiguration.group}. */
+    id: string;
+    /** Text rendered in the spanning group header cell. */
+    headerText: string;
+    /**
+     * Reserved for a future collapse affordance. Inert in v1 (static spanning
+     * headers only).
+     */
+    collapsible?: boolean;
+    /** Custom template for the group header cell, overriding `headerText`. */
+    headerTemplate?: (context: ApexColumnGroupContext) => TemplateResult | unknown;
+}
+/**
+ * Context passed to a {@link Validator} alongside the candidate value.
+ */
+export interface ValidatorContext<T extends object, K extends Keys<T> = Keys<T>> {
+    /** The column configuration the value is being validated against. */
+    column: ColumnConfiguration<T, K>;
+    /** The full data record being edited (a live reference). */
+    data: T;
+    /** The view-relative row index of the edited cell. */
+    rowIndex: number;
+}
+/**
+ * A single declarative validation rule for a column.
+ *
+ * @returns An error message string when the value is invalid, or `null` when
+ * it passes.
+ */
+export type Validator<T extends object, K extends Keys<T> = Keys<T>> = (value: unknown, context: ValidatorContext<T, K>) => string | null;
 export interface ActiveNode<T> {
     column: Keys<T>;
     row: number;
@@ -459,8 +557,8 @@ export interface ApexDetailContext<T extends object> {
  *
  * @remarks
  * Tree mode renders hierarchical data as nested rows that share the same
- * column layout — collapsible parents with indented children, AG Grid's
- * "tree data" pattern. The data array stays flat; the grid derives the
+ * column layout — collapsible parents with indented children, the
+ * flat-array "tree data" pattern. The data array stays flat; the grid derives the
  * hierarchy from {@link getDataPath} at runtime.
  *
  * This is distinct from {@link GridExpansionConfiguration} (master-detail),
@@ -530,6 +628,64 @@ export interface GridExpansionConfiguration<T extends object> {
      */
     showToggleColumn?: boolean;
 }
+/**
+ * Undo / redo history configuration for cell-data edits.
+ */
+export interface EditingHistoryConfiguration {
+    /**
+     * Whether undo / redo tracking is enabled. When `true`, every committed cell
+     * edit (single, row-mode, and bulk paste / fill) is recorded and can be
+     * reversed via {@link ApexGrid.undo} / {@link ApexGrid.redo} or the keyboard
+     * (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y).
+     */
+    enabled: boolean;
+    /**
+     * Maximum number of commands retained on the undo stack. Older commands are
+     * evicted once the cap is exceeded. Defaults to `100`.
+     */
+    stackSize?: number;
+}
+/**
+ * Grid-level row-pinning configuration.
+ */
+export interface GridRowPinningConfiguration {
+    /**
+     * Whether rows can be pinned to a sticky top / bottom band via
+     * {@link ApexGrid.pinRow}. Disabled when omitted.
+     */
+    enabled: boolean;
+}
+/**
+ * Grid-level row-reordering configuration.
+ */
+export interface GridRowReorderingConfiguration {
+    /**
+     * Whether rows can be reordered by drag, keyboard, or {@link ApexGrid.moveRow}.
+     * A manual order, once set, is mutually exclusive with column sorting
+     * (applying a sort clears it). Disabled when omitted.
+     */
+    enabled: boolean;
+    /**
+     * When `true`, a reorder also splices {@link ApexGrid.data} in place so the
+     * source array reflects the new order. Defaults to `false`: the order lives in
+     * the grid and the app persists it via the `rowMoved` event.
+     */
+    applyToData?: boolean;
+    /**
+     * Controls how a pointer drag is initiated.
+     *
+     * - `true` (default): a dedicated drag-handle (grip) cell is rendered at the
+     *   start of every reorderable row, and a drag only begins from that handle.
+     *   The rest of the row stays free for selection / editing.
+     * - `false`: no handle is rendered and a drag begins by pressing anywhere on
+     *   the row (excluding interactive sub-parts like inputs and buttons).
+     *
+     * Either way the dragged row is shown as a floating ghost that follows the
+     * cursor, and the keyboard reorder flow (grab with Space, move with arrows) is
+     * unchanged.
+     */
+    handle?: boolean;
+}
 /**
  * Grid-level editing configuration.
  */
@@ -548,6 +704,10 @@ export interface GridEditingConfiguration {
      * The interaction that opens an editor. Defaults to `'doubleClick'`.
      */
     trigger?: EditTrigger;
+    /**
+     * Undo / redo history for cell-data edits. Disabled when omitted.
+     */
+    history?: EditingHistoryConfiguration;
 }
 /**
  * The parameters passed to a {@link DataPipelineHook} callback.