virtual-tree-canvas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 virtual-tree-canvas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# virtual-tree-canvas
+
+`virtual-tree-canvas` is a framework-agnostic Canvas2D virtual tree/table widget for large hierarchical datasets.
+
+It behaves like a normal TreeView or tree-table component, but renders into a canvas instead of creating one DOM element per row.
+
+## Features
+
+- Virtualized tree rows
+- Tree-table columns
+- Expand/collapse
+- Single and multi-selection
+- Search and focus
+- Keyboard navigation
+- Horizontal and vertical scrolling
+- Themes and type-based styles
+- Canvas vector icons and image icons
+- Batched dynamic state updates
+- Benchmark/demo mode
+
+No React, Web Components, or frontend framework required.
+
+## Install
+
+```bash
+npm install virtual-tree-canvas
+```
+
+## Performance Model
+
+The renderer only draws visible rows plus a small overscan range.
+
+Dynamic updates are handled as patches:
+
+```js
+tree.setDynamicState([
+  { id: 'node-1', state: { status: 1, progress: 0.7, value: 42 } }
+]);
+```
+
+Dynamic patches update node state without rebuilding:
+
+- tree indexes
+- visible rows
+- expansion state
+- layout
+
+Cold-path operations such as `setData()`, expand/collapse, and search may rebuild the visible row list.
+
+For large datasets, `enableWorkers()` moves search and filtered row rebuilds off the main thread when browser Workers are available. The synchronous APIs remain available for small datasets, tests, and custom integrations.
+
+## Basic Usage
+
+```js
+import { TreeViewController } from 'virtual-tree-canvas';
+
+const canvas = document.querySelector('canvas');
+const tree = new TreeViewController({ canvas });
+
+tree.setData([
+  { id: 'root', label: 'Root', type: 'root' },
+  { id: 'child-1', parentId: 'root', label: 'Child', type: 'sensor' }
+]);
+```
+
+## Public API
+
+```js
+tree.setData(nodes);
+tree.setModel(model, meta, { presentation: 'pane' });
+tree.setDynamicState(patches);
+
+tree.expand(nodeId);
+tree.collapse(nodeId);
+tree.toggle(nodeId);
+tree.expandAll();
+tree.collapseAll();
+
+tree.search(query);
+tree.searchAsync(query);
+tree.clearSearch();
+tree.getSearchState();
+tree.nextSearchResult();
+tree.previousSearchResult();
+tree.setFilter(queryOrPredicate);
+tree.setFilterAsync(query);
+tree.clearFilter();
+
+tree.focusNode(nodeId);
+tree.scrollToNode(nodeId, 'center');
+
+tree.getSelection();
+tree.setSelection(['node-1', 'node-2']);
+tree.clearSelection();
+
+tree.setTheme(theme);
+tree.setColumns(columns);
+tree.resizeColumn(columnId, width);
+tree.moveColumn(columnId, targetIndex);
+tree.sortBy(columnId, 'asc');
+tree.clearSort();
+tree.registerIcon('custom', imageOrUrlOrDrawFunction);
+
+tree.enableWorkers();
+tree.disableWorkers();
+```
+
+## Model Inspector
+
+`setModel(model, meta, options)` renders plain JSON-like objects as an editable inspector.
+
+```js
+tree.setModel(
+  {
+    sensor: { enabled: true, range: 72, mode: 'track' },
+    tracks: [{ id: 'T-100', speed: 430 }]
+  },
+  {
+    'sensor.range': { min: 0, max: 120, step: 1, integer: true },
+    'sensor.mode': { options: { Search: 'search', Track: 'track' } },
+    'tracks.*.speed': { min: 0, max: 900, step: 5 },
+    'tracks.*.id': { readonly: true }
+  }
+);
+```
+
+Inspector options:
+
+```js
+tree.setModel(model, meta, {
+  presentation: 'pane',
+  flatRoot: true,    // render root properties directly
+  enforceMeta: true, // fields without metadata are readonly/disabled
+  filter: true       // use the header as a filter input
+});
+```
+
+Presentations:
+
+```js
+tree.setModel(model, meta, { presentation: 'pane' });  // compact folders + key/value controls
+tree.setModel(model, meta, { presentation: 'table' }); // Property | Value | Type | Description
+```
+
+Metadata is path-based. Dot paths target object properties, and array items use numeric indexes or `*` wildcards:
+
+```text
+sensor.range
+tracks.0.speed
+tracks.*.speed
+```
+
+Inspector editors are inferred from values and metadata: checkbox, range, number, text, select, color, button, object, and array.
+
+Inspector events:
+
+```js
+tree.on('valuechange', (event) => {});
+tree.on('modelchange', (event) => {});
+tree.on('action', (event) => {});
+```
+
+`scrollToNode()` supports:
+
+```text
+start | center | end | nearest
+```
+
+## Events
+
+```js
+tree.on('nodehover', (event) => {});
+tree.on('nodeclick', (event) => {});
+tree.on('nodedblclick', (event) => {});
+tree.on('selectionchange', (event) => {});
+tree.on('expand', (event) => {});
+tree.on('collapse', (event) => {});
+tree.on('focuschange', (event) => {});
+tree.on('searchchange', (event) => {});
+tree.on('filterchange', (event) => {});
+tree.on('sortchange', (event) => {});
+tree.on('columnschange', (event) => {});
+tree.on('viewportchange', (event) => {});
+```
+
+The event payload is available as `event.detail`.
+
+## Columns
+
+```js
+tree.setColumns([
+  {
+    id: 'name',
+    label: 'Name',
+    width: 340,
+    minWidth: 160,
+    align: 'left',
+    kind: 'tree',
+    value: (node) => node.label ?? node.id
+  },
+  {
+    id: 'status',
+    label: 'Status',
+    width: 84,
+    minWidth: 64,
+    align: 'center',
+    kind: 'status',
+    value: (_node, state) => state.status
+  }
+]);
+```
+
+Column shape:
+
+```js
+{
+  id: 'status',
+  label: 'Status',
+  width: 80,
+  minWidth: 40,
+  align: 'left' | 'center' | 'right',
+  kind: 'tree' | 'status' | 'value' | 'progress' | 'type' | 'updated' | 'text',
+  sortable: true,
+  value: (node, state) => string | number,
+  render: (ctx, cell) => {}
+}
+```
+
+Built-in helpers:
+
+```js
+import { builtInColumns, defaultTreeTableColumns } from 'virtual-tree-canvas';
+```
+
+The tree column renders indentation, chevron, icon, and label. Other columns render table cells and participate in horizontal scrolling.
+
+Columns can be resized, reordered, and sorted through the controller API. The demo also supports header click sorting and drag-to-resize on column edges.
+
+## Themes
+
+```js
+tree.setTheme({
+  rowHeight: 28,
+  indentWidth: 18,
+  font: '12px system-ui',
+  colors: {
+    background: '#0b1020',
+    row: '#0b1020',
+    rowHover: '#111827',
+    rowSelected: '#1e3a8a',
+    rowHighlighted: '#3b0764',
+    text: '#e5e7eb',
+    textMuted: '#94a3b8',
+    guide: '#1f2937',
+    chevron: '#94a3b8',
+    focus: '#38bdf8',
+    progressTrack: '#1f2937',
+    progressFill: '#22c55e',
+    badgeText: '#ffffff'
+  },
+  types: {
+    root: { icon: 'folder', color: '#38bdf8' },
+    platform: { icon: 'aircraft', color: '#60a5fa' },
+    sensor: { icon: 'radar', color: '#34d399' },
+    warning: { icon: 'warning', color: '#facc15' },
+    error: { icon: 'error', color: '#ef4444' }
+  },
+  statuses: {
+    0: { label: 'OK', color: '#22c55e' },
+    1: { label: 'WARN', color: '#facc15' },
+    2: { label: 'ERR', color: '#ef4444' }
+  }
+});
+```
+
+Built-in theme exports:
+
+```js
+import { themes, darkTheme, lightTheme, tacticalTheme } from 'virtual-tree-canvas';
+```
+
+Style resolution order:
+
+1. Dynamic state override, such as `state.color`
+2. Node type rule, such as `theme.types.sensor`
+3. Default theme color
+
+## Icons
+
+Built-in Canvas2D vector icons:
+
+```text
+folder, aircraft, radar, warning, error, task, track, placeholder
+```
+
+Register custom icons:
+
+```js
+tree.registerIcon('camera', imageElement);
+tree.registerIcon('camera-url', '/icons/camera.png');
+tree.registerIcon('custom-vector', (ctx, x, y, size, color) => {
+  ctx.fillStyle = color;
+  ctx.fillRect(x, y, size, size);
+});
+```
+
+Icons are cached by name and drawn only for rendered rows.
+
+## Demo
+
+```bash
+npm run demo
+```
+
+Open:
+
+```text
+http://localhost:4173/demo/
+```
+
+Inspector demo:
+
+```text
+http://localhost:4173/demo/inspector.html
+```
+
+The demo includes dataset sizes, update rates, benchmark stats, search, filtering, selection, expand/collapse, themes, and tree-table columns.
+
+Benchmark stats separate frame, patch, scene, render, search, filter, and worker timings. Use "Copy JSON" to export the current sample.
+
+## Tests
+
+```bash
+npm test
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "virtual-tree-canvas",
+  "version": "0.1.0",
+  "description": "High-performance Canvas2D virtual tree/table widget for very large hierarchical datasets.",
+  "type": "module",
+  "main": "./src/index.js",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core/index.js",
+    "./inspector": "./src/inspector/index.js",
+    "./renderers": "./src/renderers/index.js",
+    "./input": "./src/input/index.js",
+    "./benchmark": "./src/benchmark/index.js",
+    "./workers/tree-worker.js": "./src/workers/tree-worker.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "demo": "python3 -m http.server 4173 --bind localhost",
+    "test": "node --test test/tree-view-controller.test.js test/theme-icons.test.js test/tree-columns.test.js test/benchmark.test.js test/tree-worker-operations.test.js test/model-inspector.test.js"
+  },
+  "keywords": [
+    "tree",
+    "visualization",
+    "canvas",
+    "canvas2d",
+    "virtual-list",
+    "tree-table",
+    "hierarchy"
+  ],
+  "license": "MIT"
+}

package/src/assets/.gitkeep

@@ -0,0 +1 @@
+

package/src/benchmark/benchmark-stats.js

@@ -0,0 +1,99 @@
+export class BenchmarkStats {
+  constructor({ maxSamples = 240 } = {}) {
+    this.maxSamples = maxSamples;
+    this.samples = {
+      frameMs: [],
+      patchMs: [],
+      sceneMs: [],
+      renderMs: [],
+      inputLatencyMs: [],
+      searchMs: [],
+      filterMs: [],
+      workerMs: [],
+    };
+    this.frameCount = 0;
+    this.patchCount = 0;
+    this.lastSecondAt = null;
+    this.fps = 0;
+    this.patchesPerSecond = 0;
+    this.lastPatchesFrame = 0;
+  }
+
+  recordFrame({ now, frameMs, patchMs = 0, sceneMs, renderMs, patchesFrame = 0, inputLatencyMs = 0 }) {
+    this.frameCount++;
+    this.patchCount += patchesFrame;
+    this.lastPatchesFrame = patchesFrame;
+    pushSample(this.samples.frameMs, frameMs, this.maxSamples);
+    pushSample(this.samples.patchMs, patchMs, this.maxSamples);
+    pushSample(this.samples.sceneMs, sceneMs, this.maxSamples);
+    pushSample(this.samples.renderMs, renderMs, this.maxSamples);
+    if (inputLatencyMs) pushSample(this.samples.inputLatencyMs, inputLatencyMs, this.maxSamples);
+
+    if (this.lastSecondAt === null) this.lastSecondAt = now;
+    const elapsed = now - this.lastSecondAt;
+    if (elapsed >= 1000) {
+      this.fps = (this.frameCount * 1000) / elapsed;
+      this.patchesPerSecond = (this.patchCount * 1000) / elapsed;
+      this.frameCount = 0;
+      this.patchCount = 0;
+      this.lastSecondAt = now;
+    }
+  }
+
+  recordOperation(type, durationMs) {
+    if (type === 'search') pushSample(this.samples.searchMs, durationMs, this.maxSamples);
+    else if (type === 'filter') pushSample(this.samples.filterMs, durationMs, this.maxSamples);
+    else if (type === 'worker') pushSample(this.samples.workerMs, durationMs, this.maxSamples);
+  }
+
+  snapshot() {
+    return {
+      fps: this.fps,
+      patchesFrame: this.lastPatchesFrame,
+      patchesPerSecond: this.patchesPerSecond,
+      frameMs: describe(this.samples.frameMs),
+      patchMs: describe(this.samples.patchMs),
+      sceneMs: describe(this.samples.sceneMs),
+      renderMs: describe(this.samples.renderMs),
+      inputLatencyMs: describe(this.samples.inputLatencyMs),
+      searchMs: describe(this.samples.searchMs),
+      filterMs: describe(this.samples.filterMs),
+      workerMs: describe(this.samples.workerMs),
+      sampleCount: this.samples.frameMs.length,
+
+      // Backward-compatible aliases for existing callers/tests.
+      avgFrameMs: average(this.samples.frameMs),
+      p95FrameMs: percentile(this.samples.frameMs, 0.95),
+      avgSceneMs: average(this.samples.sceneMs),
+      avgRenderMs: average(this.samples.renderMs),
+      p95RenderMs: percentile(this.samples.renderMs, 0.95),
+      avgInputLatencyMs: average(this.samples.inputLatencyMs),
+    };
+  }
+}
+
+function describe(samples) {
+  return {
+    avg: average(samples),
+    p50: percentile(samples, 0.5),
+    p95: percentile(samples, 0.95),
+    p99: percentile(samples, 0.99),
+  };
+}
+
+function pushSample(samples, value, maxSamples) {
+  samples.push(value);
+  if (samples.length > maxSamples) samples.shift();
+}
+
+function average(samples) {
+  if (!samples.length) return 0;
+  return samples.reduce((sum, value) => sum + value, 0) / samples.length;
+}
+
+function percentile(samples, p) {
+  if (!samples.length) return 0;
+  const sorted = samples.slice().sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.ceil(sorted.length * p) - 1);
+  return sorted[index];
+}

package/src/benchmark/index.js

@@ -0,0 +1,2 @@
+export * from './benchmark-stats.js';
+export * from './renderer-state.js';

package/src/benchmark/renderer-state.js

@@ -0,0 +1,62 @@
+export function captureTreeViewState(controller) {
+  return {
+    scrollX: controller.viewport.scrollX,
+    scrollY: controller.viewport.scrollY,
+    selection: controller.getSelection(),
+    focusedId: controller.focusedId,
+    searchQuery: controller.searchIndex.lastQuery ?? '',
+    searchResults: controller.searchIndex.results.slice(),
+    searchCursor: controller.searchIndex.cursor,
+    searchMatches: new Set(controller.searchHighlights),
+    filterQuery: controller.filterQuery,
+    sort: { ...controller.columnModel.sort },
+    columns: controller.columnModel.columns.map((column) => ({ ...column })),
+    expanded: new Set(controller.expansion.model.expanded),
+    theme: controller.themeManager.get(),
+  };
+}
+
+export function restoreTreeViewState(controller, state) {
+  if (state.columns) controller.setColumns(state.columns);
+  controller.expansion.model.expanded = new Set(state.expanded);
+  if (state.sort?.columnId) controller.sortBy(state.sort.columnId, state.sort.direction);
+  if (state.filterQuery) controller.setFilter(state.filterQuery);
+  controller.rowModel.rebuild();
+  controller.viewport.setContentSize(controller.columnModel.contentWidth, controller.rowModel.contentHeight);
+  controller.viewport.scrollTo(state.scrollX, state.scrollY);
+  controller.setSelection(state.selection);
+  controller.focusedId = state.focusedId;
+  controller.selection.focused = state.focusedId;
+  controller.searchIndex.results = state.searchResults.slice();
+  controller.searchIndex.cursor = state.searchCursor;
+  controller.searchIndex.lastQuery = state.searchQuery;
+  controller.searchHighlights = new Set(state.searchMatches);
+  controller.setTheme(state.theme);
+}
+
+export function sceneSignature(scene) {
+  return {
+    visibleRange: { ...scene.visibleRange },
+    viewport: {
+      scrollX: scene.viewport.scrollX,
+      scrollY: scene.viewport.scrollY,
+      width: scene.viewport.viewportWidth,
+      height: scene.viewport.viewportHeight,
+      contentWidth: scene.viewport.contentWidth,
+      contentHeight: scene.viewport.contentHeight,
+    },
+    columns: scene.columns.map((column) => ({ id: column.id, x: column.x, width: column.width, kind: column.kind })),
+    rows: scene.rows.slice(scene.visibleRange.first, scene.visibleRange.last + 1).map((row) => ({
+      nodeId: row.nodeId,
+      rowIndex: row.rowIndex,
+      depth: row.depth,
+      expanded: row.expanded,
+    })),
+    selection: Array.from(scene.selection).sort(),
+    hoverNodeId: scene.hoverNodeId,
+    focusNodeId: scene.focusNodeId,
+    searchMatches: Array.from(scene.searchMatches).sort(),
+    sort: scene.sort,
+    filterQuery: scene.filterQuery,
+  };
+}

package/src/core/asset-manager.js

@@ -0,0 +1,25 @@
+export class AssetManager {
+  constructor() {
+    this.images = new Map();
+    this.iconIndices = new Map();
+  }
+
+  registerIcon(name) {
+    if (!this.iconIndices.has(name)) this.iconIndices.set(name, this.iconIndices.size);
+    return this.iconIndices.get(name);
+  }
+
+  async loadImage(name, url) {
+    const image = new Image();
+    image.decoding = 'async';
+    image.src = url;
+    await image.decode();
+    this.images.set(name, image);
+    return image;
+  }
+
+  getImage(name) {
+    return this.images.get(name) ?? null;
+  }
+}
+

package/src/core/culling.js

@@ -0,0 +1,12 @@
+export function rectsIntersect(a, b) {
+  return a.x <= b.x + b.width && a.x + a.width >= b.x && a.y <= b.y + b.height && a.y + a.height >= b.y;
+}
+
+export function cullLayoutNodes(layoutNodes, worldBounds) {
+  const visible = [];
+  for (const node of layoutNodes) {
+    if (rectsIntersect(node, worldBounds)) visible.push(node.index);
+  }
+  return visible;
+}
+

package/src/core/event-emitter.js

@@ -0,0 +1,21 @@
+export class EventEmitter {
+  constructor() {
+    this.listeners = new Map();
+  }
+
+  on(type, listener) {
+    if (!this.listeners.has(type)) this.listeners.set(type, new Set());
+    this.listeners.get(type).add(listener);
+    return () => this.off(type, listener);
+  }
+
+  off(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  emit(type, detail = {}) {
+    const event = { type, detail };
+    for (const listener of this.listeners.get(type) ?? []) listener(event);
+  }
+}
+