@multiplatform.one/components 7.8.0 → 7.11.0

package/src/views/TreeView.spec.tsx

@@ -92,7 +92,7 @@ describe("TreeView knob wiring", () => {
     expect(tree.getAttribute("data-fill")).toBe("transparent");
   });
 
-  it("row labels are T-VALUE primary ink, never componentColors.text.secondary", () => {
+  it("row labels are T-VALUE primary ink, never a secondary ramp step", () => {
     expect(treeViewSource).not.toMatch(/componentColors\.text\.(secondary|muted)/);
     expect(treeViewSource).toMatch(
       /color=\{isSelected && onAccentLabel \? onAccentLabel : "\$color"\}/,

package/src/views/TreeView.tsx

@@ -35,7 +35,7 @@ import React, {
   type ReactNode,
 } from "react";
 import { useTranslation } from "../shared/i18n";
-import { Text, View, XStack, YStack, type YStackProps } from "tamagui";
+import { Text, View, XStack, YStack, isWeb, type YStackProps } from "tamagui";
 import { autoScrollVelocity } from "./kanbanDnd";
 import {
   applyTreeMove,
@@ -54,6 +54,7 @@ import {
   type TreeDropTarget,
 } from "./treeViewDnd";
 import { diffVisibleRows, flattenVisibleIds, isEmptyDiff } from "./treeViewMotion";
+import { treeRevealExpansion, treeRevealOffset } from "./treeViewReveal";
 import {
   TREE_LIFT_SHADOW,
   treeDefaultHeight,
@@ -133,8 +134,20 @@ export interface TreeViewProps<T = unknown> extends Omit<YStackProps, "children"
   overscan?: number;
   /** Height of the scrollable container in pixels */
   height?: number;
+  /** Initial vertical offset in layout pixels, restored once after usable list layout. */
+  initialScrollOffset?: number;
+  /** Observed, bounded vertical offset. Does not report unacknowledged scroll commands. */
+  onScrollOffsetChange?: (offset: number) => void;
   /** Message shown when there are no nodes */
   emptyMessage?: string;
+  /** Controlled expansion; takes precedence over initial expansion props. */
+  expandedIds?: string[];
+  /** Next complete expansion set from a user toggle or explicit reveal. */
+  onExpandedIdsChange?: (ids: string[]) => void;
+  /** Expand ancestors and reveal this row. Change requestId to reveal the same ID again. */
+  revealRequest?: { id: string; requestId: number };
+  /** Called once when the current reveal target is measured, mounted and visible. */
+  onRevealComplete?: (request: { id: string; requestId: number }) => void;
   /** Initially expanded node IDs (wins over expandByDefault when provided) */
   defaultExpandedIds?: string[];
   /** Expand every branch on initial load */
@@ -291,8 +304,14 @@ export function TreeView<T = unknown>({
   estimateSize: estimateSizeProp,
   overscan = 10,
   height: heightProp,
+  initialScrollOffset,
+  onScrollOffsetChange,
   emptyMessage: emptyMessageProp,
   defaultExpandedIds,
+  expandedIds: controlledExpandedIds,
+  onExpandedIdsChange,
+  revealRequest,
+  onRevealComplete,
   expandByDefault = false,
   display = "default",
   showExpansionArrows = true,
@@ -339,6 +358,31 @@ export function TreeView<T = unknown>({
   const treeId = useId();
   const containerRef = useRef<HTMLDivElement>(null);
   const flashListRef = useRef<FlashListRef<FlatNode<T>>>(null);
+  const initialScroll = useRef<
+    | {
+        offset: number;
+        attempted?: { target: number; width: number; height: number; contentHeight: number };
+      }
+    | undefined
+  >(
+    initialScrollOffset === undefined
+      ? undefined
+      : { offset: Number.isFinite(initialScrollOffset) ? Math.max(0, initialScrollOffset) : 0 },
+  );
+  const cancelInitialScroll = useCallback(() => {
+    initialScroll.current = undefined;
+  }, []);
+  const hasNodes = nodes.length > 0;
+  const listInstance = useMemo(
+    () => ({ hasNodes, attached: false, loaded: false, indexScrollRequested: false, offset: 0 }),
+    [hasNodes],
+  );
+  const scrollActive = useRef(true);
+  const lastReportedOffset = useRef<number | undefined>(undefined);
+  const offsetCallback = useRef(onScrollOffsetChange);
+  useLayoutEffect(() => {
+    offsetCallback.current = onScrollOffsetChange;
+  }, [onScrollOffsetChange]);
   const [focusedIndex, setFocusedIndex] = useState(-1);
   // LC-71: ring is a React flag, not a render-time wasKeyboardFocus() read —
   // Tab-away/Tab-back with the same activedescendant must still re-paint.
@@ -357,12 +401,25 @@ export function TreeView<T = unknown>({
   const handleContainerBlur = useCallback(() => {
     setKeyboardRing(false);
   }, []);
-  const [expandedIds, setExpandedIds] = useState<Set<string>>(() => {
+  const [internalExpandedIds, setInternalExpandedIds] = useState<Set<string>>(() => {
     if (defaultExpandedIds) return new Set(defaultExpandedIds);
     if (expandByDefault) return collectBranchIds(nodes);
     return new Set();
   });
 
+  const expandedIds = useMemo(
+    () =>
+      controlledExpandedIds === undefined ? internalExpandedIds : new Set(controlledExpandedIds),
+    [controlledExpandedIds, internalExpandedIds],
+  );
+  const setExpandedIds = useCallback(
+    (next: ReadonlySet<string>) => {
+      if (controlledExpandedIds === undefined) setInternalExpandedIds(new Set(next));
+      onExpandedIdsChange?.([...next]);
+    },
+    [controlledExpandedIds, onExpandedIdsChange],
+  );
+
   // ── Expand/collapse motion (FLIP + enter fade; Axiom 4) ────────────────
   const [motion, setMotion] = useState<TreeMotion | null>(null);
   const rowHeights = useRef(new Map<string, number>());
@@ -373,30 +430,37 @@ export function TreeView<T = unknown>({
 
   const toggleNode = useCallback(
     (node: TreeNode<T>) => {
+      cancelInitialScroll();
       const next = new Set(expandedIds);
       if (next.has(node.id)) {
         next.delete(node.id);
       } else {
         next.add(node.id);
       }
-      // Mount never animates and `animation: none` / reduced motion skips
-      // the machine entirely — the toggle then renders in one jump.
-      if (transition) {
-        const diff = diffVisibleRows(
-          flattenVisibleIds(nodes, expandedIds),
-          flattenVisibleIds(nodes, next),
-          getRowHeight,
-        );
-        setMotion(isEmptyDiff(diff) ? null : { phase: "armed", ...diff });
-      } else {
-        setMotion(null);
-      }
       setExpandedIds(next);
       onNodeToggle?.(node);
     },
-    [expandedIds, nodes, transition, getRowHeight, onNodeToggle],
+    [expandedIds, setExpandedIds, onNodeToggle, cancelInitialScroll],
   );
 
+  const previousExpandedIds = useRef(expandedIds);
+  useLayoutEffect(() => {
+    const previous = previousExpandedIds.current;
+    previousExpandedIds.current = expandedIds;
+    if (previous.size === expandedIds.size && [...previous].every((id) => expandedIds.has(id)))
+      return;
+    if (transition) {
+      const diff = diffVisibleRows(
+        flattenVisibleIds(nodes, previous),
+        flattenVisibleIds(nodes, expandedIds),
+        getRowHeight,
+      );
+      setMotion(isEmptyDiff(diff) ? null : { phase: "armed", ...diff });
+    } else {
+      setMotion(null);
+    }
+  }, [expandedIds, nodes, transition, getRowHeight]);
+
   // Release the FLIP one frame after the armed styles paint so the tween
   // runs from the previous layout to the new one.
   useLayoutEffect(() => {
@@ -432,13 +496,243 @@ export function TreeView<T = unknown>({
     return result;
   }, [nodes, expandedIds]);
 
+  const revealIntent = useRef<
+    | {
+        id: string;
+        requestId: number;
+        complete: boolean;
+        notifiedExpansion?: ReadonlySet<string>;
+      }
+    | undefined
+  >(undefined);
+  const scrollFrame = useRef<number | undefined>(undefined);
+  const scrollStep = useRef<() => void>(() => {});
+  const renderedRows = useRef(new Set<string>());
+  const scrollBounds = useCallback(() => {
+    const list = flashListRef.current;
+    if (!scrollActive.current || !listInstance.attached || !listInstance.loaded || !list) return;
+    if (isWeb) {
+      const rect = containerRef.current?.getBoundingClientRect();
+      if (!rect || !(rect.width > 0) || !(rect.height > 0)) return;
+    }
+    const viewport = list.getWindowSize();
+    const contentHeight = list.getChildContainerDimensions().height + list.getFirstItemOffset();
+    if (
+      !Number.isFinite(viewport.width) ||
+      viewport.width <= 0 ||
+      !Number.isFinite(viewport.height) ||
+      viewport.height <= 0 ||
+      !Number.isFinite(contentHeight) ||
+      contentHeight <= 0
+    )
+      return;
+    return {
+      list,
+      width: viewport.width,
+      height: viewport.height,
+      contentHeight,
+      maxOffset: Math.max(0, contentHeight - viewport.height),
+    };
+  }, [listInstance]);
+  const observeOffset = useCallback(
+    (offset: number, fromEvent = false) => {
+      if (!scrollActive.current || !listInstance.attached || !Number.isFinite(offset)) return;
+      if (
+        fromEvent &&
+        initialScroll.current?.attempted === undefined &&
+        offset !== listInstance.offset
+      ) {
+        cancelInitialScroll();
+      }
+      listInstance.offset = offset;
+      const bounds = scrollBounds();
+      if (!bounds) return;
+      const bounded = Math.max(0, Math.min(offset, bounds.maxOffset));
+      const initial = initialScroll.current;
+      if (initial) {
+        const target = Math.min(initial.offset, bounds.maxOffset);
+        if (initial.attempted ? Math.abs(bounded - target) >= 1 : bounded !== target) return;
+        initialScroll.current = undefined;
+      }
+      if (offsetCallback.current && lastReportedOffset.current !== bounded) {
+        lastReportedOffset.current = bounded;
+        offsetCallback.current(bounded);
+      }
+    },
+    [cancelInitialScroll, scrollBounds, listInstance],
+  );
+  const scheduleScroll = useCallback(() => {
+    if (!scrollActive.current || !listInstance.attached || scrollFrame.current !== undefined)
+      return;
+    if (
+      !initialScroll.current &&
+      (!revealIntent.current || revealIntent.current.complete) &&
+      !offsetCallback.current
+    )
+      return;
+    scrollFrame.current = requestAnimationFrame(() => {
+      scrollFrame.current = undefined;
+      if (listInstance.attached) scrollStep.current();
+    });
+  }, [listInstance]);
+  const attachList = useCallback(
+    (list: FlashListRef<FlatNode<T>> | null) => {
+      flashListRef.current = list;
+      listInstance.attached = list !== null;
+      if (!list) {
+        listInstance.loaded = false;
+        if (initialScroll.current) initialScroll.current.attempted = undefined;
+        if (scrollFrame.current !== undefined) cancelAnimationFrame(scrollFrame.current);
+        scrollFrame.current = undefined;
+      }
+    },
+    [listInstance],
+  );
+
+  useLayoutEffect(() => {
+    scrollActive.current = true;
+    return () => {
+      scrollActive.current = false;
+      revealIntent.current = undefined;
+      if (scrollFrame.current !== undefined) cancelAnimationFrame(scrollFrame.current);
+      scrollFrame.current = undefined;
+    };
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!revealRequest) {
+      revealIntent.current = undefined;
+    } else if (
+      revealIntent.current?.id !== revealRequest.id ||
+      revealIntent.current?.requestId !== revealRequest.requestId
+    ) {
+      cancelInitialScroll();
+      revealIntent.current = { ...revealRequest, complete: false };
+    }
+    const step = () => {
+      const currentList = flashListRef.current;
+      if (currentList) {
+        // Index preparation changes FlashList's getter before transport completes.
+        // Once requested, only delivered events can advance this list's observation.
+        observeOffset(
+          listInstance.indexScrollRequested
+            ? listInstance.offset
+            : currentList.getAbsoluteLastScrollOffset(),
+        );
+      }
+      if (!scrollActive.current) return;
+      if (scrollStep.current !== step) {
+        scheduleScroll();
+        return;
+      }
+      const intent = revealIntent.current;
+      if (!intent || intent.complete) {
+        const initial = initialScroll.current;
+        const bounds = scrollBounds();
+        if (!initial || !bounds || flatNodes.length === 0) return;
+        const target = Math.min(initial.offset, bounds.maxOffset);
+        const attempted = initial.attempted;
+        if (
+          !attempted ||
+          attempted.target !== target ||
+          attempted.width !== bounds.width ||
+          attempted.height !== bounds.height ||
+          attempted.contentHeight !== bounds.contentHeight
+        ) {
+          initial.attempted = {
+            target,
+            width: bounds.width,
+            height: bounds.height,
+            contentHeight: bounds.contentHeight,
+          };
+          bounds.list.scrollToOffset({ offset: target, animated: false });
+        }
+        return;
+      }
+      const next = treeRevealExpansion(nodes, expandedIds, intent.id);
+      if (!next) return;
+      if (next !== expandedIds) {
+        const notified = intent.notifiedExpansion;
+        if (!notified || notified.size !== next.size || [...next].some((id) => !notified.has(id))) {
+          intent.notifiedExpansion = next;
+          setExpandedIds(next);
+        }
+        return;
+      }
+      if (motion) {
+        setMotion(null);
+        return;
+      }
+      const list = flashListRef.current;
+      const index = flatNodes.findIndex((item) => item.node.id === intent.id);
+      if (!list || index < 0) return;
+      if (isWeb) {
+        const rect = containerRef.current?.getBoundingClientRect();
+        if (!rect || rect.width <= 0 || rect.height <= 0) return;
+      }
+      const viewport = list.getWindowSize();
+      if (viewport.width <= 0) return;
+      const layout = list.getLayout(index);
+      if (!layout) return;
+      const offset = listInstance.indexScrollRequested
+        ? listInstance.offset
+        : list.getAbsoluteLastScrollOffset();
+      const top = layout.y + list.getFirstItemOffset();
+      const nextOffset = treeRevealOffset(
+        { y: top, height: layout.height },
+        offset,
+        viewport.height,
+      );
+      if (nextOffset === undefined) return;
+      if (Math.abs(nextOffset - offset) < 1) {
+        let visible = top < offset + viewport.height && top + layout.height > offset;
+        if (!listInstance.indexScrollRequested) {
+          const range = list.computeVisibleIndices();
+          visible = visible && index >= range.startIndex && index <= range.endIndex;
+        }
+        if (
+          revealIntent.current === intent &&
+          layout.isHeightMeasured &&
+          renderedRows.current.has(intent.id) &&
+          visible
+        ) {
+          intent.complete = true;
+          onRevealComplete?.({ id: intent.id, requestId: intent.requestId });
+        }
+        return;
+      }
+      // FlashList's scrollToIndex has uncancellable delayed steps. Immediate offsets
+      // let the next layout/scroll event correct estimates using only the latest intent.
+      list.scrollToOffset({ offset: nextOffset, animated: false });
+    };
+    scrollStep.current = step;
+    scheduleScroll();
+  }, [
+    nodes,
+    expandedIds,
+    setExpandedIds,
+    flatNodes,
+    revealRequest?.id,
+    revealRequest?.requestId,
+    onRevealComplete,
+    height,
+    motion,
+    scheduleScroll,
+    cancelInitialScroll,
+    observeOffset,
+    scrollBounds,
+    listInstance,
+  ]);
+
   const scrollToIndex = useCallback(
     (index: number) => {
       if (index >= 0 && index < flatNodes.length) {
+        cancelInitialScroll();
+        listInstance.indexScrollRequested = true;
         flashListRef.current?.scrollToIndex({ index, animated: true });
       }
     },
-    [flatNodes.length],
+    [flatNodes.length, cancelInitialScroll, listInstance],
   );
 
   const focusRow = useCallback(
@@ -732,6 +1026,7 @@ export function TreeView<T = unknown>({
       if (!container?.getBoundingClientRect) return false;
       const session = treeKeyboardLift(nodes, flat.node.id);
       if (!session) return false;
+      cancelInitialScroll();
       const rowRect = rowEl.getBoundingClientRect();
       const containerRect = container.getBoundingClientRect();
       grabOffsetRef.current = { x: clientX - rowRect.left, y: clientY - rowRect.top };
@@ -759,7 +1054,7 @@ export function TreeView<T = unknown>({
       startAutoScroll();
       return true;
     },
-    [announce, nodes, startAutoScroll],
+    [announce, nodes, startAutoScroll, cancelInitialScroll],
   );
 
   const handleDragHandlePointerDown = useCallback(
@@ -906,6 +1201,7 @@ export function TreeView<T = unknown>({
     if (!flat) return false;
     const session = treeKeyboardLift(nodes, flat.node.id);
     if (!session) return false;
+    cancelInitialScroll();
     const ui: TreeDragUi<T> = {
       mode: "keyboard",
       node: flat.node,
@@ -923,7 +1219,16 @@ export function TreeView<T = unknown>({
     dragUiRef.current = ui;
     announce(describeTreeDragState("lift", session, nodes, flat.node.label));
     return true;
-  }, [announce, canReorder, dndRows, flatNodes, focusedIndex, getRowHeight, nodes]);
+  }, [
+    announce,
+    canReorder,
+    dndRows,
+    flatNodes,
+    focusedIndex,
+    getRowHeight,
+    nodes,
+    cancelInitialScroll,
+  ]);
 
   const moveKeyboardDrag = useCallback(
     (direction: "up" | "down" | "left" | "right"): boolean => {
@@ -1153,16 +1458,28 @@ export function TreeView<T = unknown>({
         onFocus={handleContainerFocus}
         onBlur={handleContainerBlur}
         onKeyDown={handleTreeKeyDown}
+        onLayout={scheduleScroll}
+        {...(isWeb && { onWheel: cancelInitialScroll, onPointerDown: cancelInitialScroll })}
         position="relative"
         style={{
           height,
         }}
       >
         <FlashList
-          ref={flashListRef}
+          ref={attachList}
           data={flatNodes}
           drawDistance={overscan * estimateSize}
           keyExtractor={(item) => item.node.id}
+          onLoad={() => {
+            if (!scrollActive.current || !listInstance.attached) return;
+            listInstance.loaded = true;
+            scheduleScroll();
+          }}
+          onCommitLayoutEffect={scheduleScroll}
+          onContentSizeChange={scheduleScroll}
+          onScrollBeginDrag={() => {
+            if (scrollActive.current && listInstance.attached) cancelInitialScroll();
+          }}
           extraData={{
             focused: effectiveFocused,
             selectedId,
@@ -1173,16 +1490,17 @@ export function TreeView<T = unknown>({
             keyboardRing,
             collapsedSelectedAncestors,
           }}
-          {...(canReorder && {
-            onScroll: (e: any) => {
-              const y = e?.nativeEvent?.contentOffset?.y;
-              if (typeof y === "number") {
-                scrollOffsetRef.current = y;
-                if (dragUiRef.current) setDragScrollY(y);
-              }
-            },
-            scrollEventThrottle: 16,
-          })}
+          onScroll={(e: any) => {
+            if (!scrollActive.current || !listInstance.attached) return;
+            const y = e?.nativeEvent?.contentOffset?.y;
+            if (typeof y === "number" && Number.isFinite(y)) {
+              scrollOffsetRef.current = y;
+              if (dragUiRef.current) setDragScrollY(y);
+              observeOffset(y, true);
+            }
+            scheduleScroll();
+          }}
+          scrollEventThrottle={16}
           renderItem={({ item, index }) => {
             const { node, depth, hasChildren, isExpanded } = item;
             const isFocused = effectiveFocused === index;
@@ -1239,6 +1557,11 @@ export function TreeView<T = unknown>({
                 // Remount when a recycled cell switches nodes so state fills
                 // and the caret never tween across two different rows.
                 key={node.id}
+                ref={(row) => {
+                  if (row) renderedRows.current.add(node.id);
+                  else renderedRows.current.delete(node.id);
+                  scheduleScroll();
+                }}
                 id={`${treeId}-node-${index}`}
                 {...{ "data-treeview-row": node.id }}
                 {...(isDropParent && { "data-treeview-drop-parent": "true" })}
@@ -1265,6 +1588,7 @@ export function TreeView<T = unknown>({
                 onLayout={(e: any) => {
                   const h = e?.nativeEvent?.layout?.height;
                   if (typeof h === "number" && h > 0) rowHeights.current.set(node.id, h);
+                  scheduleScroll();
                 }}
                 backgroundColor={
                   // Nest-into parent highlight wins while a drag is active

package/src/views/treeViewReveal.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { treeRevealExpansion, treeRevealOffset } from "./treeViewReveal";
+
+const nodes = [
+  {
+    id: "folders",
+    children: [
+      {
+        id: "archive",
+        children: Array.from({ length: 500 }, (_, index) => ({ id: `item-${index}` })),
+      },
+    ],
+  },
+  { id: "other", children: [{ id: "other-item" }] },
+];
+
+describe("tree reveal ancestors", () => {
+  it("finds the exact last leaf of a 500-item branch and preserves unrelated expansion", () => {
+    const expanded = new Set(["other"]);
+    expect(treeRevealExpansion(nodes, expanded, "item-499")).toEqual(
+      new Set(["other", "folders", "archive"]),
+    );
+    expect(expanded).toEqual(new Set(["other"]));
+  });
+
+  it("does not expand the target branch itself", () => {
+    expect(treeRevealExpansion(nodes, new Set(), "archive")).toEqual(new Set(["folders"]));
+  });
+
+  it("preserves the set when the target is already exposed", () => {
+    const expanded = new Set(["folders", "archive"]);
+    expect(treeRevealExpansion(nodes, expanded, "item-499")).toBe(expanded);
+  });
+
+  it("does not substitute a prefix, ancestor or similarly named leaf for a missing ID", () => {
+    expect(treeRevealExpansion(nodes, new Set(), "item-500")).toBeUndefined();
+    expect(treeRevealExpansion(nodes, new Set(), "item")).toBeUndefined();
+    expect(treeRevealExpansion([], new Set(), "folders")).toBeUndefined();
+  });
+
+  it("reveals a root without expanding its children", () => {
+    const expanded = new Set<string>();
+    expect(treeRevealExpansion(nodes, expanded, "folders")).toBe(expanded);
+  });
+});
+
+describe("tree reveal measured offsets", () => {
+  it("uses the actual layout of a distant variable-height row, not index times an estimate", () => {
+    const heights = Array.from({ length: 500 }, (_, index) => (index % 2 === 0 ? 32 : 80));
+    const y = heights.slice(0, 499).reduce((sum, height) => sum + height, 0);
+    expect(y).toBe(27920);
+    expect(treeRevealOffset({ y, height: heights[499] }, 0, 240)).toBe(27760);
+    expect(treeRevealOffset({ y, height: heights[499] }, 27760, 240)).toBe(27760);
+  });
+
+  it("corrects again when virtualization replaces an estimate with a taller measurement", () => {
+    expect(treeRevealOffset({ y: 27920, height: 32 }, 0, 240)).toBe(27712);
+    expect(treeRevealOffset({ y: 27920, height: 80 }, 27712, 240)).toBe(27760);
+  });
+
+  it("leaves a fully visible row in place", () => {
+    expect(treeRevealOffset({ y: 300, height: 80 }, 250, 240)).toBe(250);
+  });
+
+  it("reveals a row above the viewport at its top", () => {
+    expect(treeRevealOffset({ y: 120, height: 80 }, 250, 240)).toBe(120);
+  });
+
+  it("aligns the top of a row taller than the viewport without oscillating", () => {
+    expect(treeRevealOffset({ y: 120, height: 300 }, 250, 240)).toBe(120);
+    expect(treeRevealOffset({ y: 120, height: 300 }, 120, 240)).toBe(120);
+  });
+
+  it.each([
+    [{ y: 20, height: 32 }, 0, 0],
+    [{ y: 20, height: 0 }, 0, 240],
+    [{ y: Number.NaN, height: 32 }, 0, 240],
+    [{ y: 20, height: 32 }, Number.NaN, 240],
+    [{ y: 20, height: 32 }, 0, Number.POSITIVE_INFINITY],
+  ])("waits for usable geometry: %o, %s, %s", (layout, offset, height) => {
+    expect(treeRevealOffset(layout, offset, height)).toBeUndefined();
+  });
+});

package/src/views/treeViewReveal.ts

@@ -0,0 +1,45 @@
+interface RevealTreeNode {
+  id: string;
+  children?: readonly RevealTreeNode[];
+}
+
+export function treeRevealExpansion(
+  nodes: readonly RevealTreeNode[],
+  expandedIds: ReadonlySet<string>,
+  targetId: string,
+): ReadonlySet<string> | undefined {
+  const ancestors: string[] = [];
+  const find = (items: readonly RevealTreeNode[]): boolean => {
+    for (const node of items) {
+      if (node.id === targetId) return true;
+      if (node.children?.length) {
+        ancestors.push(node.id);
+        if (find(node.children)) return true;
+        ancestors.pop();
+      }
+    }
+    return false;
+  };
+  if (!find(nodes)) return undefined;
+  if (ancestors.every((id) => expandedIds.has(id))) return expandedIds;
+  return new Set([...expandedIds, ...ancestors]);
+}
+
+export function treeRevealOffset(
+  layout: { y: number; height: number },
+  offset: number,
+  viewportHeight: number,
+): number | undefined {
+  if (
+    ![layout.y, layout.height, offset, viewportHeight].every(Number.isFinite) ||
+    viewportHeight <= 0 ||
+    layout.height <= 0
+  ) {
+    return undefined;
+  }
+  if (layout.height > viewportHeight || layout.y < offset) return Math.max(0, layout.y);
+  if (layout.y + layout.height > offset + viewportHeight) {
+    return Math.max(0, layout.y + layout.height - viewportHeight);
+  }
+  return offset;
+}