@ccheever/exact-list-core 0.1.0

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@ccheever/exact-list-core",
+  "version": "0.1.0",
+  "description": "Framework-neutral virtual list core for Exact",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/src/__tests__/virtualizer.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  computeVirtualItemsFromPrepared,
+  computeVirtualItems,
+  getEstimatedOffsetForIndex,
+  getScrollOffsetAfterMeasurement,
+  measurementsFromSnapshot,
+  createMeasurementSnapshot,
+  prepareVirtualList,
+} from '../index.ts';
+
+describe('computeVirtualItems', () => {
+  it('mounts only the overscanned window', () => {
+    const output = computeVirtualItems({
+      count: 10_000,
+      scrollOffset: 5_000,
+      viewportSize: 500,
+      drawDistance: 250,
+      estimatedItemSize: 50,
+      getKey: (index) => `row-${index}`,
+    });
+
+    expect(output.totalSize).toBe(500_000);
+    expect(output.visibleRange).toEqual({ startIndex: 100, endIndex: 109 });
+    expect(output.overscanRange).toEqual({ startIndex: 95, endIndex: 114 });
+    expect(output.items.length).toBe(20);
+    expect(output.diagnostics.itemCount).toBe(10_000);
+    expect(output.diagnostics.mountedItemCount).toBe(20);
+  });
+
+  it('uses measured sizes when available', () => {
+    const measurements = new Map<string, number>([
+      ['row-0', 100],
+      ['row-1', 25],
+    ]);
+
+    const output = computeVirtualItems({
+      count: 4,
+      scrollOffset: 0,
+      viewportSize: 400,
+      drawDistance: 0,
+      estimatedItemSize: 50,
+      measurements,
+      getKey: (index) => `row-${index}`,
+    });
+
+    expect(output.totalSize).toBe(225);
+    expect(output.items.map((item) => [item.key, item.start, item.size, item.measured])).toEqual([
+      ['row-0', 0, 100, true],
+      ['row-1', 100, 25, true],
+      ['row-2', 125, 50, false],
+      ['row-3', 175, 50, false],
+    ]);
+    expect(output.diagnostics.measuredItemCount).toBe(2);
+    expect(output.diagnostics.measurementCacheHitRate).toBe(0.5);
+  });
+
+  it('can keep specific indices mounted outside the window', () => {
+    const output = computeVirtualItems({
+      count: 200,
+      scrollOffset: 1_000,
+      viewportSize: 100,
+      drawDistance: 0,
+      estimatedItemSize: 10,
+      alwaysRenderIndices: [0, 199],
+      getKey: (index) => `row-${index}`,
+    });
+
+    expect(output.items.some((item) => item.index === 0)).toBe(true);
+    expect(output.items.some((item) => item.index === 199)).toBe(true);
+    expect(output.diagnostics.alwaysMountedCount).toBe(2);
+  });
+});
+
+describe('measurement snapshots', () => {
+  it('round-trips measurement entries', () => {
+    const snapshot = createMeasurementSnapshot(new Map([
+      ['a', 12],
+      ['b', 34],
+    ]));
+    const measurements = measurementsFromSnapshot(snapshot);
+
+    expect(measurements.get('a')).toBe(12);
+    expect(measurements.get('b')).toBe(34);
+  });
+
+  it('estimates offsets from measured and estimated sizes', () => {
+    const offset = getEstimatedOffsetForIndex({
+      count: 5,
+      estimatedItemSize: 10,
+      measurements: new Map([['row-1', 25]]),
+      getKey: (index) => `row-${index}`,
+    }, 3);
+
+    expect(offset).toBe(45);
+  });
+});
+
+describe('prepared list state', () => {
+  it('reuses prepared offsets for different scroll windows', () => {
+    const prepared = prepareVirtualList({
+      count: 1_000,
+      estimatedItemSize: 20,
+      getKey: (index) => `row-${index}`,
+    });
+
+    const first = computeVirtualItemsFromPrepared(prepared, {
+      scrollOffset: 0,
+      viewportSize: 100,
+      drawDistance: 0,
+    });
+    const second = computeVirtualItemsFromPrepared(prepared, {
+      scrollOffset: 10_000,
+      viewportSize: 100,
+      drawDistance: 0,
+    });
+
+    expect(prepared.totalSize).toBe(20_000);
+    expect(first.visibleRange).toEqual({ startIndex: 0, endIndex: 4 });
+    expect(second.visibleRange).toEqual({ startIndex: 500, endIndex: 504 });
+  });
+
+  it('preserves the visible anchor when an above-viewport item is measured', () => {
+    const prepared = prepareVirtualList({
+      count: 10,
+      estimatedItemSize: 50,
+      getKey: (index) => `row-${index}`,
+    });
+
+    expect(getScrollOffsetAfterMeasurement(prepared, 'row-1', 250, 80)).toEqual({
+      key: 'row-1',
+      affected: true,
+      delta: 30,
+      nextScrollOffset: 280,
+    });
+  });
+
+  it('does not adjust scroll when a below-viewport item is measured', () => {
+    const prepared = prepareVirtualList({
+      count: 10,
+      estimatedItemSize: 50,
+      getKey: (index) => `row-${index}`,
+    });
+
+    expect(getScrollOffsetAfterMeasurement(prepared, 'row-8', 250, 80)).toEqual({
+      key: 'row-8',
+      affected: false,
+      delta: 30,
+      nextScrollOffset: 250,
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,406 @@
+export type ListAxis = 'vertical' | 'horizontal';
+
+export interface ListVisibleRange {
+  readonly startIndex: number;
+  readonly endIndex: number;
+}
+
+export interface ListOverscanRange {
+  readonly startIndex: number;
+  readonly endIndex: number;
+}
+
+export interface VirtualListItem {
+  readonly index: number;
+  readonly key: string;
+  readonly type: string | null;
+  readonly start: number;
+  readonly size: number;
+  readonly measured: boolean;
+}
+
+export interface ListMeasurementEntry {
+  readonly key: string;
+  readonly size: number;
+  readonly type?: string | null;
+}
+
+export interface ListMeasurementSnapshot {
+  readonly entries: readonly ListMeasurementEntry[];
+}
+
+export interface ListDiagnostics {
+  readonly virtualized: boolean;
+  readonly itemCount: number;
+  readonly mountedItemCount: number;
+  readonly visibleStartIndex: number;
+  readonly visibleEndIndex: number;
+  readonly overscanStartIndex: number;
+  readonly overscanEndIndex: number;
+  readonly measuredItemCount: number;
+  readonly estimatedItemCount: number;
+  readonly averageItemSize: number;
+  readonly measurementCacheHitRate: number;
+  readonly blankAreaPx: number;
+  readonly droppedFrameEstimate: number | null;
+  readonly alwaysMountedCount: number;
+  readonly recycledCellCount: number;
+}
+
+export interface ListVirtualizerInput {
+  readonly count: number;
+  readonly scrollOffset: number;
+  readonly viewportSize: number;
+  readonly drawDistance: number;
+  readonly estimatedItemSize: number;
+  readonly measurements?: ReadonlyMap<string, number>;
+  readonly alwaysRenderIndices?: readonly number[];
+  getKey(index: number): string;
+  getType?: (index: number) => string | null;
+  getEstimatedSize?: (index: number, type: string | null) => number;
+  getFixedSize?: (index: number, type: string | null) => number | null | undefined;
+}
+
+export interface ListVirtualizerOutput {
+  readonly totalSize: number;
+  readonly items: readonly VirtualListItem[];
+  readonly visibleRange: ListVisibleRange;
+  readonly overscanRange: ListOverscanRange;
+  readonly diagnostics: ListDiagnostics;
+}
+
+export interface PreparedListItem {
+  readonly key: string;
+  readonly type: string | null;
+  readonly size: number;
+  readonly measured: boolean;
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface PreparedListState {
+  readonly count: number;
+  readonly totalSize: number;
+  readonly records: readonly PreparedListItem[];
+  readonly measuredItemCount: number;
+}
+
+export interface ListMeasurementAnchorAdjustment {
+  readonly key: string;
+  readonly affected: boolean;
+  readonly delta: number;
+  readonly nextScrollOffset: number;
+}
+
+const DEFAULT_ITEM_SIZE = 64;
+
+function normalizeCount(count: number): number {
+  return Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+}
+
+function normalizeSize(size: number | null | undefined, fallback: number): number {
+  return Number.isFinite(size) && size != null && size > 0 ? size : fallback;
+}
+
+function emptyDiagnostics(virtualized: boolean): ListDiagnostics {
+  return {
+    virtualized,
+    itemCount: 0,
+    mountedItemCount: 0,
+    visibleStartIndex: -1,
+    visibleEndIndex: -1,
+    overscanStartIndex: -1,
+    overscanEndIndex: -1,
+    measuredItemCount: 0,
+    estimatedItemCount: 0,
+    averageItemSize: 0,
+    measurementCacheHitRate: 0,
+    blankAreaPx: 0,
+    droppedFrameEstimate: null,
+    alwaysMountedCount: 0,
+    recycledCellCount: 0,
+  };
+}
+
+export function prepareVirtualList(input: Omit<ListVirtualizerInput, 'scrollOffset' | 'viewportSize' | 'drawDistance' | 'alwaysRenderIndices'>): PreparedListState {
+  const count = normalizeCount(input.count);
+  const baseEstimate = normalizeSize(input.estimatedItemSize, DEFAULT_ITEM_SIZE);
+  const records: PreparedListItem[] = [];
+  let offset = 0;
+  let measuredItemCount = 0;
+
+  for (let index = 0; index < count; index += 1) {
+    const key = input.getKey(index);
+    const type = input.getType?.(index) ?? null;
+    const fixedSize = input.getFixedSize?.(index, type);
+    const measuredSize = fixedSize == null ? input.measurements?.get(key) : undefined;
+    const estimate = input.getEstimatedSize?.(index, type) ?? baseEstimate;
+    const size = normalizeSize(fixedSize ?? measuredSize ?? estimate, baseEstimate);
+    const measured = fixedSize != null || measuredSize != null;
+    if (measured) {
+      measuredItemCount += 1;
+    }
+
+    records.push({
+      key,
+      type,
+      size,
+      measured,
+      start: offset,
+      end: offset + size,
+    });
+    offset += size;
+  }
+
+  return {
+    count,
+    totalSize: offset,
+    records,
+    measuredItemCount,
+  };
+}
+
+function findFirstIntersecting(records: readonly PreparedListItem[], offset: number): number {
+  if (records.length === 0) {
+    return -1;
+  }
+
+  let low = 0;
+  let high = records.length - 1;
+  let result = records.length;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (records[mid].end > offset) {
+      result = mid;
+      high = mid - 1;
+    } else {
+      low = mid + 1;
+    }
+  }
+
+  return result >= records.length ? records.length - 1 : result;
+}
+
+function findLastIntersecting(records: readonly PreparedListItem[], offset: number): number {
+  if (records.length === 0) {
+    return -1;
+  }
+
+  let low = 0;
+  let high = records.length - 1;
+  let result = -1;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (records[mid].start < offset) {
+      result = mid;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return result < 0 ? 0 : result;
+}
+
+function rangeItems(
+  records: readonly PreparedListItem[],
+  startIndex: number,
+  endIndex: number,
+): VirtualListItem[] {
+  if (startIndex < 0 || endIndex < startIndex) {
+    return [];
+  }
+
+  const items: VirtualListItem[] = [];
+  for (let index = startIndex; index <= endIndex; index += 1) {
+    const record = records[index];
+    items.push({
+      index,
+      key: record.key,
+      type: record.type,
+      start: record.start,
+      size: record.size,
+      measured: record.measured,
+    });
+  }
+  return items;
+}
+
+function appendAlwaysRenderedItems(
+  items: VirtualListItem[],
+  records: readonly PreparedListItem[],
+  alwaysRenderIndices: readonly number[] | undefined,
+): number {
+  if (!alwaysRenderIndices || alwaysRenderIndices.length === 0) {
+    return 0;
+  }
+
+  const existing = new Set(items.map((item) => item.index));
+  let added = 0;
+  for (const index of alwaysRenderIndices) {
+    if (index < 0 || index >= records.length || existing.has(index)) {
+      continue;
+    }
+    const record = records[index];
+    items.push({
+      index,
+      key: record.key,
+      type: record.type,
+      start: record.start,
+      size: record.size,
+      measured: record.measured,
+    });
+    existing.add(index);
+    added += 1;
+  }
+  items.sort((left, right) => left.index - right.index);
+  return added;
+}
+
+export function computeVirtualItems(input: ListVirtualizerInput): ListVirtualizerOutput {
+  const prepared = prepareVirtualList(input);
+  return computeVirtualItemsFromPrepared(prepared, {
+    scrollOffset: input.scrollOffset,
+    viewportSize: input.viewportSize,
+    drawDistance: input.drawDistance,
+    alwaysRenderIndices: input.alwaysRenderIndices,
+  });
+}
+
+export function computeVirtualItemsFromPrepared(
+  prepared: PreparedListState,
+  options: {
+    readonly scrollOffset: number;
+    readonly viewportSize: number;
+    readonly drawDistance: number;
+    readonly alwaysRenderIndices?: readonly number[];
+  },
+): ListVirtualizerOutput {
+  const count = prepared.count;
+  if (count === 0) {
+    return {
+      totalSize: 0,
+      items: [],
+      visibleRange: { startIndex: -1, endIndex: -1 },
+      overscanRange: { startIndex: -1, endIndex: -1 },
+      diagnostics: emptyDiagnostics(true),
+    };
+  }
+
+  const records = prepared.records;
+  const totalSize = prepared.totalSize;
+  const viewportSize = Math.max(0, options.viewportSize);
+  const scrollOffset = Math.max(0, Math.min(options.scrollOffset, Math.max(0, totalSize - viewportSize)));
+  const visibleStart = findFirstIntersecting(records, scrollOffset);
+  const visibleEnd = findLastIntersecting(records, scrollOffset + viewportSize);
+  const drawDistance = Math.max(0, options.drawDistance);
+  const overscanStart = findFirstIntersecting(records, Math.max(0, scrollOffset - drawDistance));
+  const overscanEnd = findLastIntersecting(records, Math.min(totalSize, scrollOffset + viewportSize + drawDistance));
+  const items = rangeItems(records, overscanStart, overscanEnd);
+  const alwaysMountedCount = appendAlwaysRenderedItems(items, records, options.alwaysRenderIndices);
+  const measuredItemCount = prepared.measuredItemCount;
+  const mountedMeasuredItemCount = items.reduce((sum, item) => sum + (item.measured ? 1 : 0), 0);
+  const averageItemSize = totalSize / count;
+  const viewportStart = scrollOffset;
+  const viewportEnd = scrollOffset + viewportSize;
+  const coveredStart = items.length === 0
+    ? viewportStart
+    : Math.max(viewportStart, Math.min(...items.map((item) => item.start)));
+  const coveredEnd = items.length === 0
+    ? viewportStart
+    : Math.min(viewportEnd, Math.max(...items.map((item) => item.start + item.size)));
+  const blankAreaPx = Math.max(0, viewportSize - Math.max(0, coveredEnd - coveredStart));
+
+  return {
+    totalSize,
+    items,
+    visibleRange: {
+      startIndex: visibleStart,
+      endIndex: visibleEnd,
+    },
+    overscanRange: {
+      startIndex: overscanStart,
+      endIndex: overscanEnd,
+    },
+    diagnostics: {
+      virtualized: true,
+      itemCount: count,
+      mountedItemCount: items.length,
+      visibleStartIndex: visibleStart,
+      visibleEndIndex: visibleEnd,
+      overscanStartIndex: overscanStart,
+      overscanEndIndex: overscanEnd,
+      measuredItemCount,
+      estimatedItemCount: count - measuredItemCount,
+      averageItemSize,
+      measurementCacheHitRate: items.length === 0 ? 0 : mountedMeasuredItemCount / items.length,
+      blankAreaPx,
+      droppedFrameEstimate: null,
+      alwaysMountedCount,
+      recycledCellCount: 0,
+    },
+  };
+}
+
+export function getEstimatedOffsetForIndex(
+  input: Omit<ListVirtualizerInput, 'scrollOffset' | 'viewportSize' | 'drawDistance'>,
+  targetIndex: number,
+): number {
+  const count = normalizeCount(input.count);
+  const clampedTarget = Math.max(0, Math.min(Math.floor(targetIndex), count));
+  const { records } = prepareVirtualList(input);
+  return records[clampedTarget]?.start ?? records[records.length - 1]?.end ?? 0;
+}
+
+export function getScrollOffsetAfterMeasurement(
+  prepared: PreparedListState,
+  key: string,
+  currentScrollOffset: number,
+  nextSize: number,
+): ListMeasurementAnchorAdjustment {
+  const record = prepared.records.find((record) => record.key === key);
+  if (!record || !Number.isFinite(nextSize) || nextSize <= 0) {
+    return {
+      key,
+      affected: false,
+      delta: 0,
+      nextScrollOffset: currentScrollOffset,
+    };
+  }
+
+  const delta = nextSize - record.size;
+  const affected = Math.abs(delta) >= 0.5 && record.start < currentScrollOffset;
+  return {
+    key,
+    affected,
+    delta,
+    nextScrollOffset: affected ? Math.max(0, currentScrollOffset + delta) : currentScrollOffset,
+  };
+}
+
+export function createMeasurementSnapshot(
+  measurements: ReadonlyMap<string, number>,
+  getType?: (key: string) => string | null | undefined,
+): ListMeasurementSnapshot {
+  return {
+    entries: [...measurements.entries()].map(([key, size]) => ({
+      key,
+      size,
+      type: getType?.(key) ?? null,
+    })),
+  };
+}
+
+export function measurementsFromSnapshot(
+  snapshot: ListMeasurementSnapshot | undefined,
+): Map<string, number> {
+  const measurements = new Map<string, number>();
+  for (const entry of snapshot?.entries ?? []) {
+    if (entry.key.length > 0 && Number.isFinite(entry.size) && entry.size > 0) {
+      measurements.set(entry.key, entry.size);
+    }
+  }
+  return measurements;
+}