@react-x11/components 0.2.1 → 0.3.0

package/dist/internal/window.js

@@ -0,0 +1,417 @@
+// The virtualization window: which rows are worth building, given where the
+// viewport is and what it is doing.
+//
+// **Shared between `<Tree>` and `<Table>`** — the fourth piece both
+// virtualizers stand on, beside `./heights.ts`, `./timers.ts` and
+// `./scroll.ts`, and promoted for the same reason: the slice arithmetic, the
+// viewport bookkeeping and the offset re-read after layout were line-for-line
+// identical in both, and the scroll-responsiveness work lands in one place
+// instead of two. See the header of `./heights.ts` for why this directory is
+// internal rather than a shared module with a subpath.
+//
+// What a scroll actually costs on this renderer is the reason this file is
+// more than `indexAt(top) ± overscan`. A wheel notch scrolls the pane and
+// repaints the exposed strip **synchronously, before React runs** — core
+// blits on the event's own frame — so whatever is mounted in that strip is
+// what the user sees. Rows built by the re-render land a frame later at the
+// earliest. The only scroll with no blank frame at all is one that lands
+// inside rows that were already built, which is what the window is for:
+//
+//   - **Idle prefetch.** While nothing is scrolling, the window grows
+//     chunk-by-chunk beyond the overscan, up to `prefetch` rows each side —
+//     prep work done while nobody is watching, so the next scroll lands on
+//     rows that are already there. Grown in small steps so no single commit
+//     is felt, and paused the moment a scroll arrives.
+//   - **Velocity lead.** While scrolling, the window extends in the
+//     direction of travel by the distance the next few frames will cover, so
+//     the rows being built are the ones about to be exposed rather than ones
+//     already behind the viewport.
+//   - **Hysteresis.** Rows already built stay in the window until the budget
+//     forces them out, trailing side first — a direction reversal lands on
+//     rows still mounted instead of rebuilding them. The budget caps what a
+//     render can be asked to carry: the on-screen slice plus `prefetch` rows
+//     each side.
+//   - **Skeletons.** A scroll that outruns everything — a thumb dragged
+//     across the list, a flick past the band — floods the window with rows
+//     no single render can build in time. Those render as *skeletons*: the
+//     row box at its indexed height, none of its content. A skeleton commit
+//     is cheap, so it lands frames sooner than the full rows would, and
+//     what blits in reads as rows arriving rather than a void. Upgrades
+//     follow viewport-first, a budget per render, until none remain.
+//
+// A row outside the viewport costs its share of layout and nothing on the
+// wire — the pane clips it — so the band is cheap to hold and pays for
+// itself on the first notch that lands inside it.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { cancelLater, later } from './timers.js';
+const EMPTY_KEYS = new Set();
+/** Rows kept either side of the viewport, so a fast scroll does not show a
+ *  gap before the next frame catches up. The components' default. */
+export const DEFAULT_OVERSCAN = 6;
+/** How long the viewport must have been showing unresolved content before
+ *  the fast-scroll pill appears. A catch-up the next few frames absorb is
+ *  not worth announcing — the pill is for the delay you can feel. */
+export const SCROLL_HINT_DELAY_MS = 250;
+/** How far past the overscan the idle band grows, rows per side — the
+ *  components' default for their `prefetch` prop. Roughly two viewports of
+ *  ordinary rows: enough that a flick lands inside it, small enough that
+ *  holding it is never felt. */
+export const DEFAULT_PREFETCH = 40;
+/**
+ * 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;
+/** How long the pane must sit quiet before prefetch may grow. Longer than a
+ *  frame, shorter than a reader's pause. */
+const IDLE_MS = 120;
+/** Between growth steps — each step is one commit of `GROW_CHUNK` rows per
+ *  side, so the band arrives in pieces no single frame feels. */
+const GROW_MS = 40;
+const GROW_CHUNK = 16;
+/** How far ahead the velocity lead looks — about three frames: one for the
+ *  render to land, one for its paint, one of margin. */
+const LEAD_MS = 50;
+/** Velocity is an EMA of the per-event slope; a gap longer than this between
+ *  events is a stop, not a very slow scroll. */
+const VEL_GAP_MS = 250;
+/** Above this the scroll is a flick, not a read — px/ms, about three rows a
+ *  frame. What `fast()` answers with, for work worth deferring to the
+ *  settle. */
+const FAST_V = 1.5;
+/** More rows than this entering the window in one render is a flood — a
+ *  teleport or a hard flick — and floods build skeletons first. An ordinary
+ *  notch brings in a handful and never trips this. */
+export const SKELETON_THRESHOLD = 16;
+/** New full rows built per render while a flood is being caught up with.
+ *  Measured (rowcost probe, 300-row commits, warm caches): a default-shape
+ *  row costs ~0.11ms against a skeleton's ~0.06ms — about 2×, not the 10×
+ *  the original pacing assumed — so the budgets lean generous and the
+ *  skeleton tier is there for heavy `render` seams and for the look of
+ *  rows arriving, not because full rows are ruinous. */
+export const BURST_BUDGET = 24;
+/** The same, once the scroll has stopped: bigger steps, still paced, so a
+ *  settle after a long flood is a few quick commits rather than one big
+ *  one. */
+export const SETTLE_BUDGET = 48;
+/**
+ * The window a virtualizing component builds its rows from.
+ *
+ * Owns the viewport state and the slice; the component keeps everything the
+ * two virtualizers genuinely differ on — what a row *is*, measuring it,
+ * revealing it. Call after `heights.sync`, so the slice is computed against
+ * the rows this render is about to draw.
+ */
+export function useVirtualWindow(inputs) {
+    const [view, setView] = useState({
+        top: 0,
+        height: 0,
+        width: 0,
+    });
+    const viewRef = useRef(view);
+    viewRef.current = view;
+    const inp = useRef(inputs);
+    inp.current = inputs;
+    /** Re-render with the same viewport — how an idle tick asks the slice to
+     *  be recomputed so the band can take its next growth step. */
+    const [, bump] = useState(0);
+    /** The window built last render, kept so this render can keep it. */
+    const built = useRef(null);
+    /** The scroll's slope, px/ms, EMA over the events of the current burst —
+     *  signed, positive downwards. Meaningful only while `active`. */
+    const vel = useRef({ t: 0, top: 0, v: 0 });
+    /** A burst is in flight: velocity is live and growth is paused. Cleared by
+     *  the idle tick rather than by a clock read at render time, so a render's
+     *  output never depends on when it ran. */
+    const active = useRef(false);
+    /** Whether the slice this render produced still wants another step — band
+     *  growth left to do, or skeletons left to upgrade — read by the idle tick
+     *  to decide whether a re-render is worth it. */
+    const wantsGrowth = useRef(false);
+    /** Skeletons the slice this render carries — the tick shortens its own
+     *  clock while any remain, so a flood is caught up with at `GROW_MS` pace
+     *  rather than waiting out the idle delay. */
+    const hasSkeletons = useRef(false);
+    /** The rows currently built in full, by id — everything else in the slice
+     *  is a skeleton. Ids, not indexes, so a re-sort moves the rows without
+     *  demoting them. */
+    const real = useRef(new Set());
+    /** When the current catch-up began — see `catchupSince` on the result. */
+    const catchupStart = useRef(null);
+    const idleTimer = useRef(null);
+    const tick = useCallback(() => {
+        idleTimer.current = null;
+        const wasActive = active.current;
+        active.current = false;
+        if (!wasActive && !wantsGrowth.current)
+            return;
+        // One re-render on settling even when there is nothing to grow: it is
+        // the render a component's deferred-while-scrolling work (measuring,
+        // estimate adaptation) runs on.
+        bump((n) => n + 1);
+        if (wantsGrowth.current) {
+            idleTimer.current = later(tick, GROW_MS);
+        }
+    }, []);
+    const scrolled = useCallback((top) => {
+        // Only a virtualizing component reads the vertical offset — a whole
+        // one has no slice to rebuild, and re-rendering it on a scroll it
+        // already drew would be work for nothing.
+        if (!inp.current.virtualizing)
+            return;
+        globalThis.__scrolls = (globalThis.__scrolls ?? 0) + 1;
+        const now = Date.now();
+        const s = vel.current;
+        const dt = now - s.t;
+        if (dt > 0 && dt < VEL_GAP_MS) {
+            // Blend rather than replace: a wheel's notches arrive unevenly, and
+            // the lead must not whip around on every one.
+            s.v = s.v * 0.6 + ((top - s.top) / dt) * 0.4;
+        }
+        else {
+            s.v = 0;
+        }
+        s.t = now;
+        s.top = top;
+        active.current = true;
+        cancelLater(idleTimer.current);
+        idleTimer.current = later(tick, IDLE_MS);
+        setView((prev) => (prev.top === top ? prev : { ...prev, top }));
+    }, [tick]);
+    const sized = useCallback((width, height) => {
+        viewRef.current = { ...viewRef.current, width, height };
+        setView((prev) => prev.width === width && prev.height === height
+            ? prev
+            : { ...prev, width, height });
+    }, []);
+    const sync = useCallback(() => {
+        const { box, virtualizing } = inp.current;
+        const node = box.current;
+        if (!node || !virtualizing)
+            return;
+        const y = node.scrollY;
+        setView((prev) => (prev.top === y ? prev : { ...prev, top: y }));
+    }, []);
+    const scrolling = useCallback(() => active.current, []);
+    const fast = useCallback(() => active.current && Math.abs(vel.current.v) >= FAST_V, []);
+    // The idle clock has to start somewhere even when nothing ever scrolls —
+    // a table that mounts and sits still owes itself the band. After any
+    // render that still wants growth, make sure a tick is coming — and while
+    // skeletons remain, a *near* one: they are on screen, and waiting out the
+    // idle delay to fill them in would be a visible pause.
+    useEffect(() => {
+        if (hasSkeletons.current) {
+            cancelLater(idleTimer.current);
+            idleTimer.current = later(tick, GROW_MS);
+        }
+        else if (wantsGrowth.current && idleTimer.current === null) {
+            idleTimer.current = later(tick, IDLE_MS);
+        }
+    });
+    useEffect(() => () => cancelLater(idleTimer.current), []);
+    const { heights, rows, exact, virtualizing, overscan, prefetch, threshold, burstBudget, settleBudget, } = inputs;
+    const count = rows.length;
+    let first = 0;
+    let last = count;
+    let jumped = false;
+    wantsGrowth.current = false;
+    /** Skeletons are still being filled in from the last render — the band
+     *  must not grow while they are, or the debt outruns the catch-up. */
+    const catchingUp = hasSkeletons.current;
+    if (virtualizing) {
+        // The core: what is on screen plus the overscan — extended, while a
+        // burst is in flight, by where that burst will be in a few frames. The
+        // lead goes on the edge being exposed; the overscan already covers the
+        // trailing one.
+        //
+        // **Clamped to one viewport.** A scrollbar scrub moves millions of
+        // pixels a second, and an unclamped `v × LEAD_MS` asked the slice for
+        // tens of thousands of rows — one commit mounting them froze the app
+        // for seconds, the very thing a virtualized list exists to prevent. A
+        // viewport ahead is all a lead can usefully buy: anything further is
+        // out of sight again before it finishes landing.
+        const rawLead = active.current ? vel.current.v * LEAD_MS : 0;
+        const lead = Math.max(-view.height, Math.min(view.height, rawLead));
+        const topEdge = Math.max(0, view.top + Math.min(0, lead));
+        const coreFirst = Math.max(0, heights.indexAt(topEdge) - overscan);
+        let coreLast;
+        if (view.height > 0) {
+            const botEdge = view.top + view.height + Math.max(0, lead);
+            coreLast = Math.min(count, heights.indexAt(botEdge) + 1 + overscan);
+        }
+        else {
+            coreLast = Math.min(count, coreFirst + ASSUMED_ROWS);
+        }
+        first = coreFirst;
+        last = coreLast;
+        if (prefetch > 0 && view.height > 0) {
+            // Keep what the last render built, so far as it touches the window —
+            // a band the viewport just left is the band a reversal comes back to.
+            // A band that does not touch it at all is a teleport's leavings, and
+            // rebuilding from the core is cheaper than carrying rows a screenful
+            // of nothing away.
+            const b = built.current;
+            if (b) {
+                const bf = Math.min(Math.max(0, b.first), count);
+                const bl = Math.min(Math.max(bf, b.last), count);
+                if (bl > bf && bl >= first && bf <= last) {
+                    first = Math.min(first, bf);
+                    last = Math.max(last, bl);
+                }
+                else if (bl > bf) {
+                    jumped = true;
+                }
+            }
+            // Grown while idle, one chunk per side per tick — never during a
+            // burst, whose renders have rows of their own to build, and never
+            // while skeletons are still filling in, whose catch-up comes first.
+            // Upward growth stops at the first row the index has no real height
+            // for — see `exact` on the inputs for why building one would make
+            // the view wobble while idle.
+            const targetFirst = Math.max(0, coreFirst - prefetch);
+            const targetLast = Math.min(count, coreLast + prefetch);
+            const growableUp = () => first > targetFirst && (exact || heights.isMeasured(first - 1));
+            if (!active.current && !catchingUp) {
+                const stop = Math.max(targetFirst, first - GROW_CHUNK);
+                while (first > stop && growableUp())
+                    first--;
+                if (last < targetLast)
+                    last = Math.min(targetLast, last + GROW_CHUNK);
+            }
+            wantsGrowth.current = growableUp() || last < targetLast;
+            // The budget: the core plus a full band each side. Trim the trailing
+            // side first — those rows are the furthest from coming back. The
+            // top-side cut stops at the first row the index has no real height
+            // for, the same rule growth follows and for the reverse reason: a
+            // row laid out taller than the index believes contributes its real
+            // height while mounted and its guessed one once dropped, so cutting
+            // it silently shrinks the content above the viewport and the view
+            // yanks up by the difference with no debt left to put it right. Held
+            // a render or two longer, it gets measured, and the next trim takes
+            // it cleanly.
+            const budget = coreLast - coreFirst + 2 * prefetch;
+            let excess = last - first - budget;
+            if (excess > 0) {
+                const cutAbove = (want) => {
+                    let k = 0;
+                    while (k < want && (exact || heights.isMeasured(first + k)))
+                        k++;
+                    return k;
+                };
+                const aboveExtra = coreFirst - first;
+                const belowExtra = last - coreLast;
+                if (vel.current.v >= 0) {
+                    const cut = cutAbove(Math.min(aboveExtra, excess));
+                    first += cut;
+                    excess -= cut;
+                    last -= Math.min(belowExtra, excess);
+                }
+                else {
+                    const cut = Math.min(belowExtra, excess);
+                    last -= cut;
+                    excess -= cut;
+                    first += cutAbove(Math.min(aboveExtra, excess));
+                }
+            }
+        }
+        built.current = { first, last };
+    }
+    else {
+        built.current = null;
+    }
+    // The skeleton tier: which of the slice's rows are worth building in full
+    // *this* render. All of them, almost always — a flood is the exception.
+    let skeletons = EMPTY_KEYS;
+    let pending = 0;
+    hasSkeletons.current = false;
+    if (virtualizing) {
+        const prev = real.current;
+        const next = new Set();
+        let entering = 0;
+        for (let i = first; i < last; i++) {
+            if (prev.has(rows[i].id))
+                next.add(rows[i].id);
+            else
+                entering++;
+        }
+        // A window with nothing carried over and no scroll in flight is a mount
+        // or a wholesale data change, not a flood — those build in full, or the
+        // first paint would be skeletons.
+        const flood = entering > threshold && (active.current || next.size > 0);
+        if (!flood) {
+            for (let i = first; i < last; i++)
+                next.add(rows[i].id);
+        }
+        else {
+            // Viewport rows first — they are the ones being looked at — then
+            // outward, up to the budget; the rest are skeletons until the ticks
+            // catch up.
+            let budget = active.current ? burstBudget : settleBudget;
+            const vFirst = heights.indexAt(view.top);
+            const vLast = view.height > 0 ? heights.indexAt(view.top + view.height) : vFirst;
+            const take = (i) => {
+                if (i < first || i >= last || budget <= 0)
+                    return;
+                if (!next.has(rows[i].id)) {
+                    next.add(rows[i].id);
+                    budget--;
+                }
+            };
+            for (let i = vFirst; i <= vLast && i < last; i++)
+                take(i);
+            for (let d = 1; budget > 0 && (vFirst - d >= first || vLast + d < last); d++) {
+                take(vLast + d);
+                take(vFirst - d);
+            }
+            const skel = new Set();
+            for (let i = first; i < last; i++) {
+                if (!next.has(rows[i].id)) {
+                    skel.add(rows[i].id);
+                    if (i >= vFirst && i <= vLast)
+                        pending++;
+                }
+            }
+            skeletons = skel;
+            hasSkeletons.current = skel.size > 0;
+            if (skel.size > 0)
+                wantsGrowth.current = true;
+        }
+        real.current = next;
+    }
+    else if (real.current.size > 0) {
+        real.current = new Set();
+    }
+    // The catch-up clock: started the first render the viewport stops being
+    // whole — placeholders in view, or a scrub outrunning the built rows —
+    // and cleared when the catch-up ends, on the same condition a hint's
+    // latch releases. Renders keep coming while it runs (the skeleton ticks,
+    // the scrub's own events), so a deadline measured against it is
+    // re-evaluated within a tick of passing.
+    if (virtualizing && (pending > 0 || (jumped && active.current))) {
+        catchupStart.current ??= Date.now();
+    }
+    else if (pending === 0 && !active.current) {
+        catchupStart.current = null;
+    }
+    /** Where the slice starts, and how much of the list is below it — the two
+     *  spacers that keep the scrollbar measuring the whole list. */
+    const above = virtualizing ? heights.offsetAt(first) : 0;
+    const below = virtualizing ? heights.total() - heights.offsetAt(last) : 0;
+    return {
+        view,
+        viewRef,
+        slice: { first, last, above, below },
+        skeletons,
+        jumped,
+        catchupSince: catchupStart.current,
+        pending,
+        scrolled,
+        sized,
+        sync,
+        scrolling,
+        fast,
+    };
+}
+//# sourceMappingURL=window.js.map

package/dist/internal/window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.js","sourceRoot":"","sources":["../../src/internal/window.ts"],"names":[],"mappings":"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"}

package/dist/table/index.d.ts

@@ -5,6 +5,28 @@ import type { Host } from './hx.js';
 import type { TableCellState, TableColumn, TableHeaderCellState, TableRow, TableRowId, TableRowState, TableSort } from './rows.js';
 export type { ResolvedWidths, TableCellState, TableColumn, TableHeaderCellState, TableRow, TableRowId, TableRowState, TableSort, } from './rows.js';
 export { MIN_COLUMN, UNSIZED_MIN, columnValue, defaultCompare, orderRows, resolveGetId, resolveWidths, } from './rows.js';
+/**
+ * What `renderScrollHint` is told: where the viewport is, while a fast
+ * scroll is still being caught up with. The top row itself is included so a
+ * hint can show what is *at* this position — a date, a group, a name — the
+ * way a photo library's scrubber shows the month.
+ */
+export interface TableScrollHintState<Row = any> {
+    /** The first row in view, in display order. */
+    row: TableRow<Row>;
+    /** Its position, 1-based — "row `from` of `count`". */
+    from: number;
+    /** The last row in view, 1-based. */
+    to: number;
+    /** How many rows the table has. */
+    count: number;
+    /** How many of the rows in view are still placeholders. */
+    pending: number;
+    /** When the viewport first stopped being whole, epoch ms — what the
+     *  show-delay was measured against. `Date.now() - since` is how long the
+     *  user has been looking at unresolved content. */
+    since: number;
+}
 /** The selection that just changed, alongside the whole set. `id`/`row` name
  *  the row the gesture landed on; a select-all has no single row to name. */
 export interface TableSelectChange<Row> {
@@ -78,14 +100,25 @@ interface TableBaseProps<Row> extends Omit<BoxProps, 'style' | 'children' | 'ref
      */
     rowHeight?: number;
     /** What an unmeasured row is assumed — and floored — at, while measuring.
-     *  Default 24. The scrollbar is this guess for every row not yet seen, and
-     *  it converges as you scroll. */
+     *  Default 24. The scrollbar is this guess for every row not yet seen; it
+     *  converges as you scroll, and once enough rows have been measured the
+     *  guess itself is re-learnt from their mean, so the scrollbar lands near
+     *  the truth without visiting the whole list. */
     estimatedRowHeight?: number;
     /** Build only the rows on screen. `'auto'` (the default) turns it on past
      *  200 rows. */
     virtual?: boolean | 'auto';
     /** Rows built either side of the viewport. */
     overscan?: number;
+    /**
+     * Rows built *beyond* the overscan while the table sits idle, per side.
+     * Default 40. The pane blits a scroll before React can run, so the only
+     * scroll with no blank frame is one that lands on rows already built —
+     * this band is that, grown in small steps while nobody is scrolling, and
+     * kept behind the viewport so a reversal lands on rows still mounted.
+     * `0` turns the band off: the slice is exactly viewport-plus-overscan.
+     */
+    prefetch?: number;
     /**
      * Everything inside the row box, given what would have been there.
      *
@@ -97,6 +130,44 @@ interface TableBaseProps<Row> extends Omit<BoxProps, 'style' | 'children' | 'ref
     /** The body's content when the rows resolve empty. Nothing by default —
      *  the header still shows. */
     renderEmpty?: () => ReactNode;
+    /**
+     * The fast-scroll overlay. Shown only while a scroll has outrun the rows
+     * far enough that placeholders cover a meaningful part of the viewport —
+     * a scroll the table absorbs within a frame never shows it — and hidden
+     * the moment the view is whole again. The default is a pill reading
+     * "2,345 / 100,000"; return something else to replace it (the state
+     * carries the top row, so a hint can show a date or a name instead of a
+     * number), or null for no overlay at all.
+     */
+    renderScrollHint?: (state: TableScrollHintState<Row>) => ReactNode;
+    /**
+     * How long the viewport must have been showing unresolved content before
+     * the overlay appears, in milliseconds. Default 250: a catch-up the next
+     * few frames absorb is never announced. `0` shows it the moment a
+     * catch-up engages.
+     */
+    scrollHintDelay?: number;
+    /**
+     * Tuning for the catch-up pacing — how a scroll that outruns the built
+     * rows is absorbed. All optional, all in rows:
+     *
+     * - `threshold` (default 16): more rows than this entering the window in
+     *   one render is a flood, and floods build skeletons first. Raise it
+     *   past the window size to never show skeletons; `0` skeletons every
+     *   scroll.
+     * - `burst` (default 24): full rows built per render while the scroll is
+     *   still moving.
+     * - `settle` (default 48): the same once it has stopped.
+     *
+     * The defaults follow the measured cost of a default-shape row (about
+     * twice a skeleton, warm); tables with heavy `render` seams may want
+     * smaller budgets, and cheap tables may raise the threshold instead.
+     */
+    catchup?: {
+        threshold?: number;
+        burst?: number;
+        settle?: number;
+    };
     styles?: TableStyles<Row>;
     style?: StyleProp;
     /** Whether the table is a tab stop. Default true; `false` for a table

package/dist/table/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/table/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/table/index.ts"],"names":[],"mappings":"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"}