@toolbox-web/grid 1.28.2 → 1.30.0

package/lib/core/constants.d.ts

@@ -12,7 +12,7 @@
  * See each plugin's index.ts for plugin-specific exports.
  */
 /**
- * CSS class names used in the grid's shadow DOM.
+ * CSS class names used in the grid's DOM.
  * Use these when adding/removing classes or querying elements.
  *
  * Classes are organized by:
@@ -62,12 +62,8 @@ export declare const GridClasses: {
  * @category Plugin Development
  */
 export declare const GridDataAttrs: {
-    readonly ROW_INDEX: "data-row-index";
-    readonly COL_INDEX: "data-col-index";
     readonly FIELD: "data-field";
     readonly GROUP_KEY: "data-group-key";
-    readonly TREE_LEVEL: "data-tree-level";
-    readonly STICKY: "data-sticky";
 };
 /**
  * Common CSS selectors for querying grid elements.
@@ -85,9 +81,7 @@ export declare const GridSelectors: {
     readonly DATA_ROW: ".data-row";
     readonly DATA_CELL: ".data-cell";
     readonly GROUP_ROW: ".group-row";
-    readonly ROW_BY_INDEX: (index: number) => string;
     readonly CELL_BY_FIELD: (field: string) => string;
-    readonly CELL_AT: (row: number, col: number) => string;
     readonly SELECTED_ROWS: ".data-row.selected";
     readonly EDITING_CELL: ".data-cell.editing";
 };

package/lib/core/grid.d.ts

@@ -52,6 +52,13 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     get _columns(): ColumnInternal<T>[];
     set _columns(value: ColumnInternal<T>[]);
     get _visibleColumns(): ColumnInternal<T>[];
+    /**
+     * Clear the cached _visibleColumns so the next access recomputes from _columns.
+     * Called by ConfigManager when it mutates effectiveConfig.columns directly
+     * (bypassing the _columns setter which normally handles invalidation).
+     * @internal
+     */
+    _invalidateVisibleColumnsCache(): void;
     _headerRowEl: HTMLElement;
     _bodyEl: HTMLElement;
     _rowPool: RowElementInternal[];
@@ -551,7 +558,7 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
     /** @internal Apply animation configuration to host element. */
     _applyAnimationConfig(config: GridConfig<T>): void;
     /**
-     * Find the header row element in the shadow DOM.
+     * Find the header row element.
      * Used by plugins that need to access header cells for styling or measurement.
      * @group DOM Access
      * @internal Plugin API
@@ -1272,6 +1279,43 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      * @group State Persistence
      */
     get columnState(): GridColumnState | undefined;
+    /**
+     * Get the current single-column sort state.
+     *
+     * Returns `null` when no sort is active.
+     *
+     * @group Sorting
+     *
+     * @example
+     * ```typescript
+     * const sort = grid.sortModel;
+     * // { field: 'name', direction: 'desc' } | null
+     * ```
+     */
+    get sortModel(): {
+        field: string;
+        direction: 'asc' | 'desc';
+    } | null;
+    /**
+     * Sort by a column, toggle a column's sort direction, or clear sorting.
+     *
+     * - `sort('id', 'desc')` — apply sort with explicit direction
+     * - `sort('id')` — toggle: none → asc → desc → none
+     * - `sort(null)` — clear sort, restore original row order
+     *
+     * @param field - Column field to sort by, or `null` to clear
+     * @param direction - Explicit direction; omit to toggle
+     *
+     * @group Sorting
+     *
+     * @example
+     * ```typescript
+     * grid.sort('id', 'desc');  // sort descending
+     * grid.sort('price');       // toggle sort on price
+     * grid.sort(null);          // clear sort
+     * ```
+     */
+    sort(field: string | null, direction?: 'asc' | 'desc'): void;
     /**
      * Request a state change event to be emitted.
      * Called internally after resize, reorder, visibility, or sort changes.
@@ -1600,10 +1644,10 @@ export declare class DataGridElement<T = any> extends HTMLElement implements Int
      */
     refreshShellHeader(): void;
     /**
-     * Register custom CSS styles to be injected into the grid's shadow DOM.
+     * Register custom CSS styles via `document.adoptedStyleSheets`.
      * Use this to style custom cell renderers, editors, or detail panels.
      *
-     * Uses adoptedStyleSheets for efficiency - styles survive shadow DOM rebuilds.
+     * Uses adoptedStyleSheets for efficiency - styles survive DOM rebuilds.
      *
      * @group Custom Styles
      * @param id - Unique identifier for the style block (for removal/updates)

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

@@ -56,7 +56,9 @@ export declare class RenderScheduler {
      */
     get isPending(): boolean;
     /**
-     * Get the current pending phase (0 if none).
+     * The current pending phase (0 if nothing is pending).
+     * Used by `forceLayout()` to flush at the correct phase
+     * without unnecessarily escalating to FULL.
      */
     get pendingPhase(): RenderPhase | 0;
 }

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

@@ -334,7 +334,7 @@ export declare abstract class BaseGridPlugin<TConfig = unknown> implements GridP
      * Third-party plugins can override with their own semver.
      */
     readonly version: string;
-    /** CSS styles to inject into the grid's shadow DOM */
+    /** CSS styles to inject via `document.adoptedStyleSheets` */
     readonly styles?: string;
     /** Custom cell renderers keyed by type name */
     readonly cellRenderers?: Record<string, CellRenderer>;

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

@@ -24,6 +24,7 @@ export declare class PluginManager {
     /** Cached hook presence flags — invalidated on plugin attach/detach */
     private _hasAfterCellRender;
     private _hasAfterRowRender;
+    private _hasProcessRows;
     /**
      * Event listeners indexed by event type.
      * Maps event type → Map<plugin instance → callback>.
@@ -108,6 +109,7 @@ export declare class PluginManager {
     }>;
     /**
      * Execute processRows hook on all plugins.
+     * Returns a mutable copy only when at least one plugin transforms rows.
      */
     processRows(rows: readonly any[]): any[];
     /**

package/lib/core/types.d.ts

@@ -232,6 +232,39 @@ export interface PublicGrid<T = any> {
      * ```
      */
     columnState?: GridColumnState;
+    /**
+     * Get the current sort state.
+     *
+     * Returns `null` when no sort is active.
+     *
+     * @example
+     * ```typescript
+     * const sort = grid.sortModel;
+     * // { field: 'id', direction: 'desc' } | null
+     * ```
+     */
+    readonly sortModel?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    } | null;
+    /**
+     * Sort by a column, toggle a column's sort direction, or clear sorting.
+     *
+     * - `sort('id', 'desc')` — apply sort with explicit direction
+     * - `sort('id')` — toggle: none → asc → desc → none
+     * - `sort(null)` — clear sort, restore original row order
+     *
+     * @param field - Column field to sort by, or `null` to clear
+     * @param direction - Explicit direction; omit to toggle
+     *
+     * @example
+     * ```typescript
+     * grid.sort('id', 'desc');  // sort descending
+     * grid.sort('price');       // toggle sort on price
+     * grid.sort(null);          // clear sort
+     * ```
+     */
+    sort?(field: string | null, direction?: 'asc' | 'desc'): void;
     /**
      * Whether the grid is currently in a loading state.
      * When true, displays a loading overlay with spinner.
@@ -506,6 +539,8 @@ export interface InternalGrid<T = any> extends PublicGrid<T>, GridConfig<T> {
     queryPlugins?: <T>(query: PluginQuery) => T[];
     /** Request emission of column-state-change event (debounced) */
     requestStateChange?: () => void;
+    /** @internal Clear the cached _visibleColumns array so the next read recomputes from _columns. */
+    _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;
@@ -2159,6 +2194,26 @@ export interface GridConfig<TRow = any> {
      * ```
      */
     sortHandler?: SortHandler<TRow>;
+    /**
+     * Initial sort state applied when the grid first renders.
+     *
+     * Equivalent to calling `grid.sort(field, direction)` after the grid is created,
+     * but avoids the imperative call and extra render cycle.
+     *
+     * @example
+     * ```ts
+     * gridConfig = {
+     *   initialSort: { field: 'salary', direction: 'desc' },
+     * };
+     * ```
+     *
+     * @see {@link DataGrid.sort} for runtime sorting
+     * @see {@link DataGrid.sortModel} for reading current sort state
+     */
+    initialSort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
     /**
      * Function to extract a unique identifier from a row.
      * Used by `updateRow()`, `getRow()`, and ID-based tracking.

package/lib/plugins/clipboard/ClipboardPlugin.d.ts

@@ -16,17 +16,6 @@ import { ClipboardConfig, CopyOptions } from './types';
  * import { ClipboardPlugin } from '@toolbox-web/grid/plugins/clipboard';
  * ```
  *
- * ## Configuration Options
- *
- * | Option | Type | Default | Description |
- * |--------|------|---------|-------------|
- * | `includeHeaders` | `boolean` | `false` | Include column headers in copied data |
- * | `delimiter` | `string` | `'\t'` | Column delimiter (tab for Excel compatibility) |
- * | `newline` | `string` | `'\n'` | Row delimiter |
- * | `quoteStrings` | `boolean` | `false` | Wrap string values in quotes |
- * | `processCell` | `(value, field, row) => string` | - | Custom cell value processor (overrides copy-what-you-see) |
- * | `pasteHandler` | `PasteHandler \| null` | `defaultPasteHandler` | Custom paste handler |
- *
  * ## Keyboard Shortcuts
  *
  * | Shortcut | Action |
@@ -44,16 +33,6 @@ import { ClipboardConfig, CopyOptions } from './types';
  * | Row selection | Paste is clipped to the selected rows |
  * | No selection | Paste starts at row 0, column 0 |
  *
- * ## Programmatic API
- *
- * | Method | Signature | Description |
- * |--------|-----------|-------------|
- * | `copy` | `(options?: CopyOptions) => Promise<string>` | Copy to clipboard with optional column/row control |
- * | `copyRows` | `(indices, options?) => Promise<string>` | Copy specific rows to clipboard |
- * | `paste` | `() => Promise<string[][] \| null>` | Read and parse clipboard content |
- * | `getSelectionAsText` | `(options?: CopyOptions) => string` | Get clipboard text without writing to clipboard |
- * | `getLastCopied` | `() => { text, timestamp } \| null` | Get info about last copy operation |
- *
  * @example Basic Usage with Excel Compatibility
  * ```ts
  * import '@toolbox-web/grid';