@toolbox-web/grid 2.2.0 → 2.4.0

package/lib/core/adapter-conformance.d.ts

@@ -0,0 +1,23 @@
+import { FrameworkAdapter } from './types';
+/**
+ * Method names that are technically optional on {@link FrameworkAdapter}
+ * but are actually consumed by the grid core. An adapter that skips any
+ * of these silently drops the matching feature for its framework users.
+ */
+export declare const CORE_CONSUMED_ADAPTER_METHODS: ReadonlyArray<keyof FrameworkAdapter>;
+export interface AdapterConformanceReport {
+    name: string;
+    implemented: (keyof FrameworkAdapter)[];
+    missing: (keyof FrameworkAdapter)[];
+}
+/**
+ * Inspect an adapter and report which core-consumed hooks are implemented
+ * vs. missing. Performs a shallow `typeof adapter[name] === 'function'`
+ * check — works for class instances, prototypes, and plain objects.
+ */
+export declare function reportAdapterConformance(adapter: FrameworkAdapter): AdapterConformanceReport;
+/**
+ * Assert that an adapter implements every core-consumed hook.
+ * Throws listing the missing method names. Intended for unit tests.
+ */
+export declare function assertAdapterConformance(adapter: FrameworkAdapter): void;

package/lib/core/grid.d.ts

@@ -1,3 +1,4 @@
+import { RenderPhase } from './internal/render-scheduler';
 import { ShellState } from './internal/shell';
 import { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from './plugin';
 import { BaseGridPlugin } from './plugin/base-plugin';
@@ -511,7 +512,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     /** Updates ARIA row/col counts. Delegates to aria.ts module. */
     _updateAriaCounts(rowCount: number, colCount: number): void;
     /** @internal Request a render at the given phase through the scheduler. */
-    _requestSchedulerPhase(phase: number, source: string): void;
+    _requestSchedulerPhase(phase: RenderPhase, source: string): void;
     /** @internal Plugin-specific row height override. */
     _getPluginRowHeight(row: T, index: number): number | undefined;
     /** @internal Let plugins adjust the virtual start index backwards. */
@@ -1222,15 +1223,21 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      *
      * // Later, restore the state
      * const saved = localStorage.getItem('gridState');
-     * if (saved) {
-     *   grid.columnState = JSON.parse(saved);
-     * }
+     * if (saved) grid.applyColumnState(JSON.parse(saved));
      * ```
      */
     getColumnState(): GridColumnState;
     /**
-     * Set the column state, restoring all saved preferences.
-     * Can be set before or after grid initialization.
+     * Get the current column state.
+     * Alias for `getColumnState()` for property-style read access.
+     * @group State Persistence
+     */
+    get columnState(): GridColumnState | undefined;
+    /**
+     * Apply a previously saved column state, restoring column order, widths,
+     * visibility, sort, and any plugin-contributed state. Can be called
+     * before or after grid initialization — pre-init calls are deferred and
+     * applied during setup.
      *
      * @group State Persistence
      * @fires column-state-change - Emitted after state is applied (if grid is initialized)
@@ -1239,18 +1246,10 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * // Restore saved state on page load
      * const grid = queryGrid('tbw-grid');
      * const saved = localStorage.getItem('myGridState');
-     * if (saved) {
-     *   grid.columnState = JSON.parse(saved);
-     * }
+     * if (saved) grid.applyColumnState(JSON.parse(saved));
      * ```
      */
-    set columnState(state: GridColumnState | undefined);
-    /**
-     * Get the current column state.
-     * Alias for `getColumnState()` for property-style access.
-     * @group State Persistence
-     */
-    get columnState(): GridColumnState | undefined;
+    applyColumnState(state: GridColumnState | undefined): void;
     /**
      * Get the current single-column sort state.
      *

package/lib/core/internal/diagnostics.d.ts

@@ -64,8 +64,12 @@ export declare const MISSING_DEPENDENCY: "TBW020";
 export declare const OPTIONAL_DEPENDENCY: "TBW021";
 /** Two loaded plugins are incompatible. */
 export declare const INCOMPATIBLE_PLUGINS: "TBW022";
+/** Two plugin instances resolve to the same canonical name (alias collapse). */
+export declare const PLUGIN_ALIAS_COLLAPSE: "TBW023";
 /** Error thrown inside a plugin event handler. */
 export declare const PLUGIN_EVENT_ERROR: "TBW024";
+/** Conflicting config values found while merging alias-collapsed plugin instances. */
+export declare const PLUGIN_ALIAS_CONFIG_CONFLICT: "TBW025";
 /** Feature was re-registered (overwritten). */
 export declare const FEATURE_REREGISTERED: "TBW030";
 /** Feature configured but not imported. */
@@ -136,7 +140,7 @@ export declare const DATASOURCE_CHILD_FETCH_ERROR: "TBW141";
 export declare const DATASOURCE_NO_CHILD_HANDLER: "TBW142";
 /** ServerSidePlugin: concurrent request limit reached, request deferred. */
 export declare const DATASOURCE_THROTTLED: "TBW143";
-export type DiagnosticCode = typeof MISSING_PLUGIN | typeof MISSING_PLUGIN_CONFIG | typeof CONFIG_RULE_ERROR | typeof CONFIG_RULE_WARN | typeof MISSING_DEPENDENCY | typeof OPTIONAL_DEPENDENCY | typeof INCOMPATIBLE_PLUGINS | typeof PLUGIN_EVENT_ERROR | typeof FEATURE_REREGISTERED | typeof FEATURE_NOT_IMPORTED | typeof FEATURE_MISSING_DEP | typeof MISSING_ROW_ID | typeof ROW_NOT_FOUND | typeof INVALID_COLUMN_WIDTH | typeof ROW_CLASS_ERROR | typeof CELL_CLASS_ERROR | typeof FORMAT_ERROR | typeof VIEW_MOUNT_ERROR | typeof VIEW_DISPATCH_ERROR | typeof TOOL_PANEL_MISSING_ATTR | typeof NO_TOOL_PANELS | typeof TOOL_PANEL_NOT_FOUND | typeof TOOL_PANEL_DUPLICATE | typeof HEADER_CONTENT_DUPLICATE | typeof TOOLBAR_CONTENT_DUPLICATE | typeof EDITOR_MOUNT_ERROR | typeof PRINT_IN_PROGRESS | typeof PRINT_NO_GRID | typeof PRINT_FAILED | typeof PRINT_DUPLICATE_ID | typeof CLIPBOARD_FAILED | typeof MISSING_BREAKPOINT | typeof TRANSACTION_IN_PROGRESS | typeof NO_TRANSACTION | typeof COLUMN_GROUP_NO_ID | typeof COLUMN_GROUPS_CONFLICT | typeof STYLE_EXTRACT_FAILED | typeof STYLE_NOT_FOUND | typeof INVALID_ATTRIBUTE_JSON | typeof DATASOURCE_FETCH_ERROR | typeof DATASOURCE_CHILD_FETCH_ERROR | typeof DATASOURCE_NO_CHILD_HANDLER | typeof DATASOURCE_THROTTLED;
+export type DiagnosticCode = typeof MISSING_PLUGIN | typeof MISSING_PLUGIN_CONFIG | typeof CONFIG_RULE_ERROR | typeof CONFIG_RULE_WARN | typeof MISSING_DEPENDENCY | typeof OPTIONAL_DEPENDENCY | typeof INCOMPATIBLE_PLUGINS | typeof PLUGIN_ALIAS_COLLAPSE | typeof PLUGIN_EVENT_ERROR | typeof PLUGIN_ALIAS_CONFIG_CONFLICT | typeof FEATURE_REREGISTERED | typeof FEATURE_NOT_IMPORTED | typeof FEATURE_MISSING_DEP | typeof MISSING_ROW_ID | typeof ROW_NOT_FOUND | typeof INVALID_COLUMN_WIDTH | typeof ROW_CLASS_ERROR | typeof CELL_CLASS_ERROR | typeof FORMAT_ERROR | typeof VIEW_MOUNT_ERROR | typeof VIEW_DISPATCH_ERROR | typeof TOOL_PANEL_MISSING_ATTR | typeof NO_TOOL_PANELS | typeof TOOL_PANEL_NOT_FOUND | typeof TOOL_PANEL_DUPLICATE | typeof HEADER_CONTENT_DUPLICATE | typeof TOOLBAR_CONTENT_DUPLICATE | typeof EDITOR_MOUNT_ERROR | typeof PRINT_IN_PROGRESS | typeof PRINT_NO_GRID | typeof PRINT_FAILED | typeof PRINT_DUPLICATE_ID | typeof CLIPBOARD_FAILED | typeof MISSING_BREAKPOINT | typeof TRANSACTION_IN_PROGRESS | typeof NO_TRANSACTION | typeof COLUMN_GROUP_NO_ID | typeof COLUMN_GROUPS_CONFLICT | typeof STYLE_EXTRACT_FAILED | typeof STYLE_NOT_FOUND | typeof INVALID_ATTRIBUTE_JSON | typeof DATASOURCE_FETCH_ERROR | typeof DATASOURCE_CHILD_FETCH_ERROR | typeof DATASOURCE_NO_CHILD_HANDLER | typeof DATASOURCE_THROTTLED;
 /**
  * Format a diagnostic message with prefix, code, and docs link.
  *

package/lib/core/internal/dom-builder.d.ts

@@ -8,31 +8,6 @@
  *
  * Benchmark: DOM construction is ~2-3x faster than innerHTML for complex structures.
  */
-/**
- * Create an element with attributes and optional children.
- * Optimized helper that avoids repeated function calls.
- */
-export declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, children?: (Node | string | null | undefined)[]): HTMLElementTagNameMap[K];
-/**
- * Create a text node (shorthand).
- */
-export declare function text(content: string): Text;
-/**
- * Create an element with class (common pattern).
- */
-export declare function div(className?: string, attrs?: Record<string, string>): HTMLDivElement;
-/**
- * Create a button element.
- */
-export declare function button(className?: string, attrs?: Record<string, string>, content?: string | Node): HTMLButtonElement;
-/**
- * Append multiple children to a parent element.
- */
-export declare function appendChildren(parent: Element, children: (Node | null | undefined)[]): void;
-/**
- * Set multiple attributes on an element.
- */
-export declare function setAttrs(el: Element, attrs: Record<string, string | undefined>): void;
 /**
  * Clone the grid content structure.
  * Using template cloning is faster than createElement for nested structures.

package/lib/core/internal/drag-drop-registry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Drag-Drop Registry
+ *
+ * Module-level singleton that holds live (WeakRef) references to row objects
+ * being dragged across grids in the same JS heap. Used by `RowDragDropPlugin`
+ * to recover live references on drop, avoiding any serialization cost when
+ * source and target grids share a heap.
+ *
+ * Lives in `core/internal/` (not in the plugin bundle) so that two copies of
+ * `@toolbox-web/grid` loaded via different entry points (e.g. `/all` vs
+ * per-plugin imports) cannot end up with two separate registries that silently
+ * fall back to JSON.
+ *
+ * Cross-window / cross-origin-iframe drags do NOT go through this registry —
+ * they fall back to `dataTransfer` JSON.
+ *
+ * @internal
+ */
+/**
+ * Register a drag session's live row references.
+ *
+ * Object rows are stored as `WeakRef<object>`; primitive rows cannot be held
+ * weakly and would either need a sentinel (which corrupts the row value on
+ * recovery) or be omitted (which misaligns indices). We instead flag the
+ * session as containing primitives — `lookupDragSession()` then returns
+ * `undefined` so callers fall back to the JSON payload, which round-trips
+ * primitives losslessly.
+ *
+ * @param sessionId - Unique drag session identifier (typically a UUID).
+ * @param rows      - Rows being dragged.
+ * @param meta      - Optional opaque metadata to associate with the session.
+ */
+export declare function registerDragSession(sessionId: string, rows: readonly unknown[], meta?: unknown): void;
+/**
+ * Look up the live row references for a drag session.
+ *
+ * Returns `undefined` when the caller MUST fall back to the JSON payload:
+ *   - the session is unknown,
+ *   - any registered reference has been garbage-collected (partial recovery
+ *     would silently corrupt cross-grid moves), or
+ *   - the session contains primitive rows (which cannot be held weakly).
+ */
+export declare function lookupDragSession<T = unknown>(sessionId: string): T[] | undefined;
+/**
+ * Get the metadata associated with a drag session, if any.
+ */
+export declare function getDragSessionMeta<M = unknown>(sessionId: string): M | undefined;
+/**
+ * Clear a drag session from the registry.
+ * Should be called from `dragend` on the source grid.
+ */
+export declare function clearDragSession(sessionId: string): void;
+/**
+ * @internal Test-only — clear all sessions.
+ */
+export declare function _clearAllDragSessions(): void;
+/**
+ * Generate a unique drag session identifier.
+ *
+ * Used as a Map key to recover live row references for in-process drags; this
+ * is **not** a security context. Uses `crypto.randomUUID()` when available
+ * (modern browsers in secure contexts, Node 19+, Bun) and falls back to
+ * `crypto.getRandomValues()` for older non-secure contexts. `Math.random()`
+ * is intentionally avoided to keep CodeQL clean.
+ */
+export declare function newDragSessionId(): string;

package/lib/core/internal/render-scheduler.d.ts

@@ -5,20 +5,21 @@ import { InternalGrid } from '../types';
  *
  * @category Plugin Development
  */
-export declare enum RenderPhase {
+export declare const RenderPhase: {
     /** Lightweight style updates only (plugin afterRender hooks) */
-    STYLE = 1,
+    readonly STYLE: 1;
     /** Virtual window recalculation (includes STYLE) */
-    VIRTUALIZATION = 2,
+    readonly VIRTUALIZATION: 2;
     /** Header re-render (includes VIRTUALIZATION) */
-    HEADER = 3,
+    readonly HEADER: 3;
     /** Row model rebuild (includes HEADER) */
-    ROWS = 4,
+    readonly ROWS: 4;
     /** Column processing (includes ROWS) */
-    COLUMNS = 5,
+    readonly COLUMNS: 5;
     /** Full render including config merge (includes COLUMNS) */
-    FULL = 6
-}
+    readonly FULL: 6;
+};
+export type RenderPhase = (typeof RenderPhase)[keyof typeof RenderPhase];
 /**
  * @internal Scheduler now takes InternalGrid directly — no callback interface needed.
  */

package/lib/core/plugin/base-plugin.d.ts

@@ -368,6 +368,29 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridP
      */
     protected get defaultConfig(): Partial<TConfig>;
     constructor(config?: Partial<TConfig>);
+    /**
+     * Merge user-supplied configuration from other plugin instances into this
+     * plugin's `userConfig`. Used by `PluginManager.attachAll()`'s alias-collapse
+     * pre-pass: when a consumer instantiates the same plugin under multiple
+     * names (e.g. `RowReorderPlugin` and `RowDragDropPlugin`, which are aliases
+     * after V2.x), only one instance is attached, and the other instances'
+     * configs are folded in via this method.
+     *
+     * Merge rules (shallow):
+     *
+     * - Same key, **same value** → silent.
+     * - Same key, **different values** (incl. function vs function) → throws
+     *   a diagnostic naming the conflicting key. Conflicting callbacks
+     *   (`canDrag`, `canDrop`, etc.) cannot be reconciled automatically.
+     * - **Disjoint keys** → merged cleanly.
+     *
+     * Subclasses may override to implement custom deep-merge logic, but should
+     * call `super.mergeConfigsFrom(others)` to inherit the conflict-detection.
+     *
+     * @internal Plugin infrastructure (used by `PluginManager.attachAll`).
+     * @throws Error with diagnostic code `TBW025` when configs conflict.
+     */
+    mergeConfigsFrom(others: readonly BaseGridPlugin<TConfig>[]): void;
     /**
      * Called when the plugin is attached to a grid.
      * Override to set up event listeners, initialize state, etc.

package/lib/core/plugin/plugin-manager.d.ts

@@ -43,6 +43,15 @@ export declare class PluginManager {
     constructor(grid: GridElement);
     /**
      * Attach all plugins from the config.
+     *
+     * Runs an alias-collapse pre-pass before per-instance attach: when multiple
+     * plugin instances resolve to the same canonical constructor (e.g.
+     * `RowReorderPlugin` and `RowDragDropPlugin`, which point to the same class
+     * after V2.x), only the first instance is attached, and the others' user
+     * configs are folded into it via `BaseGridPlugin.mergeConfigsFrom()`.
+     *
+     * Skipped duplicates trigger a one-time `console.warn` with diagnostic code
+     * `TBW023` (suppressed in production builds via `import.meta.env.PROD`).
      */
     attachAll(plugins: BaseGridPlugin[]): void;
     /**

package/lib/core/types.d.ts

@@ -1,3 +1,4 @@
+import { RenderPhase } from './internal/render-scheduler';
 import { ShellState } from './internal/shell';
 import { RowPosition } from './internal/virtualization';
 import { AfterCellRenderContext, AfterRowRenderContext, CellMouseEvent } from './plugin/types';
@@ -219,18 +220,29 @@ export interface PublicGrid<T = any> {
      */
     getColumnState?(): GridColumnState;
     /**
-     * Set/restore the column state.
-     * Can be set before or after grid initialization.
+     * Read the current column state. Property-style accessor that mirrors
+     * {@link PublicGrid.getColumnState}. To restore state, use
+     * {@link PublicGrid.applyColumnState}.
      *
      * @example
      * ```typescript
-     * const saved = localStorage.getItem('gridState');
-     * if (saved) {
-     *   grid.columnState = JSON.parse(saved);
-     * }
+     * const snapshot = grid.columnState;
      * ```
      */
     columnState?: GridColumnState;
+    /**
+     * Apply a previously saved column state, restoring column order, widths,
+     * visibility, sort, and any plugin-contributed state. Can be called before
+     * or after grid initialization — pre-init calls are deferred and applied
+     * during setup.
+     *
+     * @example
+     * ```typescript
+     * const saved = localStorage.getItem('gridState');
+     * if (saved) grid.applyColumnState(JSON.parse(saved));
+     * ```
+     */
+    applyColumnState?(state: GridColumnState | undefined): void;
     /**
      * Get the current sort state.
      *
@@ -546,7 +558,7 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     _invalidateVisibleColumnsCache(): void;
     /** @internal */ _renderVisibleRows(start: number, end: number, epoch?: number): void;
     /** @internal */ _updateAriaCounts(totalRows: number, totalCols: number): void;
-    /** @internal */ _requestSchedulerPhase(phase: number, source: string): void;
+    /** @internal */ _requestSchedulerPhase(phase: RenderPhase, source: string): void;
     /** @internal */ _rebuildRowIdMap(): void;
     /** @internal */ _emitDataChange(): void;
     /** @internal */ _getPluginRowHeight(row: T, index: number): number | undefined;
@@ -874,7 +886,58 @@ export interface BaseColumnConfig<TRow = any, TValue = any> {
      * ```
      */
     format?: (value: TValue, row: TRow) => string;
-    /** Arbitrary extra metadata */
+    /**
+     * Marks this column as a **system / utility column** — a column that exists to
+     * support grid behaviour rather than to display user data.
+     *
+     * Built-in plugins set this on the columns they synthesize (selection checkbox,
+     * row-reorder drag handle, master-detail / tree / row-grouping expander). You can
+     * also set it on columns you author yourself when you want them to behave the same
+     * way — for example, a row-action menu column, a status indicator, or any
+     * developer-defined "system" column that should be visible in the grid only.
+     *
+     * Setting `utility: true` excludes the column from:
+     *
+     * - **Visibility panel** — not listed in the show/hide UI
+     * - **Column reorder** — header drag-drop and visibility-panel drag treat it as locked
+     *   (equivalent to `lockPosition: true`)
+     * - **Print** — hidden by `PrintPlugin` during print
+     * - **Clipboard copy** — skipped by `ClipboardPlugin`
+     * - **Export** (CSV / JSON / Excel) — skipped by `ExportPlugin`
+     * - **Range / row selection** — clicks land on the column but selection ignores it
+     * - **Filter UI** — no filter button rendered, no filter model entry
+     *
+     * The column is still rendered in the grid and still receives `cellRenderer` /
+     * `viewRenderer` / `headerRenderer` callbacks — it is "hidden from the system,
+     * visible in the grid".
+     *
+     * Convention: name the field with a `__`-prefix (e.g. `__actions`) so it cannot
+     * collide with a real data field.
+     *
+     * @example A custom row-actions column
+     * ```ts
+     * {
+     *   field: '__actions',
+     *   header: '',
+     *   width: 80,
+     *   utility: true,         // excluded from print, export, reorder, visibility, etc.
+     *   resizable: false,
+     *   sortable: false,
+     *   filterable: false,
+     *   viewRenderer: ({ row }) => createActionsButton(row),
+     * }
+     * ```
+     */
+    utility?: boolean;
+    /**
+     * Arbitrary extra metadata for application use.
+     *
+     * @remarks
+     * **Do not use `meta` for grid-recognized flags.** Properties like `lockPosition`,
+     * `lockVisible`, `lockPinning`, `pinned`, `utility`, and `checkboxColumn` are first-class
+     * augmented properties on `ColumnConfig` itself. Using `meta.<flag>` for any of them is
+     * deprecated and only kept as a runtime fallback for back-compat.
+     */
     meta?: Record<string, unknown>;
 }
 /**
@@ -1860,16 +1923,24 @@ export interface RowGroupRenderConfig {
  * - A built-in aggregator name: `'sum'`, `'avg'`, `'min'`, `'max'`, `'count'`
  * - A custom function that calculates the aggregate value
  *
+ * Aggregators are not declared on a column directly — they are configured per
+ * field on the consumer (e.g. {@link RowGroupRenderConfig.aggregators} for
+ * group rows, keyed by column field name).
+ *
  * @example
  * ```typescript
- * // Built-in aggregator
- * { field: 'amount', aggregator: 'sum' }
+ * // Built-in aggregator on a group row config
+ * { aggregators: { amount: 'sum' } }
  *
  * // Custom aggregator function
- * { field: 'price', aggregator: (rows, field) => {
- *   const values = rows.map(r => r[field]).filter(v => v != null);
- *   return values.length ? Math.max(...values) : null;
- * }}
+ * {
+ *   aggregators: {
+ *     price: (rows, field) => {
+ *       const values = rows.map((r) => (r as any)[field]).filter((v) => v != null);
+ *       return values.length ? Math.max(...values as number[]) : null;
+ *     },
+ *   },
+ * }
  * ```
  *
  * @see {@link RowGroupRenderConfig} for using aggregators in group rows
@@ -2305,32 +2376,46 @@ export interface GridConfig<TRow = any> {
      */
     animation?: AnimationConfig;
     /**
-     * Custom sort handler for full control over sorting behavior.
+     * Custom sort handler for the entire grid.
      *
-     * When provided, this handler is called instead of the built-in sorting logic.
-     * Enables custom sorting algorithms, server-side sorting, or plugin-specific sorting.
+     * :::caution
+     * **Prefer {@link BaseColumnConfig.sortComparator} over `sortHandler`.**
+     *
+     * `sortHandler` is a low-level escape hatch with significant limitations:
+     * - Only consulted by the **single-column** sort path (core header click,
+     *   `TreePlugin` per-level sort, `ServerSidePlugin` `sortMode: 'local'`).
+     * - **Bypassed entirely** when `MultiSortPlugin` is loaded.
+     * - Owns ALL columns at once — your handler must implement field/direction
+     *   dispatch and null handling for every sortable column itself.
+     *
+     * For per-column custom sort logic, use {@link BaseColumnConfig.sortComparator}
+     * instead. It is honored by every sort code path in the grid (core, multi-sort,
+     * tree, server-side) and is composable across columns.
+     *
+     * For server-side sort, prefer {@link ServerSideConfig.dataSource} — the
+     * `sortModel` is shipped to your `getRows` handler so the backend can return
+     * pre-sorted blocks.
+     * :::
+     *
+     * Use `sortHandler` only when you need to replace the grid's sort engine
+     * wholesale (e.g. integrating a third-party sort library that operates on
+     * the full row array, or routing every sort through a single async pipeline).
      *
      * The handler receives:
      * - `rows`: Current row array to sort
      * - `sortState`: Sort field and direction (1 = asc, -1 = desc)
      * - `columns`: Column configurations (for accessing sortComparator)
      *
-     * Return the sorted array (sync) or a Promise that resolves to the sorted array (async).
-     * For server-side sorting, return a Promise that resolves when data is fetched.
+     * Return the sorted array (sync) or a Promise that resolves to it (async).
      *
      * @example
      * ```ts
-     * // Custom stable sort
-     * sortHandler: (rows, state, cols) => {
-     *   return stableSort(rows, (a, b) => compare(a[state.field], b[state.field]) * state.direction);
-     * }
-     *
-     * // Server-side sorting
-     * sortHandler: async (rows, state) => {
-     *   const response = await fetch(`/api/data?sort=${state.field}&dir=${state.direction}`);
-     *   return response.json();
-     * }
+     * // Replace the entire client-side sort engine with a custom stable sort
+     * sortHandler: (rows, state) => stableSort(rows, state.field, state.direction);
      * ```
+     *
+     * @see {@link BaseColumnConfig.sortComparator} — recommended per-column override
+     * @see {@link ServerSideConfig.dataSource} — recommended server-side sort path
      */
     sortHandler?: SortHandler<TRow>;
     /**
@@ -2510,8 +2595,17 @@ export interface SortState {
 /**
  * Custom sort handler function signature.
  *
- * Enables full control over sorting behavior including server-side sorting,
- * custom algorithms, or multi-column sorting.
+ * :::caution
+ * **Prefer {@link BaseColumnConfig.sortComparator} over `SortHandler`.**
+ * `sortHandler` is bypassed by `MultiSortPlugin` and only sees the single
+ * active sort field. For per-column custom sort logic that survives every
+ * sort code path (core, multi-sort, tree, server-side), set `sortComparator`
+ * on the relevant columns instead. For server-side sort, use
+ * {@link ServerSideConfig.dataSource}.
+ * :::
+ *
+ * Use `SortHandler` only when you need to replace the grid's sort engine
+ * wholesale.
  *
  * @param rows - Current row array to sort
  * @param sortState - Sort field and direction
@@ -2520,32 +2614,17 @@ export interface SortState {
  *
  * @example
  * ```typescript
- * // Custom client-side sort with locale awareness
- * const localeSortHandler: SortHandler<Employee> = (rows, state, cols) => {
- *   const col = cols.find(c => c.field === state.field);
- *   return [...rows].sort((a, b) => {
- *     const aVal = String(a[state.field] ?? '');
- *     const bVal = String(b[state.field] ?? '');
- *     return aVal.localeCompare(bVal) * state.direction;
- *   });
+ * // Replace the built-in sort with a third-party stable sort library
+ * const customSortHandler: SortHandler<Employee> = (rows, state) => {
+ *   return thirdPartyStableSort(rows, state.field, state.direction);
  * };
  *
- * // Server-side sorting
- * const serverSortHandler: SortHandler<Employee> = async (rows, state) => {
- *   const response = await fetch(
- *     `/api/employees?sortBy=${state.field}&dir=${state.direction}`
- *   );
- *   return response.json();
- * };
- *
- * grid.gridConfig = {
- *   sortHandler: localeSortHandler,
- * };
+ * grid.gridConfig = { sortHandler: customSortHandler };
  * ```
  *
  * @see {@link SortState} for the sort state object
- * @see {@link GridConfig.sortHandler} for configuring the handler
- * @see {@link BaseColumnConfig.sortComparator} for column-level comparators
+ * @see {@link GridConfig.sortHandler} for configuring the handler (and its caveats)
+ * @see {@link BaseColumnConfig.sortComparator} — recommended per-column comparator
  */
 export type SortHandler<TRow = any> = (rows: TRow[], sortState: SortState, columns: ColumnConfig<TRow>[]) => TRow[] | Promise<TRow[]>;
 /**
@@ -3053,7 +3132,11 @@ export interface GridIcons {
     /** Print icon for print button. Default: '🖨️' */
     print?: IconValue;
 }
-/** Default icons used when not overridden */
+/** Default icons used when not overridden. Most entries are short text/emoji;
+ * `filter` and `filterActive` are empty strings because the actual rendering
+ * is driven by the `--tbw-icon-filter[-active]-mask` CSS custom properties
+ * (see `core/styles/variables.css`). Userland that wants an HTML/SVG fallback
+ * via `gridConfig.icons.filter = '<svg…>'` is unaffected — that path overrides this default. */
 export declare const DEFAULT_GRID_ICONS: Required<GridIcons>;
 /**
  * Shell configuration for the grid's optional header bar and tool panels.
@@ -3280,9 +3363,7 @@ export interface HeaderContentDefinition {
  *
  * // Restore on page load
  * const saved = localStorage.getItem('gridState');
- * if (saved) {
- *   grid.columnState = JSON.parse(saved);
- * }
+ * if (saved) grid.applyColumnState(JSON.parse(saved));
  *
  * // Example column state structure
  * const state: GridColumnState = {
@@ -3343,7 +3424,7 @@ export interface ColumnSortState {
  * localStorage.setItem('grid-state', JSON.stringify(state));
  *
  * // Restore state
- * grid.columnState = JSON.parse(localStorage.getItem('grid-state'));
+ * grid.applyColumnState(JSON.parse(localStorage.getItem('grid-state')));
  * ```
  *
  * @see {@link ColumnState} for individual column state
@@ -3838,7 +3919,7 @@ export interface DataGridEventMap<TRow = unknown> {
      *
      * // Restore on load
      * const saved = localStorage.getItem('grid-state');
-     * if (saved) grid.columnState = JSON.parse(saved);
+     * if (saved) grid.applyColumnState(JSON.parse(saved));
      * ```
      *
      * @see {@link GridColumnState}