Ui/VirtualList

/**
 * Creates an initial virtual list model from a config. The container starts
 *  in `Unmeasured` state. The first `ResizeObserver` entry transitions it to
 *  `Measured`.
 */
(config: InitConfig): VirtualList.Model

/**
 * Programmatically scrolls the container so the row at `index` is visible.
 *  Returns the next model and a Command that mutates `element.scrollTop`. The
 *  natural scroll event then flows back through `ScrolledContainer` and the
 *  component re-renders the new visible slice.
 * 
 *  Uses version-based cancellation: each call increments
 *  `pendingScrollVersion` so a stale `CompletedApplyScroll` (e.g. from a
 *  previous in-flight scroll) is ignored when its version no longer matches.
 * 
 *  Should be called after the container has rendered. If the container is not
 *  yet in the DOM the Command silently no-ops (the model still transitions
 *  through `ScrollingToIndex` → `Idle` via the version-matched completion).
 * 
 *  Assumes uniform row heights: target scroll position is computed as
 *  `index * model.rowHeightPx`. For variable-height rows, use
 *  `scrollToIndexVariable`.
 */
(
  model: VirtualList.Model,
  index: number
): readonly [
  VirtualList.Model,
  readonly Array<Readonly<{
    args: Record<string, unknown>
    effect: Effect<{
      _tag: "ScrolledContainer"
      scrollTop: number
    } | {
      _tag: "MeasuredContainer"
      containerHeight: number
    } | {
      _tag: "CompletedApplyScroll"
      version: number
    }, never, never>
    name: string
  }>>
]

/**
 * Variable-height counterpart of `scrollToIndex`. Walks the heights of items
 *  before `index` to compute the target `scrollTop`. Use this when rendering
 *  the list with `itemToRowHeightPx`; use `scrollToIndex` for uniform heights.
 * 
 *  Out-of-range indices clamp to the corresponding edge: negative or zero
 *  scrolls to the top, indices past the end scroll past the last row.
 * 
 *  Note: when restoring `initialScrollTop` on the first measurement of a
 *  variable-height list, the runtime falls back to uniform-height math (using
 *  `model.rowHeightPx`) because items aren't reachable from the `update`
 *  function. Consumers who need an accurate initial scroll on a
 *  variable-height list should call `scrollToIndexVariable` after the first
 *  `MeasuredContainer` arrives.
 */
<Item>(
  model: VirtualList.Model,
  items: readonly Array<Item>,
  itemToRowHeightPx: (item: Item, index: number) => number,
  index: number
): readonly [
  VirtualList.Model,
  readonly Array<Readonly<{
    args: Record<string, unknown>
    effect: Effect<{
      _tag: "ScrolledContainer"
      scrollTop: number
    } | {
      _tag: "MeasuredContainer"
      containerHeight: number
    } | {
      _tag: "CompletedApplyScroll"
      version: number
    }, never, never>
    name: string
  }>>
]

<Item>(): ViewForItem<Item>

/**
 * Computes the visible slice of a data array given the current scroll
 *  position, container height, row height, and an overscan buffer.
 * 
 *  Assumes uniform row heights via `model.rowHeightPx`. For variable-height
 *  rows, use `visibleWindowVariable`.
 * 
 *  Returns `Option.none()` when the container has not yet been measured;
 *  callers should render a placeholder (or `Html.empty`) and wait for the
 *  first `MeasuredContainer` message.
 */
(
  model: VirtualList.Model,
  itemCount: number,
  overscan: number
): Option<Readonly<{
  bottomSpacerHeight: number
  endIndex: number
  startIndex: number
  topSpacerHeight: number
}>>

/**
 * Variable-height counterpart of `visibleWindow`. Walks the heights of every
 *  item to build a prefix-sum array, then locates the visible slice with two
 *  linear searches.
 * 
 *  Cost is O(N) per call, walking the whole `items` array once to build the
 *  prefix sums. For lists in the 10k-item range, this comfortably fits inside
 *  a 60Hz scroll budget. Larger lists or hotter scroll paths can layer a
 *  prefix-sum cache invalidated when items change; that lives behind the same
 *  return shape so consumers don't have to know.
 * 
 *  Returns `Option.none()` when the container has not yet been measured.
 */
<Item>(
  model: VirtualList.Model,
  items: readonly Array<Item>,
  itemToRowHeightPx: (item: Item, index: number) => number,
  overscan: number
): Option<Readonly<{
  bottomSpacerHeight: number
  endIndex: number
  startIndex: number
  topSpacerHeight: number
}>>