@keenmate/web-grid 1.0.5 → 1.2.0-rc01

package/README.md

@@ -2,18 +2,21 @@
 
 A feature-rich, framework-agnostic data grid web component built with TypeScript. Sorting, filtering, pagination, inline editing (8 editor types), cell range selection, clipboard support, row toolbar, context menus, frozen columns, column reorder/resize, fill handle, virtual scroll, dark mode, and full CSS variable theming — all in a Shadow DOM encapsulated `<web-grid>` element.
 
-## What's New in v1.0.5
+## What's New in v1.2.0-rc01
 
-- **Context menus flip at screen edges**: Both cell and header context menus now correctly flip to the opposite side when opened near a viewport edge (they were clipping before). Switched the root menu to `strategy: 'fixed'` + `position: fixed` so Floating UI's `flip`/`shift` run in viewport coordinates.
-- **Header submenus are viewport-aware**: Header menu submenus (e.g. Column Visibility) now use Floating UI with `placement: 'right-start'` and `flip` fallbacks, replacing the old CSS-only `left: 100%` positioning. A short hide delay lets the cursor cross the gap between parent item and submenu.
-- **Context menu closes on grid-internal scroll**: The menu now subscribes to both the `'window'` and `'container'` scroll sources. Previously, scrolling within the grid didn't close the menu because scroll events aren't composed across shadow DOM.
-- **Context menu offset flips with placement**: `contextMenuXOffset`/`contextMenuYOffset` are now applied via Floating UI's `offset` middleware (`mainAxis` / `alignmentAxis`), so the gap between cursor and menu stays correct even when the menu flips to `*-end` or `top-*`.
-- **Dropdown selected option readable in dark mode**: The selected option in select/combobox/autocomplete dropdowns no longer renders as pale blue against the dark surface. `--wg-accent-color-light` now falls back to a transparent `color-mix` that blends with the underlying surface in either theme.
+- **Tree mode polish**: The column marked `isTree: true` is now read-only by default (editing it conflicts with the toggle); Tab / Shift-Tab in heterogeneous trees skip rows where every cell is read-only, and the next editable cell auto-opens its editor after a Tab commit; `'expand-all'`, `'collapse-all'`, `'expand-tree'`, `'collapse-tree'` are now usable as predefined context-menu items via string shorthand or `{ type: ... }` object form. Tree chevron is a single rotating glyph (120 ms transition) on an inline-flex layout. CSS class `wg__tree-cell-content` renamed to `wg__tree-cell-body`.
+- **Tree-row expand is ~40× faster**: Memoized the data pipeline (`displayItems` / `paginatedItems`) and added a surgical render path that replaces only inner contents instead of rebuilding the table. Expanding a 700-row tree drops from ~700 ms to ~16 ms. Render timings surface via the new `GRID:PERF` logger category.
+- **Paste API is first-class on `<web-grid>`**: `onpaste`, `onbeforepaste`, `pasteMode`, and `shouldValidateOnPaste` are now reachable directly on the GridElement instead of requiring `el.grid.*`. `onpaste` shadows the native HTMLElement property and delivers a `PasteDetail`, not a raw `ClipboardEvent`. TypeScript consumers should cast on assignment or use `el.grid.onpaste = fn` for full type fidelity; JS consumers have no friction.
+- **Datepicker no longer closes when you click its own chrome**: previously, clicking the chevrons / month/year header / disabled days appeared as "outside the grid" to two internal listeners and silently tore the picker down. Now both listeners recognize our `document.body`-hosted popovers (datepicker + cell/header context menus) as part of the grid's logical scope. Same fix protects the cell and header context menus from the same class of bug.
+- **Datepicker `outputFormat` is honored from the action pipeline**: a column declaring `editorOptions.outputFormat: 'timestamp'` (or `'date'`) now actually emits a number (or `Date`) instead of an ISO string when commit goes through the modern pipeline executor (`editTrigger='always'` and keyboard-driven select).
 
-## What's New in v1.0.4
+## What's New in v1.1.0
 
-- **Dirty cell/row indicator**: New `isDirtyIndicatorVisible` property (default: `true`). Edited cells show a subtle orange tint + corner triangle; row numbers get an orange left border. Themable via `--wg-dirty-*` variables. Public methods: `isCellDirty()`, `isRowDirty()`.
-- **Dropdown positioning fix**: Fixed dropdown editors appearing offset in shadow DOM by switching from `position: fixed` to `position: absolute`.
+- **Tree / hierarchy mode**: Render tree-structured data using ltree-style path strings (`"1.2.3"`, `"/a/b/c"`, `"C:\\Win\\Sys"` — separator auto-detected). Mark one column with `isTree: true` to add depth-based indentation and an expand/collapse chevron. Sort is sibling-aware, filter auto-expands ancestors of matches, pagination operates on visible rows. New props: `treePathMember`, `treeLevelMember`, `treeParentMember`, `treeSeparator`, `treeDataSorted`, `expandedPaths`, `defaultExpandDepth`. Methods: `toggleExpandedPath`, `expandAll`, `collapseAll`, `getRowTreeInfo`. Event: `onexpandedpathschange`.
+- **Custom chevron icons via `treeChevronCallback`**: Receives `{ expanded, hasChildren, row, level, path }`, returns HTML for the chevron's inner content. Result is cached per `(row, expanded, hasChildren)` so the callback fires at most a handful of times per row. Use it for file/folder icons, status indicators, anything per-row. Static fallbacks: `treeExpandedGlyph` / `treeCollapsedGlyph`.
+- **Double-click to expand/collapse**: New `treeDoubleClickBehavior: 'none' | 'toggle'`. When set to `'toggle'`, double-clicking anywhere in the tree column expands/collapses the node — works reliably even when the cell DOM is re-rendered between clicks (uses `MouseEvent.detail`, not the unreliable native `dblclick`).
+- **No more spurious `onrowchange` events**: Entering edit mode and exiting via arrow keys without typing no longer fires phantom "X → X" change events. `commitEdit` now only fires `onrowchange` when the value actually changed (or validation failed).
+- **Pathological filler-cell width fix**: Removed `min-width: max-content` from `.wg__table` — it was redundant with `table-layout: fixed` and triggered intrinsic-size computation that ballooned the filler to hundreds of thousands of pixels in some browsers (Firefox especially) when cells contained absolutely-positioned editors.
 
 ## Installation
 

package/dist/grid.d.ts

@@ -1,4 +1,16 @@
-import type { Column, CellValidationState, RowToolbarConfig, ContextMenuItem, RowShortcut, RowChangeDetail, ToolbarClickDetail, RowActionClickDetail, ContextMenuContext, HeaderMenuConfig, HeaderMenuContext, EditTrigger, EditStartSelection, EditingCell, FocusedCell, SortMode, SortState, DataRequestDetail, DataRequestTrigger, BeforeCommitResult, GridMode, ToggleVisibility, PaginationLabelsCallback, SummaryContentCallback, ValidationTooltipContext, ToolbarPosition, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail, ColumnWidthState, ColumnResizeDetail, ColumnOrderState, ColumnReorderDetail, FillDragDetail, FillDirection, RangeShortcut, CellSelectionMode, CellRange, CellSelectionChangeDetail, RowFocusDetail, PasteMode, BeforePasteDetail, PasteDetail, CreateRowCallback, NewRowPosition } from './types.js';
+import type { Column, CellValidationState, RowToolbarConfig, ContextMenuConfig, RowShortcut, RowChangeDetail, ToolbarClickDetail, RowActionClickDetail, ContextMenuContext, HeaderMenuConfig, HeaderMenuContext, EditTrigger, EditStartSelection, EditingCell, FocusedCell, SortMode, SortState, DataRequestDetail, DataRequestTrigger, BeforeCommitResult, GridMode, ToggleVisibility, PaginationLabelsCallback, SummaryContentCallback, ValidationTooltipContext, ToolbarPosition, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail, ColumnWidthState, ColumnResizeDetail, ColumnOrderState, ColumnReorderDetail, FillDragDetail, FillDirection, RangeShortcut, CellSelectionMode, CellRange, CellSelectionChangeDetail, RowFocusDetail, PasteMode, BeforePasteDetail, PasteDetail, CreateRowCallback, NewRowPosition, TreeExpandedChangeDetail, TreeChevronCallback, TreeDoubleClickBehavior } from './types.js';
+type TreeNode = {
+    path: string;
+    parent: string | null;
+    level: number;
+    rowIndex: number;
+    childPaths: string[];
+};
+type TreeIndex = {
+    separator: string;
+    nodes: Map<string, TreeNode>;
+    rootPaths: string[];
+};
 /**
  * WebGrid - Core logic class for the data grid
  *
@@ -17,6 +29,7 @@ export declare class WebGrid<T = unknown> {
     protected _isStriped: boolean;
     protected _isHoverable: boolean;
     protected _isEditable: boolean;
+    protected _isRowEditable: boolean | ((row: T) => boolean) | undefined;
     protected _editTrigger: EditTrigger;
     protected _editStartSelection: EditStartSelection;
     protected _mode: GridMode;
@@ -41,7 +54,7 @@ export declare class WebGrid<T = unknown> {
     protected _cellToolbarOffset: number | string;
     protected _toolbarBtnMinWidth: string | undefined;
     protected _inlineActionsTitle: string;
-    protected _contextMenu: ContextMenuItem<T>[] | undefined;
+    protected _contextMenu: ContextMenuConfig<T>[] | undefined;
     protected _contextMenuXOffset: number;
     protected _contextMenuYOffset: number;
     protected _headerContextMenu: HeaderMenuConfig<T>[] | undefined;
@@ -93,6 +106,8 @@ export declare class WebGrid<T = unknown> {
     }) => void) | undefined;
     protected _sort: SortState[];
     protected _filters: Record<string, string>;
+    protected _onfilterchange: ((filters: Record<string, string>) => void) | undefined;
+    protected _columnMinWidth: string | undefined;
     protected _currentPage: number;
     protected _totalItems: number | null;
     protected _showPagination: boolean | 'auto';
@@ -155,6 +170,25 @@ export declare class WebGrid<T = unknown> {
     protected _newRowIndicator: string;
     protected _createEmptyRowCallback: (() => T | Promise<T>) | undefined;
     protected _emptyRowDraft: T | null;
+    protected _treePathMember: string | null;
+    protected _treeLevelMember: string | null;
+    protected _treeParentMember: string | null;
+    protected _idMember: string | null;
+    protected _hasWarnedAboutMissingRowId: boolean;
+    protected _treeSeparator: string | null;
+    protected _treeDataSorted: boolean;
+    protected _expandedPaths: Set<string>;
+    protected _expandedPathsExternal: Set<string> | null;
+    protected _defaultExpandDepth: number | null;
+    protected _treeIndex: TreeIndex | null;
+    protected _onexpandedpathschange: ((detail: TreeExpandedChangeDetail) => void) | undefined;
+    protected _treeDoubleClickBehavior: TreeDoubleClickBehavior;
+    protected _treeExpandedGlyph: string;
+    protected _treeCollapsedGlyph: string;
+    protected _treeChevronCallback: TreeChevronCallback<T> | undefined;
+    protected _treeChevronCache: WeakMap<object, Map<string, string>>;
+    protected _paginatedItemsCache: T[] | null;
+    protected _displayItemsCache: T[] | null;
     get items(): T[];
     set items(value: T[]);
     get columns(): Column<T>[];
@@ -163,6 +197,10 @@ export declare class WebGrid<T = unknown> {
     set sortMode(value: SortMode);
     get isFilterable(): boolean;
     set isFilterable(value: boolean);
+    get onfilterchange(): ((filters: Record<string, string>) => void) | undefined;
+    set onfilterchange(value: ((filters: Record<string, string>) => void) | undefined);
+    get columnMinWidth(): string | undefined;
+    set columnMinWidth(value: string | undefined);
     get isPageable(): boolean;
     set isPageable(value: boolean);
     get pageSize(): number;
@@ -177,6 +215,8 @@ export declare class WebGrid<T = unknown> {
     set isHoverable(value: boolean);
     get isEditable(): boolean;
     set isEditable(value: boolean);
+    get isRowEditable(): boolean | ((row: T) => boolean) | undefined;
+    set isRowEditable(value: boolean | ((row: T) => boolean) | undefined);
     get editTrigger(): EditTrigger;
     set editTrigger(value: EditTrigger);
     get editStartSelection(): EditStartSelection;
@@ -258,8 +298,8 @@ export declare class WebGrid<T = unknown> {
     set toolbarBtnMinWidth(value: string | undefined);
     get inlineActionsTitle(): string;
     set inlineActionsTitle(value: string);
-    get contextMenu(): ContextMenuItem<T>[] | undefined;
-    set contextMenu(value: ContextMenuItem<T>[] | undefined);
+    get contextMenu(): ContextMenuConfig<T>[] | undefined;
+    set contextMenu(value: ContextMenuConfig<T>[] | undefined);
     get contextMenuXOffset(): number;
     set contextMenuXOffset(value: number);
     get contextMenuYOffset(): number;
@@ -350,6 +390,7 @@ export declare class WebGrid<T = unknown> {
     get ontoolbarclick(): ((detail: ToolbarClickDetail<T>) => void) | undefined;
     set ontoolbarclick(value: ((detail: ToolbarClickDetail<T>) => void) | undefined);
     set onrowaction(value: ((detail: RowActionClickDetail<T>) => void) | undefined);
+    get oncontextmenuopen(): ((context: ContextMenuContext<T>) => void) | undefined;
     set oncontextmenuopen(value: ((context: ContextMenuContext<T>) => void) | undefined);
     get onheadercontextmenuopen(): ((context: HeaderMenuContext<T>) => void) | undefined;
     set onheadercontextmenuopen(value: ((context: HeaderMenuContext<T>) => void) | undefined);
@@ -440,6 +481,91 @@ export declare class WebGrid<T = unknown> {
     set newRowIndicator(value: string);
     get createEmptyRowCallback(): (() => T | Promise<T>) | undefined;
     set createEmptyRowCallback(value: (() => T | Promise<T>) | undefined);
+    get idMember(): string | null;
+    set idMember(value: string | null);
+    /**
+     * Return a stable string key for a row. Coalesce order: idMember value → treePathMember
+     * value → displayed-index string fallback. Used to key drafts and invalid-cell markers
+     * so they don't drift when the displayed order changes (sort, filter, page, tree toggle).
+     *
+     * Distinct from `getRowId` which is the row-locking identifier (any type).
+     */
+    getStableRowKey(item: T, displayedIndex: number): string;
+    private maybeWarnAboutRowIdentity;
+    get treePathMember(): string | null;
+    set treePathMember(value: string | null);
+    get treeLevelMember(): string | null;
+    set treeLevelMember(value: string | null);
+    get treeParentMember(): string | null;
+    set treeParentMember(value: string | null);
+    get treeSeparator(): string | null;
+    set treeSeparator(value: string | null);
+    get treeDataSorted(): boolean;
+    set treeDataSorted(value: boolean);
+    get expandedPaths(): Set<string>;
+    set expandedPaths(value: Set<string> | null | undefined);
+    get defaultExpandDepth(): number | null;
+    set defaultExpandDepth(value: number | null);
+    get onexpandedpathschange(): ((detail: TreeExpandedChangeDetail) => void) | undefined;
+    set onexpandedpathschange(value: ((detail: TreeExpandedChangeDetail) => void) | undefined);
+    get isTreeMode(): boolean;
+    isPathExpanded(path: string): boolean;
+    toggleExpandedPath(path: string): void;
+    expandAll(): void;
+    collapseAll(): void;
+    /**
+     * Expand a path's entire subtree (the path itself + all descendants).
+     * Used by the per-row "expand all" context-menu action — file-explorer convention
+     * is "expand everything *under here*", not the entire dataset.
+     */
+    expandSubtree(path: string): void;
+    /**
+     * Collapse a path's entire subtree (the path itself + all descendants).
+     */
+    collapseSubtree(path: string): void;
+    /**
+     * Walk up the path's ancestor chain looking for the nearest expanded ancestor.
+     * Used by Ctrl+ArrowLeft: when the focused row has no expanded children to collapse,
+     * step up to the closest ancestor that is expanded so the user gets meaningful action.
+     */
+    findNearestExpandedAncestor(path: string): string | null;
+    /** Returns tree info for a row (used by rendering) */
+    getRowTreeInfo(item: T): {
+        path: string;
+        level: number;
+        hasChildren: boolean;
+    } | null;
+    get treeDoubleClickBehavior(): TreeDoubleClickBehavior;
+    set treeDoubleClickBehavior(value: TreeDoubleClickBehavior);
+    get treeExpandedGlyph(): string;
+    set treeExpandedGlyph(value: string);
+    get treeCollapsedGlyph(): string;
+    set treeCollapsedGlyph(value: string);
+    get treeChevronCallback(): TreeChevronCallback<T> | undefined;
+    set treeChevronCallback(value: TreeChevronCallback<T> | undefined);
+    /**
+     * Resolve the inner HTML for a row's chevron, using callback (cached) or static glyph.
+     * Cache is keyed per (row reference, expanded). When the row reference changes
+     * (immutable update) or items are replaced, stale entries are dropped via WeakMap GC
+     * or explicit cache clear.
+     */
+    getTreeChevronHtml(item: T, expanded: boolean, hasChildren: boolean, level: number, path: string): string;
+    /** Read the path field from a row */
+    protected getRowTreePath(item: T): string | null;
+    /** Detect separator from a sample path */
+    protected detectTreeSeparator(path: string): string;
+    /** Rebuild _treeIndex from current items */
+    protected rebuildTreeState(): void;
+    /** Re-initialize the active expanded set after items/config changes */
+    protected rebuildExpandedPaths(): void;
+    /** Compare two tree nodes using current sort state, falling back to path */
+    protected compareTreeNodes(a: TreeNode, b: TreeNode): number;
+    /** Compute paths matched by current text filters, plus their ancestors */
+    protected getTreeFilterAllowedPaths(): Set<string> | null;
+    /** Items in tree-aware sort order (depth-first, sibling-sorted), with filter applied */
+    protected getTreeSortedItems(): T[];
+    /** Items currently visible (post-collapse). When filter is active, ancestors of matches are auto-expanded. */
+    protected getTreeVisibleItems(): T[];
     selectCellRange(range: CellRange): void;
     clearCellSelection(): void;
     /** Clear cell selection state without triggering re-render (caller handles visuals) */
@@ -490,6 +616,15 @@ export declare class WebGrid<T = unknown> {
     copyCellSelectionToClipboard(): Promise<boolean>;
     get isNavigateMode(): boolean;
     get filteredItems(): T[];
+    /**
+     * Returns the set of fields whose current filter input is "incomplete" (column.filter
+     * returned null when probed against the first row). Renderers can use this to mark the
+     * input visually (red border) without excluding all rows.
+     */
+    getInvalidFilterFields(): Set<string>;
+    get filters(): Record<string, string>;
+    set filters(value: Record<string, string>);
+    setFilter(field: string, value: string): void;
     get sortedItems(): T[];
     get paginatedItems(): T[];
     get totalPages(): number;
@@ -545,6 +680,12 @@ export declare class WebGrid<T = unknown> {
      */
     protected checkToolbarConflicts(): void;
     protected requestUpdate(): void;
+    /**
+     * Drop memoized pipeline output. The web-component's requestUpdate override
+     * calls this on every state mutation, so callers don't need to invoke it
+     * directly — but it's safe to call any time the cache might be stale.
+     */
+    invalidateDisplayCache(): void;
     getRowDraft(rowIndex: number): T | undefined;
     hasRowDraft(rowIndex: number): boolean;
     /**
@@ -565,6 +706,8 @@ export declare class WebGrid<T = unknown> {
     discardAllDrafts(): void;
     getCellRawValue(item: T, rowIndex: number, field: string): unknown;
     getCellValue(item: T, column: Column<T>, rowIndex?: number): string;
+    /** Compute the stable rowKey for a displayed-row index, or null if no row at that index. */
+    private rowKeyForIndex;
     isCellInvalid(rowIndex: number, field: string): boolean;
     getCellValidationError(rowIndex: number, field: string): string | null;
     addInvalidCell(rowIndex: number, field: string, error: string): void;
@@ -611,16 +754,42 @@ export declare class WebGrid<T = unknown> {
      */
     updateDraftValue(rowIndex: number, field: string, newValue: unknown): void;
     /**
-     * Check if a column's cells can be edited
-     */
-    isCellEditable(column: Column<T>): boolean;
-    /**
-     * Get all editable columns with their indices
-     */
-    getEditableColumns(): {
+     * Check if a column's cells can be edited.
+     * `row` is required to evaluate function-form predicates; pass it for per-row checks,
+     * omit it for static column-level checks (e.g. building toolbar UI). When omitted and a
+     * predicate exists, conservatively returns true so the column isn't hidden.
+     *
+     * Resolution order:
+     *   0. tree column in tree mode → not editable (the tree column displays hierarchy, not data)
+     *   1. column.isEditable === false → not editable (hard veto)
+     *   2. column.isEditable === function with row → must return true to continue
+     *   3. grid.isRowEditable with row → must pass to continue
+     *   4. column.isEditable === true → editable (overrides grid-level)
+     *   5. else → defer to grid-level isEditable
+     */
+    isCellEditable(column: Column<T>, row?: T): boolean;
+    /**
+     * Get all editable columns with their indices.
+     * Pass `row` to evaluate per-row predicates (function-form `isEditable`, `isRowEditable`).
+     * Without `row`, returns columns that are *potentially* editable (any row could pass).
+     */
+    getEditableColumns(row?: T): {
         index: number;
         column: Column<T>;
     }[];
+    /**
+     * Walk rows in `direction` looking for the next row that has at least one editable
+     * column at or beyond `fromColEditableIndex` (or beyond the last when going forward
+     * past the row's editable list). Used by Tab traversal in heterogeneous trees so the
+     * cursor skips read-only rows (e.g. team rows) entirely instead of landing on a cell
+     * with no tabindex and silently losing focus.
+     *
+     * Returns null if no editable cell exists in the requested direction.
+     */
+    findNextEditableCell(fromRowIndex: number, fromColEditableIndex: number, direction: 'forward' | 'backward'): {
+        rowIndex: number;
+        colIndex: number;
+    } | null;
     /**
      * Check if a specific cell is currently focused
      */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { GridElement } from './web-component.js';
 export { WebGrid } from './grid.js';
-export type { EditorType, EditTrigger, OptionsLoadTrigger, DateOutputFormat, EditorOption, EditorOptions, CustomEditorContext, CellValidationState, ValidationResult, BeforeCommitContext, BeforeCommitResult, Column, CellRenderCallback, RowChangeDetail, RowFocusDetail, PredefinedToolbarItemType, ToolbarPosition, NewRowPosition, ToolbarTooltip, RowToolbarItem, RowToolbarConfig, NormalizedToolbarItem, ToolbarClickDetail, RowActionType, RowActionClickDetail, ContextMenuContext, ContextMenuItem, QuickGridProps, SortState, DataRequestDetail, DataRequestTrigger, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail, LockedRowEditBehavior, ColumnWidthState, ColumnResizeDetail, ColumnOrderState, ColumnReorderDetail, FillDragDetail, FillDirection, RangeShortcut, RangeShortcutContext, CellSelectionMode, CellRange, CellSelectionChangeDetail, PasteMode, PasteColumnMapping, BeforePasteDetail, PasteCellResult, PasteDetail, CreateRowCallback, EditingCell, FocusedCell, SortDirection, ToolbarRowGroup, PopupPosition, ConnectorArrowDir } from './types.js';
+export type { EditorType, EditTrigger, OptionsLoadTrigger, DateOutputFormat, EditorOption, EditorOptions, CustomEditorContext, CellValidationState, ValidationResult, BeforeCommitContext, BeforeCommitResult, Column, CellRenderCallback, RowChangeDetail, RowFocusDetail, PredefinedToolbarItemType, ToolbarPosition, NewRowPosition, ToolbarTooltip, RowToolbarItem, RowToolbarConfig, NormalizedToolbarItem, ToolbarClickDetail, RowActionType, RowActionClickDetail, ContextMenuContext, ContextMenuItem, QuickGridProps, SortState, DataRequestDetail, DataRequestTrigger, GridLabels, RowLockInfo, RowLockingOptions, RowLockChangeDetail, LockedRowEditBehavior, ColumnWidthState, ColumnResizeDetail, ColumnOrderState, ColumnReorderDetail, FillDragDetail, FillDirection, RangeShortcut, RangeShortcutContext, CellSelectionMode, CellRange, CellSelectionChangeDetail, PasteMode, PasteColumnMapping, BeforePasteDetail, PasteCellResult, PasteDetail, CreateRowCallback, TreeExpandedChangeDetail, TreeChevronContext, TreeChevronCallback, TreeDoubleClickBehavior, EditingCell, FocusedCell, SortDirection, ToolbarRowGroup, PopupPosition, ConnectorArrowDir } from './types.js';
 export { GridElement as default } from './web-component.js';

package/dist/logger.d.ts

@@ -28,6 +28,7 @@ export declare const initLogger: any;
 export declare const dataLogger: any;
 export declare const uiLogger: any;
 export declare const interactionLogger: any;
+export declare const perfLogger: any;
 export default log;
 /**
  * List of all logging categories for introspection

package/dist/modules/click-events/index.d.ts

@@ -22,8 +22,12 @@ export interface ClickEventManager {
      * Initialize click listeners
      * @param container - The grid container element (.wg)
      * @param hostElement - The custom element host (<web-grid>) for outside detection
+     * @param isPathInOwnedScope - Optional predicate; when it returns true for a
+     *   click's composed path, the click is treated as inside the grid (used for
+     *   document.body-hosted popovers like the datepicker and context menus
+     *   that need to extend the grid's "inside" scope beyond the host element).
      */
-    init(container: HTMLElement, hostElement: HTMLElement): void;
+    init(container: HTMLElement, hostElement: HTMLElement, isPathInOwnedScope?: (path: EventTarget[]) => boolean): void;
     /**
      * Remove all listeners and subscriptions (called in disconnectedCallback)
      */

package/dist/modules/contextmenu/index.d.ts

@@ -1,5 +1,14 @@
-import type { ContextMenuItem, ContextMenuContext, HeaderMenuConfig, HeaderMenuItem, HeaderMenuContext } from '../../types.js';
+import type { ContextMenuItem, ContextMenuConfig, ContextMenuContext, HeaderMenuConfig, HeaderMenuItem, HeaderMenuContext } from '../../types.js';
 import type { GridContext } from '../types.js';
+/**
+ * Normalize a ContextMenuConfig list (which may contain string shorthand and/or items
+ * with `type` set) into a flat list of fully-defined ContextMenuItem objects.
+ * Predefined types get default labels, icons, visibility predicates, and onclick handlers.
+ *
+ * The grid is needed at click time for `expand-all` etc. to call `expandSubtree(path)`,
+ * so we close over it rather than passing it through later.
+ */
+export declare function normalizeContextMenu<T>(config: ContextMenuConfig<T>[], grid: GridContext<T>['grid']): ContextMenuItem<T>[];
 /**
  * Open context menu at position
  */

package/dist/modules/datepicker/datepicker.d.ts

@@ -11,6 +11,8 @@ export declare class DatePicker {
     private anchor;
     private input;
     private cleanupAutoUpdate;
+    /** The picker's outer container (mounted in document.body), or null when closed. */
+    getElement(): HTMLElement | null;
     private previousInputValue;
     private boundHandleClickOutside;
     private boundHandleKeyDown;

package/dist/modules/rendering/tree-render.d.ts

@@ -0,0 +1,18 @@
+import type { Column } from '../../types.js';
+import type { GridContext } from '../types.js';
+/**
+ * Wrap cell content with tree indent + chevron when column is the tree column.
+ * Returns the original innerHtml unchanged when tree mode is off or column isn't isTree.
+ *
+ * Layout: inline-flex wrapper with `padding-inline-start: level * --wg-tree-indent`.
+ * Inside the wrapper sits either a chevron <button> (branch) or an empty
+ * <span class="wg__tree-leaf-spacer"> (leaf, keeps alignment with branches).
+ *
+ * Chevron rotation: when treeExpandedGlyph === treeCollapsedGlyph (the default
+ * setup) we add `.wg__tree-chevron--expanded` and CSS rotates the glyph 90°.
+ * When the glyphs differ, the glyph is swapped on state change instead.
+ *
+ * Used by both the full-table render (table.ts) and the surgical single-cell
+ * render (cell.ts), so both paths keep the chevron after focus/edit transitions.
+ */
+export declare function wrapTreeCell<T>(ctx: GridContext<T>, column: Column<T>, item: T, innerHtml: string): string;

package/dist/perf.d.ts

@@ -0,0 +1,15 @@
+export declare const gridPerf: {
+    counters: {
+        displayItems: number;
+        displayItemsMs: number;
+        paginatedItems: number;
+        paginatedItemsMs: number;
+        treeSorted: number;
+        treeSortedMs: number;
+        treeVisible: number;
+        treeVisibleMs: number;
+        cellDisplayItemsLookup: number;
+    };
+    reset(): void;
+    summary(): string;
+};

package/dist/types.d.ts

@@ -75,7 +75,7 @@ export type CustomEditorContext<T> = {
     cancel: () => void;
 };
 export type CellValidationState = {
-    rowIndex: number;
+    rowKey: string;
     field: string;
     error: string;
 };
@@ -104,6 +104,8 @@ export type Column<T> = {
     maxWidth?: string;
     textOverflow?: 'wrap' | 'ellipsis';
     maxLines?: number;
+    nowrap?: boolean;
+    filter?: (filterValue: string, row: T) => boolean | null;
     horizontalAlign?: "left" | "center" | "right" | "justify";
     verticalAlign?: "top" | "middle" | "bottom";
     headerHorizontalAlign?: "left" | "center" | "right" | "justify";
@@ -113,7 +115,7 @@ export type Column<T> = {
     formatCallback?: (value: unknown, row: T) => string;
     templateCallback?: (row: T) => string;
     renderCallback?: CellRenderCallback<T>;
-    isEditable?: boolean;
+    isEditable?: boolean | ((row: T) => boolean);
     editor?: EditorType;
     editTrigger?: EditTrigger;
     dropdownToggleVisibility?: ToggleVisibility;
@@ -134,6 +136,7 @@ export type Column<T> = {
     isMovable?: boolean;
     fillDirection?: FillDirection;
     isHidden?: boolean;
+    isTree?: boolean;
 };
 export type ValidationTooltipContext<T> = {
     field: string;
@@ -213,23 +216,27 @@ export type ContextMenuContext<T> = {
     column: Column<T>;
     cellValue: unknown;
 };
+export type PredefinedContextMenuItemType = 'expand-all' | 'collapse-all' | 'expand-tree' | 'collapse-tree';
 export type ContextMenuItem<T> = {
     id: string;
-    label: string | ((context: ContextMenuContext<T>) => string);
+    label?: string | ((context: ContextMenuContext<T>) => string);
     icon?: string | ((context: ContextMenuContext<T>) => string);
     shortcut?: string;
     disabled?: boolean | ((context: ContextMenuContext<T>) => boolean);
     visible?: boolean | ((context: ContextMenuContext<T>) => boolean);
     danger?: boolean;
     dividerBefore?: boolean;
+    type?: PredefinedContextMenuItemType;
     onclick?: (context: ContextMenuContext<T>) => void | Promise<void>;
 };
+export type ContextMenuConfig<T> = PredefinedContextMenuItemType | ContextMenuItem<T>;
 export type HeaderMenuContext<T> = {
     column: Column<T>;
     field: string;
     columnIndex: number;
     sortDirection: 'asc' | 'desc' | null;
     isFrozen: boolean;
+    isTreeMode: boolean;
     allColumns: Column<T>[];
     labels: GridLabels;
 };
@@ -300,6 +307,8 @@ export type QuickGridProps<T> = {
     items: T[];
     columns: Column<T>[];
     isFilterable?: boolean;
+    columnMinWidth?: string;
+    onfilterchange?: (filters: Record<string, string>) => void;
     isPageable?: boolean;
     pageSize?: number;
     isStriped?: boolean;
@@ -312,6 +321,7 @@ export type QuickGridProps<T> = {
     style?: string;
     customStylesCallback?: () => string;
     rowClassCallback?: (row: T, rowIndex: number) => string | null;
+    idMember?: keyof T | string;
     sort?: SortState[];
     sortMode?: SortMode;
     currentPage?: number;
@@ -326,6 +336,7 @@ export type QuickGridProps<T> = {
     summaryContentCallback?: SummaryContentCallback<T>;
     isSummaryInline?: boolean;
     isEditable?: boolean;
+    isRowEditable?: boolean | ((row: T) => boolean);
     editTrigger?: EditTrigger;
     editStartSelection?: EditStartSelection;
     mode?: GridMode;
@@ -346,7 +357,7 @@ export type QuickGridProps<T> = {
     cellToolbarOffset?: number | string;
     toolbarBtnMinWidth?: string;
     inlineActionsTitle?: string;
-    contextMenu?: ContextMenuItem<T>[];
+    contextMenu?: ContextMenuConfig<T>[];
     contextMenuXOffset?: number;
     contextMenuYOffset?: number;
     oncontextmenuopen?: (context: ContextMenuContext<T>) => void;
@@ -401,6 +412,18 @@ export type QuickGridProps<T> = {
     cellSelectionMode?: CellSelectionMode;
     shouldCopyWithHeaders?: boolean;
     oncellselectionchange?: (detail: CellSelectionChangeDetail) => void;
+    treePathMember?: keyof T | string;
+    treeLevelMember?: keyof T | string;
+    treeParentMember?: keyof T | string;
+    treeSeparator?: string;
+    treeDataSorted?: boolean;
+    expandedPaths?: Set<string>;
+    defaultExpandDepth?: number;
+    treeDoubleClickBehavior?: TreeDoubleClickBehavior;
+    onexpandedpathschange?: (detail: TreeExpandedChangeDetail) => void;
+    treeExpandedGlyph?: string;
+    treeCollapsedGlyph?: string;
+    treeChevronCallback?: TreeChevronCallback<T>;
     isNewRowEnabled?: boolean;
     newRowPosition?: NewRowPosition;
     newRowIndicator?: string;
@@ -595,3 +618,25 @@ export type PasteDetail<T> = {
 };
 /** Callback to create new rows from pasted data */
 export type CreateRowCallback<T> = (pastedData: Record<string, unknown>, rowIndex: number) => T;
+/** What happens when the user double-clicks a tree-column cell */
+export type TreeDoubleClickBehavior = 'none' | 'toggle';
+/** Detail passed to onexpandedpathschange when user toggles a tree node */
+export type TreeExpandedChangeDetail = {
+    path: string;
+    expanded: boolean;
+    expandedPaths: Set<string>;
+};
+/** Context passed to treeChevronCallback */
+export type TreeChevronContext<T> = {
+    expanded: boolean;
+    hasChildren: boolean;
+    row: T;
+    level: number;
+    path: string;
+};
+/**
+ * Callback that returns HTML for the chevron's inner content.
+ * Result is cached per (row, expanded) — the callback is invoked at most twice
+ * per row, once per expanded state. Invalidated when items or the callback change.
+ */
+export type TreeChevronCallback<T> = (context: TreeChevronContext<T>) => string;