Primitives / foldkit-primitives/state

Virtual

const · packages/primitives/src/state/virtual.ts:249

Args{ estimatedHeight: number, overscan: number, gap: number, paddingStart: number, paddingEnd: number, settleMs?: number, initialScrollTop?: number, initialHeights?: Readonly<Record<string, number>> }
Model{ scrollTop: number, heights: { readonly [x: string]: number; }, scrolling: boolean, generation: number, estimatedHeight: number, overscan: number, gap: number, paddingStart: number, paddingEnd: number }
MessagesMeasured { key: string, height: number }, Scrolled { top: number }, Prune { keys: readonly string[] }, Settled { generation: number }
Its full type
const Virtual: Bundle.Bundle<
  'Virtual',
  {
    readonly estimatedHeight: number
    readonly overscan: number
    readonly gap: number
    readonly paddingStart: number
    readonly paddingEnd: number
    readonly settleMs?: number | undefined
    readonly initialScrollTop?: number | undefined
    readonly initialHeights?: Readonly<Record<string, number>> | undefined
  },
  {
    readonly scrollTop: number
    readonly heights: { readonly [x: string]: number }
    readonly scrolling: boolean
    readonly generation: number
    readonly estimatedHeight: number
    readonly overscan: number
    readonly gap: number
    readonly paddingStart: number
    readonly paddingEnd: number
  },
  | { readonly _tag: 'Measured'; readonly key: string; readonly height: number }
  | { readonly _tag: 'Scrolled'; readonly top: number }
  | { readonly _tag: 'Prune'; readonly keys: readonly string[] }
  | { readonly _tag: 'Settled'; readonly generation: number },
  never,
  never,
  never,
  void,
  {},
  {}
>

Windowing math for virtualized lists as pure functions: which rows to render, how tall the scrollable area is, and where each row starts. Row heights come from measured values with a per-row estimate fallback, so unmeasured rows still occupy space and measuring later only corrects. Keys are strings; heights are non-negative, and non-finite measurements fall back to the estimate instead of poisoning the sums.

The Virtual bundle below owns the scroll position and the measured heights; Viewport reports container scrolls and MeasureRow reports row heights, both as Mounts on the elements they observe. The application renders windowFor(...) rows with its own views (keyed, so each placements keep identity) inside a spacer of totalHeight(...).

In the guides