@keenmate/web-grid 1.0.4 → 1.1.0

package/README.md

@@ -2,24 +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.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.
 
-### v1.0.3
+## What's New in v1.0.5
 
-- **`onrowfocus` fixes**: No longer fires during cell range selection (drag/shift+click). Mouse-triggered row focus now defers to click (mouseup) instead of mousedown; keyboard navigation still fires immediately.
-- **Cell selection visual fix**: Focused cell outline no longer persists during cell range drag.
-- **Toolbar fixes**: Tooltip hides when toolbar moves/closes. Selections cleared on toolbar action click. `triggerElement` in `ontoolbarclick` detail stays alive (no longer detached by synchronous re-render).
-- **Z-index layer system**: All z-index values now use CSS custom properties (`--wg-z-header`, `--wg-z-frozen`, etc.). Fixes cell selection bleeding through sticky header and frozen header stacking.
-
-### v1.0.2
-
-- **Tooltip positioning in transformed containers**: Fixed tooltips appearing at grid's top-left when ancestor has CSS `transform`. Switched to `position: absolute` with `:host` as positioning context.
-- **HTML tooltips**: New `isTooltipHtml` column option for rich tooltip content.
-- **`ontoolbarclick` detail**: Now includes `event` (MouseEvent) and `triggerElement` (HTMLElement) for anchoring popovers to toolbar buttons inside shadow DOM.
-- **Tooltip show delay**: Reduced default from 400ms to 200ms.
+- **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.
 
 ## Installation
 
@@ -27,37 +24,220 @@ A feature-rich, framework-agnostic data grid web component built with TypeScript
 npm install @keenmate/web-grid
 ```
 
-## Quick Start
+Or via CDN (no bundler):
+
+```html
+<script type="module" src="https://unpkg.com/@keenmate/web-grid"></script>
+```
+
+## Getting Started
+
+### Step 1 — Import the component
 
-### ES Module (recommended)
+Importing the package registers the `<web-grid>` custom element globally. You only need to import it once anywhere in your app.
+
+```javascript
+import '@keenmate/web-grid'
+```
+
+For vanilla HTML without a bundler:
 
 ```html
-<script type="module">
-  import '@keenmate/web-grid'
-</script>
+<script type="module" src="https://unpkg.com/@keenmate/web-grid"></script>
+```
+
+### Step 2 — Drop the element into your markup
 
-<web-grid id="grid"></web-grid>
+```html
+<web-grid id="grid" style="max-height: 400px"></web-grid>
+```
+
+`max-height` (or `height`) on the host is how you control sizing — see [Height Modes](#height-modes).
+
+### Step 3 — Assign data and columns
+
+The grid reads its configuration from properties on the element, not attributes. Grab a reference and set what you need:
+
+```javascript
+const grid = document.getElementById('grid')
+
+grid.items = [
+  { id: 1, name: 'Alice', age: 28, department: 'Engineering' },
+  { id: 2, name: 'Bob',   age: 34, department: 'Marketing' }
+]
+
+grid.columns = [
+  { field: 'id',         title: 'ID',         width: '60px' },
+  { field: 'name',       title: 'Name',       width: '160px' },
+  { field: 'age',        title: 'Age',        width: '80px', horizontalAlign: 'right' },
+  { field: 'department', title: 'Department', width: '160px' }
+]
+```
 
-<script type="module">
-  const grid = document.getElementById('grid')
-  grid.items = [
-    { id: 1, name: 'Alice', age: 28 },
-    { id: 2, name: 'Bob', age: 34 }
-  ]
-  grid.columns = [
-    { field: 'id', title: 'ID', width: '60px' },
-    { field: 'name', title: 'Name' },
-    { field: 'age', title: 'Age' }
-  ]
-  grid.sortMode = 'multi'  // Enable multi-column sorting
-</script>
+That's the minimum — a read-only grid with the headers, rows, and columns you defined.
+
+### Step 4 — Enable the features you need
+
+Turn on whatever the page calls for. Everything is off by default:
+
+```javascript
+grid.isStriped = true            // alternating row backgrounds
+grid.isHoverable = true          // hover highlight
+grid.isRowNumbersVisible = true  // leftmost # column
+grid.sortMode = 'multi'          // click headers to sort, Ctrl+click to add
+grid.isPageable = true
+grid.pageSize = 25
+grid.isEditable = true
+grid.editTrigger = 'navigate'    // Excel-like: type to edit the focused cell
+```
+
+### Essential Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `items` | `T[]` | Row data — the only required "content" property |
+| `columns` | `Column<T>[]` | Column definitions with at least a `field` each |
+| `isStriped` / `isHoverable` / `isRowNumbersVisible` | `boolean` | Cosmetic toggles |
+| `sortMode` | `'none' \| 'single' \| 'multi'` | Column sort behavior |
+| `isPageable` + `pageSize` | `boolean` + `number` | Pagination |
+| `isEditable` + `editTrigger` | `boolean` + `EditTrigger` | Enable inline editing and how it starts |
+| `isFilterable` | `boolean` | Per-column filter row under the headers |
+| `mode` | `'read-only' \| 'excel' \| 'input-matrix'` | Presets that set several of the above together |
+
+## Common Configurations
+
+Short recipes for common setups. Each sets only what's necessary on top of the Step 3 minimum.
+
+### Sortable grid
+
+```javascript
+grid.sortMode = 'multi'   // or 'single'
+```
+
+### Paginated grid with top + bottom pager
+
+```javascript
+grid.isPageable = true
+grid.pageSize = 25
+grid.paginationPosition = 'top-center|bottom-center'
+```
+
+### Editable grid (Excel-like navigation)
+
+```javascript
+grid.mode = 'excel'   // isEditable + editTrigger='navigate' + cellSelectionMode='click'
+```
+
+Or opt in manually for finer control:
+
+```javascript
+grid.isEditable = true
+grid.editTrigger = 'navigate'
 ```
 
-### UMD (Script Tag)
+### Per-column editors
+
+```javascript
+grid.columns = [
+  { field: 'name',       title: 'Name',  editor: 'text' },
+  { field: 'salary',     title: 'Salary', editor: 'number', editorOptions: { min: 0, step: 1000 } },
+  { field: 'department', title: 'Dept',  editor: 'select',
+    editorOptions: {
+      options: [
+        { value: 'eng', label: 'Engineering' },
+        { value: 'sal', label: 'Sales' }
+      ]
+    }
+  }
+]
+```
+
+### Height modes
+
+The grid's shadow DOM uses `max-height: inherit`, so setting `max-height` on the host controls its internal scroll container:
 
 ```html
-<script src="https://unpkg.com/@keenmate/web-grid"></script>
-<web-grid id="grid"></web-grid>
+<!-- Container: grid caps at 400px, scrolls internally -->
+<web-grid style="max-height: 400px"></web-grid>
+
+<!-- Full height: grid expands with content, page handles scrolling -->
+<web-grid style="height: 100%"></web-grid>
+```
+
+For full-height mode, also set `tableBorderOnly = true` so the grid doesn't capture wheel events:
+
+```javascript
+grid.tableBorderOnly = true
+```
+
+### Header context menu with column hide + visibility submenu
+
+```javascript
+grid.headerContextMenu = [
+  'sortAsc', 'sortDesc', 'clearSort',
+  { dividerBefore: true },
+  'hideColumn',         // hide the right-clicked column
+  'columnVisibility'    // submenu with a toggle per column
+]
+```
+
+### Hide a column programmatically
+
+```javascript
+grid.columns.find(c => c.field === 'email').isHidden = true
+grid.columns = [...grid.columns]   // reassign to trigger re-render
+```
+
+### Row toolbar
+
+```javascript
+grid.isRowToolbarVisible = true
+grid.rowToolbar = ['add', 'delete', 'duplicate', 'moveUp', 'moveDown']
+```
+
+### Master/detail — react to row focus
+
+```javascript
+grid.onrowfocus = ({ row, rowIndex }) => {
+  showDetailsFor(row)
+}
+```
+
+### Validate a cell before commit
+
+```javascript
+grid.columns = [{
+  field: 'email',
+  title: 'Email',
+  editor: 'text',
+  beforeCommitCallback: ({ value }) => {
+    if (!/^[^@]+@[^@]+$/.test(String(value))) {
+      return { valid: false, message: 'Invalid email address' }
+    }
+    return { valid: true }
+  }
+}]
+```
+
+### TypeScript
+
+Full type definitions ship with the package. Import types from the root:
+
+```typescript
+import '@keenmate/web-grid'
+import type { Column, RowChangeDetail } from '@keenmate/web-grid'
+
+interface Employee {
+  id: number
+  name: string
+  salary: number
+}
+
+const columns: Column<Employee>[] = [
+  { field: 'id',     title: 'ID',     width: '60px' },
+  { field: 'name',   title: 'Name',   width: '200px' },
+  { field: 'salary', title: 'Salary', editor: 'number' }
+]
 ```
 
 ## Features

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, 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, 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
  *
@@ -155,6 +167,21 @@ 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 _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>>;
     get items(): T[];
     set items(value: T[]);
     get columns(): Column<T>[];
@@ -440,6 +467,64 @@ export declare class WebGrid<T = unknown> {
     set newRowIndicator(value: string);
     get createEmptyRowCallback(): (() => T | Promise<T>) | undefined;
     set createEmptyRowCallback(value: (() => T | Promise<T>) | undefined);
+    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;
+    /** 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) */

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/modules/rendering/tree-render.d.ts

@@ -0,0 +1,10 @@
+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.
+ *
+ * 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/types.d.ts

@@ -134,6 +134,7 @@ export type Column<T> = {
     isMovable?: boolean;
     fillDirection?: FillDirection;
     isHidden?: boolean;
+    isTree?: boolean;
 };
 export type ValidationTooltipContext<T> = {
     field: string;
@@ -401,6 +402,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 +608,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;

package/dist/web-component.d.ts

@@ -196,6 +196,34 @@ export declare class GridElement<T = unknown> extends HTMLElement implements Gri
     set newRowIndicator(value: string);
     get createEmptyRowCallback(): () => T | Promise<T>;
     set createEmptyRowCallback(value: () => T | Promise<T>);
+    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);
+    set onexpandedpathschange(value: ((detail: import('./types.js').TreeExpandedChangeDetail) => void) | undefined);
+    get onexpandedpathschange(): ((detail: import("./types.js").TreeExpandedChangeDetail) => void) | undefined;
+    isPathExpanded(path: string): boolean;
+    toggleExpandedPath(path: string): void;
+    expandAll(): void;
+    collapseAll(): void;
+    get treeDoubleClickBehavior(): import('./types.js').TreeDoubleClickBehavior;
+    set treeDoubleClickBehavior(value: import('./types.js').TreeDoubleClickBehavior);
+    get treeExpandedGlyph(): string;
+    set treeExpandedGlyph(value: string);
+    get treeCollapsedGlyph(): string;
+    set treeCollapsedGlyph(value: string);
+    get treeChevronCallback(): import('./types.js').TreeChevronCallback<T> | undefined;
+    set treeChevronCallback(value: import('./types.js').TreeChevronCallback<T> | undefined);
     get isShortcutsHelpVisible(): boolean;
     set isShortcutsHelpVisible(value: boolean);
     get shortcutsHelpPosition(): 'top-right' | 'top-left';