@virtual-content/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,422 @@
+declare class FenwickTree {
+    private readonly values;
+    private readonly tree;
+    constructor(values: readonly number[]);
+    get size(): number;
+    get(index: number): number;
+    add(index: number, delta: number): void;
+    set(index: number, value: number): number;
+    sum(endExclusive: number): number;
+    total(): number;
+    lowerBound(offset: number): number;
+    private hasIndex;
+}
+
+type ItemKey = string | number;
+type ScrollAxis = "vertical" | "horizontal" | "both";
+type LayoutMode = "linear" | "grid" | "masonry" | "free";
+type LayoutDirection = "vertical" | "horizontal";
+type MeasurementAxes = "none" | "main" | "cross" | "both";
+type ScrollAlign = "start" | "center" | "end" | "auto" | "nearest";
+type VirtualStickAxis = "x" | "y" | "both";
+type VirtualStickToEndOptions = boolean | {
+    x?: boolean;
+    y?: boolean;
+    threshold?: number;
+    initial?: boolean;
+};
+interface VirtualStickState {
+    x: boolean;
+    y: boolean;
+    distanceToRight: number;
+    distanceToBottom: number;
+}
+interface OverscanRange {
+    before?: number;
+    after?: number;
+}
+interface VirtualPoint {
+    x: number;
+    y: number;
+}
+interface VirtualRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface VirtualOverscan {
+    before: number;
+    after: number;
+    maxItems?: number;
+    maxPx?: number;
+}
+interface VirtualScrollOptions {
+    axis: ScrollAxis;
+    initialOffset?: number;
+    initialPoint?: VirtualPoint;
+    restore?: {
+        offset?: number;
+        point?: VirtualPoint;
+    };
+    stickToEnd?: VirtualStickToEndOptions;
+}
+type VirtualLayoutGap = number | {
+    main?: number;
+    cross?: number;
+};
+type VirtualLayoutPadding = number | {
+    mainStart?: number;
+    mainEnd?: number;
+    crossStart?: number;
+    crossEnd?: number;
+};
+interface VirtualLayoutConfig {
+    mode: LayoutMode;
+    direction?: LayoutDirection;
+    lanes?: number;
+    gap?: VirtualLayoutGap;
+    padding?: VirtualLayoutPadding;
+    crossSize?: number | string;
+}
+interface VirtualMeasurementConfig {
+    axes: MeasurementAxes;
+}
+interface AdaptiveRangeOptions {
+    enabled?: boolean;
+    base?: number | OverscanRange;
+    min?: number;
+    max?: number;
+    lookaheadMs?: number;
+    velocitySmoothing?: number;
+    directionBias?: number;
+    settleMs?: number;
+}
+interface VirtualRangeConfig {
+    overscan?: number | OverscanRange;
+    adaptive?: boolean | AdaptiveRangeOptions;
+    maxItems?: number;
+    maxPx?: number;
+}
+interface VirtualSyncConfig {
+    recenterThreshold?: number;
+    jumpThreshold?: number | ((state: VirtualState) => number);
+    mode?: "raf" | "sync-on-jump";
+}
+interface VirtualContentOptions {
+    count: number;
+    scroll: VirtualScrollOptions;
+    layout: VirtualLayoutConfig;
+    measurement: VirtualMeasurementConfig;
+    range?: VirtualRangeConfig;
+    minSize?: number;
+    sync?: VirtualSyncConfig;
+    estimateRect: (index: number) => VirtualRect;
+    getKey: (index: number) => ItemKey;
+}
+interface VirtualState {
+    count: number;
+    scrollAxis: ScrollAxis;
+    layoutMode: LayoutMode;
+    measurementAxes: MeasurementAxes;
+    viewportSize: number;
+    viewportRect: VirtualRect;
+    scrollOffset: number;
+    scrollPoint: VirtualPoint;
+    viewportCenter: number;
+    viewportCenterPoint: VirtualPoint;
+    centerIndex: number;
+    centerKey?: ItemKey;
+    centerStart: number;
+    centerSize: number;
+    centerRect?: VirtualRect;
+    rangeStart: number;
+    rangeEnd: number;
+    totalSize: number;
+    totalRect: VirtualRect;
+    overscanBefore: number;
+    overscanAfter: number;
+    scrollVelocity: number;
+    scrollDirection: -1 | 0 | 1;
+    adaptiveRangeActive: boolean;
+}
+interface VirtualItem {
+    index: number;
+    key: ItemKey;
+    rect: VirtualRect;
+    start: number;
+    size: number;
+    end: number;
+    offsetFromCenter: number;
+    isMeasured: boolean;
+}
+type VirtualScrollTarget = {
+    index: number;
+    align?: ScrollAlign;
+} | {
+    key: ItemKey;
+    align?: ScrollAlign;
+} | {
+    offset: number;
+} | {
+    point: VirtualPoint;
+} | {
+    rect: VirtualRect;
+    align?: ScrollAlign;
+};
+interface VirtualAnchor {
+    key: ItemKey;
+    index: number;
+    offsetInsideItem: number;
+    offsetInsideRect?: VirtualPoint;
+}
+interface VirtualSnapshot extends VirtualState {
+    items: VirtualItem[];
+}
+type LocateMode = "initial" | "tracked" | "recenter";
+interface VirtualMeasurementResult {
+    delta: number;
+    changed: boolean;
+    stale: boolean;
+    size: number;
+    rect: VirtualRect;
+    correctedScrollOffset: number;
+    correctedScrollPoint: VirtualPoint;
+}
+interface VirtualizerDebugState {
+    lastCenterIndex: number;
+    lastViewportCenter: number | undefined;
+    lastLocateMode: LocateMode;
+    scrollVelocity: number;
+    scrollDirection: -1 | 0 | 1;
+    overscanBefore: number;
+    overscanAfter: number;
+    adaptiveRangeActive: boolean;
+}
+
+declare function createPoint(x?: number, y?: number): VirtualPoint;
+declare function createRect(x?: number, y?: number, width?: number, height?: number): VirtualRect;
+declare function rectsIntersect(a: VirtualRect, b: VirtualRect): boolean;
+declare function expandRect(rect: VirtualRect, overscan: VirtualOverscan, axis: ScrollAxis): VirtualRect;
+declare function rectFromScrollPoint(point: VirtualPoint, size: Pick<VirtualRect, "width" | "height">): VirtualRect;
+
+interface LayoutMeasurementResult {
+    delta: number;
+    changed: boolean;
+    stale: boolean;
+    rect: VirtualRect;
+}
+interface LayoutEngine {
+    readonly count: number;
+    setCount(count: number): void;
+    keyOf(index: number): ItemKey | undefined;
+    indexOfKey(key: ItemKey): number;
+    getTotalRect(): VirtualRect;
+    getVisibleItems(viewport: VirtualRect, overscan: VirtualOverscan): VirtualItem[];
+    getItemRect(index: number): VirtualRect | undefined;
+    getItemMainStart(index: number): number;
+    getItemMainSize(index: number): number;
+    isMeasured(index: number): boolean;
+    measureItem(index: number, key: ItemKey, rect: Partial<VirtualRect>): LayoutMeasurementResult;
+    resetMeasurements(keys?: ItemKey[]): void;
+    getScrollTarget(index: number, align: ScrollAlign, viewport: VirtualRect): VirtualPoint;
+    locateCenter(viewportCenter: VirtualPoint, lastIndex: number, lastViewportCenter: VirtualPoint | undefined, recenterThreshold: number): {
+        index: number;
+        mode: "initial" | "tracked" | "recenter";
+    };
+}
+
+declare class LinearBandEngine implements LayoutEngine {
+    private readonly sizes;
+    private readonly direction;
+    private readonly estimateRect;
+    private readonly configuredCrossSize;
+    private readonly gap;
+    private readonly padding;
+    private crossSizes;
+    constructor(options: VirtualContentOptions);
+    get count(): number;
+    setCount(count: number): void;
+    keyOf(index: number): ItemKey | undefined;
+    indexOfKey(key: ItemKey): number;
+    getTotalRect(): VirtualRect;
+    getVisibleItems(viewport: VirtualRect, overscan: VirtualOverscan): VirtualItem[];
+    getItemRect(index: number): VirtualRect | undefined;
+    getItemMainStart(index: number): number;
+    getItemMainSize(index: number): number;
+    isMeasured(index: number): boolean;
+    measureItem(index: number, key: ItemKey, rect: Partial<VirtualRect>): LayoutMeasurementResult;
+    resetMeasurements(keys?: ItemKey[]): void;
+    getScrollTarget(index: number, align: ScrollAlign, viewport: VirtualRect): VirtualPoint;
+    locateCenter(viewportCenter: VirtualPoint, lastIndex: number, lastViewportCenter: VirtualPoint | undefined, recenterThreshold: number): {
+        index: number;
+        mode: "initial" | "tracked" | "recenter";
+    };
+    private locateAbsolute;
+    private locateTracked;
+    private createItem;
+    private rectFor;
+    private spacing;
+    private totalMainSize;
+    private rebuildCrossSizes;
+}
+
+declare class SpatialRectEngine implements LayoutEngine {
+    private countValue;
+    private readonly getKey;
+    private readonly estimateRect;
+    private readonly mode;
+    private readonly direction;
+    private readonly lanes;
+    private readonly gap;
+    private readonly padding;
+    private readonly minSize;
+    private keys;
+    private sourceRects;
+    private rects;
+    private measured;
+    private measuredRectsByKey;
+    private keyToIndex;
+    constructor(options: VirtualContentOptions);
+    get count(): number;
+    setCount(count: number): void;
+    keyOf(index: number): ItemKey | undefined;
+    indexOfKey(key: ItemKey): number;
+    getTotalRect(): VirtualRect;
+    getVisibleItems(viewport: VirtualRect, overscan: VirtualOverscan): VirtualItem[];
+    getItemRect(index: number): VirtualRect | undefined;
+    getItemMainStart(index: number): number;
+    getItemMainSize(index: number): number;
+    isMeasured(index: number): boolean;
+    measureItem(index: number, key: ItemKey, rect: Partial<VirtualRect>): LayoutMeasurementResult;
+    resetMeasurements(keys?: ItemKey[]): void;
+    getScrollTarget(index: number, align: ScrollAlign, viewport: VirtualRect): VirtualPoint;
+    locateCenter(viewportCenter: VirtualPoint): {
+        index: number;
+        mode: "initial" | "tracked" | "recenter";
+    };
+    private rebuild;
+    private placeMasonryRect;
+    private placeFreeRect;
+    private createItem;
+}
+
+interface ResolvedLayoutGap {
+    main: number;
+    cross: number;
+}
+interface ResolvedLayoutPadding {
+    mainStart: number;
+    mainEnd: number;
+    crossStart: number;
+    crossEnd: number;
+}
+declare function resolveLayoutGap(gap: VirtualLayoutGap | undefined): ResolvedLayoutGap;
+declare function resolveLayoutPadding(padding: VirtualLayoutPadding | undefined): ResolvedLayoutPadding;
+
+interface SizeModelSpacing {
+    gap?: number;
+    paddingStart?: number;
+    paddingEnd?: number;
+}
+interface SizeModelOptions {
+    count: number;
+    estimateSize: (index: number) => number;
+    getKey: (index: number) => ItemKey;
+    minSize?: number;
+}
+interface SizeModelMeasurement {
+    delta: number;
+    changed: boolean;
+    stale: boolean;
+    size: number;
+}
+declare class SizeModel {
+    private countValue;
+    private readonly estimateSize;
+    private readonly getKey;
+    private readonly minSize;
+    private keys;
+    private measured;
+    private measuredSizesByKey;
+    private tree;
+    private keyToIndex;
+    constructor(options: SizeModelOptions);
+    get count(): number;
+    setCount(count: number): void;
+    keyOf(index: number): ItemKey | undefined;
+    indexOfKey(key: ItemKey): number;
+    sizeOf(index: number): number;
+    isMeasured(index: number): boolean;
+    startOf(index: number): number;
+    endOf(index: number): number;
+    spacedStartOf(index: number, spacing?: SizeModelSpacing): number;
+    spacedEndOf(index: number, spacing?: SizeModelSpacing): number;
+    totalSize(): number;
+    spacedTotalSize(spacing?: SizeModelSpacing): number;
+    lowerBound(offset: number): number;
+    spacedLowerBound(offset: number, spacing?: SizeModelSpacing): number;
+    measure(key: ItemKey, index: number, size: number): SizeModelMeasurement;
+    resetMeasurements(keys?: ItemKey[]): void;
+    private rebuild;
+    private normalizeSize;
+}
+
+declare class Virtualizer {
+    private readonly engine;
+    private readonly baseOverscan;
+    private readonly adaptiveRange;
+    private readonly scrollAxis;
+    private readonly layoutMode;
+    private readonly layoutDirection;
+    private readonly measurementAxes;
+    private readonly recenterThreshold;
+    private viewportRect;
+    private scrollPoint;
+    private lastScrollPoint;
+    private lastScrollTime;
+    private lastMovementTime;
+    private scrollVelocity;
+    private scrollDirection;
+    private lastCenterIndex;
+    private lastViewportCenter;
+    private lastLocateMode;
+    constructor(options: VirtualContentOptions);
+    setViewport(size: number): void;
+    setViewportRect(rect: VirtualRect): void;
+    setScrollOffset(offset: number, timestamp?: number): void;
+    setScrollPoint(point: VirtualPoint, timestamp?: number): void;
+    recenter(offsetOrPoint?: number | VirtualPoint): void;
+    setCount(count: number): void;
+    setMeasuredSize(key: ItemKey, index: number, size: number): VirtualMeasurementResult;
+    setMeasuredRect(key: ItemKey, index: number, rect: Partial<VirtualRect>): VirtualMeasurementResult;
+    resetMeasurements(keys?: ItemKey[]): void;
+    getState(): VirtualState;
+    getSnapshot(): VirtualSnapshot;
+    makeAnchor(snapshot?: VirtualSnapshot): VirtualAnchor | undefined;
+    getScrollOffsetForAnchor(anchor: VirtualAnchor): number;
+    getScrollPointForAnchor(anchor: VirtualAnchor): VirtualPoint;
+    scrollToIndex(index: number, align?: ScrollAlign): number;
+    scrollToItem(index: number, align?: ScrollAlign): VirtualPoint;
+    getScrollTarget(index: number, align?: ScrollAlign): VirtualPoint;
+    resolveScrollTarget(target: VirtualScrollTarget): VirtualPoint;
+    scrollToPoint(point: VirtualPoint): VirtualPoint;
+    scrollToRect(rect: VirtualRect, align?: ScrollAlign): VirtualPoint;
+    getDebugState(): VirtualizerDebugState;
+    private createSnapshot;
+    private locateCenter;
+    private updateScrollVelocity;
+    private resetScrollVelocity;
+    private resolveCurrentOverscan;
+    private getViewportCenterPoint;
+    private getRecenterThreshold;
+    private clampScrollPoint;
+    private projectScrollOffset;
+    private projectViewportSize;
+    private projectTotalSize;
+    private projectPoint;
+    private isHorizontalLayoutDirection;
+    private resolveAnchorIndex;
+}
+
+export { type AdaptiveRangeOptions, FenwickTree, type ItemKey, type LayoutDirection, type LayoutEngine, type LayoutMeasurementResult, type LayoutMode, LinearBandEngine, type LocateMode, type MeasurementAxes, type OverscanRange, type ResolvedLayoutGap, type ResolvedLayoutPadding, type ScrollAlign, type ScrollAxis, SizeModel, type SizeModelMeasurement, SpatialRectEngine, type VirtualAnchor, type VirtualContentOptions, type VirtualItem, type VirtualLayoutConfig, type VirtualLayoutGap, type VirtualLayoutPadding, type VirtualMeasurementConfig, type VirtualMeasurementResult, type VirtualOverscan, type VirtualPoint, type VirtualRangeConfig, type VirtualRect, type VirtualScrollOptions, type VirtualScrollTarget, type VirtualSnapshot, type VirtualState, type VirtualStickAxis, type VirtualStickState, type VirtualStickToEndOptions, type VirtualSyncConfig, Virtualizer, type VirtualizerDebugState, createPoint, createRect, expandRect, rectFromScrollPoint, rectsIntersect, resolveLayoutGap, resolveLayoutPadding };