xonecas.io
70160
Ce

cel-tui / files

cel-tui / packages / components / src / virtual-list.ts

27.9 KB
1import { cel, measureContentHeight, VStack } from "@cel-tui/core";
2import type {
3  ContainerNode,
4  ContainerProps,
5  Node,
6  StateKey,
7} from "@cel-tui/types";
8
9/** Why a {@link VirtualListScrollHandler} was invoked. */
10export type VirtualListScrollReason = "input" | "anchor";
11
12/**
13 * Scroll changes requested by a {@link VirtualList}.
14 *
15 * Returning exactly `false` for an `"input"` event lets the wheel event
16 * continue to a scrollable ancestor. Anchor notifications are informational:
17 * the list has already compensated its viewport to keep the same row stable.
18 */
19export type VirtualListScrollHandler =
20  | ((
21      offset: number,
22      maxOffset: number,
23      reason: VirtualListScrollReason,
24    ) => void)
25  | ((
26      offset: number,
27      maxOffset: number,
28      reason: VirtualListScrollReason,
29    ) => boolean);
30
31/** Construction options for a callable {@link VirtualListInstance}. */
32export interface VirtualListOptions<T> {
33  /** Return an identity unique within this list's current items. */
34  itemKey: (item: T, index: number) => StateKey;
35  /**
36   * Build an item's node tree. Only the active window is rendered. Rows should
37   * have intrinsic or fixed height rather than viewport-relative main sizing.
38   */
39  renderItem: (item: T, index: number) => Node;
40  /**
41   * Estimated row height used until a row has been measured.
42   * Must resolve to a positive integer cell count.
43   * @default 1
44   */
45  estimatedItemHeight?:
46    number | ((item: T, index: number, width: number) => number);
47  /**
48   * Version used to invalidate a keyed row's measured height.
49   * Defaults to the item value/reference. Supply this for mutable items.
50   */
51  itemVersion?: (item: T, index: number) => unknown;
52  /** Vertical gap between rows, in cells. @default 0 */
53  gap?: number;
54  /** Extra cells rendered before and after the viewport. @default 4 */
55  overscan?: number;
56  /** Maximum retained measured-height entries. @default 2048 */
57  maxCachedItems?: number;
58  /**
59   * Hard cap on rows in the returned node tree. This prevents degenerate
60   * zero-height content or extreme overscan from defeating virtualization.
61   * @default 512
62   */
63  maxRenderedItems?: number;
64  /** Initial offset for uncontrolled scrolling. @default 0 */
65  defaultScrollOffset?: number;
66  /** Start an uncontrolled list pinned to its end. @default false */
67  defaultStickToBottom?: boolean;
68}
69
70type ForwardedContainerProps = Pick<
71  ContainerProps,
72  | "stateKey"
73  | "scrollbar"
74  | "scrollbarStyle"
75  | "scrollStep"
76  | "onClick"
77  | "focusable"
78  | "focused"
79  | "autoFocus"
80  | "onFocus"
81  | "onBlur"
82  | "focusStyle"
83  | "onKeyPress"
84  | "bold"
85  | "italic"
86  | "underline"
87  | "fgColor"
88  | "bgColor"
89>;
90
91/** Props supplied whenever a {@link VirtualListInstance} is rendered. */
92export type VirtualListProps<T> = ForwardedContainerProps & {
93  /** Current ordered collection. Keys must be unique within this list. */
94  items: readonly T[];
95  /** Exact viewport width in terminal cells, used for row measurement. */
96  width: number;
97  /** Exact viewport height in terminal cells. */
98  height: number;
99  /** Override the instance's vertical row gap. */
100  gap?: number;
101  /** Override the instance's overscan, measured in cells. */
102  overscan?: number;
103  /** Controlled scroll offset. Omit for instance-managed scrolling. */
104  scrollOffset?: number;
105  /**
106   * Controlled sticky-bottom state. Omit to use the instance-managed state.
107   * While true, appends and height changes remain pinned to the end.
108   */
109  stickToBottom?: boolean;
110  /** Called when wheel input or anchor compensation changes the offset. */
111  onScroll?: VirtualListScrollHandler;
112  /** Called when wheel input changes whether the viewport is at the end. */
113  onStickToBottomChange?: (stuck: boolean) => void;
114};
115
116/** Observable snapshot of a {@link VirtualListInstance}. */
117export interface VirtualListState {
118  /** Effective cell offset used by the most recent render. */
119  scrollOffset: number;
120  /** Maximum offset in the most recent render. */
121  maxScrollOffset: number;
122  /** Total estimated/measured content height, including row gaps. */
123  totalHeight: number;
124  /** Whether the most recent render was pinned to the bottom. */
125  stickToBottom: boolean;
126  /** Inclusive first rendered item index. */
127  visibleStart: number;
128  /** Exclusive final rendered item index. */
129  visibleEnd: number;
130  /** Number of item nodes present in the most recent returned tree. */
131  renderedItems: number;
132  /** Number of rows measured during the most recent render call. */
133  measuredItems: number;
134  /** Number of retained height-cache entries. */
135  cachedItems: number;
136  /** First viewport anchor key, when the list is non-empty. */
137  anchorKey?: StateKey;
138}
139
140/** A callable variable-height virtual list with an explicit cache lifecycle. */
141export interface VirtualListInstance<T> {
142  /** Build the current virtualized node tree. Call inside `cel.viewport()`. */
143  (props: VirtualListProps<T>): ContainerNode;
144  /** Reset state to defaults and request a render. */
145  reset(): void;
146  /** Clear all retained state eagerly. The callable may be reused afterward. */
147  dispose(): void;
148  /** Invalidate one measured row (or all rows) and request a render. */
149  invalidate(key?: StateKey): void;
150  /** Set an uncontrolled offset, leave sticky mode, and request a render. */
151  scrollTo(offset: number): void;
152  /** Pin uncontrolled renders to the current end and request a render. */
153  scrollToEnd(): void;
154  /** Inspect the last committed render state. */
155  getState(): Readonly<VirtualListState>;
156}
157
158interface HeightEntry {
159  height: number;
160  revision: unknown;
161  width: number;
162}
163
164interface Metrics {
165  starts: number[];
166  ends: number[];
167  totalHeight: number;
168}
169
170interface WindowRange {
171  start: number;
172  end: number;
173}
174
175interface PreviousFrame {
176  keys: StateKey[];
177  revisions: unknown[];
178  starts: number[];
179  offset: number;
180  sourceOffset: number;
181  controlled: boolean;
182  anchorIndex: number;
183}
184
185const DEFAULT_OVERSCAN = 4;
186const DEFAULT_CACHE_LIMIT = 2_048;
187const DEFAULT_RENDER_LIMIT = 512;
188const MAX_MEASUREMENT_PASSES = 3;
189
190function assertNonNegativeInteger(value: number, name: string): void {
191  if (!Number.isSafeInteger(value) || value < 0) {
192    throw new RangeError(`${name} must be a non-negative safe integer`);
193  }
194}
195
196function assertPositiveInteger(value: number, name: string): void {
197  if (!Number.isSafeInteger(value) || value <= 0) {
198    throw new RangeError(`${name} must be a positive safe integer`);
199  }
200}
201
202function normalizeOffset(value: number, name: string): number {
203  if (value === Infinity) return value;
204  if (!Number.isFinite(value)) {
205    throw new RangeError(`${name} must be a finite number or Infinity`);
206  }
207  return Math.max(0, value);
208}
209
210function clampOffset(value: number, maxOffset: number): number {
211  return value === Infinity
212    ? maxOffset
213    : Math.min(Math.max(0, value), maxOffset);
214}
215
216function formatKey(key: StateKey): string {
217  return `${typeof key} ${JSON.stringify(key)}`;
218}
219
220function lowerBound(values: readonly number[], target: number): number {
221  let low = 0;
222  let high = values.length;
223  while (low < high) {
224    const middle = low + Math.floor((high - low) / 2);
225    const value = values[middle];
226    if (value === undefined || value >= target) high = middle;
227    else low = middle + 1;
228  }
229  return low;
230}
231
232function firstEndAfter(values: readonly number[], target: number): number {
233  let low = 0;
234  let high = values.length;
235  while (low < high) {
236    const middle = low + Math.floor((high - low) / 2);
237    const value = values[middle];
238    if (value === undefined || value > target) high = middle;
239    else low = middle + 1;
240  }
241  return low;
242}
243
244/**
245 * Calculate the bounded item window intersecting a cell viewport.
246 * Exported for deterministic testing; application code normally uses
247 * {@link VirtualList} instead.
248 */
249export function calculateVirtualWindow(
250  metrics: Pick<Metrics, "starts" | "ends">,
251  offset: number,
252  viewportHeight: number,
253  overscan: number,
254  maxRenderedItems: number,
255): WindowRange {
256  const count = metrics.starts.length;
257  if (count === 0) return { start: 0, end: 0 };
258
259  const visibleStart = Math.min(firstEndAfter(metrics.ends, offset), count - 1);
260  const visibleTarget = offset + viewportHeight;
261  const visibleEnd = Math.max(
262    visibleStart + 1,
263    Math.min(count, lowerBound(metrics.starts, visibleTarget)),
264  );
265
266  const boundedVisibleEnd = Math.min(
267    count,
268    visibleStart + maxRenderedItems,
269    visibleEnd,
270  );
271  let start = visibleStart;
272  let end = boundedVisibleEnd;
273  let remaining = maxRenderedItems - (end - start);
274  if (remaining <= 0) return { start, end };
275
276  const wantedStart = Math.min(
277    firstEndAfter(metrics.ends, Math.max(0, offset - overscan)),
278    start,
279  );
280  const wantedEnd = Math.max(
281    end,
282    Math.min(count, lowerBound(metrics.starts, visibleTarget + overscan)),
283  );
284  const wantedBefore = start - wantedStart;
285  const wantedAfter = wantedEnd - end;
286
287  const before = Math.min(wantedBefore, Math.floor(remaining / 2));
288  start -= before;
289  remaining -= before;
290
291  const after = Math.min(wantedAfter, remaining);
292  end += after;
293  remaining -= after;
294
295  if (remaining > 0) {
296    const extraBefore = Math.min(start - wantedStart, remaining);
297    start -= extraBefore;
298    remaining -= extraBefore;
299  }
300  if (remaining > 0) {
301    end += Math.min(wantedEnd - end, remaining);
302  }
303
304  return { start, end };
305}
306
307function rangeEquals(left: WindowRange, right: WindowRange): boolean {
308  return left.start === right.start && left.end === right.end;
309}
310
311function offsetEquals(left: number, right: number): boolean {
312  return Object.is(left, right) || Math.abs(left - right) < 1e-9;
313}
314
315/**
316 * Create a measured variable-height virtual list.
317 *
318 * The returned callable owns only scroll/measurement metadata. It renders
319 * nodes for the visible cell window plus overscan, measures those rows at the
320 * supplied width, and represents cold rows with exact/estimated spacer
321 * heights. Height retention is bounded and prioritizes recently measured
322 * (normally visible) rows; entries are invalidated when an item version or
323 * viewport width changes.
324 *
325 * Structural edits preserve the first visible keyed row and its screen
326 * position. In controlled mode an anchor correction is applied immediately
327 * and reported through `onScroll(..., "anchor")`, allowing the caller to
328 * commit the compensated offset.
329 *
330 * @example
331 * ```ts
332 * const messages = VirtualList<Message>({
333 *   itemKey: (message) => message.id,
334 *   renderItem: (message) => Text(message.body, { wrap: "word" }),
335 *   estimatedItemHeight: 3,
336 *   defaultStickToBottom: true,
337 * });
338 *
339 * cel.viewport(() =>
340 *   messages({ items, width: columns, height: rows, scrollbar: true }),
341 * );
342 *
343 * // When this view is permanently removed:
344 * messages.dispose();
345 * ```
346 */
347export function VirtualList<T>(
348  options: VirtualListOptions<T>,
349): VirtualListInstance<T> {
350  const {
351    itemKey,
352    renderItem,
353    itemVersion = (item: T) => item,
354    estimatedItemHeight = 1,
355    gap: defaultGap = 0,
356    overscan: defaultOverscan = DEFAULT_OVERSCAN,
357    maxCachedItems = DEFAULT_CACHE_LIMIT,
358    maxRenderedItems = DEFAULT_RENDER_LIMIT,
359    defaultScrollOffset = 0,
360    defaultStickToBottom = false,
361  } = options;
362
363  assertNonNegativeInteger(defaultGap, "VirtualList gap");
364  assertNonNegativeInteger(defaultOverscan, "VirtualList overscan");
365  assertPositiveInteger(maxCachedItems, "VirtualList maxCachedItems");
366  assertPositiveInteger(maxRenderedItems, "VirtualList maxRenderedItems");
367  normalizeOffset(defaultScrollOffset, "VirtualList defaultScrollOffset");
368  if (typeof estimatedItemHeight === "number") {
369    assertPositiveInteger(
370      estimatedItemHeight,
371      "VirtualList estimatedItemHeight",
372    );
373  }
374
375  const heightCache = new Map<StateKey, HeightEntry>();
376  const explicitlyInvalidatedKeys = new Set<StateKey>();
377  let explicitlyInvalidatedAll = false;
378  let cacheWidth: number | undefined;
379  let uncontrolledOffset = defaultScrollOffset;
380  let uncontrolledSticky = defaultStickToBottom;
381  let previousFrame: PreviousFrame | undefined;
382  let lastAnchorNotice:
383    | {
384        baseOffset: number;
385        effectiveOffset: number;
386        maxOffset: number;
387      }
388    | undefined;
389  let state: VirtualListState = {
390    scrollOffset: 0,
391    maxScrollOffset: 0,
392    totalHeight: 0,
393    stickToBottom: defaultStickToBottom,
394    visibleStart: 0,
395    visibleEnd: 0,
396    renderedItems: 0,
397    measuredItems: 0,
398    cachedItems: 0,
399  };
400
401  function estimate(item: T, index: number, width: number): number {
402    const value =
403      typeof estimatedItemHeight === "number"
404        ? estimatedItemHeight
405        : estimatedItemHeight(item, index, width);
406    assertPositiveInteger(value, `VirtualList estimate for item ${index}`);
407    return value;
408  }
409
410  function retainHeight(key: StateKey, entry: HeightEntry): void {
411    heightCache.delete(key);
412    heightCache.set(key, entry);
413    while (heightCache.size > maxCachedItems) {
414      const oldest = heightCache.keys().next().value as StateKey | undefined;
415      if (oldest === undefined) break;
416      heightCache.delete(oldest);
417    }
418  }
419
420  function resolveHeight(
421    item: T,
422    index: number,
423    key: StateKey,
424    revision: unknown,
425    width: number,
426    frameHeights: ReadonlyMap<StateKey, number>,
427  ): number {
428    const measured = frameHeights.get(key);
429    if (measured !== undefined) return measured;
430    const entry = heightCache.get(key);
431    if (entry && entry.width === width && Object.is(entry.revision, revision)) {
432      return entry.height;
433    }
434    return estimate(item, index, width);
435  }
436
437  function buildMetrics(
438    items: readonly T[],
439    keys: readonly StateKey[],
440    revisions: readonly unknown[],
441    width: number,
442    gap: number,
443    frameHeights: ReadonlyMap<StateKey, number>,
444  ): Metrics {
445    const starts: number[] = [];
446    const ends: number[] = [];
447    let position = 0;
448    for (let index = 0; index < items.length; index++) {
449      const item = items[index];
450      const key = keys[index];
451      if (item === undefined || key === undefined) {
452        throw new Error(`VirtualList lost item metadata at index ${index}`);
453      }
454      const height = resolveHeight(
455        item,
456        index,
457        key,
458        revisions[index],
459        width,
460        frameHeights,
461      );
462      starts.push(position);
463      ends.push(position + height);
464      position += height;
465      if (index < items.length - 1) position += gap;
466      if (!Number.isSafeInteger(position)) {
467        throw new RangeError("VirtualList total height exceeds safe integers");
468      }
469    }
470    return { starts, ends, totalHeight: position };
471  }
472
473  function anchoredOffset(
474    frame: PreviousFrame,
475    currentIndices: ReadonlyMap<StateKey, number>,
476    metrics: Metrics,
477    maxOffset: number,
478  ): number {
479    if (currentIndices.size === 0 || frame.keys.length === 0) return 0;
480
481    const resolveCandidate = (oldIndex: number): number | undefined => {
482      const key = frame.keys[oldIndex];
483      if (key === undefined) return undefined;
484      const newIndex = currentIndices.get(key);
485      if (newIndex === undefined) return undefined;
486      const oldStart = frame.starts[oldIndex];
487      const newStart = metrics.starts[newIndex];
488      if (oldStart === undefined || newStart === undefined) return undefined;
489      const screenPosition = oldStart - frame.offset;
490      return clampOffset(newStart - screenPosition, maxOffset);
491    };
492
493    for (let index = frame.anchorIndex; index < frame.keys.length; index++) {
494      const offset = resolveCandidate(index);
495      if (offset !== undefined) return offset;
496    }
497    for (let index = frame.anchorIndex - 1; index >= 0; index--) {
498      const offset = resolveCandidate(index);
499      if (offset !== undefined) return offset;
500    }
501    return clampOffset(frame.offset, maxOffset);
502  }
503
504  function resetState(): void {
505    heightCache.clear();
506    explicitlyInvalidatedKeys.clear();
507    explicitlyInvalidatedAll = false;
508    cacheWidth = undefined;
509    uncontrolledOffset = defaultScrollOffset;
510    uncontrolledSticky = defaultStickToBottom;
511    previousFrame = undefined;
512    lastAnchorNotice = undefined;
513    state = {
514      scrollOffset: 0,
515      maxScrollOffset: 0,
516      totalHeight: 0,
517      stickToBottom: defaultStickToBottom,
518      visibleStart: 0,
519      visibleEnd: 0,
520      renderedItems: 0,
521      measuredItems: 0,
522      cachedItems: 0,
523    };
524  }
525
526  function render(props: VirtualListProps<T>): ContainerNode {
527    const {
528      items,
529      width,
530      height,
531      gap = defaultGap,
532      overscan = defaultOverscan,
533      scrollOffset,
534      stickToBottom,
535      onScroll,
536      onStickToBottomChange,
537      ...containerProps
538    } = props;
539
540    assertPositiveInteger(width, "VirtualList width");
541    assertPositiveInteger(height, "VirtualList height");
542    assertNonNegativeInteger(gap, "VirtualList gap");
543    assertNonNegativeInteger(overscan, "VirtualList overscan");
544    if (scrollOffset !== undefined) {
545      normalizeOffset(scrollOffset, "VirtualList scrollOffset");
546    }
547
548    const keys: StateKey[] = [];
549    const revisions: unknown[] = [];
550    const keyIndices = new Map<StateKey, number>();
551    for (let index = 0; index < items.length; index++) {
552      const item = items[index];
553      if (item === undefined) {
554        throw new Error(`VirtualList item ${index} is unexpectedly undefined`);
555      }
556      const key = itemKey(item, index);
557      if (keyIndices.has(key)) {
558        throw new Error(`Duplicate VirtualList item key: ${formatKey(key)}`);
559      }
560      keyIndices.set(key, index);
561      keys.push(key);
562      revisions.push(itemVersion(item, index));
563    }
564
565    if (cacheWidth !== undefined && cacheWidth !== width) {
566      heightCache.clear();
567    }
568    cacheWidth = width;
569    for (const key of heightCache.keys()) {
570      if (!keyIndices.has(key)) heightCache.delete(key);
571    }
572    for (let index = 0; index < keys.length; index++) {
573      const key = keys[index];
574      if (key === undefined) continue;
575      const entry = heightCache.get(key);
576      if (entry && !Object.is(entry.revision, revisions[index])) {
577        heightCache.delete(key);
578      }
579    }
580
581    const controlled = scrollOffset !== undefined;
582    const sourceOffset = normalizeOffset(
583      controlled ? scrollOffset : uncontrolledOffset,
584      "VirtualList scroll offset",
585    );
586    const sticky = stickToBottom ?? uncontrolledSticky;
587    const pinnedToBottom = sticky || sourceOffset === Infinity;
588    const modelChanged =
589      previousFrame === undefined ||
590      previousFrame.keys.length !== keys.length ||
591      keys.some(
592        (key, index) =>
593          key !== previousFrame?.keys[index] ||
594          !Object.is(revisions[index], previousFrame.revisions[index]),
595      );
596    const sourceChanged =
597      previousFrame !== undefined &&
598      (controlled !== previousFrame.controlled ||
599        (!offsetEquals(sourceOffset, previousFrame.sourceOffset) &&
600          !offsetEquals(sourceOffset, previousFrame.offset)));
601    const frameHeights = new Map<StateKey, number>();
602    const renderedNodes = new Map<StateKey, Node>();
603
604    let metrics = buildMetrics(
605      items,
606      keys,
607      revisions,
608      width,
609      gap,
610      frameHeights,
611    );
612    let maxOffset = Math.max(0, metrics.totalHeight - height);
613
614    const resolveEffectiveOffset = (): number => {
615      if (pinnedToBottom) return maxOffset;
616      const baseOffset = clampOffset(sourceOffset, maxOffset);
617      if (!previousFrame || sourceChanged) return baseOffset;
618      return anchoredOffset(previousFrame, keyIndices, metrics, maxOffset);
619    };
620
621    let effectiveOffset = resolveEffectiveOffset();
622    let range = calculateVirtualWindow(
623      metrics,
624      effectiveOffset,
625      height,
626      overscan,
627      maxRenderedItems,
628    );
629    let metricsDirty = false;
630
631    const materialize = (window: WindowRange): void => {
632      for (let index = window.start; index < window.end; index++) {
633        const item = items[index];
634        const key = keys[index];
635        if (item === undefined || key === undefined) continue;
636        if (renderedNodes.has(key)) continue;
637        const node = renderItem(item, index);
638        const expectedHeight = resolveHeight(
639          item,
640          index,
641          key,
642          revisions[index],
643          width,
644          frameHeights,
645        );
646        const measuredHeight = measureContentHeight(VStack({}, [node]), {
647          width,
648        });
649        assertNonNegativeInteger(
650          measuredHeight,
651          `VirtualList measured height for item ${index}`,
652        );
653        if (measuredHeight !== expectedHeight) metricsDirty = true;
654        renderedNodes.set(key, node);
655        frameHeights.set(key, measuredHeight);
656        retainHeight(key, {
657          height: measuredHeight,
658          revision: revisions[index],
659          width,
660        });
661      }
662    };
663
664    const refreshMetricsAndOffset = (): void => {
665      metrics = buildMetrics(items, keys, revisions, width, gap, frameHeights);
666      maxOffset = Math.max(0, metrics.totalHeight - height);
667      effectiveOffset = resolveEffectiveOffset();
668      metricsDirty = false;
669    };
670
671    // Newly prepended rows affect the preserved anchor even though they are
672    // outside the visible window. Measure a bounded batch immediately so a
673    // typical history-page prepend is compensated with exact heights instead
674    // of estimates. Very large prepends remain bounded and converge as their
675    // rows enter the measured window.
676    if (
677      previousFrame &&
678      !sourceChanged &&
679      !pinnedToBottom &&
680      previousFrame.anchorIndex >= 0 &&
681      (modelChanged ||
682        explicitlyInvalidatedAll ||
683        explicitlyInvalidatedKeys.size > 0)
684    ) {
685      const oldAnchorKey = previousFrame.keys[previousFrame.anchorIndex];
686      const newAnchorIndex =
687        oldAnchorKey === undefined ? -1 : (keyIndices.get(oldAnchorKey) ?? -1);
688      if (newAnchorIndex > 0) {
689        const previousKeys = new Set(previousFrame.keys);
690        const previousRevisions = new Map<StateKey, unknown>();
691        for (let index = 0; index < previousFrame.keys.length; index++) {
692          const key = previousFrame.keys[index];
693          if (key !== undefined) {
694            previousRevisions.set(key, previousFrame.revisions[index]);
695          }
696        }
697        let measuredPrepends = 0;
698        for (
699          let index = 0;
700          index < newAnchorIndex && measuredPrepends < maxRenderedItems;
701          index++
702        ) {
703          const key = keys[index];
704          if (key === undefined) continue;
705          const isNew = !previousKeys.has(key);
706          const versionChanged =
707            previousRevisions.has(key) &&
708            !Object.is(previousRevisions.get(key), revisions[index]);
709          const explicitlyInvalidated =
710            explicitlyInvalidatedAll || explicitlyInvalidatedKeys.has(key);
711          if (!isNew && !versionChanged && !explicitlyInvalidated) continue;
712          materialize({ start: index, end: index + 1 });
713          measuredPrepends++;
714        }
715        if (measuredPrepends > 0 && metricsDirty) {
716          refreshMetricsAndOffset();
717          range = calculateVirtualWindow(
718            metrics,
719            effectiveOffset,
720            height,
721            overscan,
722            maxRenderedItems,
723          );
724        }
725      }
726    }
727
728    for (let pass = 0; pass < MAX_MEASUREMENT_PASSES; pass++) {
729      materialize(range);
730      if (!metricsDirty) break;
731      refreshMetricsAndOffset();
732      const nextRange = calculateVirtualWindow(
733        metrics,
734        effectiveOffset,
735        height,
736        overscan,
737        maxRenderedItems,
738      );
739      const settled = rangeEquals(range, nextRange);
740      range = nextRange;
741      if (settled) break;
742    }
743    materialize(range);
744
745    // A moving window can expose one final set of estimated rows at its edge.
746    // Commit those measurements so spacer and scrollbar extents are exact for
747    // every node included in this frame. A pathological non-converging model
748    // naturally settles on the next render while the returned row cap holds.
749    if (metricsDirty) refreshMetricsAndOffset();
750
751    const baseOffset = clampOffset(sourceOffset, maxOffset);
752    if (
753      !pinnedToBottom &&
754      onScroll &&
755      !offsetEquals(effectiveOffset, baseOffset)
756    ) {
757      const duplicateNotice =
758        lastAnchorNotice !== undefined &&
759        offsetEquals(lastAnchorNotice.baseOffset, baseOffset) &&
760        offsetEquals(lastAnchorNotice.effectiveOffset, effectiveOffset) &&
761        offsetEquals(lastAnchorNotice.maxOffset, maxOffset);
762      if (!duplicateNotice) {
763        lastAnchorNotice = {
764          baseOffset,
765          effectiveOffset,
766          maxOffset,
767        };
768        onScroll(effectiveOffset, maxOffset, "anchor");
769      }
770    } else {
771      lastAnchorNotice = undefined;
772    }
773
774    if (!controlled && sourceOffset !== Infinity) {
775      uncontrolledOffset = effectiveOffset;
776    }
777
778    const anchorIndex =
779      keys.length === 0
780        ? -1
781        : Math.min(
782            firstEndAfter(metrics.ends, effectiveOffset),
783            keys.length - 1,
784          );
785    const anchorKey = anchorIndex >= 0 ? keys[anchorIndex] : undefined;
786    previousFrame = {
787      keys: [...keys],
788      revisions: [...revisions],
789      starts: [...metrics.starts],
790      offset: effectiveOffset,
791      sourceOffset: controlled ? sourceOffset : effectiveOffset,
792      controlled,
793      anchorIndex,
794    };
795    explicitlyInvalidatedKeys.clear();
796    explicitlyInvalidatedAll = false;
797
798    state = {
799      scrollOffset: effectiveOffset,
800      maxScrollOffset: maxOffset,
801      totalHeight: metrics.totalHeight,
802      stickToBottom: pinnedToBottom,
803      visibleStart: range.start,
804      visibleEnd: range.end,
805      renderedItems: range.end - range.start,
806      measuredItems: frameHeights.size,
807      cachedItems: heightCache.size,
808      ...(anchorKey === undefined ? {} : { anchorKey }),
809    };
810
811    const visibleItems: Node[] = [];
812    for (let index = range.start; index < range.end; index++) {
813      const key = keys[index];
814      if (key === undefined) continue;
815      const node = renderedNodes.get(key);
816      if (node) visibleItems.push(node);
817    }
818
819    const children: Node[] = [];
820    const topHeight = metrics.starts[range.start] ?? 0;
821    if (topHeight > 0) children.push(VStack({ height: topHeight }, []));
822    if (visibleItems.length > 0) {
823      children.push(VStack({ gap }, visibleItems));
824    }
825    const visibleHeight =
826      range.end > range.start
827        ? (metrics.ends[range.end - 1] ?? topHeight) - topHeight
828        : 0;
829    const bottomHeight = Math.max(
830      0,
831      metrics.totalHeight - topHeight - visibleHeight,
832    );
833    if (bottomHeight > 0) children.push(VStack({ height: bottomHeight }, []));
834
835    const handleScroll: NonNullable<ContainerProps["onScroll"]> = (
836      nextOffset,
837      reportedMaxOffset,
838    ) => {
839      const clamped = clampOffset(nextOffset, reportedMaxOffset);
840      const result = onScroll?.(clamped, reportedMaxOffset, "input");
841      if (result === false) return false;
842
843      if (!controlled) uncontrolledOffset = clamped;
844      const nextSticky = clamped >= reportedMaxOffset;
845      if (stickToBottom === undefined && nextSticky !== uncontrolledSticky) {
846        uncontrolledSticky = nextSticky;
847      }
848      if (nextSticky !== pinnedToBottom) {
849        onStickToBottomChange?.(nextSticky);
850      }
851      cel.render();
852      return result;
853    };
854
855    return VStack(
856      {
857        ...containerProps,
858        width,
859        height,
860        overflow: "scroll",
861        scrollOffset: effectiveOffset,
862        onScroll: handleScroll,
863      },
864      children,
865    );
866  }
867
868  render.reset = () => {
869    resetState();
870    cel.render();
871  };
872  render.dispose = resetState;
873  render.invalidate = (key?: StateKey) => {
874    if (key === undefined) {
875      heightCache.clear();
876      explicitlyInvalidatedAll = true;
877      explicitlyInvalidatedKeys.clear();
878    } else {
879      heightCache.delete(key);
880      explicitlyInvalidatedKeys.add(key);
881    }
882    lastAnchorNotice = undefined;
883    cel.render();
884  };
885  render.scrollTo = (offset: number) => {
886    uncontrolledOffset = normalizeOffset(offset, "VirtualList scrollTo offset");
887    uncontrolledSticky = false;
888    cel.render();
889  };
890  render.scrollToEnd = () => {
891    uncontrolledSticky = true;
892    cel.render();
893  };
894  render.getState = () => ({ ...state });
895
896  return render as VirtualListInstance<T>;
897}