virtual-tree-canvas 0.5.0 → 0.7.0

package/src/core/view-options.js

@@ -0,0 +1,37 @@
+import { resolveTheme } from './theme-manager.js';
+/** 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,
+  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');
+  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 === '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 === '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', 'showHeader'].includes(key) && typeof value !== 'boolean') throw new TypeError(`${key} must be boolean`);
+  }
+}

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

@@ -151,7 +151,7 @@ export class VisibleRowModel extends EventTarget {
   /** @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);

package/src/index.d.ts

@@ -1,10 +1,54 @@
+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;
+  parentId: string | null;
+  fromIndex: number;
+  toIndex: number;
+  siblingOrder: string[];
+  order: string[];
+  source: 'api' | 'pointer' | 'button' | 'keyboard';
+}
+
+export interface TreeViewOptions {
+  nativeScrollbars?: boolean;
+  iconsBaseUrl?: string | URL;
+  iconRegistry?: IconRegistry;
+  rowReorder?: boolean;
+  rowActions?: RowAction[];
+  rowDrag?: RowDragResolver;
+  autoRender?: boolean;
+  tooltip?: boolean;
+  canvas?: HTMLCanvasElement;
+  host?: HTMLElement;
+  [key: string]: any;
+}
+
+export class TreeTooltip {
+  constructor(options: { controller: TreeViewController; host?: HTMLElement });
+  hide(): void;
+  destroy(): void;
+}
+
 export type TreeViewAlign = 'start' | 'center' | 'end' | 'nearest';
 
 export type IconDrawFunction = (ctx: CanvasRenderingContext2D, x: number, y: number, size: number, color: string) => void;
 export type IconSource = string | CanvasImageSource | IconDrawFunction;
 
 export class IconRegistry {
-  constructor(options?: { pixelRatio?: number });
+  constructor(options?: { pixelRatio?: number; iconsBaseUrl?: string | URL });
   register(name: string, icon: IconSource): any;
   get(name: string): any;
   onChange(listener: () => void): () => void;
@@ -20,6 +64,7 @@ export type TreeNode = {
   icon?: string;
   image?: string;
   tags?: string[];
+  reorderable?: boolean;
   data?: any;
 };
 
@@ -60,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;
 };
 
@@ -89,16 +138,50 @@ export class TreeViewController {
   rowModel: any;
   expansion: any;
   selection: any;
-  constructor(options?: Record<string, any> & { nativeScrollbars?: boolean });
+  constructor(options?: TreeViewOptions);
+  iconRegistry: IconRegistry;
+  tooltip?: TreeTooltip | null;
+  rowReorder: boolean;
+  editable: boolean;
+  initialExpandDepth: number;
+  filterOptions: {caseSensitive: boolean; wholeWord: boolean};
+  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;
+  setInspectorOptions(options: {filter?: boolean; markUpdated?: boolean}): void;
+  setHeaderFilter(enabled: boolean): void;
+  setInspectorValue(path: string, value: any, options?: InspectorWriteOptions): boolean;
+  updateInspectorValue(nodeId: string, value: any, editorType?: string, options?: InspectorWriteOptions): boolean;
+  closeEditor(): void;
+  clearSearch(): void;
+  getSearchState(): TreeSearchState;
+  nextSearchResult(): string | null;
+  previousSearchResult(): string | null;
+  setRowReorder(enabled: boolean): void;
+  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;
+  requestRender(force?: boolean): void;
+  cancelRender(): void;
+  attachTooltip(options?: {host?: HTMLElement}): TreeTooltip;
   initialize(canvas: HTMLCanvasElement): this;
   attachCellEditor(options?: { host?: HTMLElement | null }): CellEditorManager;
   attachInput(options?: { cellEditor?: CellEditorManager | null }): TreeViewInputController;
   destroy(): void;
-  on(type: string, listener: (event: any) => void): any;
+  on<K extends keyof TreeViewEvents>(type: K, listener: (event: TreeViewEvent<K>) => void): () => void;
+  on(type: string, listener: (event: any) => void): () => void;
   off(type: string, listener: (event: any) => void): void;
-  setData(nodes: TreeNode[]): void;
+  setData(nodes: TreeNode[], options?: { iconResolver?: TreeViewConfiguration['iconResolver'] }): void;
   setModel(model: any, meta?: Record<string, MetaRule>, options?: Record<string, any>): void;
-  setColumns(columns: Column[]): void;
+  setColumns(columns: Column[] | null): void;
   setDynamicState(patches: DynamicPatch[]): void;
   setTheme(theme: any): void;
   setLayoutMetrics(options?: { rowHeight?: number; indentWidth?: number; headerHeight?: number }): void;
@@ -117,6 +200,7 @@ export class TreeViewController {
   getSelection(): string[];
   setSelection(ids: string[]): void;
   clearSelection(): void;
+  toggle(nodeId: string): boolean;
   expandAll(): void;
   collapseAll(): void;
 }
@@ -129,5 +213,125 @@ export class TreeViewInputController {
 export class CellEditorManager {
   constructor(options: { controller: TreeViewController; host?: HTMLElement | null });
   destroy(): void;
+  setEditable(enabled: boolean): void;
   close(): void;
 }
+
+export interface InspectorWriteOptions { emit?: boolean; source?: string }
+export interface TreeViewConfiguration {
+  mode?: 'tree' | 'inspector';
+  presentation?: 'pane' | 'table';
+  nodes?: TreeNode[];
+  model?: any;
+  meta?: Record<string, MetaRule> | null;
+  columns?: Column[] | null;
+  theme?: string | Record<string, any>;
+  flatRoot?: boolean;
+  enforceMeta?: boolean;
+  filter?: boolean;
+  filterPlacement?: 'auto' | 'bar' | 'header';
+  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;
+}
+export const treeViewOptionNames: readonly (keyof TreeViewConfiguration)[];
+export function validateTreeViewOptions(options: TreeViewConfiguration): void;
+
+export class TreeView {
+  constructor(host: HTMLElement, options?: TreeViewConfiguration & Pick<TreeViewOptions, 'iconsBaseUrl' | 'iconRegistry' | 'nativeScrollbars'>);
+  readonly controller: TreeViewController;
+  readonly element: HTMLDivElement;
+  readonly canvas: HTMLCanvasElement;
+  readonly destroyed: boolean;
+  configure(options: TreeViewConfiguration): this;
+  flush(): void;
+  destroy(): void;
+  setData(nodes: TreeNode[]): void;
+  setModel(model: any, meta?: Record<string, MetaRule>): void;
+  setColumns(columns: Column[] | null): void;
+  setTheme(theme: string | Record<string, any>): void;
+  setDynamicState(patches: DynamicPatch[]): void;
+  setInspectorValue(path: string, value: any, options?: InspectorWriteOptions): boolean;
+  on<K extends keyof TreeViewEvents>(type: K, listener: (event: TreeViewEvent<K>) => void): () => void;
+  on(type: string, listener: (event: any) => void): () => void;
+  off(type: string, listener: (event: any) => void): void;
+  setFilter(query?: string | ((node: TreeNode, state: Record<string, any>) => boolean), options?: {caseSensitive?: boolean; wholeWord?: boolean}): void;
+  clearFilter(): void;
+  getRowOrder(parentId?: string | null): string[];
+  moveRow(id: string, index: number, options?: {source?: RowReorderDetail['source']}): boolean;
+  moveRowBy(id: string, offset: number, options?: {source?: RowReorderDetail['source']}): boolean;
+  getSelection(): string[];
+  setSelection(ids: string[]): void;
+  clearSelection(): void;
+  search(query: string, options?: Record<string, any>): any;
+  clearSearch(): void;
+  getSearchState(): TreeSearchState;
+  nextSearchResult(): string | null;
+  previousSearchResult(): string | null;
+  focusNode(id: string, options?: Record<string, any>): boolean;
+  scrollToNode(id: string, align?: TreeViewAlign): boolean;
+  expandAll(): void;
+  collapseAll(): void;
+  registerIcon(name: string, source: IconSource): any;
+}
+
+/** Public event details shared by the DOM view and the controller. */
+export interface InspectorValueChange {
+  path: string;
+  oldValue: any;
+  newValue: any;
+  model: any;
+  nodeId: string;
+  editorType: string;
+  source: string;
+}
+export interface TreeSearchState {
+  query: string;
+  results: string[];
+  cursor: number;
+  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};
+  rowreorder: RowReorderDetail;
+  selectionchange: {selection: string[]; focusedId: string | null};
+  focuschange: {nodeId: string | null};
+  filterchange: {query: string; options: {caseSensitive: boolean; wholeWord: boolean}; visibleRows: number; worker?: boolean};
+  searchchange: Omit<TreeSearchState, 'count'>;
+  nodeclick: {nodeId: string; row: any; originalEvent: any};
+  nodedblclick: {nodeId: string; row: any; originalEvent: any};
+  editablechange: {editable: boolean};
+  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[];
+}

package/src/index.js

@@ -4,3 +4,6 @@ export * from './inspector/index.js';
 export * from './renderers/index.js';
 export * from './tree-view-controller.js';
 export * from './benchmark/index.js';
+export { builtinIconNames } from './assets/icons.js';
+export { TreeView } from './tree-view.js';
+export { treeViewOptionNames, validateTreeViewOptions } from './core/view-options.js';

package/src/input/index.js

@@ -1,2 +1,3 @@
 export * from './pointer-controller.js';
 export * from './tree-view-input-controller.js';
+export * from './tree-tooltip.js';

package/src/input/row-actions.js

@@ -0,0 +1,115 @@
+import { drawCheckbox } from '../renderers/checkbox.js';
+/** Accessible buttons for visible rows. Actions and their meaning belong to the host. */
+export class RowActions {
+  constructor(controller) {
+    this.controller = controller;
+    this.buttons = new Map();
+    this.preparedIcons = new Set();
+    this.element = controller.canvas.ownerDocument.createElement('div');
+    Object.assign(this.element.style, { position: 'absolute', overflow: 'hidden', pointerEvents: 'none', zIndex: '2' });
+    const style = controller.canvas.ownerDocument.createElement('style');
+    style.textContent = `
+      .vtc-row-action { appearance:none; display:flex; align-items:center; justify-content:center;
+        background:transparent; color:inherit; outline:none; }
+      .vtc-row-action:hover:not(:disabled) canvas { filter:brightness(1.45) drop-shadow(0 0 2px var(--vtc-action-focus)); }
+      .vtc-row-action:focus-visible { outline:1px solid var(--vtc-action-focus); outline-offset:-2px; }
+    `;
+    this.element.append(style);
+    controller.canvas.parentElement?.append(this.element);
+    this.element.addEventListener('pointerdown', event => event.stopPropagation());
+  }
+
+  render(scene) {
+    const { viewport, theme, rows, visibleRange, stickyRows } = scene;
+    const ratio = Math.max(1, this.element.ownerDocument.defaultView.devicePixelRatio || 1);
+    for (const action of this.controller.rowActions) {
+      const icons = action.preloadIcons ?? (typeof action.icon === 'string' ? [action.icon] : []);
+      for (const icon of icons) for (const color of [theme.colors.text, theme.colors.textMuted]) {
+        const key = JSON.stringify([icon, color, ratio]);
+        if (this.preparedIcons.has(key)) continue;
+        this.preparedIcons.add(key);
+        void this.controller.iconRegistry.prepare({icons:[icon],size:16,color,pixelRatio:ratio});
+      }
+    }
+    const column = scene.columns.find(c => c.id === '__vtc_actions');
+    const used = new Set();
+    const width = column?.width ?? 0;
+    this.element.style.setProperty('--vtc-action-focus', theme.colors.focus);
+    Object.assign(this.element.style, { background:'transparent', left: `${viewport.renderInsetX + Math.max(0, viewport.contentViewportWidth - width)}px`, top: `${viewport.renderInsetY + viewport.headerHeight}px`,
+      width: `${width}px`, height: `${viewport.rowViewportHeight}px` });
+    if (column) {
+      const visible = new Map();
+      const stickyBottom = stickyRows.reduce((end, row) => Math.max(end, row.stickyY + row.height), 0);
+      for (let i = visibleRange.first; i <= visibleRange.last; i++) {
+        const row = rows[i];
+        if (row && row.y + row.height - viewport.scrollY > stickyBottom) visible.set(row.nodeId, {row, y:row.y - viewport.scrollY});
+      }
+      for (const row of stickyRows) visible.set(row.nodeId, {row, y:row.stickyY, sticky:true});
+      for (const {row, y, sticky} of visible.values()) {
+        if (y + row.height <= 0 || y >= viewport.rowViewportHeight) continue;
+        const node = this.controller.model.index.getNode(row.nodeId);
+        const state = this.controller.model.dynamicState.get(node.id) ?? {};
+        this.controller.rowActions.forEach((action, index) => {
+          const resolve = value => typeof value === 'function' ? value(node, state) : value;
+          if (resolve(action.visible) === false) return;
+          const key = JSON.stringify([node.id, action.id, action.kind]);
+          used.add(key);
+          let button = this.buttons.get(key);
+          if (!button) {
+            button = this.element.ownerDocument.createElement('button');
+            button.type = 'button';
+            if (action.kind === 'checkbox') button.setAttribute('role','checkbox');
+            button.className = 'vtc-row-action';
+            button.dataset.nodeId = node.id;
+            button.dataset.action = action.id;
+            Object.assign(button.style, { position:'absolute', pointerEvents:'auto', width:'26px', padding:'3px', border:'0', borderRadius:'3px', cursor:'pointer' });
+            const icon = this.element.ownerDocument.createElement('canvas');
+            Object.assign(icon.style, {width:'16px',height:'16px',display:'block'});
+            button.append(icon);
+            button.onclick = event => {
+              event.stopPropagation();
+              const current = this.controller.model.index.getNode(button.dataset.nodeId);
+              const spec = this.controller.rowActions.find(item => item.id === button.dataset.action);
+              const currentState = this.controller.model.dynamicState.get(current?.id) ?? {};
+              if (!current || !spec || (typeof spec.disabled === 'function' ? spec.disabled(current, currentState) : spec.disabled)) return;
+              this.controller.events.emit('rowaction', { actionId: spec.id, nodeId: current.id, node: current, ...(spec.kind === 'checkbox' ? {checked:!(typeof spec.checked === 'function' ? spec.checked(current,currentState) : spec.checked)} : {}), originalEvent: event });
+            };
+            this.buttons.set(key, button);
+            this.element.append(button);
+          }
+          button.title = action.label;
+          button.setAttribute('aria-label', `${action.label}: ${node.label ?? node.id}`);
+          if (action.pressed !== undefined) button.setAttribute('aria-pressed', String(Boolean(resolve(action.pressed))));
+          else button.removeAttribute('aria-pressed');
+          button.disabled = Boolean(resolve(action.disabled));
+          Object.assign(button.style, { left:`${index * 28 + 1}px`, top:`${y + 1}px`, height:`${row.height - 2}px`,
+            clipPath:sticky ? 'none' : `inset(${Math.max(0, stickyBottom - y - 1)}px 0 0)`, opacity:button.disabled ? '0.3':'1' });
+          const canvas = button.firstChild;
+          const ratio = Math.max(1, this.element.ownerDocument.defaultView.devicePixelRatio || 1);
+          const size = action.kind === 'checkbox' ? 18 : 16;
+          canvas.style.width = canvas.style.height = `${size}px`;
+          const pixels = Math.round(size * ratio);
+          if (canvas.width !== pixels || canvas.height !== pixels) canvas.width = canvas.height = pixels;
+          const ctx = canvas.getContext('2d');
+          ctx.setTransform(pixels / size, 0, 0, pixels / size, 0, 0);
+          ctx.clearRect(0,0,size,size);
+          if (action.kind === 'checkbox') {
+            const checked = Boolean(resolve(action.checked));
+            button.setAttribute('aria-checked', String(checked));
+            drawCheckbox(ctx,1,1,checked,theme);
+            return;
+          }
+          this.controller.iconRegistry.draw(ctx, resolve(action.icon) ?? 'star', 0,0,16,resolve(action.pressed) ? theme.colors.text : theme.colors.textMuted);
+        });
+      }
+    }
+    let refocus = false;
+    for (const [key, button] of this.buttons) if (!used.has(key)) {
+      refocus ||= this.element.getRootNode().activeElement === button;
+      button.remove(); this.buttons.delete(key);
+    }
+    if (refocus) (this.buttons.values().next().value ?? this.controller.canvas).focus({preventScroll:true});
+  }
+
+  destroy() { this.element.remove(); this.buttons.clear(); }
+}

package/src/input/row-reorder-input.js

@@ -0,0 +1,168 @@
+let nextStatusId = 0;
+
+/** Pointer interaction for the optional row-order column; persistence belongs to the host. */
+export class RowReorderInput {
+  constructor(controller) {
+    this.controller = controller;
+    this.canvas = controller.canvas;
+    this.view = this.canvas.ownerDocument?.defaultView ?? globalThis.window;
+    this.gesture = null;
+    this.frame = null;
+    this.previousTouchAction = this.canvas.style.touchAction;
+    this.canvas.addEventListener('pointerdown', this.onDown);
+    this.canvas.addEventListener('keydown', this.onKey);
+    this.canvas.addEventListener('lostpointercapture', this.onCancel);
+    this.view.addEventListener('pointermove', this.onMove);
+    this.view.addEventListener('pointerup', this.onUp);
+    this.view.addEventListener('pointercancel', this.onCancel);
+    this.view.addEventListener('blur', this.cancel);
+    this.stops = ['filterchange', 'sortchange', 'rowreorderchange'].map(type => controller.on(type, () => {
+      this.cancel();
+      this.syncMode();
+    }));
+    this.stops.push(controller.on('datachange', () => {
+      if (this.gesture && !controller.model.index.getNode(this.gesture.id)) this.cancel();
+    }));
+    this.stops.push(controller.on('rowreorder', event => {
+      if (!this.status) return;
+      const { nodeId, toIndex, siblingOrder } = event.detail;
+      const label = controller.model.index.getNode(nodeId)?.label ?? nodeId;
+      this.status.textContent = `${label}: position ${toIndex + 1} of ${siblingOrder.length}`;
+    }));
+    const doc = this.canvas.ownerDocument;
+    if (doc?.createElement && this.canvas.parentElement) {
+      this.status = doc.createElement('span');
+      this.status.id = `vtc-row-order-status-${nextStatusId++}`;
+      this.status.setAttribute('aria-live', 'polite');
+      Object.assign(this.status.style, { position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', clipPath: 'inset(50%)' });
+      this.canvas.parentElement.appendChild(this.status);
+    }
+    this.syncMode();
+  }
+
+  syncMode() {
+    this.canvas.style.touchAction = (this.controller.canReorderRows() || this.controller.rowDrag) ? 'none' : this.previousTouchAction;
+  }
+
+  onDown = event => {
+    if (event.button !== 0 || event.isPrimary === false || this.gesture) return;
+    this.suppressClick = false;
+    const point = this.point(event);
+    const hit = this.controller.hitTest(point.x, point.y);
+    if (!hit?.row) return;
+    const node = this.controller.model.index.getNode(hit.row.nodeId);
+    const payload = this.controller.rowDrag?.(node, this.controller.model.dynamicState.get(node.id) ?? {}) ?? null;
+    const orderPart = ['rowDrag', 'rowUp', 'rowDown'].includes(hit.part);
+    if (orderPart && node.reorderable === false) return;
+    if (orderPart ? !this.controller.canReorderRows() && !(payload != null && hit.part === 'rowDrag') : payload == null || !['label', 'row', 'icon', 'cell'].includes(hit.part)) return;
+    this.canvas.focus({ preventScroll: true });
+    this.controller.cellEditor?.close?.();
+    this.controller.focusedId = hit.row.nodeId;
+    this.gesture = { id: hit.row.nodeId, part: orderPart ? hit.part : 'rowDrag', payload, pointerId: event.pointerId,
+      startX: point.x, startY: point.y, point, dragging: false };
+    this.canvas.setPointerCapture?.(event.pointerId);
+    event.stopPropagation();
+    if (orderPart) event.preventDefault();
+  };
+
+  onMove = event => {
+    const gesture = this.gesture;
+    if (!gesture || event.pointerId !== gesture.pointerId) return;
+    gesture.point = this.point(event);
+    if (gesture.part !== 'rowDrag') return;
+    if (!gesture.dragging && Math.hypot(gesture.point.x - gesture.startX, gesture.point.y - gesture.startY) < 5) return;
+    if (!gesture.dragging && gesture.payload != null) this.emitDrag('rowdragstart', event);
+    gesture.dragging = true;
+    if (gesture.payload != null) this.emitDrag('rowdragmove', event);
+    this.canvas.style.cursor = 'grabbing';
+    this.updateTarget();
+    this.scheduleScroll();
+    event.preventDefault();
+  };
+
+  onUp = event => {
+    const gesture = this.gesture;
+    if (!gesture || event.pointerId !== gesture.pointerId) return;
+    gesture.point = this.point(event);
+    const target = gesture.dragging ? this.controller.getRowDropTarget(gesture.id, gesture.point.x, gesture.point.y) : null;
+    const hit = this.controller.hitTest(gesture.point.x, gesture.point.y);
+    if (gesture.dragging && gesture.payload != null) this.emitDrag('rowdragend', event);
+    this.suppressClick = gesture.dragging;
+    this.cancel(false);
+    if (target) this.controller.moveRow(gesture.id, target.index, { source: 'pointer' });
+    else if (!gesture.dragging && hit?.row?.nodeId === gesture.id && hit.part === gesture.part) {
+      if (gesture.part === 'rowUp') this.controller.moveRowBy(gesture.id, -1, { source: 'button' });
+      if (gesture.part === 'rowDown') this.controller.moveRowBy(gesture.id, 1, { source: 'button' });
+    }
+  };
+
+  onCancel = event => { if (this.gesture?.pointerId === event.pointerId) this.cancel(); };
+  onKey = event => {
+    if (event.key === 'Escape' && this.gesture) {
+      this.cancel();
+      event.preventDefault();
+    }
+  };
+
+  point(event) {
+    const rect = this.canvas.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  }
+
+  updateTarget() {
+    const gesture = this.gesture;
+    this.controller.setRowDrop(gesture ? this.controller.getRowDropTarget(gesture.id, gesture.point.x, gesture.point.y) : null);
+  }
+
+  scheduleScroll() {
+    if (this.frame !== null || !this.gesture?.dragging) return;
+    const viewport = this.controller.viewport;
+    if (this.gesture.point.x < 0 || this.gesture.point.x > viewport.viewportWidth || this.gesture.point.y < 0 || this.gesture.point.y > viewport.viewportHeight) return;
+    const y = this.gesture.point.y - viewport.renderInsetY;
+    const top = viewport.headerHeight;
+    const bottom = top + viewport.rowViewportHeight;
+    const delta = y < top + 24 ? -10 : y > bottom - 24 ? 10 : 0;
+    if (!delta) return;
+    const schedule = this.view.requestAnimationFrame?.bind(this.view) ?? (callback => setTimeout(callback, 16));
+    this.frame = schedule(() => {
+      this.frame = null;
+      if (!this.gesture?.dragging) return;
+      const previous = viewport.scrollY;
+      this.controller.scrollBy(0, delta);
+      this.updateTarget();
+      if (viewport.scrollY !== previous) this.scheduleScroll();
+    });
+  }
+
+  emitDrag(type, originalEvent) {
+    const gesture = this.gesture;
+    if (gesture) this.controller.events.emit(type, { nodeId: gesture.id, payload: gesture.payload,
+      label: this.controller.model.index.getNode(gesture.id)?.label ?? gesture.id, originalEvent });
+  }
+
+  cancel = (notify = true) => {
+    const gesture = this.gesture;
+    if (gesture?.dragging) this.suppressClick = true;
+    if (notify && gesture?.dragging && gesture.payload != null) this.emitDrag('rowdragcancel');
+    this.gesture = null;
+    if (this.frame !== null) (this.view.cancelAnimationFrame?.bind(this.view) ?? clearTimeout)(this.frame);
+    this.frame = null;
+    if (gesture && this.canvas.hasPointerCapture?.(gesture.pointerId)) this.canvas.releasePointerCapture(gesture.pointerId);
+    this.canvas.style.cursor = '';
+    this.controller.setRowDrop(null);
+  };
+
+  destroy() {
+    this.cancel();
+    this.canvas.removeEventListener('pointerdown', this.onDown);
+    this.canvas.removeEventListener('keydown', this.onKey);
+    this.canvas.removeEventListener('lostpointercapture', this.onCancel);
+    this.view.removeEventListener('pointermove', this.onMove);
+    this.view.removeEventListener('pointerup', this.onUp);
+    this.view.removeEventListener('pointercancel', this.onCancel);
+    this.view.removeEventListener('blur', this.cancel);
+    this.canvas.style.touchAction = this.previousTouchAction;
+    for (const stop of this.stops) stop();
+    this.status?.remove();
+  }
+}

package/src/input/tree-filter-bar.js

@@ -0,0 +1,55 @@
+/** A view of controller filter state. No duplicated query or toggle state. */
+export class TreeFilterBar {
+  constructor(controller, document) {
+    this.controller = controller;
+    this.element = document.createElement('div');
+    this.element.className = 'vtc-filter';
+    this.input = document.createElement('input');
+    this.input.type = 'search';
+    this.input.placeholder = 'Filter';
+    this.input.setAttribute('aria-label', 'Filter rows');
+    this.caseButton = this.button(document, 'Aa', 'Match case');
+    this.wholeButton = this.button(document, 'W', 'Match whole word');
+    this.element.append(this.input, this.caseButton, this.wholeButton);
+    this.input.addEventListener('input', this.onInput);
+    this.caseButton.addEventListener('click', this.onCase);
+    this.wholeButton.addEventListener('click', this.onWhole);
+    this.stop = controller.on('filterchange', () => this.sync());
+    this.sync();
+  }
+
+  button(document, label, title) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = label;
+    button.title = title;
+    button.setAttribute('aria-label', title);
+    return button;
+  }
+
+  onInput = () => this.controller.setFilter(this.input.value, this.controller.filterOptions);
+  onCase = () => this.toggle('caseSensitive');
+  onWhole = () => this.toggle('wholeWord');
+
+  toggle(key) {
+    const options = this.controller.filterOptions;
+    this.controller.setFilter(this.input.value, { ...options, [key]: !options[key] });
+    this.input.focus();
+  }
+
+  sync() {
+    this.input.value = this.controller.filterQuery;
+    this.caseButton.setAttribute('aria-pressed', String(this.controller.filterOptions.caseSensitive));
+    this.wholeButton.setAttribute('aria-pressed', String(this.controller.filterOptions.wholeWord));
+  }
+
+  setVisible(visible) { this.element.hidden = !visible; }
+
+  destroy() {
+    this.stop();
+    this.input.removeEventListener('input', this.onInput);
+    this.caseButton.removeEventListener('click', this.onCase);
+    this.wholeButton.removeEventListener('click', this.onWhole);
+    this.element.remove();
+  }
+}