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}