virtual-tree-canvas 0.6.0 → 0.7.1

package/src/core/view-options.js

@@ -1,30 +1,110 @@
 import { resolveTheme } from './theme-manager.js';
-/** Supported TreeView configuration options and defaults. */
+
+/**
+ * Supported TreeView configuration options and defaults.
+ */
 export const treeViewDefaults = Object.freeze({
-  mode: 'tree', presentation: 'pane', nodes: Object.freeze([]), model: null, meta: null,
-  columns: null, theme: 'dark', flatRoot: true, enforceMeta: false,
-  filter: true, filterPlacement: 'auto', markUpdated: true, editable: true,
-  rowReorder: false, initialExpandDepth: 1, rowHeight: undefined,
-  indentWidth: undefined, headerHeight: 28, iconResolver: null, fontFamily: null,
+  mode: 'tree',
+  presentation: 'pane',
+  nodes: Object.freeze([]),
+  model: null,
+  meta: null,
+  columns: null,
+  theme: 'dark',
+  flatRoot: true,
+  enforceMeta: false,
+  filter: true,
+  filterPlacement: 'auto',
+  markUpdated: true,
+  editable: true,
+  rowActions: Object.freeze([]),
+  rowDrag: null,
+  rowReorder: false,
+  initialExpandDepth: 1,
+  rowHeight: undefined,
+  indentWidth: undefined,
+  showHeader: true,
+  headerHeight: 28,
+  iconResolver: null,
+  fontFamily: null
 });
 export const treeViewOptionNames = Object.freeze(Object.keys(treeViewDefaults));
 
 export function validateTreeViewOptions(options) {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Options must be an object');
+  if (!options || typeof options !== 'object' || Array.isArray(options))
+    throw new TypeError('Options must be an object');
   for (const [key, value] of Object.entries(options)) {
+    if (
+      key === 'rowActions' &&
+      (!Array.isArray(value) ||
+        value.some(
+          (action) =>
+            !action ||
+            typeof action.id !== 'string' ||
+            !action.id ||
+            typeof action.label !== 'string'
+        ) ||
+        new Set(value.map((action) => action.id)).size !== value.length)
+    )
+      throw new TypeError('rowActions requires unique ids and labels');
+    if (key === 'rowActions')
+      for (const action of value) {
+        if (action.kind !== undefined && !['button', 'checkbox'].includes(action.kind))
+          throw new TypeError('row action kind must be button or checkbox');
+        for (const property of ['visible', 'disabled', 'pressed', 'checked'])
+          if (
+            action[property] !== undefined &&
+            !['boolean', 'function'].includes(typeof action[property])
+          )
+            throw new TypeError(`${property} must be boolean or a function`);
+        if (action.icon !== undefined && !['string', 'function'].includes(typeof action.icon))
+          throw new TypeError('action icon must be a name or a function');
+      }
+    if (key === 'rowDrag' && value !== null && typeof value !== 'function')
+      throw new TypeError('rowDrag must be a function or null');
     if (key === 'theme') resolveTheme(value);
-    if (key === 'mode' && !['tree', 'inspector'].includes(value)) throw new TypeError('mode must be tree or inspector');
-    if (key === 'presentation' && !['pane', 'table'].includes(value)) throw new TypeError('presentation must be pane or table');
-    if (key === 'filterPlacement' && !['auto', 'bar', 'header'].includes(value)) throw new TypeError('filterPlacement must be auto, bar or header');
+    if (key === 'mode' && !['tree', 'inspector'].includes(value))
+      throw new TypeError('mode must be tree or inspector');
+    if (key === 'presentation' && !['pane', 'table'].includes(value))
+      throw new TypeError('presentation must be pane or table');
+    if (key === 'filterPlacement' && !['auto', 'bar', 'header'].includes(value))
+      throw new TypeError('filterPlacement must be auto, bar or header');
     if (key === 'nodes' && !Array.isArray(value)) throw new TypeError('nodes must be an array');
-    if (key === 'columns' && value !== null && !Array.isArray(value)) throw new TypeError('columns must be an array or null');
+    if (key === 'columns' && value !== null && !Array.isArray(value))
+      throw new TypeError('columns must be an array or null');
     if (key === 'model' && value === undefined) throw new TypeError('model must not be undefined');
-    if (key === 'meta' && value !== null && (!value || typeof value !== 'object' || Array.isArray(value))) throw new TypeError('meta must be an object or null');
-    if (['rowHeight', 'indentWidth'].includes(key) && value !== undefined && (!Number.isFinite(value) || value <= 0)) throw new TypeError(`${key} must be a positive number`);
-    if (key === 'headerHeight' && (!Number.isFinite(value) || value < 0)) throw new TypeError('headerHeight must be non-negative');
-    if (key === 'initialExpandDepth' && (!Number.isInteger(value) || value < 0)) throw new TypeError('initialExpandDepth must be a non-negative integer');
-    if (key === 'iconResolver' && value !== null && typeof value !== 'function') throw new TypeError('iconResolver must be a function or null');
-    if (key === 'fontFamily' && value !== null && typeof value !== 'string') throw new TypeError('fontFamily must be a string or null');
-    if (['flatRoot', 'enforceMeta', 'filter', 'markUpdated', 'editable', 'rowReorder'].includes(key) && typeof value !== 'boolean') throw new TypeError(`${key} must be boolean`);
+    if (
+      key === 'meta' &&
+      value !== null &&
+      (!value || typeof value !== 'object' || Array.isArray(value))
+    )
+      throw new TypeError('meta must be an object or null');
+    if (
+      ['rowHeight', 'indentWidth'].includes(key) &&
+      value !== undefined &&
+      (!Number.isFinite(value) || value <= 0)
+    )
+      throw new TypeError(`${key} must be a positive number`);
+    if (key === 'headerHeight' && (!Number.isFinite(value) || value < 0))
+      throw new TypeError('headerHeight must be non-negative');
+    if (key === 'initialExpandDepth' && (!Number.isInteger(value) || value < 0))
+      throw new TypeError('initialExpandDepth must be a non-negative integer');
+    if (key === 'iconResolver' && value !== null && typeof value !== 'function')
+      throw new TypeError('iconResolver must be a function or null');
+    if (key === 'fontFamily' && value !== null && typeof value !== 'string')
+      throw new TypeError('fontFamily must be a string or null');
+    if (
+      [
+        'flatRoot',
+        'enforceMeta',
+        'filter',
+        'markUpdated',
+        'editable',
+        'rowReorder',
+        'showHeader'
+      ].includes(key) &&
+      typeof value !== 'boolean'
+    )
+      throw new TypeError(`${key} must be boolean`);
   }
 }

package/src/core/visible-row-model.js

@@ -12,6 +12,7 @@
  */
 
 export class VisibleRowModel extends EventTarget {
+
   /**
    * @param {{
    *   model: import('./tree-model.js').TreeModel,
@@ -26,9 +27,15 @@ export class VisibleRowModel extends EventTarget {
     this.expansion = expansion;
     this.rowHeight = rowHeight;
     this.indentWidth = indentWidth;
-    /** @type {TreeRow[]} */
+
+    /**
+     * @type {TreeRow[]}
+     */
     this.rows = [];
-    /** @type {Map<string, number>} */
+
+    /**
+     * @type {Map<string, number>}
+     */
     this.rowIndexById = new Map();
     this.contentWidth = 0;
     this.contentHeight = 0;
@@ -75,14 +82,18 @@ export class VisibleRowModel extends EventTarget {
       const node = this.model.index.getNode(id);
       const state = this.model.dynamicState.get(id) ?? {};
       const ownMatch = node ? this.filterPredicate(node, state) : false;
-      const childMatch = this.model.index.getChildren(id).some((childId) => subtreeIncluded(childId));
+      const childMatch = this.model.index
+        .getChildren(id)
+        .some((childId) => subtreeIncluded(childId));
       const included = ownMatch || childMatch;
       includeCache.set(id, included);
       return included;
     };
 
     const sortedChildren = (id) => {
-      const children = this.model.index.getChildren(id).filter((childId) => subtreeIncluded(childId));
+      const children = this.model.index
+        .getChildren(id)
+        .filter((childId) => subtreeIncluded(childId));
       if (!this.sortComparator) return children;
       return children.slice().sort((aId, bId) => {
         const a = this.model.index.getNode(aId);
@@ -98,7 +109,8 @@ export class VisibleRowModel extends EventTarget {
       const children = sortedChildren(id);
       const hasChildren = this.expansion.hasChildren(id);
       const autoExpanded = Boolean(this.filterPredicate && children.length > 0);
-      const expanded = (this.expansion.isExpanded(id) || autoExpanded) && !this.filterCollapsed.has(id);
+      const expanded =
+        (this.expansion.isExpanded(id) || autoExpanded) && !this.filterCollapsed.has(id);
       const rowIndex = this.rows.length;
       this.rows.push({
         nodeId: id,
@@ -108,7 +120,7 @@ export class VisibleRowModel extends EventTarget {
         y: rowIndex * this.rowHeight,
         height: this.rowHeight,
         expanded,
-        hasChildren,
+        hasChildren
       });
       this.rowIndexById.set(id, rowIndex);
       maxDepth = Math.max(maxDepth, depth);
@@ -118,7 +130,9 @@ export class VisibleRowModel extends EventTarget {
 
     const roots = this.model.index.roots.filter((rootId) => subtreeIncluded(rootId));
     if (this.sortComparator) {
-      roots.sort((aId, bId) => this.sortComparator(this.model.index.getNode(aId), this.model.index.getNode(bId), aId, bId));
+      roots.sort((aId, bId) =>
+        this.sortComparator(this.model.index.getNode(aId), this.model.index.getNode(bId), aId, bId)
+      );
     }
     for (const rootId of roots) visit(rootId, 0);
     this.contentHeight = this.rows.length * this.rowHeight;
@@ -126,13 +140,17 @@ export class VisibleRowModel extends EventTarget {
     this.dispatchEvent(new Event('change'));
   }
 
-  /** @param {string} id */
+  /**
+   * @param {string} id
+   */
   getRowById(id) {
     const rowIndex = this.rowIndexById.get(id);
     return rowIndex === undefined ? null : this.rows[rowIndex];
   }
 
-  /** @param {number} rowIndex */
+  /**
+   * @param {number} rowIndex
+   */
   getRow(rowIndex) {
     return this.rows[rowIndex] ?? null;
   }
@@ -144,14 +162,23 @@ export class VisibleRowModel extends EventTarget {
   getVisibleRange(viewport, overscan = 6) {
     const rowViewportHeight = viewport.rowViewportHeight ?? viewport.viewportHeight;
     const first = Math.max(0, Math.floor(viewport.scrollY / this.rowHeight) - overscan);
-    const last = Math.min(this.rows.length - 1, Math.ceil((viewport.scrollY + rowViewportHeight) / this.rowHeight) + overscan);
-    return { first, last, count: last >= first ? last - first + 1 : 0 };
+    const last = Math.min(
+      this.rows.length - 1,
+      Math.ceil((viewport.scrollY + rowViewportHeight) / this.rowHeight) + overscan
+    );
+    return {
+      first,
+      last,
+      count: last >= first ? last - first + 1 : 0
+    };
   }
 
-  /** @param {import('./tree-view-viewport.js').TreeViewViewport} viewport */
+  /**
+   * @param {import('./tree-view-viewport.js').TreeViewViewport} viewport
+   */
   getStickyRows(viewport) {
     const rowViewportHeight = viewport.rowViewportHeight ?? viewport.viewportHeight;
-    if (rowViewportHeight < this.rowHeight * 2) return [];
+    if (viewport.scrollY <= 0 || rowViewportHeight < this.rowHeight * 2) return [];
     const max = Math.max(0, Math.min(6, Math.floor(rowViewportHeight / this.rowHeight) - 1));
     const first = Math.max(0, Math.floor(viewport.scrollY / this.rowHeight));
     let row = this.getRow(first);
@@ -169,20 +196,23 @@ export class VisibleRowModel extends EventTarget {
         sticky = [...sticky.slice(0, replaceAt), candidate];
       }
     }
-    return sticky
-      .slice(-max)
-      .map((ancestor, index) => ({
-        ...ancestor,
-        stickyY: Math.max(ancestor.y - viewport.scrollY, index * this.rowHeight),
-      }));
+    return sticky.slice(-max).map((ancestor, index) => ({
+      ...ancestor,
+      stickyY: Math.max(ancestor.y - viewport.scrollY, index * this.rowHeight)
+    }));
   }
 
-  /** @param {TreeRow} row */
+  /**
+   * @param {TreeRow} row
+   */
   #getStickyPath(row) {
-    const ancestors = this.model.index.getAncestors(row.nodeId).reverse()
+    const ancestors = this.model.index
+      .getAncestors(row.nodeId)
+      .reverse()
       .map((id) => this.getRowById(id))
       .filter((ancestor) => ancestor && ancestor.rowIndex < row.rowIndex);
     if (row.hasChildren) ancestors.push(row);
     return ancestors;
   }
+
 }

package/src/index.d.ts

@@ -1,3 +1,16 @@
+export interface RowAction {
+  kind?: 'button' | 'checkbox';
+  checked?: boolean | ((node: TreeNode, state: Record<string, any>) => boolean);
+  id: string;
+  label: string;
+  icon?: string | ((node: TreeNode, state: Record<string, any>) => string);
+  /** Icon variants to rasterize before the first action. */
+  preloadIcons?: string[];
+  visible?: boolean | ((node: TreeNode, state: Record<string, any>) => boolean);
+  disabled?: boolean | ((node: TreeNode, state: Record<string, any>) => boolean);
+  pressed?: boolean | ((node: TreeNode, state: Record<string, any>) => boolean);
+}
+export type RowDragResolver = ((node: TreeNode, state: Record<string, any>) => any | null) | null;
 export const builtinIconNames: readonly string[];
 export interface RowReorderDetail {
   nodeId: string;
@@ -14,6 +27,8 @@ export interface TreeViewOptions {
   iconsBaseUrl?: string | URL;
   iconRegistry?: IconRegistry;
   rowReorder?: boolean;
+  rowActions?: RowAction[];
+  rowDrag?: RowDragResolver;
   autoRender?: boolean;
   tooltip?: boolean;
   canvas?: HTMLCanvasElement;
@@ -49,6 +64,7 @@ export type TreeNode = {
   icon?: string;
   image?: string;
   tags?: string[];
+  reorderable?: boolean;
   data?: any;
 };
 
@@ -89,8 +105,12 @@ export type Column = {
   minWidth?: number;
   align?: 'left' | 'center' | 'right';
   kind?: string;
+  /** Optional semantic type for value-column coloring; defaults to the raw value type. */
+  valueType?: string | ((value: any, node: TreeNode, state: Record<string, any>) => string);
   sortable?: boolean;
   value?: (node: TreeNode, state: Record<string, any>) => string | number | boolean;
+  /** Formats displayed text and tooltips without changing sorting values. */
+  format?: (value: any, node: TreeNode, state: Record<string, any>) => string;
   render?: (ctx: CanvasRenderingContext2D, cell: any) => void;
 };
 
@@ -128,6 +148,10 @@ export class TreeViewController {
   model: any;
   inspector: any;
   columnModel: any;
+  setRowActions(actions: RowAction[]): void;
+  setRowDrag(resolver: RowDragResolver): void;
+  sortBy(id: string, direction?: string): boolean;
+  clearSort(): void;
   setEditable(enabled: boolean): void;
   setInitialExpandDepth(depth: number): void;
   setIconResolver(resolver: TreeViewConfiguration['iconResolver']): void;
@@ -141,7 +165,7 @@ export class TreeViewController {
   nextSearchResult(): string | null;
   previousSearchResult(): string | null;
   setRowReorder(enabled: boolean): void;
-  canReorderRows(): boolean;
+  canReorderRows(nodeId?: string): boolean;
   getRowOrder(parentId?: string | null): string[];
   moveRow(nodeId: string, targetIndex: number, options?: {source?: RowReorderDetail["source"]}): boolean;
   moveRowBy(nodeId: string, offset: number, options?: {source?: RowReorderDetail["source"]}): boolean;
@@ -159,12 +183,14 @@ export class TreeViewController {
   setModel(model: any, meta?: Record<string, MetaRule>, options?: Record<string, any>): void;
   setColumns(columns: Column[] | null): void;
   setDynamicState(patches: DynamicPatch[]): void;
+  flushDynamicState(): Set<string>;
   setTheme(theme: any): void;
   setLayoutMetrics(options?: { rowHeight?: number; indentWidth?: number; headerHeight?: number }): void;
   registerIcon(name: string, icon: IconSource): any;
   resize(width: number, height: number): void;
   render(time?: number): void;
   renderMeasured(time?: number): any;
+  getStats(): TreeViewStats;
   hitTest(clientX: number, clientY: number): any;
   getTooltipForHit(hit: any): any;
   search(query: string, options?: Record<string, any> & { caseSensitive?: boolean; wholeWord?: boolean }): any;
@@ -176,10 +202,31 @@ export class TreeViewController {
   getSelection(): string[];
   setSelection(ids: string[]): void;
   clearSelection(): void;
+  toggle(nodeId: string): boolean;
   expandAll(): void;
   collapseAll(): void;
 }
 
+export interface TreeViewStats {
+  totalNodes: number;
+  visibleRows: number;
+  renderedRows: number;
+  patchesFrame: number;
+  dirtyNodes: number;
+  selectedCount: number;
+  rebuildCount: number;
+  setDynamicStateCalls: number;
+  patchesReceived: number;
+  uniqueNodesReceived: number;
+  nodesChanged: number;
+  rendersRequested: number;
+  rendersExecuted: number;
+  rendersAvoidedNoChanges: number;
+  rendersAvoidedOffscreen: number;
+  rowActionsFullUpdates: number;
+  rowActionsIncrementalUpdates: number;
+}
+
 export class TreeViewInputController {
   constructor(options: { controller: TreeViewController; cellEditor?: CellEditorManager | null });
   destroy(): void;
@@ -208,9 +255,13 @@ export interface TreeViewConfiguration {
   markUpdated?: boolean;
   editable?: boolean;
   rowReorder?: boolean;
+  rowActions?: RowAction[];
+  rowDrag?: RowDragResolver;
   initialExpandDepth?: number;
   rowHeight?: number;
   indentWidth?: number;
+  /** Hide column headings without hiding the filter bar. Defaults to true; inspector panes may hide headings automatically. */
+  showHeader?: boolean;
   headerHeight?: number;
   iconResolver?: ((node: TreeNode) => string | Partial<TreeNode> | null | undefined) | null;
   fontFamily?: string | null;
@@ -273,7 +324,18 @@ export interface TreeSearchState {
   current: string | null;
   count: number;
 }
+export interface RowDragDetail {
+  nodeId: string;
+  payload: any;
+  label: string;
+  originalEvent: PointerEvent;
+}
 export interface TreeViewEvents {
+  rowaction: {checked?: boolean; actionId: string; nodeId: string; node: TreeNode; originalEvent: MouseEvent};
+  rowdragstart: RowDragDetail;
+  rowdragmove: RowDragDetail;
+  rowdragend: RowDragDetail;
+  rowdragcancel: Omit<RowDragDetail, 'originalEvent'>;
   valuechange: InspectorValueChange;
   modelchange: {model: any; meta?: Record<string, MetaRule>; path?: string; structural?: boolean; action?: string; value?: any} & Partial<InspectorValueChange>;
   action: {path: string; label: string; nodeId: string; model: any; source: string};
@@ -288,3 +350,10 @@ export interface TreeViewEvents {
   rowreorderchange: {enabled: boolean};
 }
 export type TreeViewEvent<K extends keyof TreeViewEvents> = {type: K; detail: TreeViewEvents[K]};
+
+/** Formats an inspector value using its options and precision. */
+export function formatInspectorValue(value: any, meta?: MetaRule): string;
+
+export class ModelInspectorBuilder {
+  build(model: any, meta?: Record<string, MetaRule>, options?: {flatRoot?: boolean; enforceMeta?: boolean}): TreeNode[];
+}