@react-x11/components 0.2.0 → 0.3.0

package/dist/table/index.js

@@ -36,7 +36,9 @@ import { hx } from './hx.js';
 // Shared with <Tree> — 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 { afterLayout, cancelAfterLayout, cancelLater, later, } from '../internal/timers.js';
+import { useReveal } from '../internal/scroll.js';
+import { BURST_BUDGET, DEFAULT_OVERSCAN, DEFAULT_PREFETCH, SCROLL_HINT_DELAY_MS, SKELETON_THRESHOLD, SETTLE_BUDGET, useVirtualWindow, } from '../internal/window.js';
 import { MIN_COLUMN, columnValue, orderRows, resolveGetId, resolveWidths, } from './rows.js';
 export { MIN_COLUMN, UNSIZED_MIN, columnValue, defaultCompare, orderRows, resolveGetId, resolveWidths, } from './rows.js';
 /** The header strip's height. Core's number — independent of the body's
@@ -54,16 +56,6 @@ const HALF = 3;
 const GRIP = HALF + RULE + HALF;
 /** What one Left/Right on a focused grip is worth. */
 const STEP = 16;
-/** 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.
  *
@@ -124,6 +116,37 @@ const s = createStyles({
     },
     cellText: { fontSize: 12, textWrap: 'nowrap', textBoxTrim: 'cap-alphabetic' },
     spacer: { flexShrink: 0 },
+    /** The bar inside a skeleton row — a line of "text" with no text, so a
+     *  band of placeholders reads as rows arriving rather than a void. */
+    skeletonBar: {
+        height: 8,
+        borderRadius: 4,
+        marginStart: 8,
+        alignSelf: 'center',
+        flexShrink: 0,
+    },
+    /** The lane the fast-scroll pill floats in: absolute against the table's
+     *  root so the body pane scrolls under it, full-width so the pill centres
+     *  itself, and transparent to the pointer so the rows beneath stay
+     *  clickable. */
+    scrollHintLane: {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: 12,
+        flexDirection: 'row',
+        justifyContent: 'center',
+        pointerEvents: 'none',
+    },
+    scrollHint: {
+        paddingStart: 10,
+        paddingEnd: 10,
+        paddingTop: 5,
+        paddingBottom: 5,
+        borderRadius: 12,
+        flexDirection: 'row',
+        alignItems: 'center',
+    },
     sortMark: { marginStart: 4 },
     empty: {
         flexGrow: 1,
@@ -133,6 +156,97 @@ const s = createStyles({
     },
 });
 const EMPTY_SET = new Set();
+function TableRowView(props) {
+    const { entry, columns, widths, setSize, isSelected, selectable, uniform, rowHeight, estimate, theme, rowStyle, cellStyle, renderRow, hasMenu, onTap, onOpen, onMenu, register, } = props;
+    const color = isSelected ? theme.hoverText : theme.text;
+    const state = { ...entry, selected: isSelected, color };
+    const content = columns.map((column, at) => {
+        const cellState = { ...state, column };
+        return hx('box', {
+            key: column.id,
+            role: 'cell',
+            style: [
+                s.cell,
+                { width: widths[at] },
+                uniform && { height: rowHeight },
+                column.align === 'end' && {
+                    alignItems: 'flex-end',
+                    paddingEnd: 8,
+                },
+                column.align === 'center' && { alignItems: 'center' },
+                typeof cellStyle === 'function' ? cellStyle(cellState) : cellStyle,
+            ],
+        }, column.render
+            ? // A cell that draws itself still has to know it is on the
+                // selected row — see the doc comment. Keyed by the component,
+                // the way every seam's return is.
+                React.createElement(React.Fragment, { key: 'content' }, column.render(entry.row, cellState))
+            : hx('text', { style: [s.cellText, { color }] }, String(columnValue(entry.row, column) ?? '')));
+    });
+    return hx('box', {
+        role: 'row',
+        'aria-selected': selectable ? isSelected : undefined,
+        'aria-posinset': entry.index + 1,
+        'aria-setsize': setSize,
+        // The index the row was drawn at travels with the node, so measuring
+        // does not have to search the row list for it. 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) => {
+            register(entry.id, entry.index, node);
+        },
+        onClick: (ev) => {
+            // A right-click also arrives here as a click; the selection it
+            // implies is `onContextMenu`'s to make (select-unless-selected),
+            // not the left button's replace.
+            if (ev.button !== 1)
+                return;
+            onTap(entry, { ctrl: ev.ctrlKey, shift: ev.shiftKey });
+            // 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)
+                onOpen(entry);
+        },
+        onContextMenu: hasMenu
+            ? (ev) => {
+                onMenu(entry, ev);
+            }
+            : undefined,
+        style: [
+            s.row,
+            // Declared uniform: exactly this tall, content clipped — core's
+            // row. Measured: a floor, and the row grows to whatever its
+            // content needs; the height index reads back what it became.
+            uniform
+                ? { height: rowHeight, alignItems: 'center' }
+                : { minHeight: estimate },
+            selectable && { cursor: 'pointer' },
+            {
+                backgroundColor: isSelected ? theme.hoverBackground : 'transparent',
+                // The row's ink, said once: `color` inherits, so default cells
+                // take it without being handed it.
+                color,
+            },
+            selectable && {
+                // pressed even on the selected row: a re-press on the row that
+                // is already current is the one click in the table that would
+                // otherwise look ignored
+                ':active': {
+                    backgroundColor: isSelected
+                        ? theme.accentActive
+                        : theme.surfaceActive,
+                },
+            },
+            selectable &&
+                !isSelected && {
+                ':hover': { backgroundColor: theme.surfaceHover },
+            },
+            typeof rowStyle === 'function' ? rowStyle(state) : rowStyle,
+        ],
+    }, renderRow ? renderRow(state, content) : content);
+}
+const MemoTableRow = React.memo(TableRowView);
 /**
  * `<Table columns rows />` — a data table with a header that stays put.
  *
@@ -165,7 +279,7 @@ const EMPTY_SET = new Set();
  * the same rows a sighted user can see.
  */
 export function Table(props) {
-    const { columns = [], rows = [], getId, sort, defaultSort, onSortChange, presorted = false, onActivate, onRowContextMenu, onColumnResize, rowHeight, estimatedRowHeight, virtual = 'auto', overscan = OVERSCAN, renderRow, renderEmpty, styles, style, focusable = true, ref, selectionMode = 'single', selected, defaultSelected, onSelect, onSelectedChange, 
+    const { columns = [], rows = [], getId, sort, defaultSort, onSortChange, presorted = false, onActivate, onRowContextMenu, onColumnResize, rowHeight, estimatedRowHeight, virtual = 'auto', overscan = DEFAULT_OVERSCAN, prefetch = DEFAULT_PREFETCH, renderRow, renderEmpty, renderScrollHint, scrollHintDelay = SCROLL_HINT_DELAY_MS, catchup, styles, style, focusable = true, ref, selectionMode = 'single', selected, defaultSelected, onSelect, onSelectedChange, 
     // ours to chain rather than to hand over: virtualization and the sticky
     // header are measured through both of these
     onScroll, onViewport, ...boxProps } = props;
@@ -198,7 +312,6 @@ export function Table(props) {
     const [cursorId, setCursorId] = useState(null);
     const [userWidths, setUserWidths] = useState({});
     const [scrollX, setScrollX] = useState(0);
-    const [view, setView] = useState({ top: 0, height: 0, width: 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
@@ -234,8 +347,6 @@ export function Table(props) {
     selectedRef.current = selectedIds;
     const cursorRef = useRef(cursor);
     cursorRef.current = cursor;
-    const viewRef = useRef(view);
-    viewRef.current = view;
     /** Where a Shift range grows from — the last plain click or plain step. */
     const anchorRef = useRef(null);
     const root = useRef(null);
@@ -244,6 +355,9 @@ export function Table(props) {
      *  measurement pass does not have to search the row list for it. */
     const rowNodes = useRef(new Map());
     const drag = useRef(null);
+    /** Whether the fast-scroll pill is up — kept across renders so it does not
+     *  flicker through a catch-up, only appearing and disappearing once. */
+    const hintShown = useRef(false);
     const userWidthsRef = useRef(userWidths);
     userWidthsRef.current = userWidths;
     /** Declared uniform: divide, never measure — core's model. */
@@ -259,26 +373,54 @@ export function Table(props) {
     heights.sync(ordered, estimate);
     const virtualizing = virtual === true ||
         (virtual === 'auto' && ordered.length > VIRTUAL_THRESHOLD);
-    // The slice worth building: what is on screen, plus a little either side.
-    const first = virtualizing
-        ? Math.max(0, heights.indexAt(view.top) - overscan)
-        : 0;
-    let last = ordered.length;
-    if (virtualizing) {
-        if (view.height > 0) {
-            last = Math.min(ordered.length, heights.indexAt(view.top + view.height) + 1 + overscan);
-        }
-        else {
-            last = Math.min(ordered.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 table. */
-    const above = virtualizing ? heights.offsetAt(first) : 0;
-    const below = virtualizing ? heights.total() - heights.offsetAt(last) : 0;
+    /** The viewport, and the slice worth building from it — the machinery
+     *  shared with `<Tree>` (`../internal/window.ts`). */
+    const win = useVirtualWindow({
+        box: body,
+        heights,
+        rows: ordered,
+        // declared uniform: every height is exact, so the idle band may grow
+        // upward freely — see `exact` on the inputs
+        exact: uniform,
+        virtualizing,
+        overscan,
+        prefetch,
+        threshold: catchup?.threshold ?? SKELETON_THRESHOLD,
+        burstBudget: catchup?.burst ?? BURST_BUDGET,
+        settleBudget: catchup?.settle ?? SETTLE_BUDGET,
+    });
+    const { view, viewRef } = win;
+    const { first, last, above, below } = win.slice;
     /** Columns resolve to pixels once, at the table level, per (columns,
      *  viewport, resizes) — every row agrees on the grid by construction. */
     const { widths, total } = useMemo(() => resolveWidths(columns, userWidths, view.width), [columns, userWidths, view.width]);
+    /**
+     * The scroll the table 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.
+     */
+    const reveal = useReveal({
+        box: body,
+        rows: orderedRef,
+        nodes: rowNodes,
+        heights,
+    });
+    /**
+     * Re-read the offset the body is *actually* at — the window's `sync` (see
+     * `../internal/window.ts` for why the pane moves silently), plus the
+     * horizontal half only this component has: the header is shifted by
+     * `scrollX`, so the sideways offset is re-read on the same tick.
+     */
+    const winSync = win.sync;
+    const syncScroll = useCallback(() => {
+        const box = body.current;
+        if (!box)
+            return;
+        const x = box.scrollX;
+        setScrollX((prev) => (prev === x ? prev : x));
+        winSync();
+    }, [winSync]);
     /**
      * Read back what the rows on screen actually laid out at.
      *
@@ -291,12 +433,12 @@ export function Table(props) {
      */
     const measureRows = useCallback(() => {
         if (uniform || !virtualizing)
-            return;
+            return false;
         // Before the first `onViewport` the flex columns sit on their floors and
         // every row is laid out against a width that is about to change — there
         // is nothing honest to measure yet.
         if (viewRef.current.width <= 0)
-            return;
+            return false;
         // A row laid out at a width the columns no longer resolve to is a
         // measurement of the wrong table, and it must not be recorded — a row
         // that scrolls out before the corrected pass would keep a wrong-width
@@ -325,46 +467,100 @@ export function Table(props) {
                 shift += height - was;
         }
         if (!changed)
-            return;
-        if (shift !== 0 && box) {
-            box.scrollTo({ y: Math.max(0, box.scrollY + shift) });
-        }
+            return false;
+        // A debt, not a one-shot: the pane clamps against the last layout's
+        // content height, so a shift from rows measured above the viewport can
+        // land short until the layout that admits the growth has run.
+        reveal.nudge(shift);
         setMeasured((n) => n + 1);
+        return true;
         // eslint-disable-next-line react-hooks/exhaustive-deps -- `heights` is a
         // stable instance
     }, [uniform, virtualizing]);
-    useEffect(() => {
-        if (uniform || !virtualizing)
-            return undefined;
-        const id = afterLayout(measureRows);
-        return () => cancelAfterLayout(id);
-    });
     /**
-     * Put a row in view. A mounted row can say where it is, and
-     * `scrollIntoView` then works whatever height it turned out to be; a row
-     * that is not mounted has no geometry to ask, so the height index answers
-     * instead.
+     * Let the estimate learn from the rows that have been measured — the
+     * scrollbar of a measured table starts as a guess times the row count,
+     * and the measured mean is a far better guess for the rows not yet seen.
+     * Idle only: every unmeasured offset moves when it applies, and the
+     * anchor arithmetic keeping the screen still is `measureRows`'s.
      */
-    const reveal = useCallback((at) => {
+    const adaptEstimate = useCallback(() => {
+        if (uniform || !virtualizing)
+            return false;
         const box = body.current;
-        const row = orderedRef.current[at];
-        if (!box || !row)
-            return;
-        const drawn = rowNodes.current.get(row.id);
-        if (drawn) {
-            box.scrollIntoView(drawn.node);
-            return;
-        }
-        const top = heights.offsetAt(at);
-        const rowH = heights.heightAt(at);
-        const height = viewRef.current.height;
-        if (top < box.scrollY)
-            box.scrollTo({ y: top });
-        else if (height > 0 && top + rowH > box.scrollY + height) {
-            box.scrollTo({ y: top + rowH - height });
+        if (!box)
+            return false;
+        const anchor = heights.indexAt(box.scrollY);
+        const before = heights.offsetAt(anchor);
+        if (!heights.adapt())
+            return false;
+        reveal.nudge(heights.offsetAt(anchor) - before);
+        setMeasured((n) => n + 1);
+        return true;
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `heights` and
+        // `reveal` are stable instances
+    }, [uniform, 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 new rows are laid out, and where the body actually ended up. In that
+     * order — each step can move the offset the next one reads.
+     *
+     * Scheduled for every render a virtualized table makes, because every one
+     * of them can move the offset its next slice is built from. A whole table
+     * needs none of it: `onViewport` is when its content can have been
+     * re-clamped, and it rebuilds no slice anyway.
+     */
+    /** Whether some drawn row has no size yet — a commit can land between
+     *  frame flushes, and a measure pass over it reads zeros. */
+    const rowsPendingLayout = useCallback(() => {
+        if (uniform)
+            return false;
+        const rows = orderedRef.current;
+        for (const [id, { node, at }] of rowNodes.current) {
+            if (rows[at]?.id === id && !(node.abs.height > 0))
+                return true;
         }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
+        return false;
+    }, [uniform]);
+    useEffect(() => {
+        if (!virtualizing)
+            return undefined;
+        let look = null;
+        let tries = 0;
+        const pass = () => {
+            // `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. During a
+            // flick nothing is measured at all — every correction at that speed is
+            // invalidated by the next event — and the settle tick that follows any
+            // burst is where the deferred passes catch up.
+            const moved = win.fast() ? false : measureRows();
+            const adapted = !win.scrolling() && adaptEstimate();
+            reveal.retry(moved || adapted);
+            syncScroll();
+            // A commit can land between frame flushes: its rows report zero size
+            // until the flush, this tick has already run, and nothing else would
+            // come back for them — a window that just finished growing renders
+            // nothing further, and the missed measurements would stand for good.
+            // Look again, briefly, while any drawn row is still unsized.
+            if (rowsPendingLayout() && tries++ < 8)
+                look = later(pass, 16);
+        };
+        const id = afterLayout(pass);
+        return () => {
+            cancelAfterLayout(id);
+            cancelLater(look);
+        };
+    });
+    /** Put a row in view, by the index its call site already has. */
+    const revealAt = useCallback((at) => {
+        const row = orderedRef.current[at];
+        if (row)
+            reveal.to(row.id);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `reveal` is a
+        // stable handle
+    }, [reveal]);
     const commitSingle = useCallback((row) => {
         cursorRef.current = row.id;
         if (selected === undefined)
@@ -389,7 +585,7 @@ export function Table(props) {
             return;
         if (selectionMode === 'single') {
             commitSingle(row);
-            reveal(row.index);
+            revealAt(row.index);
             return;
         }
         cursorRef.current = row.id;
@@ -417,8 +613,8 @@ export function Table(props) {
             anchorRef.current = row.id;
             commitMulti([row.id], { type: 'replace', id: row.id, row: row.row });
         }
-        reveal(row.index);
-    }, [selectionMode, commitSingle, commitMulti, reveal]);
+        revealAt(row.index);
+    }, [selectionMode, commitSingle, commitMulti, revealAt]);
     const activate = useCallback((row) => {
         onActivate?.(row.id, row.row);
     }, [onActivate]);
@@ -573,120 +769,79 @@ export function Table(props) {
             const row = orderedRef.current.find((r) => r.id === id);
             if (!row)
                 return false;
-            reveal(row.index);
+            revealAt(row.index);
             return true;
         },
         handleKey,
         rows: () => orderedRef.current,
-    }), [tap, handleKey, reveal, selectionMode, selected]);
+    }), [tap, handleKey, revealAt, selectionMode, selected]);
     // --- rendering -----------------------------------------------------------
     const rowStyleProp = styles?.row;
     const cellStyleProp = styles?.cell;
     const headerCellStyleProp = styles?.headerCell;
     const selectable = selectionMode !== 'none';
-    const renderOneRow = (entry) => {
+    // The row component's stable halves — `MemoTableRow` bails out of a
+    // re-render only if every prop kept its identity, and these are the two
+    // that would otherwise be rebuilt per row per render.
+    const registerRow = useCallback((id, at, node) => {
+        if (node)
+            rowNodes.current.set(id, { node, at });
+        else
+            rowNodes.current.delete(id);
+    }, []);
+    const rowMenu = useCallback((entry, ev) => {
+        // The menu applies to what is under the pointer, so the row is
+        // selected first — unless it is already part of the selection,
+        // which a menu over "the selected files" must not collapse.
+        if (selectable && !selectedRef.current.has(entry.id)) {
+            tap(entry, { ctrl: false, shift: false });
+        }
+        onRowContextMenu?.(entry.id, entry.row, ev);
+    }, [selectable, tap, onRowContextMenu]);
+    /**
+     * A row the window said not to build in full yet: the box at its indexed
+     * height and none of its content. Cheap on purpose — no cells, no text, no
+     * seams — so the commit answering a flood lands frames before the full
+     * rows could, and what blits in reads as rows arriving rather than a
+     * void. `styles.row` still applies, so zebra striping and row backgrounds
+     * hold. Not registered in `rowNodes`: a skeleton must not be measured
+     * into the height index, and cannot satisfy a reveal.
+     */
+    const renderSkeletonRow = (entry) => {
         const isSelected = selectedIds.has(entry.id);
-        const color = isSelected ? theme.hoverText : theme.text;
-        const state = { ...entry, selected: isSelected, color };
-        const content = columns.map((column, at) => {
-            const cellState = { ...state, column };
-            return hx('box', {
-                key: column.id,
-                role: 'cell',
-                style: [
-                    s.cell,
-                    { width: widths[at] },
-                    uniform && { height: rowHeight },
-                    column.align === 'end' && {
-                        alignItems: 'flex-end',
-                        paddingEnd: 8,
-                    },
-                    column.align === 'center' && { alignItems: 'center' },
-                    typeof cellStyleProp === 'function'
-                        ? cellStyleProp(cellState)
-                        : cellStyleProp,
-                ],
-            }, column.render
-                ? // A cell that draws itself still has to know it is on the
-                    // selected row — see the doc comment. Keyed by the component,
-                    // the way every seam's return is.
-                    React.createElement(React.Fragment, { key: 'content' }, column.render(entry.row, cellState))
-                : hx('text', { style: [s.cellText, { color }] }, String(columnValue(entry.row, column) ?? '')));
-        });
+        const state = {
+            ...entry,
+            selected: isSelected,
+            color: isSelected ? theme.hoverText : theme.text,
+        };
         return hx('box', {
             key: String(entry.id),
-            role: 'row',
-            'aria-selected': selectable ? isSelected : undefined,
-            'aria-posinset': entry.index + 1,
-            'aria-setsize': ordered.length,
-            // The index the row was drawn at travels with the node, so measuring
-            // does not have to search the row list for it. 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(entry.id, { node, at: entry.index });
-                else
-                    rowNodes.current.delete(entry.id);
-            },
-            onClick: (ev) => {
-                // A right-click also arrives here as a click; the selection it
-                // implies is `onContextMenu`'s to make (select-unless-selected),
-                // not the left button's replace.
-                if (ev.button !== 1)
-                    return;
-                tap(entry, { ctrl: ev.ctrlKey, shift: ev.shiftKey });
-                // 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(entry);
-            },
-            onContextMenu: onRowContextMenu
-                ? (ev) => {
-                    // The menu applies to what is under the pointer, so the row is
-                    // selected first — unless it is already part of the selection,
-                    // which a menu over "the selected files" must not collapse.
-                    if (selectable && !selectedRef.current.has(entry.id)) {
-                        tap(entry, { ctrl: false, shift: false });
-                    }
-                    onRowContextMenu(entry.id, entry.row, ev);
-                }
-                : undefined,
+            'aria-hidden': true,
             style: [
                 s.row,
-                // Declared uniform: exactly this tall, content clipped — core's
-                // row. Measured: a floor, and the row grows to whatever its
-                // content needs; the height index reads back what it became.
-                uniform
-                    ? { height: rowHeight, alignItems: 'center' }
-                    : { minHeight: estimate },
-                selectable && { cursor: 'pointer' },
+                // Exactly what the index believes, so the spacers and the
+                // scrollbar agree with the rows on where everything is.
+                { height: heights.heightAt(entry.index) },
                 {
                     backgroundColor: isSelected ? theme.hoverBackground : 'transparent',
-                    // The row's ink, said once: `color` inherits, so default cells
-                    // take it without being handed it.
-                    color,
-                },
-                selectable && {
-                    // pressed even on the selected row: a re-press on the row that
-                    // is already current is the one click in the table that would
-                    // otherwise look ignored
-                    ':active': {
-                        backgroundColor: isSelected
-                            ? theme.accentActive
-                            : theme.surfaceActive,
-                    },
-                },
-                selectable &&
-                    !isSelected && {
-                    ':hover': { backgroundColor: theme.surfaceHover },
                 },
                 typeof rowStyleProp === 'function'
                     ? rowStyleProp(state)
                     : rowStyleProp,
             ],
-        }, renderRow ? renderRow(state, content) : content);
+        }, 
+        // A line of "text" with no text. Width varied by index, so a band of
+        // placeholders reads as rows arriving rather than a repeated tile.
+        hx('box', {
+            key: 'bar',
+            style: [
+                s.skeletonBar,
+                {
+                    width: 96 + ((entry.index * 37) % 89),
+                    backgroundColor: theme.track,
+                },
+            ],
+        }));
     };
     const headerCells = columns.map((column, at) => {
         const canSort = column.sortable !== false;
@@ -759,6 +914,73 @@ export function Table(props) {
             ],
         }, hx('box', { style: [s.rule, { backgroundColor: theme.border }] })));
     });
+    /**
+     * The row *elements*, reused by identity while nothing they depend on has
+     * changed. The memo already skips re-rendering an unchanged row, but the
+     * skip still costs a `createElement` and a props compare per row per
+     * notch — the burst profile put bare `createElement` at a tenth of a
+     * flick's CPU. Handing React the identical element object instead takes
+     * the cheapest path it has: the fiber is reused with no compare at all.
+     * The cache empties whenever any shared input changes identity, and
+     * per-row entries revalidate on the row object and its selection.
+     */
+    const rowElems = useRef(new Map());
+    const rowElemDeps = useRef([]);
+    {
+        const deps = [
+            columns,
+            widths,
+            theme,
+            uniform,
+            rowHeight,
+            estimate,
+            selectable,
+            rowStyleProp,
+            cellStyleProp,
+            renderRow,
+            Boolean(onRowContextMenu),
+            tap,
+            activate,
+            rowMenu,
+            registerRow,
+            ordered.length,
+        ];
+        const prev = rowElemDeps.current;
+        if (prev.length !== deps.length || deps.some((d, at) => d !== prev[at])) {
+            rowElems.current.clear();
+            rowElemDeps.current = deps;
+        }
+    }
+    const rowElement = (entry) => {
+        const isSelected = selectedIds.has(entry.id);
+        const cached = rowElems.current.get(entry.id);
+        if (cached && cached.entry === entry && cached.selected === isSelected) {
+            return cached.el;
+        }
+        const el = React.createElement(MemoTableRow, {
+            key: String(entry.id),
+            entry,
+            columns,
+            widths,
+            setSize: ordered.length,
+            isSelected,
+            selectable,
+            uniform,
+            rowHeight,
+            estimate,
+            theme,
+            rowStyle: rowStyleProp,
+            cellStyle: cellStyleProp,
+            renderRow,
+            hasMenu: Boolean(onRowContextMenu),
+            onTap: tap,
+            onOpen: activate,
+            onMenu: rowMenu,
+            register: registerRow,
+        });
+        rowElems.current.set(entry.id, { entry, selected: isSelected, el });
+        return el;
+    };
     const bodyChildren = [];
     if (ordered.length === 0) {
         if (renderEmpty) {
@@ -772,14 +994,81 @@ export function Table(props) {
                 style: [s.spacer, { height: above }],
             }));
         }
-        for (let i = first; i < last; i++)
-            bodyChildren.push(renderOneRow(ordered[i]));
+        for (let i = first; i < last; i++) {
+            const entry = ordered[i];
+            bodyChildren.push(win.skeletons.has(entry.id)
+                ? renderSkeletonRow(entry)
+                : rowElement(entry));
+        }
         if (virtualizing && last < ordered.length) {
             bodyChildren.push(hx('box', {
                 key: 'spacer:after',
                 style: [s.spacer, { height: below }],
             }));
         }
+        // Rows that left the window leave the cache too, once it has grown
+        // well past the window — a scrub across a long list would otherwise
+        // hold an element for every row it passed.
+        if (rowElems.current.size > (last - first) * 3 + 64) {
+            rowElems.current.clear();
+        }
+    }
+    /**
+     * The fast-scroll overlay — shown only while placeholders cover enough of
+     * the viewport that the user would otherwise be looking at blank rows.
+     * The half-viewport threshold keeps a near-miss quiet: a scroll the next
+     * frame will absorb is not worth announcing. Once up it stays until the
+     * view is whole again, so it does not flicker through the catch-up.
+     */
+    let scrollHint = null;
+    if (virtualizing && ordered.length > 0 && view.height > 0) {
+        const vFirst = heights.indexAt(view.top);
+        const vLast = Math.min(ordered.length - 1, heights.indexAt(view.top + view.height));
+        // Two ways in: placeholders covering enough of the viewport that it
+        // would otherwise read as blank, or a scrub — the window teleporting
+        // while the burst is still in flight, where every commit chases a
+        // viewport that has already left and nothing useful can be on screen.
+        // Either way only once the catch-up has already *lasted*: a jump the
+        // next few frames absorb is not worth announcing, so the pill waits
+        // out the show-delay against the catch-up clock. Latched once
+        // triggered: `pending` bounces to zero between catch-up commits, and a
+        // pill that blinked with it would read as a glitch. It goes when the
+        // burst does.
+        const engaged = (win.pending > 0 && win.pending * 2 >= vLast - vFirst + 1) ||
+            (win.jumped && win.scrolling());
+        const lasted = win.catchupSince !== null &&
+            Date.now() - win.catchupSince >= scrollHintDelay;
+        const show = (engaged && lasted) ||
+            (hintShown.current && (win.pending > 0 || win.scrolling()));
+        hintShown.current = show;
+        if (show) {
+            const hintState = {
+                row: ordered[vFirst],
+                from: vFirst + 1,
+                to: vLast + 1,
+                count: ordered.length,
+                pending: win.pending,
+                since: win.catchupSince ?? Date.now(),
+            };
+            const content = renderScrollHint
+                ? renderScrollHint(hintState)
+                : hx('text', { style: { fontSize: 11, color: theme.hoverText } }, `${hintState.from.toLocaleString()} / ${hintState.count.toLocaleString()}`);
+            if (content !== null && content !== undefined && content !== false) {
+                scrollHint = hx('box', {
+                    key: 'scroll-hint',
+                    // The pill duplicates what the scrollbar already tells an
+                    // assistive technology, and it comes and goes with the catch-up
+                    // — chatter, not content.
+                    'aria-hidden': true,
+                    style: s.scrollHintLane,
+                }, hx('box', {
+                    style: [s.scrollHint, { backgroundColor: theme.hoverBackground }],
+                }, content));
+            }
+        }
+    }
+    else {
+        hintShown.current = false;
     }
     return hx('box', {
         theme,
@@ -816,10 +1105,12 @@ export function Table(props) {
         ref: body,
         style: s.body,
         onScroll: (ev) => {
+            // A scroll this component did not ask for is the user taking over,
+            // and an owed `scrollToRow` must not yank the list back out from
+            // under them on the next layout.
+            reveal.heard(ev.scrollY);
             setScrollX((prev) => (prev === ev.scrollX ? prev : ev.scrollX));
-            if (virtualizing) {
-                setView((prev) => prev.top === ev.scrollY ? prev : { ...prev, top: ev.scrollY });
-            }
+            win.scrolled(ev.scrollY);
             onScroll?.(ev);
         },
         // Layout, not scrolling, is what first tells a table how much of it
@@ -827,18 +1118,17 @@ export function Table(props) {
         // columns resolve against, so this is measured whether or not the
         // table virtualizes.
         onViewport: (ev) => {
-            // The ref first, at event time: the measure tick runs before the
-            // re-render this setState causes, and it must see this viewport.
-            viewRef.current = {
-                ...viewRef.current,
-                height: ev.height,
-                width: ev.width,
-            };
-            setView((prev) => prev.height === ev.height && prev.width === ev.width
-                ? prev
-                : { ...prev, height: ev.height, width: ev.width });
+            win.sized(ev.width, 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
+            // container may have re-clamped the offset without saying so. It is
+            // not a moment anything can be *settled* in while rows are still
+            // being measured: this runs from layout, a tick before the pass that
+            // reads those rows back.
+            reveal.retry(virtualizing && !uniform);
+            syncScroll();
             onViewport?.(ev);
         },
-    }, hx('box', { style: [s.rowsBox, { width: total }] }, bodyChildren)));
+    }, hx('box', { style: [s.rowsBox, { width: total }] }, bodyChildren)), scrollHint);
 }
 //# sourceMappingURL=index.js.map