@react-x11/components 0.1.0 → 0.2.1

package/dist/tree/index.js

@@ -0,0 +1,751 @@
+// <Tree> — a disclosure tree: file browsers, outline panes, property
+// inspectors, anything with a twisty.
+//
+// This is a **successor to react-x11's own `<Tree>`, not a wrapper around
+// it**. Core's is being retired, so nothing here imports it and the two share
+// no code. What is kept is the behaviour a user has already learnt — the
+// keyboard map, type-ahead, the twisty being its own hit target — because
+// that is the part it would be rude to change.
+//
+// Three things it has that core's does not, and they are the reason it lives
+// out here rather than in core:
+//
+//  1. **It reads the app's own data.** `getId` / `getChildren` / `isBranch`
+//     and friends mean a filesystem listing, an AST or a normalized store is
+//     rendered where it lies, instead of being copied into a shape this
+//     component preferred. The defaults describe `{ id, label, children }`,
+//     so a tree that has that shape configures nothing.
+//  2. **It virtualizes.** Past a couple of hundred visible rows it builds
+//     only the slice on screen, the way `Table` does, and the rest of the
+//     list is two spacer boxes so the scrollbar still measures the whole
+//     tree. That is what "very large number of elements" costs: nothing.
+//  3. **Every visible part is a seam.** The twisty, the branch edge down the
+//     indent, the label, the row's contents and — in `layout="nested"` — the
+//     subtree container are each a render prop with a style override beside
+//     it. The default look is deliberately plain: a chevron, no branch lines,
+//     just indentation.
+//
+// Nothing here registers a host element. A tree is `<box>`, `<text>` and
+// core's chevron, so there is no `registerElement` call, no JSX augmentation
+// and no side effect at import time at all.
+import React, { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, } from 'react';
+import { createStyles } from 'react-x11/style';
+import { Icon, useDirection, useTheme } from 'react-x11';
+import { XK_DOWN, XK_END, XK_HOME, XK_LEFT, XK_PAGE_DOWN, XK_PAGE_UP, XK_RETURN, XK_RIGHT, XK_UP, } from 'react-x11/keysyms';
+import { hx } from './hx.js';
+// Shared with <Table> — internal, deliberately not a shared *module*; the
+// header of src/internal/heights.ts says why.
+import { RowHeights } from '../internal/heights.js';
+import { afterLayout, cancelAfterLayout } from '../internal/timers.js';
+import { useReveal } from '../internal/scroll.js';
+import { typeAheadChar, useTypeAhead } from './internal.js';
+import { branchEdges, findItem, groupRows, isGroup, resolveAccessors, visibleRows, } from './rows.js';
+export { branchEdges, findItem, resolveAccessors, visibleRows, } from './rows.js';
+/** One level of indent. */
+const INDENT = 14;
+/** The twisty's hit box — what a file browser lets you click to peek into a
+ *  folder without selecting it. It stays this wide whatever the glyph does. */
+const TWISTY = 12;
+/** The chevron inside it. A chevron's long axis is its box and its short one
+ *  is half of that, so `size` for one reads as its width. */
+const TWISTY_GLYPH = 10;
+const ROW_HEIGHT = 22;
+/** Rows kept either side of the viewport, so a fast scroll does not show a
+ *  gap before the next frame catches up. */
+const OVERSCAN = 6;
+/**
+ * What to build before the viewport has been measured. `onViewport` cannot
+ * arrive until layout has run, which is a frame after the first commit, so
+ * there is always one render that has to guess — and guessing "all of them"
+ * puts a hundred thousand rows in the tree for a frame.
+ */
+const ASSUMED_ROWS = 40;
+/**
+ * Where `virtual="auto"` starts virtualizing.
+ *
+ * Well above any viewport, so a tree that is merely long is still built whole
+ * and keeps the two things virtualization costs: a row may be any height, and
+ * every row is in the accessibility tree. Well below the point where building
+ * every row is felt.
+ */
+const VIRTUAL_THRESHOLD = 200;
+const s = createStyles({
+    root: { flexGrow: 1, minHeight: 0, overflow: 'scroll' },
+    row: {
+        flexShrink: 0,
+        flexDirection: 'row',
+        alignItems: 'center',
+        gap: 4,
+        paddingEnd: 8,
+        paddingTop: 3,
+        paddingBottom: 3,
+        cursor: 'pointer',
+        transition: { backgroundColor: 80 },
+    },
+    twisty: {
+        width: TWISTY,
+        height: TWISTY,
+        flexShrink: 0,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    guide: { flexShrink: 0, alignSelf: 'stretch' },
+    /**
+     * The label **wraps**, and the row grows to hold it.
+     *
+     * This is the whole point of rows being measured rather than fixed: a name
+     * too long for the pane becomes two lines of a taller row, not two lines
+     * drawn over the row below. An app that wants the one-line, clipped look a
+     * file browser has says so — `styles={{ label: { textWrap: 'nowrap' } }}` —
+     * and gets it for the whole tree.
+     *
+     * `textBoxTrim` makes the box the letters rather than the font's ascent and
+     * descent, so a label centres on what can be seen. That is what core's
+     * `labelContent` gives every label in the widget set.
+     */
+    label: {
+        flexShrink: 1,
+        minWidth: 0,
+        textBoxTrim: 'cap-alphabetic',
+    },
+    subtree: { flexShrink: 0 },
+    spacer: { flexShrink: 0 },
+});
+/** A string or a number becomes a `<text>`; anything else is already a
+ *  node. */
+function labelNode(label, style) {
+    return typeof label === 'string' || typeof label === 'number'
+        ? hx('text', { key: 'label', style }, String(label))
+        : label;
+}
+/**
+ * `<Tree items />` — a disclosure tree.
+ *
+ *     <Tree items={[{ id: 'src', label: 'src', children: [...] }]} />
+ *
+ * An item with a `children` array is a branch, **even when the array is
+ * empty** — that is how a directory shows a twisty before anything has read
+ * it. A branch whose children are not loaded at all says `branch: true`, and
+ * fills them in from `onExpandedChange`.
+ *
+ * Expansion and selection are each controlled (`expanded` + `onExpandedChange`,
+ * `selected` + `onSelect`) or uncontrolled (`defaultExpanded`,
+ * `defaultSelected`).
+ *
+ * The tree is a single tab stop. Up/Down walk the visible rows, Right expands
+ * a branch and then steps into it, Left collapses and then steps out to the
+ * parent, PageUp/PageDown move by a viewport, Home/End jump to the ends,
+ * Enter and Space activate, and typing letters jumps to a matching row — the
+ * same type-ahead core's `Select` and menus use.
+ *
+ * **The focus is on the tree, not on the row.** Core's tree focused each row
+ * node; a virtualized row is unmounted the moment it scrolls out of view and
+ * the focus would go with it, so the container is the focusable thing and the
+ * selection is the cursor. That is `Table`'s model, and the honest caveat is
+ * the one `Table` carries: while virtualizing, only the rendered rows are in
+ * the accessibility tree — the same rows a sighted user can see.
+ *
+ * **Selection is one row.** Multiple selection is not a prop because there is
+ * no version of it everybody agrees on (does Shift extend from the anchor or
+ * from the cursor? does Ctrl+click on a branch take its children?), and every
+ * such policy is expressible on top of what is here: hold the set yourself,
+ * pass `selected` for the cursor, and paint the rest from `styles.row`.
+ */
+export function Tree({ items = [], expanded, defaultExpanded, onExpandedChange, selected, defaultSelected, onSelect, onActivate, indent = INDENT, rowHeight = ROW_HEIGHT, estimatedRowHeight, virtual = 'auto', overscan = OVERSCAN, layout = 'flat', renderToggle, renderGuide, renderLabel, renderContent, renderSubtree, styles, style, ref, 
+// the accessors, pulled out so the rest can be spread onto the box
+getId, getLabel, getText, getChildren, isBranch, isDisabled, 
+// ours to chain rather than to hand over: virtualization is measured
+// through both of these
+onScroll, onViewport, ...boxProps }) {
+    const theme = useTheme();
+    const rtl = useDirection() === 'rtl';
+    const [ownExpanded, setOwnExpanded] = useState(() => new Set(defaultExpanded));
+    const [ownSelected, setOwnSelected] = useState(defaultSelected ?? null);
+    const [view, setView] = useState({ top: 0, height: 0 });
+    // Bumped by a measurement pass that found a row taller or shorter than the
+    // index believed. It is the only reason the component re-renders for a
+    // measurement, and a pass that finds nothing new does not bump it, which is
+    // what makes measure → render → measure converge instead of spinning.
+    const [, setMeasured] = useState(0);
+    const typeAhead = useTypeAhead();
+    const scroller = useRef(null);
+    /** The rows on screen, by id — with the index each was drawn at, so a
+     *  measurement pass does not have to search the row list for it. */
+    const rowNodes = useRef(new Map());
+    const estimate = estimatedRowHeight ?? rowHeight;
+    // `useState` for its lazy initializer rather than `useRef`: one index per
+    // mounted tree, built once. Nothing ever calls the setter — what it holds
+    // is mutable and its changes are announced through `setMeasured`.
+    const [heights] = useState(() => new RowHeights(estimate));
+    const accessors = useMemo(() => resolveAccessors({
+        getId,
+        getLabel,
+        getText,
+        getChildren,
+        isBranch,
+        isDisabled,
+    }), [getId, getLabel, getText, getChildren, isBranch, isDisabled]);
+    const openSet = useMemo(() => (expanded ? new Set(expanded) : ownExpanded), [expanded, ownExpanded]);
+    const current = selected === undefined ? ownSelected : selected;
+    const rows = useMemo(() => visibleRows(items, openSet, accessors), [items, openSet, accessors]);
+    // Held-down or fast keys arrive in a burst, and every handler in that burst
+    // sees the render it started from — so what is open and what is selected
+    // are mirrored here and updated the moment they change, or three Downs in a
+    // row all step off the same starting point.
+    const openRef = useRef(openSet);
+    openRef.current = openSet;
+    const currentRef = useRef(current);
+    currentRef.current = current;
+    const rowsRef = useRef(rows);
+    rowsRef.current = rows;
+    const itemsRef = useRef(items);
+    itemsRef.current = items;
+    const viewRef = useRef(view);
+    viewRef.current = view;
+    const virtualizing = layout === 'flat' &&
+        (virtual === true ||
+            (virtual === 'auto' && rows.length > VIRTUAL_THRESHOLD));
+    // The index is re-pointed at the rows about to be drawn before anything
+    // asks it where they are. `rows` is memoized, so this is an identity check
+    // on every render that did not change the tree.
+    const index = heights;
+    index.sync(rows, estimate);
+    // The slice worth building: what is on screen, plus a little either side.
+    // Which rows those are is a question for the height index now — with rows
+    // of different heights there is no division that answers it.
+    const first = virtualizing
+        ? Math.max(0, index.indexAt(view.top) - overscan)
+        : 0;
+    let last = rows.length;
+    if (virtualizing) {
+        if (view.height > 0) {
+            last = Math.min(rows.length, index.indexAt(view.top + view.height) + 1 + overscan);
+        }
+        else {
+            // Before the first layout there is no viewport to measure against, and
+            // guessing "all of them" would put a hundred thousand rows in the tree
+            // for a frame.
+            last = Math.min(rows.length, first + ASSUMED_ROWS);
+        }
+    }
+    /** Where the slice starts, and how much of the list is below it — the two
+     *  spacers that keep the scrollbar measuring the whole tree. */
+    const above = virtualizing ? index.offsetAt(first) : 0;
+    const below = virtualizing ? index.total() - index.offsetAt(last) : 0;
+    const setExpandedSet = useCallback((next, change) => {
+        openRef.current = next;
+        if (expanded === undefined)
+            setOwnExpanded(next);
+        onExpandedChange?.([...next], change);
+    }, [expanded, onExpandedChange]);
+    const toggleId = useCallback((id, item, open) => {
+        const next = new Set(openRef.current);
+        const shouldOpen = open ?? !next.has(id);
+        if (shouldOpen)
+            next.add(id);
+        else
+            next.delete(id);
+        setExpandedSet(next, { id, item, open: shouldOpen });
+    }, [setExpandedSet]);
+    /**
+     * The scroll the tree owes a row, and the pane's real offset read back
+     * after every layout — the two halves of `../internal/scroll.ts`, which
+     * says why a reveal cannot be a one-shot and why `onScroll` is not the
+     * whole story. A tree grows and shrinks under its own hands: opening a
+     * branch is a content that got taller between the ask and the layout, in
+     * exactly the way an arriving row is.
+     */
+    const reveal = useReveal({
+        box: scroller,
+        rows: rowsRef,
+        nodes: rowNodes,
+        heights,
+    });
+    /** Put a row in view, by the index its call site already has. */
+    const revealAt = useCallback((at) => {
+        const row = rowsRef.current[at];
+        if (row)
+            reveal.to(row.id);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `reveal` is a
+        // stable handle
+    }, [reveal]);
+    /**
+     * Re-read the offset the pane is *actually* at.
+     *
+     * It moves silently — a queued reveal resolves during layout, and an offset
+     * the content outgrew or outshrank is re-clamped there — and a slice built
+     * from the offset before those is drawn where the viewport is not: a blank
+     * band where the rows should be, until a scroll of your own re-syncs it by
+     * accident.
+     */
+    const syncScroll = useCallback(() => {
+        const box = scroller.current;
+        if (!box || !virtualizing)
+            return;
+        const y = box.scrollY;
+        setView((prev) => (prev.top === y ? prev : { ...prev, top: y }));
+    }, [virtualizing]);
+    /**
+     * Read back what the rows on screen actually laid out at.
+     *
+     * The one thing that makes rows of different heights work, and the reason
+     * it is not simply "read the height in an effect": **layout runs after
+     * React's effects, on the frame flush**, so a `useEffect` sees the
+     * *previous* pass's geometry — zero, on the render that created the row.
+     * This runs a tick later, when `abs` is current.
+     *
+     * Idempotent by construction. A row whose measurement has not changed
+     * reports no change, so the second pass over the same rows costs a map walk
+     * and re-renders nothing, and measure → render → measure terminates.
+     */
+    const measureRows = useCallback(() => {
+        if (!virtualizing)
+            return false;
+        const box = scroller.current;
+        const rows = rowsRef.current;
+        const idx = heights;
+        // Rows above the top of the viewport are the ones that move the content
+        // under it, so their total change is what has to come back out of the
+        // scroll offset — otherwise measuring a row you have already scrolled
+        // past yanks the list under the pointer.
+        const anchor = box ? idx.indexAt(box.scrollY) : 0;
+        let shift = 0;
+        let changed = false;
+        for (const [id, { node, at }] of rowNodes.current) {
+            if (rows[at]?.id !== id)
+                continue; // drawn against a list that has moved
+            const height = node.abs.height;
+            const was = idx.heightAt(at);
+            if (!idx.measure(id, at, height))
+                continue;
+            changed = true;
+            if (at < anchor)
+                shift += height - was;
+        }
+        if (!changed)
+            return false;
+        if (shift !== 0 && box) {
+            reveal.scrollTo(box.scrollY + shift);
+        }
+        setMeasured((n) => n + 1);
+        return true;
+    }, [virtualizing]);
+    /**
+     * The one tick after layout, and everything that can only be known there:
+     * what the rows measured, whether an owed scroll can go further now that
+     * the rows it was waiting for are laid out, and where the pane actually
+     * ended up. In that order — each step can move the offset the next one
+     * reads.
+     */
+    useEffect(() => {
+        if (!virtualizing)
+            return undefined;
+        const id = afterLayout(() => {
+            // `measureRows` first, and its answer handed on: a pass that moved the
+            // heights has not settled anything, and an owed scroll judged against
+            // the layout it is about to invalidate is not owed any less.
+            reveal.retry(measureRows());
+            syncScroll();
+        });
+        return () => cancelAfterLayout(id);
+    });
+    const goTo = useCallback((row) => {
+        if (!row)
+            return;
+        currentRef.current = row.id;
+        if (selected === undefined)
+            setOwnSelected(row.id);
+        onSelect?.(row.id, row.item);
+        revealAt(row.index);
+    }, [selected, onSelect, revealAt]);
+    const activate = useCallback((row) => {
+        if (row.branch)
+            toggleId(row.id, row.item);
+        onActivate?.(row.id, row.item);
+    }, [toggleId, onActivate]);
+    /** Returns whether the key was the tree's, so a control that forwards its
+     *  keys here keeps the ones it did not use. */
+    const handleKey = useCallback((ev) => {
+        const rows = rowsRef.current;
+        if (!rows.length)
+            return false;
+        const index = rows.findIndex((r) => r.id === currentRef.current);
+        const row = rows[index];
+        const step = (delta) => {
+            for (let i = index + delta; i >= 0 && i < rows.length; i += delta) {
+                if (!rows[i].disabled)
+                    return rows[i];
+            }
+            return null;
+        };
+        /** The nearest enabled row at or before `to`, walking `dir` if the
+         *  landing row is disabled — what a page jump needs. */
+        const nearest = (to, dir) => {
+            const at = Math.max(0, Math.min(rows.length - 1, to));
+            for (let i = at; i >= 0 && i < rows.length; i += dir) {
+                if (!rows[i].disabled)
+                    return rows[i];
+            }
+            return null;
+        };
+        // Deeper is the direction the indent grows in, which is the direction
+        // the text runs — so it is Left that opens a branch in a mirrored tree,
+        // and the two arrows swap wholesale rather than the tree growing a
+        // second set of cases.
+        const deeper = rtl ? XK_LEFT : XK_RIGHT;
+        const shallower = rtl ? XK_RIGHT : XK_LEFT;
+        /**
+         * How far a page key moves, in rows.
+         *
+         * A viewport's worth, which with rows of different heights is not a
+         * division: it is "where does the row `index` sits at end up if I add a
+         * viewport to its offset". One row of overlap is kept, the way every
+         * document viewer does, so a page down leaves a line of context.
+         */
+        const pageFrom = (from, dir) => {
+            const idx = heights;
+            const viewport = viewRef.current.height;
+            if (viewport <= 0)
+                return from + dir;
+            const at = Math.max(0, Math.min(rows.length - 1, from));
+            const target = idx.offsetAt(at) + dir * Math.max(1, viewport - rowHeight);
+            const landed = idx.indexAt(Math.max(0, target));
+            // never stand still: a row taller than the viewport would otherwise
+            // make Page Down a no-op
+            return landed === at ? at + dir : landed;
+        };
+        switch (ev.keysym) {
+            case XK_UP:
+                goTo(step(-1));
+                return true;
+            case XK_DOWN:
+                goTo(step(1));
+                return true;
+            case XK_PAGE_UP:
+                goTo(nearest(index < 0 ? 0 : pageFrom(index, -1), 1));
+                return true;
+            case XK_PAGE_DOWN:
+                goTo(nearest(index < 0 ? pageFrom(0, 1) : pageFrom(index, 1), -1));
+                return true;
+            case deeper:
+                // open it, then walk into it — one key does both, in order
+                if (row?.branch && !row.open)
+                    toggleId(row.id, row.item, true);
+                else if (row?.branch)
+                    goTo(step(1));
+                return true;
+            case shallower:
+                if (row?.branch && row.open)
+                    toggleId(row.id, row.item, false);
+                else if (row?.parent)
+                    goTo(row.parent);
+                return true;
+            case XK_HOME:
+                goTo(rows.find((r) => !r.disabled));
+                return true;
+            case XK_END:
+                goTo([...rows].reverse().find((r) => !r.disabled));
+                return true;
+            case XK_RETURN:
+                if (row)
+                    activate(row);
+                return true;
+            default:
+                break;
+        }
+        if (ev.codepoint === 32) {
+            if (row)
+                activate(row);
+            return true;
+        }
+        const char = typeAheadChar(ev);
+        if (!char)
+            return false;
+        const found = typeAhead(char, rows, index < 0 ? null : index, (r) => accessors.getText(r.item), (r) => !r.disabled);
+        if (found >= 0)
+            goTo(rows[found]);
+        return found >= 0;
+    }, [rtl, rowHeight, goTo, toggleId, activate, typeAhead, accessors]);
+    useImperativeHandle(ref, () => ({
+        focus: () => {
+            scroller.current?.focus();
+        },
+        select: (id) => {
+            const row = rowsRef.current.find((r) => r.id === id);
+            if (row)
+                goTo(row);
+            else if (id === null) {
+                currentRef.current = null;
+                if (selected === undefined)
+                    setOwnSelected(null);
+            }
+        },
+        setExpanded: (id, open) => {
+            // An id nobody can see is still legitimately expandable — a lazy load
+            // finishing under a branch the user collapsed again, say — so the
+            // whole tree is searched rather than the rows on screen.
+            //
+            // An id that is in neither is a no-op, and that is the point: the
+            // change this reports carries the item, `TreeExpandChange<T>.item` is
+            // `T`, and an id nothing answers to has no item to put there. Doing
+            // nothing beats reporting an expansion of `undefined`.
+            const item = rowsRef.current.find((r) => r.id === id)?.item ??
+                findItem(itemsRef.current, id, accessors);
+            if (item === undefined)
+                return false;
+            toggleId(id, item, open);
+            return true;
+        },
+        scrollToItem: (id) => {
+            const row = rowsRef.current.find((r) => r.id === id);
+            if (!row)
+                return false;
+            revealAt(row.index);
+            return true;
+        },
+        handleKey,
+        rows: () => rowsRef.current,
+    }), [goTo, toggleId, revealAt, handleKey, selected, accessors]);
+    // --- rendering -----------------------------------------------------------
+    const rowStyleProp = styles?.row;
+    const guideStyleProp = styles?.guide;
+    const renderOneRow = (row) => {
+        const isSelected = row.id === current;
+        const color = row.disabled
+            ? theme.textMuted
+            : isSelected
+                ? theme.hoverText
+                : theme.text;
+        const state = {
+            ...row,
+            selected: isSelected,
+            color,
+            toggle: (open) => toggleId(row.id, row.item, open),
+            select: () => goTo(row),
+        };
+        const content = [];
+        // The indent. With no guide seam it is one padding value rather than
+        // `depth` empty boxes — a tree ten deep would otherwise build ten nodes
+        // per row to draw nothing.
+        if (renderGuide && row.depth > 0) {
+            const edges = branchEdges(row);
+            for (let level = 0; level < row.depth; level++) {
+                const guide = {
+                    row: state,
+                    level,
+                    continues: edges[level],
+                    own: level === row.depth - 1,
+                    width: indent,
+                    height: rowHeight,
+                };
+                content.push(hx('box', {
+                    key: `guide${level}`,
+                    style: [
+                        s.guide,
+                        { width: indent },
+                        typeof guideStyleProp === 'function'
+                            ? guideStyleProp(guide)
+                            : guideStyleProp,
+                    ],
+                }, renderGuide(guide)));
+            }
+        }
+        const toggleState = { ...state, size: TWISTY_GLYPH };
+        content.push(hx('box', {
+            key: 'toggle',
+            style: [s.twisty, styles?.toggle],
+            // The twisty is its own hit target: clicking it opens the branch
+            // without moving the selection, the way a file browser lets you
+            // peek inside a folder you have not chosen.
+            onClick: row.branch
+                ? (ev) => {
+                    ev.stopPropagation();
+                    toggleId(row.id, row.item);
+                }
+                : undefined,
+        }, renderToggle
+            ? renderToggle(toggleState)
+            : row.branch
+                ? React.createElement(Icon, {
+                    name: row.open
+                        ? 'chevronDown'
+                        : rtl
+                            ? 'chevronLeft'
+                            : 'chevronRight',
+                    size: TWISTY_GLYPH,
+                    // dimmer than the label on a resting row, and the row's own
+                    // ink once it is selected
+                    style: isSelected ? undefined : { color: theme.textMuted },
+                })
+                : null));
+        content.push(renderLabel
+            ? // Keyed here rather than by the app, for the reason `renderSubtree`
+                // is: the label sits in an array beside the guides and the twisty,
+                // and "add a key to the box you return" is not something a render
+                // prop should have to know.
+                React.createElement(React.Fragment, { key: 'label' }, renderLabel(state))
+            : labelNode(accessors.getLabel(row.item), [s.label, styles?.label]));
+        return hx('box', {
+            key: String(row.id),
+            role: 'treeitem',
+            'aria-level': row.depth + 1,
+            'aria-selected': isSelected,
+            'aria-expanded': row.branch ? row.open : undefined,
+            'aria-posinset': row.posInSet,
+            'aria-setsize': row.setSize,
+            // `disabled` rather than `aria-disabled`: on a react-x11 node it is
+            // the real thing — it clears the AT-SPI ENABLED/SENSITIVE states and
+            // selects the `:disabled` style block — and there is no aria spelling
+            // of it to write instead.
+            disabled: row.disabled || undefined,
+            // The index the row was drawn at travels with the node, so measuring
+            // does not have to search a hundred thousand rows for where it is.
+            // It can go stale — the rows may move before the tick that measures —
+            // and both this and the height index check it rather than trust it.
+            ref: (node) => {
+                if (node)
+                    rowNodes.current.set(row.id, { node, at: row.index });
+                else
+                    rowNodes.current.delete(row.id);
+            },
+            onClick: (ev) => {
+                if (row.disabled)
+                    return;
+                goTo(row);
+                // Select on the first click, open on the second — the gesture every
+                // file list has. `detail` is the click count the renderer already
+                // counts for text selection.
+                if (ev.detail === 2)
+                    activate(row);
+            },
+            style: [
+                s.row,
+                // A floor, not a height. The row grows to whatever its content
+                // needs — a wrapped label, two lines, a thumbnail — and the height
+                // index reads back what it actually became.
+                { minHeight: rowHeight },
+                // The indent is what says "inside", so it is measured from the edge
+                // the row's label begins at.
+                { paddingStart: renderGuide ? 4 : 4 + row.depth * indent },
+                {
+                    backgroundColor: isSelected ? theme.hoverBackground : 'transparent',
+                    // The row's ink, said once: `color` inherits, so the label takes
+                    // it without being handed it.
+                    color,
+                },
+                !row.disabled && {
+                    ':hover': {
+                        backgroundColor: isSelected
+                            ? theme.hoverBackground
+                            : theme.surfaceHover,
+                    },
+                    // The selection only moves on the release, and `:active` marks
+                    // the whole press chain, so a press on the label or the twisty
+                    // still darkens the row it is in.
+                    ':active': {
+                        backgroundColor: isSelected
+                            ? theme.accentActive
+                            : theme.surfaceActive,
+                    },
+                },
+                typeof rowStyleProp === 'function'
+                    ? rowStyleProp(state)
+                    : rowStyleProp,
+            ],
+        }, renderContent ? renderContent(state, content) : content);
+    };
+    /** `layout="nested"`: the same rows, wrapped group by group. */
+    const renderGroup = (group, key) => {
+        const children = group.rows.map((node, i) => isGroup(node) ? renderGroup(node, `${key}.${i}`) : renderOneRow(node));
+        if (!group.parent)
+            return children;
+        const state = {
+            parent: group.parent,
+            depth: group.parent.depth + 1,
+        };
+        // The key is this component's either way, and a fragment is how a seam
+        // gets one without being told to write it. A `renderSubtree` that had to
+        // remember a key would get it wrong the obvious way — keying on the
+        // parent id, which is already the key of the parent *row* beside it.
+        if (renderSubtree) {
+            return React.createElement(React.Fragment, { key: `subtree:${group.parent.id}` }, renderSubtree(state, children));
+        }
+        return hx('box', {
+            key: `subtree:${group.parent.id}`,
+            role: 'group',
+            style: [s.subtree, styles?.subtree],
+        }, children);
+    };
+    const body = [];
+    if (layout === 'nested') {
+        body.push(renderGroup(groupRows(rows), 'root'));
+    }
+    else {
+        if (virtualizing && first > 0) {
+            body.push(hx('box', {
+                key: 'spacer:before',
+                style: [s.spacer, { height: above }],
+            }));
+        }
+        for (let i = first; i < last; i++)
+            body.push(renderOneRow(rows[i]));
+        if (virtualizing && last < rows.length) {
+            body.push(hx('box', {
+                key: 'spacer:after',
+                style: [s.spacer, { height: below }],
+            }));
+        }
+    }
+    return hx('box', {
+        theme,
+        role: 'tree',
+        // The tree takes the focus, not the row — see the doc comment.
+        focusable: true,
+        ...boxProps,
+        ref: scroller,
+        style: [s.root, style],
+        /**
+         * `preventDefault` is the load-bearing half.
+         *
+         * The tree's root is a scroll container **and** the focused node, and a
+         * focused scroller has default key actions of its own: Down and Up
+         * scroll by a wheel notch, the Page keys by a viewport, Home and End to
+         * the ends, Space by a page. Without this, every arrow did both — moved
+         * the selection *and* scrolled the list under it — which reads as the
+         * tree scrolling whenever you use the keyboard rather than only when
+         * the selection would otherwise leave the viewport.
+         *
+         * `handleKey` reports whether the tree took the key, so a key it did
+         * not take (a letter that matched nothing) still gets the default.
+         */
+        onKeyDown: (ev) => {
+            if (handleKey(ev))
+                ev.preventDefault();
+        },
+        // Layout, not scrolling, is what first tells a list how much of it is
+        // worth building — and it is also where a page key gets its distance,
+        // so this is measured whether or not the tree virtualizes.
+        onViewport: (ev) => {
+            setView((prev) => prev.height === ev.height ? prev : { ...prev, height: ev.height });
+            // The content just changed size, which is both the moment an owed
+            // scroll can reach further than the clamp let it and the moment the
+            // pane may have re-clamped its offset without saying so. It is not a
+            // moment anything can be *settled* in: this runs from layout, a tick
+            // before the pass that reads the rows it just drew back.
+            reveal.retry(virtualizing);
+            syncScroll();
+            onViewport?.(ev);
+        },
+        onScroll: (ev) => {
+            // A scroll this component did not ask for is the user taking over,
+            // and an owed reveal must not yank the tree back out from under them
+            // on the next layout.
+            reveal.heard(ev.scrollY);
+            if (virtualizing) {
+                setView((prev) => prev.top === ev.scrollY ? prev : { ...prev, top: ev.scrollY });
+            }
+            onScroll?.(ev);
+        },
+    }, body);
+}
+//# sourceMappingURL=index.js.map