@ixfx/components 0.13.4 → 0.13.6

package/dist/{tree-DD8OaqsK.js → tree-BjrfaX7d.js}

@@ -1027,6 +1027,19 @@ function treeScrollTopToReveal(params, index, scrollTop, topInset = 0) {
 	if (bottom > scrollTop + params.viewportHeight) return Math.max(0, bottom - params.viewportHeight);
 	return scrollTop;
 }
+/**
+* `scrollTop` that centres row `index` in the viewport, but only when the row is
+* not already fully visible (below `topInset` px of overlay). Otherwise returns
+* `scrollTop` unchanged.
+*/
+function treeScrollTopToCenterIfHidden(params, index, scrollTop, topInset = 0) {
+	if (index < 0 || index >= params.count) return scrollTop;
+	const top = treeRowTop(params, index);
+	const bottom = top + params.rowHeight;
+	if (top >= scrollTop + topInset && bottom <= scrollTop + params.viewportHeight) return scrollTop;
+	const centred = top + params.rowHeight / 2 - (params.viewportHeight + topInset) / 2;
+	return Math.max(0, centred);
+}
 /** Rows that fit one viewport (PageUp / PageDown step), at least 1. */
 function treePageSize(params) {
 	return Math.max(1, Math.floor(params.viewportHeight / treeStride(params)) - 1);
@@ -1166,6 +1179,8 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 		this.#stickyDirty = true;
 		this.#stickyRaf = 0;
 		this.#stickyScrollBound = false;
+		this.#selectOrigin = `user`;
+		this.#selectSilent = false;
 		this.#revealToken = 0;
 		this.#onKeyDown = (event) => {
 			if (this.search.isOpen) return;
@@ -1467,12 +1482,12 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 	* container's `scrollTop` and `_scrollTop` together, so the very next render
 	* already contains the target row — no frame where it is missing.
 	*/
-	#revealIndex(index) {
+	#revealIndex(index, mode = `edge`) {
 		const container = this.#container();
 		if (!container) return;
 		const params = this.#layoutParams(this.#getFlat().rows.length);
 		const inset = this.renderRoot.querySelector(`.sticky-headers`)?.getBoundingClientRect().height ?? 0;
-		const next = treeScrollTopToReveal(params, index, container.scrollTop, inset);
+		const next = (mode === `center-if-hidden` ? treeScrollTopToCenterIfHidden : treeScrollTopToReveal)(params, index, container.scrollTop, inset);
 		if (next === container.scrollTop && next === this._scrollTop) return;
 		container.scrollTop = next;
 		this._scrollTop = next;
@@ -2371,8 +2386,20 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 		this.#dispatchSelect(prev);
 		this.requestUpdate();
 	}
-	navigateTo(keys) {
+	navigateTo(keys, options = {}) {
 		if (!this.root?.children) return false;
+		const prevOrigin = this.#selectOrigin;
+		const prevSilent = this.#selectSilent;
+		this.#selectOrigin = `programmatic`;
+		this.#selectSilent = options.silent === true;
+		try {
+			return this.#navigateTo(keys, options.reveal ?? `edge`);
+		} finally {
+			this.#selectOrigin = prevOrigin;
+			this.#selectSilent = prevSilent;
+		}
+	}
+	#navigateTo(keys, reveal) {
 		this.#abortPending();
 		this.#clearSelectionInternal();
 		this.tickled.clearTickled();
@@ -2393,7 +2420,7 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 		}
 		this.#stickyDirty = true;
 		this.requestUpdate();
-		this.#scrollKeyIntoView(keys.at(-1));
+		this.#scrollKeyIntoView(keys.at(-1), reveal);
 		return true;
 	}
 	navigateToNode(predicate) {
@@ -2449,11 +2476,15 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 		this._selectedNodes.clear();
 		this.selectedNode = void 0;
 	}
+	#selectOrigin;
+	#selectSilent;
 	#dispatchSelect(previous) {
 		this._selectionVersion++;
+		if (this.#selectSilent) return;
 		const detail = {
 			selected: new Set(this._selectedNodes),
-			previous
+			previous,
+			origin: this.#selectOrigin
 		};
 		this.dispatchEvent(new CustomEvent(`select`, {
 			detail,
@@ -2645,7 +2676,7 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 	_handleCheckboxClick(event, node, _depth) {
 		event.stopPropagation();
 		const prev = new Set(this._selectedNodes);
-		const allSelected = this.#allDescendantsSelected(node);
+		const allSelected = this.#allSelectableDescendantsSelected(node);
 		this.#applyCheckedToggle(node, !allSelected);
 		if (this.selectedNode === void 0 || !this._selectedNodes.has(this.selectedNode)) this.selectedNode = [...this._selectedNodes].at(-1);
 		this.#dispatchSelect(prev);
@@ -2685,10 +2716,14 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 			}));
 		}
 	}
-	#allDescendantsSelected(node) {
-		if (!this._selectedNodes.has(node)) return false;
-		if (!node.children?.length) return true;
-		return node.children.every((child) => this.#allDescendantsSelected(child));
+	#allSelectableDescendantsSelected(node) {
+		const selectable = [];
+		const walk = (n) => {
+			if (this.#canSelect(n)) selectable.push(n);
+			n.children?.forEach(walk);
+		};
+		walk(node);
+		return selectable.length > 0 && selectable.every((n) => this._selectedNodes.has(n));
 	}
 	#applyCheckedToggle(node, selected) {
 		if (this.#canSelect(node)) {
@@ -2784,7 +2819,15 @@ let TreeBaseElement = class TreeBaseElement extends LitElement {
 	get _pendingNode() {
 		return this.#pendingNode;
 	}
-	#scrollKeyIntoView(key) {
+	#scrollKeyIntoView(key, mode = `edge`) {
+		if (mode === `center-if-hidden`) {
+			this.updateComplete.then(() => {
+				this.#measureMetrics();
+				const idx = this.#getFlat().indexByKey.get(key);
+				if (idx !== void 0) this.#revealIndex(idx, mode);
+			});
+			return;
+		}
 		if (this.#virtualActive()) {
 			this.updateComplete.then(() => {
 				const idx = this.#getFlat().indexByKey.get(key);
@@ -3549,6 +3592,9 @@ var TreeController = class {
 	#options;
 	#nodeToTree = /* @__PURE__ */ new WeakMap();
 	#identityToTreeNode = /* @__PURE__ */ new Map();
+	#keyToTreeNode = /* @__PURE__ */ new Map();
+	/** `valueToItem` results per source node identity; replaced wholesale by `sync()`. */
+	#itemCache = /* @__PURE__ */ new WeakMap();
 	#connectSignal;
 	constructor(root, element, options) {
 		this.#root = root;
@@ -3559,13 +3605,13 @@ var TreeController = class {
 		this.disconnect();
 		this.#connectSignal = new AbortController();
 		const { signal } = this.#connectSignal;
-		const rootValue = this.#root.getValue();
-		const rootItem = this.#options.valueToItem(rootValue, this.#root);
-		const rootChildren = this.#childrenOf(this.#root);
-		this.#element.root = {
-			item: rootItem,
-			children: rootChildren
-		};
+		this.#itemCache = /* @__PURE__ */ new WeakMap();
+		this.#identityToTreeNode.clear();
+		this.#keyToTreeNode.clear();
+		const rootNode = { item: this.#itemOf(this.#root) };
+		this.#nodeToTree.set(rootNode, this.#root);
+		rootNode.children = this.#childrenOf(this.#root);
+		this.#element.root = rootNode;
 		this.#element.addEventListener(`expand`, (e) => {
 			const { node } = e.detail;
 			const treeNode = this.#nodeToTree.get(node);
@@ -3579,45 +3625,101 @@ var TreeController = class {
 		this.#connectSignal?.abort();
 		this.#connectSignal = void 0;
 	}
-	navigateToValue(predicate) {
-		const treePath = this.#findTreePath(this.#root, predicate);
-		if (!treePath) return false;
+	/**
+	* Re-derive children for every already-materialised node from the source tree
+	* and patch them in place. Existing `TreeNode` objects are reused by key, so
+	* expansion and selection survive; only added and removed nodes change. Calls
+	* `invalidateStructure()` once.
+	*/
+	sync() {
+		const root = this.#element.root;
+		if (!root) return;
+		this.#itemCache = /* @__PURE__ */ new WeakMap();
+		this.#identityToTreeNode.clear();
+		this.#keyToTreeNode.clear();
+		this.#nodeToTree.set(root, this.#root);
+		root.item = this.#itemOf(this.#root);
+		root.children = this.#syncChildren(this.#root, root.children ?? []);
+		this.#element.invalidateStructure();
+	}
+	/** The source node whose item key is `key`, if it has been materialised. */
+	lookupByKey(key) {
+		return this.#keyToTreeNode.get(key);
+	}
+	/** Navigate using item keys (root excluded), without searching the source tree. */
+	navigateToKeyPath(keys, options) {
+		if (keys.length === 0) return false;
 		let currentColumn = this.#element.root?.children ?? [];
-		const keys = [];
-		for (let i = 1; i < treePath.length; i++) {
-			const treeNode = treePath[i];
-			const key = this.#options.valueToItem(treeNode.getValue(), treeNode).key;
-			keys.push(key);
-			if (i < treePath.length - 1) {
-				const node = currentColumn.find((n) => n.item.key === key);
-				if (!node) return false;
-				if (node.children === void 0) {
-					const mapped = this.#nodeToTree.get(node);
-					if (mapped) {
-						node.children = this.#childrenOf(mapped);
-						this.#element.invalidateStructure();
-					}
+		for (let i = 0; i < keys.length - 1; i++) {
+			const node = currentColumn.find((n) => n.item.key === keys[i]);
+			if (!node) return false;
+			if (node.children === void 0) {
+				const mapped = this.#nodeToTree.get(node);
+				if (mapped) {
+					node.children = this.#childrenOf(mapped);
+					this.#element.invalidateStructure();
 				}
-				currentColumn = node.children ?? [];
 			}
+			currentColumn = node.children ?? [];
+		}
+		return this.#element.navigateTo(keys, options);
+	}
+	/** Navigate to the source node with this identity, walking up via `getParent()`. */
+	navigateToIdentity(identity, options) {
+		let node = this.#identityToTreeNode.get(identity);
+		if (!node) return false;
+		const keys = [];
+		const rootId = this.#root.getIdentity();
+		while (node && node.getIdentity() !== rootId) {
+			keys.unshift(this.#itemOf(node).key);
+			node = node.getParent();
 		}
-		return this.#element.navigateTo(keys);
+		return node !== void 0 && this.navigateToKeyPath(keys, options);
+	}
+	navigateToValue(predicate, options) {
+		const treePath = this.#findTreePath(this.#root, predicate);
+		if (!treePath) return false;
+		return this.navigateToKeyPath(treePath.slice(1).map((n) => this.#itemOf(n).key), options);
+	}
+	#itemOf(treeNode, isLeaf) {
+		const id = treeNode.getIdentity();
+		let userItem = this.#itemCache.get(id);
+		if (!userItem) {
+			userItem = this.#options.valueToItem(treeNode.getValue(), treeNode);
+			this.#itemCache.set(id, userItem);
+		}
+		return isLeaf === void 0 ? userItem : {
+			...userItem,
+			isLeaf: userItem.isLeaf ?? isLeaf
+		};
 	}
 	#childrenOf(treeNode) {
 		return Array.from(treeNode.children(), (child) => this.#toTreeNode(child));
 	}
+	#register(node, treeNode) {
+		this.#nodeToTree.set(node, treeNode);
+		this.#identityToTreeNode.set(treeNode.getIdentity(), treeNode);
+		this.#keyToTreeNode.set(node.item.key, treeNode);
+	}
 	#toTreeNode(treeNode) {
-		const value = treeNode.getValue();
 		const childList = [...treeNode.children()];
-		const userItem = this.#options.valueToItem(value, treeNode);
-		const isLeaf = userItem.isLeaf ?? childList.length === 0;
-		const treeNodeMap = { item: {
-			...userItem,
-			isLeaf
-		} };
-		this.#nodeToTree.set(treeNodeMap, treeNode);
-		this.#identityToTreeNode.set(treeNode.getIdentity(), treeNode);
-		return treeNodeMap;
+		for (const child of childList) this.#identityToTreeNode.set(child.getIdentity(), child);
+		const node = { item: this.#itemOf(treeNode, childList.length === 0) };
+		this.#register(node, treeNode);
+		return node;
+	}
+	/** Patch `existing` to match the source children of `treeNode`; recurse into materialised nodes. */
+	#syncChildren(treeNode, existing) {
+		const byKey = new Map(existing.map((n) => [n.item.key, n]));
+		return Array.from(treeNode.children(), (child) => {
+			const fresh = this.#toTreeNode(child);
+			const old = byKey.get(fresh.item.key);
+			if (!old) return fresh;
+			old.item = fresh.item;
+			this.#register(old, child);
+			if (old.children !== void 0) old.children = this.#syncChildren(child, old.children);
+			return old;
+		});
 	}
 	#findTreePath(node, predicate, ancestors = []) {
 		const path = [...ancestors, node];

package/dist/{tree-component-Cj8V3uar.d.ts → tree-component-Bx40hxMz.d.ts}

@@ -222,6 +222,11 @@ type TreeSelectDetail = {
   readonly selected: ReadonlySet<TreeNode>;
   /** The previous selection set (empty set if there was no prior selection). */
   readonly previous: ReadonlySet<TreeNode>;
+  /**
+   * What caused the change: `programmatic` for `navigateTo` and friends, `user`
+   * otherwise. Absent on components that do not distinguish the two.
+   */
+  readonly origin?: `user` | `programmatic`;
 };
 /**
  * Fired when an item enters cursor focus — either the pointer hovers over it, or

package/dist/tree.d.ts

@@ -1,4 +1,4 @@
-import { A as TreeDataModelOptions, D as TreeTickleDetail, E as TreeSelectEvent, O as TreeTickleEvent, T as TreeSelectDetail, _ as TreeDropTarget, b as TreeItemClickDetail, c as TreeDragContext, d as TreeDragStartEvent, g as TreeDropPosition, h as TreeDropEvent, i as TreeCollapseEvent, k as TreeDataModel, l as TreeDragEndEvent, m as TreeDropDetail, n as TreeActivateEvent, o as TreeComponentEventMap, p as TreeDropContext, r as TreeCollapseDetail, s as TreeDndMode, t as TreeActivateDetail, u as TreeDragOverEvent, v as TreeExpandDetail, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-Cj8V3uar.js";
+import { A as TreeDataModelOptions, D as TreeTickleDetail, E as TreeSelectEvent, O as TreeTickleEvent, T as TreeSelectDetail, _ as TreeDropTarget, b as TreeItemClickDetail, c as TreeDragContext, d as TreeDragStartEvent, g as TreeDropPosition, h as TreeDropEvent, i as TreeCollapseEvent, k as TreeDataModel, l as TreeDragEndEvent, m as TreeDropDetail, n as TreeActivateEvent, o as TreeComponentEventMap, p as TreeDropContext, r as TreeCollapseDetail, s as TreeDndMode, t as TreeActivateDetail, u as TreeDragOverEvent, v as TreeExpandDetail, x as TreeItemClickEvent, y as TreeExpandEvent } from "./tree-component-Bx40hxMz.js";
 import { a as TreeItem, n as TreeExclusivity, o as TreeNode, r as TreeFilterPredicate, s as TreeSelectionFilter, t as LoadChildrenCallback } from "./types-DQ7KOUIj.js";
-import { a as TreeDropVisibleRow, c as TreeListElement, d as TreeBaseElementEventMap, f as TreeVirtualize, i as TreeDropRowInfo, l as TreeCheckboxState, n as TreeDropControllerConfig, o as TreeController, p as TreeConfig, r as TreeDropResolvedDrag, s as TreeControllerOptions, t as TreeDropController, u as TreeBaseElement } from "./index-CCC0G1nO.js";
-export { type LoadChildrenCallback, type TreeActivateDetail, type TreeActivateEvent, TreeBaseElement, TreeBaseElementEventMap, type TreeCheckboxState, type TreeCollapseDetail, type TreeCollapseEvent, type TreeComponentEventMap, TreeConfig, TreeController, TreeControllerOptions, TreeDataModel, type TreeDataModelOptions, type TreeDndMode, type TreeDragContext, type TreeDragEndEvent, type TreeDragOverEvent, type TreeDragStartEvent, type TreeDropContext, TreeDropController, TreeDropControllerConfig, type TreeDropDetail, type TreeDropEvent, type TreeDropPosition, TreeDropResolvedDrag, TreeDropRowInfo, type TreeDropTarget, TreeDropVisibleRow, type TreeExclusivity, type TreeExpandDetail, type TreeExpandEvent, type TreeFilterPredicate, type TreeItem, type TreeItemClickDetail, type TreeItemClickEvent, TreeListElement, type TreeNode, type TreeSelectDetail, type TreeSelectEvent, type TreeSelectionFilter, type TreeTickleDetail, type TreeTickleEvent, TreeVirtualize };
+import { a as TreeDropVisibleRow, c as TreeListElement, d as TreeBaseElementEventMap, f as TreeNavigateOptions, h as TreeConfig, i as TreeDropRowInfo, l as TreeCheckboxState, m as TreeVirtualize, n as TreeDropControllerConfig, o as TreeController, p as TreeRevealMode, r as TreeDropResolvedDrag, s as TreeControllerOptions, t as TreeDropController, u as TreeBaseElement } from "./index-AifRs3k9.js";
+export { type LoadChildrenCallback, type TreeActivateDetail, type TreeActivateEvent, TreeBaseElement, TreeBaseElementEventMap, type TreeCheckboxState, type TreeCollapseDetail, type TreeCollapseEvent, type TreeComponentEventMap, TreeConfig, TreeController, TreeControllerOptions, TreeDataModel, type TreeDataModelOptions, type TreeDndMode, type TreeDragContext, type TreeDragEndEvent, type TreeDragOverEvent, type TreeDragStartEvent, type TreeDropContext, TreeDropController, TreeDropControllerConfig, type TreeDropDetail, type TreeDropEvent, type TreeDropPosition, TreeDropResolvedDrag, TreeDropRowInfo, type TreeDropTarget, TreeDropVisibleRow, type TreeExclusivity, type TreeExpandDetail, type TreeExpandEvent, type TreeFilterPredicate, type TreeItem, type TreeItemClickDetail, type TreeItemClickEvent, TreeListElement, TreeNavigateOptions, type TreeNode, TreeRevealMode, type TreeSelectDetail, type TreeSelectEvent, type TreeSelectionFilter, type TreeTickleDetail, type TreeTickleEvent, TreeVirtualize };

package/dist/tree.js

@@ -1,2 +1,2 @@
-import { a as TreeDataModel, i as TreeDropController, n as TreeListElement, r as TreeBaseElement, t as TreeController } from "./tree-DD8OaqsK.js";
+import { a as TreeDataModel, i as TreeDropController, n as TreeListElement, r as TreeBaseElement, t as TreeController } from "./tree-BjrfaX7d.js";
 export { TreeBaseElement, TreeController, TreeDataModel, TreeDropController, TreeListElement };

package/dist/{vertical-list-m7GJtXwv.d.ts → vertical-list-BohPAS04.d.ts}

@@ -1,6 +1,6 @@
-import { F as ListDragPreviewSourceResolver, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent } from "./tree-component-Cj8V3uar.js";
+import { F as ListDragPreviewSourceResolver, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent } from "./tree-component-Bx40hxMz.js";
 import { n as ListViewportChangeEvent } from "./list-viewport-types-BRZsLcvp.js";
-import { S as ListSearchController } from "./index-BYIRgv49.js";
+import { S as ListSearchController } from "./index-CzFRWPzh.js";
 import { i as ListInteractionMode, l as ListSelectionMode, r as ListElementEventMap } from "./list-selection-types-PjKdhF-a.js";
 import "./editable-label-rzXkjf1H.js";
 import { LitElement, PropertyValues } from "lit";

package/dist/vertical-list.d.ts

@@ -1,5 +1,5 @@
-import { I as ListDragSource, L as ListNativeDragStartDetail, M as ListDragPreview, N as ListDragPreviewContext, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent, j as ListDragEntry } from "./tree-component-Cj8V3uar.js";
+import { I as ListDragSource, L as ListNativeDragStartDetail, M as ListDragPreview, N as ListDragPreviewContext, P as ListDragPreviewRenderer, R as ListNativeDragStartEvent, j as ListDragEntry } from "./tree-component-Bx40hxMz.js";
 import { n as ListViewportChangeEvent, t as ListViewportChangeDetail } from "./list-viewport-types-BRZsLcvp.js";
 import { a as ListItemClickDetail, c as ListSelectEvent, d as ListTickleEvent, i as ListInteractionMode, l as ListSelectionMode, n as ListActivateEvent, o as ListItemClickEvent, r as ListElementEventMap, s as ListSelectDetail, t as ListActivateDetail, u as ListTickleDetail } from "./list-selection-types-PjKdhF-a.js";
-import { a as ListContextMenuDetail, c as ListDragLeaveEvent, d as ListDropEvent, f as ListEditCancelDetail, h as ListEditCommitEvent, i as VerticalListElementEventMap, l as ListDragOverEvent, m as ListEditCommitDetail, n as CustomCheckboxOptions, o as ListContextMenuEvent, p as ListEditCancelEvent, r as VerticalListElement, s as ListDragLeaveDetail, t as AddItemOptions, u as ListDropDetail } from "./vertical-list-m7GJtXwv.js";
+import { a as ListContextMenuDetail, c as ListDragLeaveEvent, d as ListDropEvent, f as ListEditCancelDetail, h as ListEditCommitEvent, i as VerticalListElementEventMap, l as ListDragOverEvent, m as ListEditCommitDetail, n as CustomCheckboxOptions, o as ListContextMenuEvent, p as ListEditCancelEvent, r as VerticalListElement, s as ListDragLeaveDetail, t as AddItemOptions, u as ListDropDetail } from "./vertical-list-BohPAS04.js";
 export { AddItemOptions, CustomCheckboxOptions, type ListActivateDetail, type ListActivateEvent, type ListContextMenuDetail, type ListContextMenuEvent, type ListDragEntry, type ListDragLeaveDetail, type ListDragLeaveEvent, type ListDragOverEvent, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListDropDetail, type ListDropEvent, type ListEditCancelDetail, type ListEditCancelEvent, type ListEditCommitDetail, type ListEditCommitEvent, type ListElementEventMap, type ListInteractionMode, type ListItemClickDetail, type ListItemClickEvent, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSelectDetail, type ListSelectEvent, type ListSelectionMode, type ListTickleDetail, type ListTickleEvent, type ListViewportChangeDetail, type ListViewportChangeEvent, VerticalListElement, VerticalListElementEventMap };

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.13.4",
-  "generated": "2026-10-04T00:00:52.270Z",
+  "version": "0.13.6",
+  "generated": "2026-10-05T20:21:38.161Z",
   "components": [
     {
       "name": "ac-text",

package/docs-user/tree.md

@@ -46,6 +46,8 @@ type TreeNode = {
 
 `TreeNode` is **immutable** — structural changes always produce a new root. Never mutate a node in place; use `TreeDataModel` convenience methods or replace `root` directly.
 
+**Incremental updates.** `TreeController.sync()` re-derives children of already-materialised nodes from the source tree and patches them in place (nodes are reused by key, so expansion and selection survive). `navigateToKeyPath(keys)`, `navigateToIdentity(id)` and `lookupByKey(key)` resolve targets without searching the source tree.
+
 **Escape hatch for in-place edits.** The component itself fills in `node.children` when lazy-loading, and `TreeController` does the same. If you must edit `node.children` or `node.item` (e.g. an icon) in place, call `el.invalidateStructure()` afterwards. It drops the cached whole-tree indexes (parent map, icon depths, filter matches, checkbox states) and re-renders. Visible rows are re-derived on every update, so ordinary expand / collapse never needs it.
 
 ---
@@ -248,7 +250,7 @@ they do without windowing and cover rows that are not rendered:
   is never missing.
 - **Incremental search**: `navigate`, `select` and `filter` modes search the whole tree.
   Match highlights are repainted as the window moves.
-- **`navigateTo` / `revealKey`**: expand ancestors and scroll to the row.
+- **`navigateTo` / `revealKey`**: expand ancestors and scroll to the row. `navigateTo(keys, { reveal: 'center-if-hidden' })` centres the row only when it is off screen (arithmetic, no DOM measuring); `{ silent: true }` suppresses the `select` event. Otherwise `select` detail carries `origin: 'user' | 'programmatic'`.
 - **Drag and drop**: drop targets are computed from the layout, so auto-scroll while dragging works.
 - **Sticky headers**: found by arithmetic, with no per-row measuring.
 
@@ -817,7 +819,7 @@ interface TreeComponent extends EventTarget {
   select(node: TreeNode): void;
   deselect(node: TreeNode): void;
   clearSelection(): void;
-  navigateTo(keys: readonly string[]): boolean;
+  navigateTo(keys: readonly string[], options?: { reveal?: 'edge' | 'center-if-hidden'; silent?: boolean }): boolean;
   navigateToNode(predicate: (node: TreeNode) => boolean): boolean;
   getNodes(): ReadonlyArray<{ node: TreeNode; depth: number }>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",