apex-grid 3.5.0 → 3.6.0

package/internal/feature-module.d.ts

@@ -41,11 +41,38 @@ export interface GridFeatureModule<T extends object = any> {
  * Controllers that don't implement this are skipped, so the community grid
  * (which registers no modules) is unaffected.
  *
+ * Transforms run in a fixed order set by {@link transformOrder}, not in the
+ * order modules were registered, because they do not commute (a grand-total
+ * row appended before grouping would itself be grouped).
+ *
  * @remarks Unstable; part of `apex-grid/internal`.
  */
 export interface RowTransformer<T extends object = any> {
     /** Return the transformed rows. Must not mutate the input array in place. */
     processRows(rows: ReadonlyArray<T>): T[];
+    /**
+     * Position of this transform in the module chain: lower runs first, ties keep
+     * registration order, unset means `0`. First-party values: grouping `100`,
+     * pivot `200`, grand-total row `1000`. Transforms that restructure the view
+     * come first; rows that summarise the finished view come last. Leaving it
+     * unset (`0`) runs the transform before grouping.
+     */
+    readonly transformOrder?: number;
+    /**
+     * Whether `row` is one this transform synthesized (a group header, a total
+     * row) rather than a data record. Synthesized rows are kept out of row
+     * selection and export (see {@link StateController.isDataRow}). Leave it
+     * unset when the transform's output rows are the view's records (pivot).
+     */
+    isSyntheticRow?(row: T): boolean;
+    /**
+     * The data records a synthesized `row` stands for that the view does not
+     * also hold, in view order: a collapsed group header's leaves. Return an
+     * empty array when they are in the view too (an expanded group) or the row
+     * stands for none (a total row). Lets Select all and a `'view'` export
+     * cover collapsed groups (see {@link StateController.viewRecords}).
+     */
+    hiddenRecords?(row: T): ReadonlyArray<T>;
 }
 /** Runtime type-guard for {@link RowTransformer}. */
 export declare function isRowTransformer<T extends object>(controller: unknown): controller is RowTransformer<T>;
@@ -69,6 +96,12 @@ export interface PresentedRow {
     readonly expanded?: boolean;
     /** Shadow part for the container element; defaults to `group-row`. */
     readonly part?: string;
+    /**
+     * Parts used inside {@link content} that the row should re-export, so
+     * `apex-grid::part(name)` can style them. The container {@link part} is
+     * exported without being listed here.
+     */
+    readonly exportParts?: ReadonlyArray<string>;
 }
 /**
  * Optional capability a feature module's controller may implement to render
@@ -104,11 +137,34 @@ export interface RowAriaProvider<T extends object = any> {
 }
 /** Runtime type-guard for {@link RowAriaProvider}. */
 export declare function isRowAriaProvider<T extends object>(controller: unknown): controller is RowAriaProvider<T>;
+/**
+ * Optional capability a module's controller may implement to label the
+ * spreadsheet coordinate hints (`coordinateHints`): the row-number gutter and
+ * the column letters. A module whose references address the data rather than
+ * the view (the enterprise formula engine) answers with the coordinates a
+ * reference reads, so the hints stay true through sort, filter, paging, hidden
+ * columns and column moves. Return `null` for no label, or `undefined` to leave
+ * the default (view position) in place.
+ *
+ * @remarks Unstable; part of `apex-grid/internal`.
+ */
+export interface CoordinateLabeler<T extends object = any> {
+    /** The gutter label for a row. */
+    rowCoordinate(row: T): string | null | undefined;
+    /** The letter label for a column key. */
+    columnCoordinate(key: string): string | null | undefined;
+}
+/** Runtime type-guard for {@link CoordinateLabeler}. */
+export declare function isCoordinateLabeler<T extends object>(controller: unknown): controller is CoordinateLabeler<T>;
 /** Per-cell context handed to a {@link CellDecorator}. */
 export interface CellDecoratorContext<T extends object = any> {
     /** The row's backing data (or a synthesized row object). */
     readonly row: T;
-    /** Index of the row within the current page/view (matches `host.pageItems`). */
+    /**
+     * Index of the row within the current page/view (matches `host.pageItems`),
+     * or `-1` for a row rendered in a pinned band, which is outside that view.
+     * Key pinned-row state by {@link row} instead.
+     */
     readonly rowIndex: number;
     /** The cell's column configuration. */
     readonly column: ColumnConfiguration<T>;
@@ -202,7 +258,8 @@ export declare function isCellInteractionHandler<T extends object>(controller: u
  * / {@link StateController.restoreModuleState}, driven by `ApexGrid.getState` /
  * `ApexGrid.setState`). The grid collects each implementer's
  * {@link serializeState} output under the module's id and dispatches the
- * matching value back via {@link restoreState} on restore.
+ * matching value back via {@link restoreState} on restore. Ids with no
+ * implementer are reported back by {@link StateController.restoreModuleState}.
  *
  * Controllers that don't implement this are skipped, so the community grid
  * (which registers no modules) contributes nothing to a snapshot.
@@ -212,7 +269,7 @@ export declare function isCellInteractionHandler<T extends object>(controller: u
 export interface SerializableModule {
     /**
      * Return a JSON-serializable snapshot of this module's restorable state
-     * (e.g. grouping's `groupBy` + aggregations). Exclude transient/derived
+     * (e.g. the options the feature was configured with). Exclude transient/derived
      * state and anything not JSON-safe (functions, DOM nodes).
      */
     serializeState(): unknown;

package/internal/feature-module.js

@@ -13,6 +13,12 @@ export function isRowAriaProvider(controller) {
         controller !== null &&
         typeof controller.describeRow === 'function');
 }
+export function isCoordinateLabeler(controller) {
+    return (typeof controller === 'object' &&
+        controller !== null &&
+        typeof controller.rowCoordinate === 'function' &&
+        typeof controller.columnCoordinate === 'function');
+}
 export function isCellDecorator(controller) {
     return (typeof controller === 'object' &&
         controller !== null &&

package/internal/feature-module.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-module.js","sourceRoot":"","sources":["../../src/internal/feature-module.ts"],"names":[],"mappings":"AAwDA,MAAM,UAAU,gBAAgB,CAC9B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAgC,CAAC,WAAW,KAAK,UAAU,CACpE,CAAC;AACJ,CAAC;AAqCD,MAAM,UAAU,cAAc,CAC5B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAA8B,CAAC,UAAU,KAAK,UAAU,CACjE,CAAC;AACJ,CAAC;AAyBD,MAAM,UAAU,iBAAiB,CAC/B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAiC,CAAC,WAAW,KAAK,UAAU,CACrE,CAAC;AACJ,CAAC;AA+CD,MAAM,UAAU,eAAe,CAC7B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAA+B,CAAC,YAAY,KAAK,UAAU,CACpE,CAAC;AACJ,CAAC;AAmBD,MAAM,UAAU,oBAAoB,CAAC,UAAmB;IACtD,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAiC,CAAC,kBAAkB,KAAK,UAAU,CAC5E,CAAC;AACJ,CAAC;AAoCD,MAAM,UAAU,wBAAwB,CACtC,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAwC,CAAC,qBAAqB,KAAK,UAAU,CACtF,CAAC;AACJ,CAAC;AA+BD,MAAM,UAAU,oBAAoB,CAAC,UAAmB;IACtD,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAiC,CAAC,cAAc,KAAK,UAAU;QACvE,OAAQ,UAAiC,CAAC,YAAY,KAAK,UAAU,CACtE,CAAC;AACJ,CAAC","sourcesContent":["import type { ReactiveController, TemplateResult } from 'lit';\n// Type-only import — erased at runtime, so this does not create a runtime\n// import cycle with `controllers/state.ts` (which imports the guards below).\nimport type { StateController } from '../controllers/state.js';\nimport type { ColumnConfiguration, GridHost } from './types.js';\n\n/**\n * Extension point for layering optional features onto the grid without baking\n * them into the community build.\n *\n * A feature module contributes a {@link ReactiveController} that is constructed\n * alongside the grid's built-in controllers (see {@link StateController}). It is\n * the seam used by the first-party `@apexcharts/grid-enterprise` package; it is\n * intentionally minimal and additive so the community `<apex-grid>` element is\n * unaffected (it registers zero modules).\n *\n * @remarks This API lives under the unstable `apex-grid/internal` entry point.\n */\nexport interface GridFeatureModule<T extends object = any> {\n  /**\n   * Stable identifier, e.g. `'grouping'`. Used to de-duplicate modules and to\n   * look the controller up later via {@link StateController.module}.\n   */\n  readonly id: string;\n\n  /**\n   * Construct the feature's controller. The controller is expected to register\n   * itself with the host (typically `host.addController(this)` in its\n   * constructor), exactly like the built-in controllers.\n   *\n   * @param host  The grid host the controller drives.\n   * @param state The owning {@link StateController}, passed so a module can\n   *   coordinate with cross-cutting grid state (e.g. request a cell-decoration\n   *   refresh via {@link StateController.bumpDecoration} or look up a peer\n   *   module). Modules that don't need it may ignore the argument.\n   */\n  create(host: GridHost<T>, state: StateController<T>): ReactiveController;\n}\n\n/**\n * Optional capability a feature module's controller may implement to transform\n * the row set *after* the built-in pipeline (filter → sort → tree) and *before*\n * pagination is sliced at render time. Lets a module inject or reorder rows —\n * e.g. synthesized group-header rows — in the rendered `dataView`.\n *\n * Controllers that don't implement this are skipped, so the community grid\n * (which registers no modules) is unaffected.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface RowTransformer<T extends object = any> {\n  /** Return the transformed rows. Must not mutate the input array in place. */\n  processRows(rows: ReadonlyArray<T>): T[];\n}\n\n/** Runtime type-guard for {@link RowTransformer}. */\nexport function isRowTransformer<T extends object>(\n  controller: unknown\n): controller is RowTransformer<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as RowTransformer<T>).processRows === 'function'\n  );\n}\n\n/** Per-row context handed to a {@link RowPresenter}. */\nexport interface RowPresenterContext<T extends object = any> {\n  /** The grid's visible columns (post-reorder/visibility). */\n  readonly columns: ReadonlyArray<ColumnConfiguration<T>>;\n  /** Index of the row within the current page/view. */\n  readonly rowIndex: number;\n}\n\n/**\n * A module-rendered, full-width row. Rendered inside a container that spans all\n * columns (`grid-column: 1 / -1`), mirroring the master-detail panel pattern.\n */\nexport interface PresentedRow {\n  /** Template rendered inside the full-width container. */\n  readonly content: TemplateResult;\n  /** Optional 1-based `aria-level` applied to the row element. */\n  readonly level?: number;\n  /** Optional `aria-expanded` for the row element; omit for non-expandable rows. */\n  readonly expanded?: boolean;\n  /** Shadow part for the container element; defaults to `group-row`. */\n  readonly part?: string;\n}\n\n/**\n * Optional capability a feature module's controller may implement to render\n * specific rows as full-width custom content (e.g. group headers) instead of\n * the normal cell grid. Returns `null` for rows the module does not own.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface RowPresenter<T extends object = any> {\n  presentRow(row: T, ctx: RowPresenterContext<T>): PresentedRow | null;\n}\n\n/** Runtime type-guard for {@link RowPresenter}. */\nexport function isRowPresenter<T extends object>(\n  controller: unknown\n): controller is RowPresenter<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as RowPresenter<T>).presentRow === 'function'\n  );\n}\n\n/** ARIA tree/expansion semantics a module can attach to a normal (cell-rendered) row. */\nexport interface RowAria {\n  /** 1-based `aria-level` for the row element. */\n  readonly level?: number;\n  /** `aria-expanded` for the row element; omit for non-expandable rows. */\n  readonly expanded?: boolean;\n}\n\n/**\n * Optional capability a module's controller may implement to attach ARIA\n * tree/expansion semantics (`aria-level` / `aria-expanded`) to rows that still\n * render as a normal cell grid — unlike {@link RowPresenter}, which replaces the\n * cells with full-width content. Used by pivoting's expandable row groups, whose\n * parent rows must keep showing per-column aggregate values. Returns `null` for\n * rows the module does not own.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface RowAriaProvider<T extends object = any> {\n  describeRow(row: T, ctx: RowPresenterContext<T>): RowAria | null;\n}\n\n/** Runtime type-guard for {@link RowAriaProvider}. */\nexport function isRowAriaProvider<T extends object>(\n  controller: unknown\n): controller is RowAriaProvider<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as RowAriaProvider<T>).describeRow === 'function'\n  );\n}\n\n/** Per-cell context handed to a {@link CellDecorator}. */\nexport interface CellDecoratorContext<T extends object = any> {\n  /** The row's backing data (or a synthesized row object). */\n  readonly row: T;\n  /** Index of the row within the current page/view (matches `host.pageItems`). */\n  readonly rowIndex: number;\n  /** The cell's column configuration. */\n  readonly column: ColumnConfiguration<T>;\n  /** The cell's resolved value (`row[column.key]`). */\n  readonly value: unknown;\n}\n\n/**\n * A set of host attributes a module asks the cell to reflect on itself. This is\n * the only thing a {@link CellDecorator} returns — styling is expressed by\n * keying CSS off these attributes (the cell ships an inert, variable-driven\n * `:host([data-range])` style; enterprise themes it via inheriting custom\n * properties).\n */\nexport interface CellDecoration {\n  /**\n   * Attributes to set on the decorated cell host. Use a `data-*` namespace\n   * (e.g. `data-range`) so decoration never collides with the cell's built-in\n   * reflected attributes (`active`, `editing`, `data-pinned`, …). A `null`/\n   * `undefined` value removes the attribute. Attributes set on a previous\n   * update that are absent here are removed automatically.\n   */\n  readonly attributes: Readonly<Record<string, string | null | undefined>>;\n}\n\n/**\n * Optional capability a feature module's controller may implement to decorate\n * individual cells with extra host attributes during the cell's own render\n * lifecycle — e.g. flagging the cells inside a selected range. Consulted per\n * cell via {@link StateController.decorateCell}; controllers that don't\n * implement it are skipped, so the community grid is unaffected.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface CellDecorator<T extends object = any> {\n  /** Return decoration for this cell, or `null` to leave it undecorated. */\n  decorateCell(ctx: CellDecoratorContext<T>): CellDecoration | null;\n}\n\n/** Runtime type-guard for {@link CellDecorator}. */\nexport function isCellDecorator<T extends object>(\n  controller: unknown\n): controller is CellDecorator<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as CellDecorator<T>).decorateCell === 'function'\n  );\n}\n\n/**\n * Optional capability a feature module's controller may implement to signal that\n * it provides a **column header menu** (opened from the header's kebab button).\n * The core header shows the kebab whenever a column is sortable or resizable, or\n * when a module reports `true` here, so a feature (e.g. the enterprise context\n * menu) can surface pin / hide / group / chart actions on any column. The module\n * owns the menu content itself (it opens on the `apex-grid-column-menu` event the\n * header dispatches). Inert for the community grid, which registers no modules.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface ColumnMenuProvider {\n  /** Whether the column-menu (kebab) button should be offered for columns. */\n  providesColumnMenu(): boolean;\n}\n\n/** Runtime type-guard for {@link ColumnMenuProvider}. */\nexport function isColumnMenuProvider(controller: unknown): controller is ColumnMenuProvider {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as ColumnMenuProvider).providesColumnMenu === 'function'\n  );\n}\n\n/** The kind of pointer interaction forwarded from a body cell. */\nexport type CellInteractionKind = 'down' | 'over' | 'up';\n\n/** A pointer interaction on a body cell, forwarded to feature modules. */\nexport interface CellInteraction<T extends object = any> {\n  /** `down` on press, `over` while the pointer moves across cells, `up` on release. */\n  readonly kind: CellInteractionKind;\n  /** The cell's row data. */\n  readonly row: T;\n  /** Index of the row within the current page/view (matches `host.pageItems`). */\n  readonly rowIndex: number;\n  /** The cell's column configuration. */\n  readonly column: ColumnConfiguration<T>;\n  readonly shiftKey: boolean;\n  readonly ctrlKey: boolean;\n  readonly metaKey: boolean;\n  /** The originating pointer event (e.g. to call `preventDefault`). */\n  readonly originalEvent: PointerEvent;\n}\n\n/**\n * Optional capability a feature module's controller may implement to receive\n * pointer interactions on body cells (press / drag-over / release) — the seam a\n * range-selection feature uses to track a drag. The grid forwards interactions\n * only when at least one feature module is registered, so the community grid\n * pays nothing.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface CellInteractionHandler<T extends object = any> {\n  handleCellInteraction(interaction: CellInteraction<T>): void;\n}\n\n/** Runtime type-guard for {@link CellInteractionHandler}. */\nexport function isCellInteractionHandler<T extends object>(\n  controller: unknown\n): controller is CellInteractionHandler<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as CellInteractionHandler<T>).handleCellInteraction === 'function'\n  );\n}\n\n/**\n * Optional capability a feature module's controller may implement so its state\n * participates in grid-state snapshots ({@link StateController.serializeModuleState}\n * / {@link StateController.restoreModuleState}, driven by `ApexGrid.getState` /\n * `ApexGrid.setState`). The grid collects each implementer's\n * {@link serializeState} output under the module's id and dispatches the\n * matching value back via {@link restoreState} on restore.\n *\n * Controllers that don't implement this are skipped, so the community grid\n * (which registers no modules) contributes nothing to a snapshot.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface SerializableModule {\n  /**\n   * Return a JSON-serializable snapshot of this module's restorable state\n   * (e.g. grouping's `groupBy` + aggregations). Exclude transient/derived\n   * state and anything not JSON-safe (functions, DOM nodes).\n   */\n  serializeState(): unknown;\n  /**\n   * Restore module state from a value previously produced by\n   * {@link serializeState}. Implementations should tolerate partial or\n   * unexpected shapes (validate before applying) since the blob is opaque.\n   */\n  restoreState(data: unknown): void;\n}\n\n/** Runtime type-guard for {@link SerializableModule}. */\nexport function isSerializableModule(controller: unknown): controller is SerializableModule {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as SerializableModule).serializeState === 'function' &&\n    typeof (controller as SerializableModule).restoreState === 'function'\n  );\n}\n"]}
+{"version":3,"file":"feature-module.js","sourceRoot":"","sources":["../../src/internal/feature-module.ts"],"names":[],"mappings":"AAsFA,MAAM,UAAU,gBAAgB,CAC9B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAgC,CAAC,WAAW,KAAK,UAAU,CACpE,CAAC;AACJ,CAAC;AA2CD,MAAM,UAAU,cAAc,CAC5B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAA8B,CAAC,UAAU,KAAK,UAAU,CACjE,CAAC;AACJ,CAAC;AAyBD,MAAM,UAAU,iBAAiB,CAC/B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAiC,CAAC,WAAW,KAAK,UAAU,CACrE,CAAC;AACJ,CAAC;AAqBD,MAAM,UAAU,mBAAmB,CACjC,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAmC,CAAC,aAAa,KAAK,UAAU;QACxE,OAAQ,UAAmC,CAAC,gBAAgB,KAAK,UAAU,CAC5E,CAAC;AACJ,CAAC;AAmDD,MAAM,UAAU,eAAe,CAC7B,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAA+B,CAAC,YAAY,KAAK,UAAU,CACpE,CAAC;AACJ,CAAC;AAmBD,MAAM,UAAU,oBAAoB,CAAC,UAAmB;IACtD,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAiC,CAAC,kBAAkB,KAAK,UAAU,CAC5E,CAAC;AACJ,CAAC;AAoCD,MAAM,UAAU,wBAAwB,CACtC,UAAmB;IAEnB,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAwC,CAAC,qBAAqB,KAAK,UAAU,CACtF,CAAC;AACJ,CAAC;AAgCD,MAAM,UAAU,oBAAoB,CAAC,UAAmB;IACtD,OAAO,CACL,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAQ,UAAiC,CAAC,cAAc,KAAK,UAAU;QACvE,OAAQ,UAAiC,CAAC,YAAY,KAAK,UAAU,CACtE,CAAC;AACJ,CAAC","sourcesContent":["import type { ReactiveController, TemplateResult } from 'lit';\n// Type-only import — erased at runtime, so this does not create a runtime\n// import cycle with `controllers/state.ts` (which imports the guards below).\nimport type { StateController } from '../controllers/state.js';\nimport type { ColumnConfiguration, GridHost } from './types.js';\n\n/**\n * Extension point for layering optional features onto the grid without baking\n * them into the community build.\n *\n * A feature module contributes a {@link ReactiveController} that is constructed\n * alongside the grid's built-in controllers (see {@link StateController}). It is\n * the seam used by the first-party `@apexcharts/grid-enterprise` package; it is\n * intentionally minimal and additive so the community `<apex-grid>` element is\n * unaffected (it registers zero modules).\n *\n * @remarks This API lives under the unstable `apex-grid/internal` entry point.\n */\nexport interface GridFeatureModule<T extends object = any> {\n  /**\n   * Stable identifier, e.g. `'grouping'`. Used to de-duplicate modules and to\n   * look the controller up later via {@link StateController.module}.\n   */\n  readonly id: string;\n\n  /**\n   * Construct the feature's controller. The controller is expected to register\n   * itself with the host (typically `host.addController(this)` in its\n   * constructor), exactly like the built-in controllers.\n   *\n   * @param host  The grid host the controller drives.\n   * @param state The owning {@link StateController}, passed so a module can\n   *   coordinate with cross-cutting grid state (e.g. request a cell-decoration\n   *   refresh via {@link StateController.bumpDecoration} or look up a peer\n   *   module). Modules that don't need it may ignore the argument.\n   */\n  create(host: GridHost<T>, state: StateController<T>): ReactiveController;\n}\n\n/**\n * Optional capability a feature module's controller may implement to transform\n * the row set *after* the built-in pipeline (filter → sort → tree) and *before*\n * pagination is sliced at render time. Lets a module inject or reorder rows —\n * e.g. synthesized group-header rows — in the rendered `dataView`.\n *\n * Controllers that don't implement this are skipped, so the community grid\n * (which registers no modules) is unaffected.\n *\n * Transforms run in a fixed order set by {@link transformOrder}, not in the\n * order modules were registered, because they do not commute (a grand-total\n * row appended before grouping would itself be grouped).\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface RowTransformer<T extends object = any> {\n  /** Return the transformed rows. Must not mutate the input array in place. */\n  processRows(rows: ReadonlyArray<T>): T[];\n\n  /**\n   * Position of this transform in the module chain: lower runs first, ties keep\n   * registration order, unset means `0`. First-party values: grouping `100`,\n   * pivot `200`, grand-total row `1000`. Transforms that restructure the view\n   * come first; rows that summarise the finished view come last. Leaving it\n   * unset (`0`) runs the transform before grouping.\n   */\n  readonly transformOrder?: number;\n\n  /**\n   * Whether `row` is one this transform synthesized (a group header, a total\n   * row) rather than a data record. Synthesized rows are kept out of row\n   * selection and export (see {@link StateController.isDataRow}). Leave it\n   * unset when the transform's output rows are the view's records (pivot).\n   */\n  isSyntheticRow?(row: T): boolean;\n\n  /**\n   * The data records a synthesized `row` stands for that the view does not\n   * also hold, in view order: a collapsed group header's leaves. Return an\n   * empty array when they are in the view too (an expanded group) or the row\n   * stands for none (a total row). Lets Select all and a `'view'` export\n   * cover collapsed groups (see {@link StateController.viewRecords}).\n   */\n  hiddenRecords?(row: T): ReadonlyArray<T>;\n}\n\n/** Runtime type-guard for {@link RowTransformer}. */\nexport function isRowTransformer<T extends object>(\n  controller: unknown\n): controller is RowTransformer<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as RowTransformer<T>).processRows === 'function'\n  );\n}\n\n/** Per-row context handed to a {@link RowPresenter}. */\nexport interface RowPresenterContext<T extends object = any> {\n  /** The grid's visible columns (post-reorder/visibility). */\n  readonly columns: ReadonlyArray<ColumnConfiguration<T>>;\n  /** Index of the row within the current page/view. */\n  readonly rowIndex: number;\n}\n\n/**\n * A module-rendered, full-width row. Rendered inside a container that spans all\n * columns (`grid-column: 1 / -1`), mirroring the master-detail panel pattern.\n */\nexport interface PresentedRow {\n  /** Template rendered inside the full-width container. */\n  readonly content: TemplateResult;\n  /** Optional 1-based `aria-level` applied to the row element. */\n  readonly level?: number;\n  /** Optional `aria-expanded` for the row element; omit for non-expandable rows. */\n  readonly expanded?: boolean;\n  /** Shadow part for the container element; defaults to `group-row`. */\n  readonly part?: string;\n  /**\n   * Parts used inside {@link content} that the row should re-export, so\n   * `apex-grid::part(name)` can style them. The container {@link part} is\n   * exported without being listed here.\n   */\n  readonly exportParts?: ReadonlyArray<string>;\n}\n\n/**\n * Optional capability a feature module's controller may implement to render\n * specific rows as full-width custom content (e.g. group headers) instead of\n * the normal cell grid. Returns `null` for rows the module does not own.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface RowPresenter<T extends object = any> {\n  presentRow(row: T, ctx: RowPresenterContext<T>): PresentedRow | null;\n}\n\n/** Runtime type-guard for {@link RowPresenter}. */\nexport function isRowPresenter<T extends object>(\n  controller: unknown\n): controller is RowPresenter<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as RowPresenter<T>).presentRow === 'function'\n  );\n}\n\n/** ARIA tree/expansion semantics a module can attach to a normal (cell-rendered) row. */\nexport interface RowAria {\n  /** 1-based `aria-level` for the row element. */\n  readonly level?: number;\n  /** `aria-expanded` for the row element; omit for non-expandable rows. */\n  readonly expanded?: boolean;\n}\n\n/**\n * Optional capability a module's controller may implement to attach ARIA\n * tree/expansion semantics (`aria-level` / `aria-expanded`) to rows that still\n * render as a normal cell grid — unlike {@link RowPresenter}, which replaces the\n * cells with full-width content. Used by pivoting's expandable row groups, whose\n * parent rows must keep showing per-column aggregate values. Returns `null` for\n * rows the module does not own.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface RowAriaProvider<T extends object = any> {\n  describeRow(row: T, ctx: RowPresenterContext<T>): RowAria | null;\n}\n\n/** Runtime type-guard for {@link RowAriaProvider}. */\nexport function isRowAriaProvider<T extends object>(\n  controller: unknown\n): controller is RowAriaProvider<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as RowAriaProvider<T>).describeRow === 'function'\n  );\n}\n\n/**\n * Optional capability a module's controller may implement to label the\n * spreadsheet coordinate hints (`coordinateHints`): the row-number gutter and\n * the column letters. A module whose references address the data rather than\n * the view (the enterprise formula engine) answers with the coordinates a\n * reference reads, so the hints stay true through sort, filter, paging, hidden\n * columns and column moves. Return `null` for no label, or `undefined` to leave\n * the default (view position) in place.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface CoordinateLabeler<T extends object = any> {\n  /** The gutter label for a row. */\n  rowCoordinate(row: T): string | null | undefined;\n  /** The letter label for a column key. */\n  columnCoordinate(key: string): string | null | undefined;\n}\n\n/** Runtime type-guard for {@link CoordinateLabeler}. */\nexport function isCoordinateLabeler<T extends object>(\n  controller: unknown\n): controller is CoordinateLabeler<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as CoordinateLabeler<T>).rowCoordinate === 'function' &&\n    typeof (controller as CoordinateLabeler<T>).columnCoordinate === 'function'\n  );\n}\n\n/** Per-cell context handed to a {@link CellDecorator}. */\nexport interface CellDecoratorContext<T extends object = any> {\n  /** The row's backing data (or a synthesized row object). */\n  readonly row: T;\n  /**\n   * Index of the row within the current page/view (matches `host.pageItems`),\n   * or `-1` for a row rendered in a pinned band, which is outside that view.\n   * Key pinned-row state by {@link row} instead.\n   */\n  readonly rowIndex: number;\n  /** The cell's column configuration. */\n  readonly column: ColumnConfiguration<T>;\n  /** The cell's resolved value (`row[column.key]`). */\n  readonly value: unknown;\n}\n\n/**\n * A set of host attributes a module asks the cell to reflect on itself. This is\n * the only thing a {@link CellDecorator} returns — styling is expressed by\n * keying CSS off these attributes (the cell ships an inert, variable-driven\n * `:host([data-range])` style; enterprise themes it via inheriting custom\n * properties).\n */\nexport interface CellDecoration {\n  /**\n   * Attributes to set on the decorated cell host. Use a `data-*` namespace\n   * (e.g. `data-range`) so decoration never collides with the cell's built-in\n   * reflected attributes (`active`, `editing`, `data-pinned`, …). A `null`/\n   * `undefined` value removes the attribute. Attributes set on a previous\n   * update that are absent here are removed automatically.\n   */\n  readonly attributes: Readonly<Record<string, string | null | undefined>>;\n}\n\n/**\n * Optional capability a feature module's controller may implement to decorate\n * individual cells with extra host attributes during the cell's own render\n * lifecycle — e.g. flagging the cells inside a selected range. Consulted per\n * cell via {@link StateController.decorateCell}; controllers that don't\n * implement it are skipped, so the community grid is unaffected.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface CellDecorator<T extends object = any> {\n  /** Return decoration for this cell, or `null` to leave it undecorated. */\n  decorateCell(ctx: CellDecoratorContext<T>): CellDecoration | null;\n}\n\n/** Runtime type-guard for {@link CellDecorator}. */\nexport function isCellDecorator<T extends object>(\n  controller: unknown\n): controller is CellDecorator<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as CellDecorator<T>).decorateCell === 'function'\n  );\n}\n\n/**\n * Optional capability a feature module's controller may implement to signal that\n * it provides a **column header menu** (opened from the header's kebab button).\n * The core header shows the kebab whenever a column is sortable or resizable, or\n * when a module reports `true` here, so a feature (e.g. the enterprise context\n * menu) can surface pin / hide / group / chart actions on any column. The module\n * owns the menu content itself (it opens on the `apex-grid-column-menu` event the\n * header dispatches). Inert for the community grid, which registers no modules.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface ColumnMenuProvider {\n  /** Whether the column-menu (kebab) button should be offered for columns. */\n  providesColumnMenu(): boolean;\n}\n\n/** Runtime type-guard for {@link ColumnMenuProvider}. */\nexport function isColumnMenuProvider(controller: unknown): controller is ColumnMenuProvider {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as ColumnMenuProvider).providesColumnMenu === 'function'\n  );\n}\n\n/** The kind of pointer interaction forwarded from a body cell. */\nexport type CellInteractionKind = 'down' | 'over' | 'up';\n\n/** A pointer interaction on a body cell, forwarded to feature modules. */\nexport interface CellInteraction<T extends object = any> {\n  /** `down` on press, `over` while the pointer moves across cells, `up` on release. */\n  readonly kind: CellInteractionKind;\n  /** The cell's row data. */\n  readonly row: T;\n  /** Index of the row within the current page/view (matches `host.pageItems`). */\n  readonly rowIndex: number;\n  /** The cell's column configuration. */\n  readonly column: ColumnConfiguration<T>;\n  readonly shiftKey: boolean;\n  readonly ctrlKey: boolean;\n  readonly metaKey: boolean;\n  /** The originating pointer event (e.g. to call `preventDefault`). */\n  readonly originalEvent: PointerEvent;\n}\n\n/**\n * Optional capability a feature module's controller may implement to receive\n * pointer interactions on body cells (press / drag-over / release) — the seam a\n * range-selection feature uses to track a drag. The grid forwards interactions\n * only when at least one feature module is registered, so the community grid\n * pays nothing.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface CellInteractionHandler<T extends object = any> {\n  handleCellInteraction(interaction: CellInteraction<T>): void;\n}\n\n/** Runtime type-guard for {@link CellInteractionHandler}. */\nexport function isCellInteractionHandler<T extends object>(\n  controller: unknown\n): controller is CellInteractionHandler<T> {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as CellInteractionHandler<T>).handleCellInteraction === 'function'\n  );\n}\n\n/**\n * Optional capability a feature module's controller may implement so its state\n * participates in grid-state snapshots ({@link StateController.serializeModuleState}\n * / {@link StateController.restoreModuleState}, driven by `ApexGrid.getState` /\n * `ApexGrid.setState`). The grid collects each implementer's\n * {@link serializeState} output under the module's id and dispatches the\n * matching value back via {@link restoreState} on restore. Ids with no\n * implementer are reported back by {@link StateController.restoreModuleState}.\n *\n * Controllers that don't implement this are skipped, so the community grid\n * (which registers no modules) contributes nothing to a snapshot.\n *\n * @remarks Unstable; part of `apex-grid/internal`.\n */\nexport interface SerializableModule {\n  /**\n   * Return a JSON-serializable snapshot of this module's restorable state\n   * (e.g. the options the feature was configured with). Exclude transient/derived\n   * state and anything not JSON-safe (functions, DOM nodes).\n   */\n  serializeState(): unknown;\n  /**\n   * Restore module state from a value previously produced by\n   * {@link serializeState}. Implementations should tolerate partial or\n   * unexpected shapes (validate before applying) since the blob is opaque.\n   */\n  restoreState(data: unknown): void;\n}\n\n/** Runtime type-guard for {@link SerializableModule}. */\nexport function isSerializableModule(controller: unknown): controller is SerializableModule {\n  return (\n    typeof controller === 'object' &&\n    controller !== null &&\n    typeof (controller as SerializableModule).serializeState === 'function' &&\n    typeof (controller as SerializableModule).restoreState === 'function'\n  );\n}\n"]}

package/internal/index.d.ts

@@ -11,14 +11,16 @@
  * minor releases. Do not depend on them from third-party code.
  */
 export { ApexGrid } from '../components/grid.js';
+export { viewIndexer } from '../controllers/history.js';
 export { gridStateContext, StateController } from '../controllers/state.js';
+export { clampRating, commitDateInSameShape, getColumnTypeRenderer, getRatingMax, getSelectOptions, parseDate, } from './column-types.js';
 export { PIPELINE } from './constants.js';
 export type { ExportCellValue, ExportFormat, ExportOptions } from './export.js';
-export { downloadBlob, getColumnLabel, resolveExportColumns, resolveExportRows, resolveExportValue, } from './export.js';
-export type { CellDecoration, CellDecorator, CellDecoratorContext, CellInteraction, CellInteractionHandler, CellInteractionKind, ColumnMenuProvider, GridFeatureModule, PresentedRow, RowAria, RowAriaProvider, RowPresenter, RowPresenterContext, RowTransformer, SerializableModule, } from './feature-module.js';
-export { isCellDecorator, isCellInteractionHandler, isColumnMenuProvider, isRowAriaProvider, isRowPresenter, isRowTransformer, isSerializableModule, } from './feature-module.js';
+export { downloadBlob, escapeCSVCell, escapeFormula, getColumnLabel, resolveExportColumns, resolveExportRows, resolveExportValue, } from './export.js';
+export type { CellDecoration, CellDecorator, CellDecoratorContext, CellInteraction, CellInteractionHandler, CellInteractionKind, ColumnMenuProvider, CoordinateLabeler, GridFeatureModule, PresentedRow, RowAria, RowAriaProvider, RowPresenter, RowPresenterContext, RowTransformer, SerializableModule, } from './feature-module.js';
+export { isCellDecorator, isCellInteractionHandler, isColumnMenuProvider, isCoordinateLabeler, isRowAriaProvider, isRowPresenter, isRowTransformer, isSerializableModule, } from './feature-module.js';
 export { registerComponent } from './register.js';
 export type { ColumnLayoutState, FilterStateSnapshot, GetStateOptions, GridState, RowRef, SetStateOptions, SortStateSnapshot, } from './state-snapshot.js';
-export { applyColumnLayout, deserializeFilter, resolveRowRefs, serializeColumnLayout, serializeFilter, serializeRowRefs, serializeSort, } from './state-snapshot.js';
+export { applyColumnLayout, deserializeFilter, mergeColumnLayout, registerFilterOperand, resolveFilterOperand, resolveRowRefs, serializeColumnLayout, serializeFilter, serializeRowRefs, serializeSort, } from './state-snapshot.js';
 export type { ActiveNode, ColumnConfiguration, GridHost, Keys, ToolbarAction } from './types.js';
 export { getDisplayColumns } from './utils.js';

package/internal/index.js

@@ -1,9 +1,11 @@
 export { ApexGrid } from '../components/grid.js';
+export { viewIndexer } from '../controllers/history.js';
 export { gridStateContext, StateController } from '../controllers/state.js';
+export { clampRating, commitDateInSameShape, getColumnTypeRenderer, getRatingMax, getSelectOptions, parseDate, } from './column-types.js';
 export { PIPELINE } from './constants.js';
-export { downloadBlob, getColumnLabel, resolveExportColumns, resolveExportRows, resolveExportValue, } from './export.js';
-export { isCellDecorator, isCellInteractionHandler, isColumnMenuProvider, isRowAriaProvider, isRowPresenter, isRowTransformer, isSerializableModule, } from './feature-module.js';
+export { downloadBlob, escapeCSVCell, escapeFormula, getColumnLabel, resolveExportColumns, resolveExportRows, resolveExportValue, } from './export.js';
+export { isCellDecorator, isCellInteractionHandler, isColumnMenuProvider, isCoordinateLabeler, isRowAriaProvider, isRowPresenter, isRowTransformer, isSerializableModule, } from './feature-module.js';
 export { registerComponent } from './register.js';
-export { applyColumnLayout, deserializeFilter, resolveRowRefs, serializeColumnLayout, serializeFilter, serializeRowRefs, serializeSort, } from './state-snapshot.js';
+export { applyColumnLayout, deserializeFilter, mergeColumnLayout, registerFilterOperand, resolveFilterOperand, resolveRowRefs, serializeColumnLayout, serializeFilter, serializeRowRefs, serializeSort, } from './state-snapshot.js';
 export { getDisplayColumns } from './utils.js';
 //# sourceMappingURL=index.js.map

package/internal/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internal/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAkBrB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUlD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC","sourcesContent":["/**\n * Unstable, first-party extension surface for `apex-grid`.\n *\n * This entry point (`apex-grid/internal`) exposes the internals that the\n * first-party `@apexcharts/grid-enterprise` package builds on: the grid class,\n * its state controller, the component registration helper, and the feature\n * module contract. It is intentionally separate from the public `.` barrel.\n *\n * @remarks\n * No semver guarantees are made for these exports. They may change between\n * minor releases. Do not depend on them from third-party code.\n */\nexport { ApexGrid } from '../components/grid.js';\nexport { gridStateContext, StateController } from '../controllers/state.js';\nexport { PIPELINE } from './constants.js';\nexport type { ExportCellValue, ExportFormat, ExportOptions } from './export.js';\nexport {\n  downloadBlob,\n  getColumnLabel,\n  resolveExportColumns,\n  resolveExportRows,\n  resolveExportValue,\n} from './export.js';\nexport type {\n  CellDecoration,\n  CellDecorator,\n  CellDecoratorContext,\n  CellInteraction,\n  CellInteractionHandler,\n  CellInteractionKind,\n  ColumnMenuProvider,\n  GridFeatureModule,\n  PresentedRow,\n  RowAria,\n  RowAriaProvider,\n  RowPresenter,\n  RowPresenterContext,\n  RowTransformer,\n  SerializableModule,\n} from './feature-module.js';\nexport {\n  isCellDecorator,\n  isCellInteractionHandler,\n  isColumnMenuProvider,\n  isRowAriaProvider,\n  isRowPresenter,\n  isRowTransformer,\n  isSerializableModule,\n} from './feature-module.js';\nexport { registerComponent } from './register.js';\nexport type {\n  ColumnLayoutState,\n  FilterStateSnapshot,\n  GetStateOptions,\n  GridState,\n  RowRef,\n  SetStateOptions,\n  SortStateSnapshot,\n} from './state-snapshot.js';\nexport {\n  applyColumnLayout,\n  deserializeFilter,\n  resolveRowRefs,\n  serializeColumnLayout,\n  serializeFilter,\n  serializeRowRefs,\n  serializeSort,\n} from './state-snapshot.js';\nexport type { ActiveNode, ColumnConfiguration, GridHost, Keys, ToolbarAction } from './types.js';\nexport { getDisplayColumns } from './utils.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/internal/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAmBrB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUlD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC","sourcesContent":["/**\n * Unstable, first-party extension surface for `apex-grid`.\n *\n * This entry point (`apex-grid/internal`) exposes the internals that the\n * first-party `@apexcharts/grid-enterprise` package builds on: the grid class,\n * its state controller, the component registration helper, and the feature\n * module contract. It is intentionally separate from the public `.` barrel.\n *\n * @remarks\n * No semver guarantees are made for these exports. They may change between\n * minor releases. Do not depend on them from third-party code.\n */\nexport { ApexGrid } from '../components/grid.js';\nexport { viewIndexer } from '../controllers/history.js';\nexport { gridStateContext, StateController } from '../controllers/state.js';\nexport {\n  clampRating,\n  commitDateInSameShape,\n  getColumnTypeRenderer,\n  getRatingMax,\n  getSelectOptions,\n  parseDate,\n} from './column-types.js';\nexport { PIPELINE } from './constants.js';\nexport type { ExportCellValue, ExportFormat, ExportOptions } from './export.js';\nexport {\n  downloadBlob,\n  escapeCSVCell,\n  escapeFormula,\n  getColumnLabel,\n  resolveExportColumns,\n  resolveExportRows,\n  resolveExportValue,\n} from './export.js';\nexport type {\n  CellDecoration,\n  CellDecorator,\n  CellDecoratorContext,\n  CellInteraction,\n  CellInteractionHandler,\n  CellInteractionKind,\n  ColumnMenuProvider,\n  CoordinateLabeler,\n  GridFeatureModule,\n  PresentedRow,\n  RowAria,\n  RowAriaProvider,\n  RowPresenter,\n  RowPresenterContext,\n  RowTransformer,\n  SerializableModule,\n} from './feature-module.js';\nexport {\n  isCellDecorator,\n  isCellInteractionHandler,\n  isColumnMenuProvider,\n  isCoordinateLabeler,\n  isRowAriaProvider,\n  isRowPresenter,\n  isRowTransformer,\n  isSerializableModule,\n} from './feature-module.js';\nexport { registerComponent } from './register.js';\nexport type {\n  ColumnLayoutState,\n  FilterStateSnapshot,\n  GetStateOptions,\n  GridState,\n  RowRef,\n  SetStateOptions,\n  SortStateSnapshot,\n} from './state-snapshot.js';\nexport {\n  applyColumnLayout,\n  deserializeFilter,\n  mergeColumnLayout,\n  registerFilterOperand,\n  resolveFilterOperand,\n  resolveRowRefs,\n  serializeColumnLayout,\n  serializeFilter,\n  serializeRowRefs,\n  serializeSort,\n} from './state-snapshot.js';\nexport type { ActiveNode, ColumnConfiguration, GridHost, Keys, ToolbarAction } from './types.js';\nexport { getDisplayColumns } from './utils.js';\n"]}

package/internal/normalize-case.d.ts

@@ -1 +1,8 @@
-export declare function normalizeCase(string: string, caseSensitive?: boolean): string;
+/**
+ * The text a string filter operand compares: strings as they are, `null` and
+ * `undefined` as `''`, any other value (number, Date, array) through `String`,
+ * case-folded unless `caseSensitive`. Total, so a cell of any type can be
+ * matched by a string condition without throwing. A string cell allocates
+ * nothing beyond the case fold.
+ */
+export declare function normalizeCase(value: unknown, caseSensitive?: boolean): string;

package/internal/normalize-case.js

@@ -1,4 +1,5 @@
-export function normalizeCase(string, caseSensitive) {
-    return caseSensitive ? string : string.toLowerCase();
+export function normalizeCase(value, caseSensitive) {
+    const text = typeof value === 'string' ? value : value == null ? '' : String(value);
+    return caseSensitive ? text : text.toLowerCase();
 }
 //# sourceMappingURL=normalize-case.js.map

package/internal/normalize-case.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-case.js","sourceRoot":"","sources":["../../src/internal/normalize-case.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,aAAuB;IACnE,OAAO,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;AACvD,CAAC","sourcesContent":["export function normalizeCase(string: string, caseSensitive?: boolean) {\n  return caseSensitive ? string : string.toLowerCase();\n}\n"]}
+{"version":3,"file":"normalize-case.js","sourceRoot":"","sources":["../../src/internal/normalize-case.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,aAAuB;IACnE,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpF,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;AACnD,CAAC","sourcesContent":["/**\n * The text a string filter operand compares: strings as they are, `null` and\n * `undefined` as `''`, any other value (number, Date, array) through `String`,\n * case-folded unless `caseSensitive`. Total, so a cell of any type can be\n * matched by a string condition without throwing. A string cell allocates\n * nothing beyond the case fold.\n */\nexport function normalizeCase(value: unknown, caseSensitive?: boolean): string {\n  const text = typeof value === 'string' ? value : value == null ? '' : String(value);\n  return caseSensitive ? text : text.toLowerCase();\n}\n"]}

package/internal/state-snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { FilterCriteria, FilterExpression } from '../operations/filter/types.js';
+import type { FilterCriteria, FilterExpression, FilterOperation } from '../operations/filter/types.js';
 import type { SortExpression, SortingDirection } from '../operations/sort/types.js';
 import type { ColumnConfiguration, PinPosition } from './types.js';
 /**
@@ -105,6 +105,27 @@ export interface SetStateOptions<T extends object> {
      */
     strict?: boolean;
 }
+/**
+ * The `setState` slices in the order `setState` applies them, each mapped to
+ * the {@link GridState} keys it restores (`tree` restores both tree keys).
+ */
+export declare const SET_STATE_SLICE_KEYS: {
+    readonly columns: readonly ["columns"];
+    readonly sort: readonly ["sort"];
+    readonly filter: readonly ["filter"];
+    readonly quickFilter: readonly ["quickFilter"];
+    readonly modules: readonly ["modules"];
+    readonly rowOrder: readonly ["rowOrder"];
+    readonly tree: readonly ["treeExpanded", "treeExpandedKeys"];
+    readonly expansion: readonly ["expansion"];
+    readonly rowPinning: readonly ["rowPinning"];
+    readonly selection: readonly ["selection"];
+    readonly pagination: readonly ["pagination"];
+};
+/** A `setState` slice name, as reported in {@link SetStateResult}. */
+export type SetStateSlice = keyof typeof SET_STATE_SLICE_KEYS;
+/** Every slice name, in apply order. */
+export declare const SET_STATE_SLICES: SetStateSlice[];
 /**
  * The outcome of an {@link SetStateOptions} apply. `setState` never throws on
  * malformed input (unless `strict`): it applies recognized slices, skips the
@@ -112,9 +133,12 @@ export interface SetStateOptions<T extends object> {
  * clamped, or unresolved.
  */
 export interface SetStateResult {
-    /** Slice names that were present and applied (e.g. `'sort'`, `'columns'`). */
+    /**
+     * Slice names that were present and applied (e.g. `'sort'`, `'columns'`); see
+     * {@link SET_STATE_SLICE_KEYS} for the {@link GridState} keys of each.
+     */
     applied: string[];
-    /** Known slice names that were absent (left untouched). */
+    /** Known slice names ({@link SetStateSlice}) that were absent or not applied. */
     skipped: string[];
     /** What was dropped / clamped / unresolved, one message each. */
     warnings: string[];
@@ -125,28 +149,56 @@ export declare function serializeColumnLayout<T extends object>(columns: Readonl
  * 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.
+ * from `layout` are appended unchanged; layout entries with no matching column,
+ * a repeated key, or no string `key` are ignored. This is the full-layout
+ * restorer: to change a few fields in place, overlay them with
+ * {@link mergeColumnLayout} first.
  */
 export declare function applyColumnLayout<T extends object>(columns: ReadonlyArray<ColumnConfiguration<T>>, layout: ReadonlyArray<ColumnLayoutState>): ColumnConfiguration<T>[];
+/**
+ * Overlay a partial layout onto `current` (a full {@link serializeColumnLayout}
+ * result): each `partial` entry changes only the fields it defines on the
+ * column with the same key, and the order of `current` is kept. `null` clears
+ * a field (e.g. `pinned: null` unpins). Entries for unknown keys are ignored.
+ * Returns a new full layout to hand to `setState({ columns })`.
+ */
+export declare function mergeColumnLayout(current: ReadonlyArray<ColumnLayoutState>, partial: ReadonlyArray<Partial<Record<keyof ColumnLayoutState, unknown>>>): ColumnLayoutState[];
 export declare function serializeSort<T extends object>(expressions: ReadonlyArray<SortExpression<T>>): SortStateSnapshot[];
 export declare function serializeFilter<T extends object>(expressions: ReadonlyArray<FilterExpression<T>>): FilterStateSnapshot[];
+/**
+ * Make `operation` resolvable by its `name` on every column, after the
+ * column type's own operands. For first-party filter UIs (the enterprise set
+ * filter) whose expressions must survive `setState(getState())`. The
+ * operation must be stateless: everything it needs travels in `searchTerm`.
+ */
+export declare function registerFilterOperand(operation: FilterOperation<unknown>): void;
+/**
+ * Resolve a filter operand name (e.g. `'contains'`) to the live
+ * {@link FilterOperation} of `column`'s type, else to one registered with
+ * {@link registerFilterOperand}. Only the tables' own names resolve, so
+ * `'toString'` or `'constructor'` never pass as operands.
+ */
+export declare function resolveFilterOperand<T extends object>(column: ColumnConfiguration<T>, name: unknown): FilterOperation<unknown> | undefined;
 /**
  * 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.
+ * Entries that are not keyed objects, whose column or operand can't be
+ * resolved, or whose binary operand has no `searchTerm` 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.
+ * Index mode builds one position map per call, so it is linear in the sizes
+ * of `rows` and `universe` rather than their product.
  */
 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.
+ * positionally and must be non-negative integers. Refs that are not objects,
+ * and 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

@@ -1,4 +1,23 @@
 import { getFilterOperandsFor } from './utils.js';
+export const SET_STATE_SLICE_KEYS = {
+    columns: ['columns'],
+    sort: ['sort'],
+    filter: ['filter'],
+    quickFilter: ['quickFilter'],
+    modules: ['modules'],
+    rowOrder: ['rowOrder'],
+    tree: ['treeExpanded', 'treeExpandedKeys'],
+    expansion: ['expansion'],
+    rowPinning: ['rowPinning'],
+    selection: ['selection'],
+    pagination: ['pagination'],
+};
+export const SET_STATE_SLICES = Object.keys(SET_STATE_SLICE_KEYS);
+const _everyKeyHasASlice = true;
+void _everyKeyHasASlice;
+function isKeyed(value) {
+    return typeof value === 'object' && value !== null && typeof value.key === 'string';
+}
 export function serializeColumnLayout(columns) {
     return columns.map((column) => ({
         key: String(column.key),
@@ -14,6 +33,8 @@ export function applyColumnLayout(columns, layout) {
     const used = new Set();
     const ordered = [];
     for (const entry of layout) {
+        if (!isKeyed(entry) || used.has(entry.key))
+            continue;
         const column = byKey.get(entry.key);
         if (!column)
             continue;
@@ -31,6 +52,24 @@ export function applyColumnLayout(columns, layout) {
     }
     return ordered;
 }
+export function mergeColumnLayout(current, partial) {
+    const patches = new Map();
+    for (const entry of partial) {
+        if (isKeyed(entry))
+            patches.set(entry.key, entry);
+    }
+    return current.map((column) => {
+        const next = { ...column };
+        const patch = patches.get(column.key);
+        if (patch) {
+            for (const field of ['width', 'pinned', 'hidden']) {
+                if (patch[field] !== undefined)
+                    next[field] = patch[field] ?? undefined;
+            }
+        }
+        return next;
+    });
+}
 export function serializeSort(expressions) {
     return expressions.map((expression) => ({
         key: String(expression.key),
@@ -38,53 +77,80 @@ export function serializeSort(expressions) {
         caseSensitive: expression.caseSensitive,
     }));
 }
+function copyTerm(term) {
+    return Array.isArray(term) ? [...term] : term;
+}
 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,
+            searchTerm: copyTerm(expression.searchTerm),
             criteria: expression.criteria,
             caseSensitive: expression.caseSensitive,
         };
     });
 }
+const registeredOperands = new Map();
+export function registerFilterOperand(operation) {
+    registeredOperands.set(operation.name, operation);
+}
+export function resolveFilterOperand(column, name) {
+    if (typeof name !== 'string')
+        return undefined;
+    const operands = getFilterOperandsFor(column);
+    return Object.hasOwn(operands, name) ? operands[name] : registeredOperands.get(name);
+}
 export function deserializeFilter(snapshots, getColumn, onDrop) {
     const expressions = [];
     for (const snapshot of snapshots) {
+        if (!isKeyed(snapshot)) {
+            onDrop?.({ key: String(snapshot) }, 'not a filter entry');
+            continue;
+        }
         const column = getColumn(snapshot.key);
         if (!column) {
             onDrop?.(snapshot, 'unknown column');
             continue;
         }
-        const operands = getFilterOperandsFor(column);
-        const condition = operands[snapshot.operand];
+        const condition = resolveFilterOperand(column, 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,
-        });
+        if (!condition.unary && (snapshot.searchTerm === undefined || snapshot.searchTerm === null)) {
+            onDrop?.(snapshot, `operand "${snapshot.operand}" needs a searchTerm`);
+            continue;
+        }
+        const expression = { key: snapshot.key, condition };
+        if (snapshot.searchTerm !== undefined)
+            expression.searchTerm = copyTerm(snapshot.searchTerm);
+        if (snapshot.criteria !== undefined)
+            expression.criteria = snapshot.criteria;
+        if (snapshot.caseSensitive !== undefined)
+            expression.caseSensitive = snapshot.caseSensitive;
+        expressions.push(expression);
     }
     return expressions;
 }
 export function serializeRowRefs(rows, universe, rowId) {
+    if (rowId)
+        return rows.map((row) => ({ id: rowId(row) }));
+    if (rows.length < 2) {
+        const index = rows.length ? universe.indexOf(rows[0]) : -1;
+        return index === -1 ? [] : [{ index }];
+    }
+    const positions = new Map();
+    universe.forEach((row, index) => {
+        if (!positions.has(row))
+            positions.set(row, index);
+    });
     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 });
-        }
+        const index = positions.get(row);
+        if (index !== undefined)
+            refs.push({ index });
     }
     return refs;
 }
@@ -92,6 +158,8 @@ export function resolveRowRefs(refs, universe, rowId) {
     const out = [];
     let byId = null;
     for (const ref of refs) {
+        if (typeof ref !== 'object' || ref === null)
+            continue;
         if ('id' in ref) {
             if (!rowId)
                 continue;
@@ -104,7 +172,7 @@ export function resolveRowRefs(refs, universe, rowId) {
             if (row)
                 out.push(row);
         }
-        else {
+        else if (Number.isInteger(ref.index) && ref.index >= 0) {
             const row = universe[ref.index];
             if (row)
                 out.push(row);