@pdanpdan/virtual-scroll 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import { DefineComponent } from 'vue';
 import { MaybeRefOrGetter } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
+import { ShallowRef } from 'vue';
 import { ShallowUnwrapRef } from 'vue';
 import { VNode } from 'vue';
 import { VNodeChild } from 'vue';
@@ -23,6 +24,17 @@ declare type __VLS_PrettifyLocal<T> = {
  */
 export declare const BROWSER_MAX_SIZE = 10000000;
 
+/**
+ * Helper to calculate total size for a single axis.
+ *
+ * @param count - Item count.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param query - Prefix sum resolver.
+ * @returns Total size.
+ */
+export declare function calculateAxisSize(count: number, fixedSize: number | null, gap: number, query: (index: number) => number): number;
+
 /**
  * Calculates the range of columns to render for bidirectional scroll.
  *
@@ -47,6 +59,64 @@ export declare function calculateColumnRange({ columnCount, relativeScrollX, usa
     padEnd: number;
 };
 
+/**
+ * Helper to get the index at a virtual offset.
+ *
+ * @param offset - Virtual offset.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param findLowerBound - Binary search resolver.
+ * @returns Index at offset.
+ */
+export declare function calculateIndexAt(offset: number, fixedSize: number | null, gap: number, findLowerBound: (offset: number) => number): number;
+
+/**
+ * Calculates the next step in an inertia animation.
+ *
+ * @param velocity - Current velocity.
+ * @param velocity.x - Horizontal velocity.
+ * @param velocity.y - Vertical velocity.
+ * @param friction - Friction coefficient (0-1).
+ * @param frameTime - Time elapsed since last frame in ms (default 16ms).
+ * @returns Next velocity and distance to move.
+ */
+export declare function calculateInertiaStep(velocity: {
+    x: number;
+    y: number;
+}, friction: number, frameTime?: number): {
+    nextVelocity: {
+        x: number;
+        y: number;
+    };
+    delta: {
+        x: number;
+        y: number;
+    };
+};
+
+/**
+ * Calculates instantaneous velocity from position change.
+ *
+ * @param lastPos - Previous position.
+ * @param lastPos.x - Horizontal position.
+ * @param lastPos.y - Vertical position.
+ * @param currentPos - Current position.
+ * @param currentPos.x - Horizontal position.
+ * @param currentPos.y - Vertical position.
+ * @param dt - Time delta in ms.
+ * @returns Calculated velocity {x, y}.
+ */
+export declare function calculateInstantaneousVelocity(lastPos: {
+    x: number;
+    y: number;
+}, currentPos: {
+    x: number;
+    y: number;
+}, dt: number): {
+    x: number;
+    y: number;
+};
+
 /**
  * Calculates the position and size of a single item.
  *
@@ -91,6 +161,26 @@ export declare function calculateItemPosition({ index, direction, fixedSize, gap
  */
 export declare function calculateItemStyle<T = unknown>({ item, direction, itemSize, containerTag, paddingStartX, paddingStartY, isHydrated, isRtl, }: ItemStyleParams<T>): Record<string, string | number | undefined>;
 
+/**
+ * Helper to calculate offset at a specific index.
+ *
+ * @param index - Item index.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param query - Prefix sum resolver.
+ * @returns Offset at index.
+ */
+export declare function calculateOffsetAt(index: number, fixedSize: number | null, gap: number, query: (index: number) => number): number;
+
+/**
+ * Detects how many items were prepended to the list based on item identity.
+ *
+ * @param oldItems - Previous items list.
+ * @param newItems - Current items list.
+ * @returns Number of prepended items.
+ */
+export declare function calculatePrependCount<T>(oldItems: T[], newItems: T[]): number;
+
 /**
  * Calculates the range of items to render based on scroll position and viewport size.
  *
@@ -118,6 +208,37 @@ export declare function calculateRange({ direction, relativeScrollX, relativeScr
     end: number;
 };
 
+/**
+ * Helper to calculate size for a range on a single axis.
+ *
+ * @param start - Start index.
+ * @param end - End index.
+ * @param fixedSize - Fixed size if any.
+ * @param gap - Gap size.
+ * @param query - Prefix sum resolver.
+ * @returns Range size.
+ */
+export declare function calculateRangeSize(start: number, end: number, fixedSize: number | null, gap: number, query: (index: number) => number): number;
+
+/**
+ * Calculates the physical size to be rendered in the DOM.
+ *
+ * @param isWindow - If the container is the window.
+ * @param totalSize - Total virtual size (VU).
+ * @returns Physical size (DU).
+ */
+export declare function calculateRenderedSize(isWindow: boolean, totalSize: number): number;
+
+/**
+ * Calculates the coordinate scaling factor between virtual and display units.
+ *
+ * @param isWindow - If the container is the window.
+ * @param totalSize - Total virtual size (VU).
+ * @param viewportSize - Viewport size (DU).
+ * @returns Scaling factor (VU/DU).
+ */
+export declare function calculateScale(isWindow: boolean, totalSize: number, viewportSize: number): number;
+
 /**
  * Calculates the target scroll position (relative to content) for a given row/column index and alignment.
  *
@@ -163,6 +284,25 @@ export declare function calculateRange({ direction, relativeScrollX, relativeScr
  */
 export declare function calculateScrollTarget({ rowIndex, colIndex, options, direction, viewportWidth, viewportHeight, totalWidth, totalHeight, gap, columnGap, fixedSize, fixedWidth, relativeScrollX, relativeScrollY, getItemSizeY, getItemSizeX, getItemQueryY, getItemQueryX, getColumnSize, getColumnQuery, scaleX, scaleY, hostOffsetX, hostOffsetY, stickyIndices, stickyStartX, stickyStartY, stickyEndX, stickyEndY, flowPaddingStartX, flowPaddingStartY, paddingStartX, paddingStartY, paddingEndX, paddingEndY, }: ScrollTargetParams): ScrollTargetResult;
 
+/**
+ * Calculates the SSR offsets for items based on the configured SSR range and direction.
+ *
+ * @param direction - Scroll direction.
+ * @param ssrRange - SSR configuration.
+ * @param fixedItemSize - Fixed item size (VU).
+ * @param fixedColumnWidth - Fixed column width (VU).
+ * @param gap - Item gap (VU).
+ * @param columnGap - Column gap (VU).
+ * @param queryY - Resolver for vertical offset (VU).
+ * @param queryX - Resolver for horizontal offset (VU).
+ * @param queryColumn - Resolver for column offset (VU).
+ * @returns Offset X and Y (VU).
+ */
+export declare function calculateSSROffsets(direction: ScrollDirection, ssrRange: SSRRange, fixedItemSize: number | null, fixedColumnWidth: number | null, gap: number, columnGap: number, queryY: (index: number) => number, queryX: (index: number) => number, queryColumn: (index: number) => number): {
+    x: number;
+    y: number;
+};
+
 /**
  * Calculates the sticky state and offset for a single item.
  *
@@ -372,42 +512,42 @@ export declare type GetItemAriaProps = (index: number) => Record<string, string
 /**
  * Extracts the horizontal padding from a padding configuration.
  *
- * @param p - The padding value (number or object with x/y).
+ * @param p - The padding value (number or object with x/y). Optional.
  * @param direction - The current scroll direction.
  * @returns The horizontal padding in pixels.
  */
-export declare function getPaddingX(p: number | {
+export declare function getPaddingX(p?: number | {
     x?: number;
     y?: number;
-} | undefined, direction?: ScrollDirection): number;
+} | null, direction?: ScrollDirection): number;
 
 /**
  * Extracts the vertical padding from a padding configuration.
  *
- * @param p - The padding value (number or object with x/y).
+ * @param p - The padding value (number or object with x/y). Optional.
  * @param direction - The current scroll direction.
  * @returns The vertical padding in pixels.
  */
-export declare function getPaddingY(p: number | {
+export declare function getPaddingY(p?: number | {
     x?: number;
     y?: number;
-} | undefined, direction?: ScrollDirection): number;
+} | null, direction?: ScrollDirection): number;
 
 /**
  * Checks if the container is the document body element.
  *
- * @param container - The container element or window to check.
+ * @param container - The container element or window to check. Optional.
  * @returns `true` if the container is the `<body>` element.
  */
-export declare function isBody(container: HTMLElement | Window | null | undefined): container is HTMLElement;
+export declare function isBody(container?: HTMLElement | Window | null): container is HTMLElement;
 
 /**
  * Checks if the container is a valid HTML Element with bounding rect support.
  *
- * @param container - The container to check.
+ * @param container - The container to check. Optional.
  * @returns `true` if the container is an `HTMLElement`.
  */
-export declare function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement;
+export declare function isElement(container?: HTMLElement | Window | null): container is HTMLElement;
 
 /**
  * Determines if an item is visible within the usable viewport.
@@ -425,10 +565,10 @@ export declare function isItemVisible(itemPos: number, itemSize: number, scrollP
 /**
  * Checks if the target is an element that supports scrolling.
  *
- * @param target - The event target to check.
+ * @param target - The event target to check. Optional.
  * @returns `true` if the target is an `HTMLElement` with scroll properties.
  */
-export declare function isScrollableElement(target: EventTarget | null): target is HTMLElement;
+export declare function isScrollableElement(target?: EventTarget | null): target is HTMLElement;
 
 /**
  * Helper to determine if an options argument is a full `ScrollToIndexOptions` object.
@@ -441,18 +581,18 @@ export declare function isScrollToIndexOptions(options: unknown): options is Scr
 /**
  * Checks if the container is the window object.
  *
- * @param container - The container element or window to check.
+ * @param container - The container element or window to check. Optional.
  * @returns `true` if the container is the global window object.
  */
-export declare function isWindow(container: HTMLElement | Window | null | undefined): container is Window;
+export declare function isWindow(container?: HTMLElement | Window | null): container is Window;
 
 /**
  * Checks if the container is window-like (global window or document body).
  *
- * @param container - The container element or window to check.
+ * @param container - The container element or window to check. Optional.
  * @returns `true` if the container is window or body.
  */
-export declare function isWindowLike(container: HTMLElement | Window | null | undefined): boolean;
+export declare function isWindowLike(container?: HTMLElement | Window | null): boolean;
 
 /** Parameters for calculating an item's position and size. */
 export declare interface ItemPositionParams {
@@ -619,6 +759,23 @@ export declare interface RenderedItem<T = unknown> {
     stickyOffset: Point;
 }
 
+/**
+ * Resolves the target index and alignment for snapping on a single axis.
+ *
+ * @param mode - The snap mode ('start', 'center', 'end', 'auto').
+ * @param dir - The scroll direction on this axis.
+ * @param currentIdx - The current first visible index.
+ * @param currentEndIdx - The current last visible index.
+ * @param relScroll - The current virtual scroll offset.
+ * @param viewSize - The viewport dimension.
+ * @param count - Total number of items/columns.
+ * @param getSize - Resolver for item size.
+ * @param getQuery - Resolver for item prefix sum.
+ * @param getIndexAt - Resolver for index at a virtual offset.
+ * @returns Snap result or null.
+ */
+export declare function resolveSnap(mode: SnapMode, dir: 'start' | 'end' | null, currentIdx: number, currentEndIdx: number, relScroll: number, viewSize: number, count: number, getSize: (i: number) => number, getQuery: (i: number) => number, getIndexAt: (o: number) => number): SnapResult | null;
+
 /**
  * Alignment of an item within the viewport after a scroll operation.
  * - 'start': Aligns item to the top or left edge.
@@ -840,6 +997,25 @@ export declare interface Size {
     height: number;
 }
 
+/**
+ * Snap mode for automatic alignment after scrolling stops.
+ * - `false`: No snapping.
+ * - `true`: Same as 'auto'.
+ * - 'start': Aligns the first visible item to the viewport start if at least 50% visible, otherwise aligns the next item.
+ * - 'center': Aligns the item that intersects the viewport center to the center.
+ * - 'end': Aligns the last visible item to the viewport end if at least 50% visible, otherwise aligns the previous item.
+ * - 'auto': Intelligent snapping based on scroll direction. Acts as 'end' when scrolling towards start, and 'start' when scrolling towards end.
+ */
+export declare type SnapMode = boolean | 'start' | 'center' | 'end' | 'auto';
+
+/** Snap result. */
+export declare interface SnapResult {
+    /** Target index. */
+    index: number;
+    /** Alignment. */
+    align: 'start' | 'center' | 'end';
+}
+
 /**
  * Configuration for Server-Side Rendering.
  * Defines which items are rendered statically on the server.
@@ -1006,7 +1182,7 @@ export declare function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGett
      * @see ScrollAlignment
      * @see ScrollToIndexOptions
      */
-    scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
     /**
      * Programmatically scroll to a specific pixel offset relative to the content start.
      *
@@ -1100,15 +1276,23 @@ export declare function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGett
      * Physical height of the items wrapper in the DOM (clamped to browser limits, in DU).
      */
     renderedVirtualHeight: ComputedRef<number>;
+    /**
+     * Helper to get the row index at a specific virtual offset.
+     */
+    getRowIndexAt: (offset: number) => number;
+    /**
+     * Helper to get the column index at a specific virtual offset.
+     */
+    getColIndexAt: (offset: number) => number;
 };
 
 /**
  * Composable for virtual scrollbar logic.
  * Provides attributes and event listeners for track and thumb elements.
  *
- * @param props - Configuration properties.
+ * @param propsInput - Configuration properties.
  */
-export declare function useVirtualScrollbar(props: UseVirtualScrollbarProps): {
+export declare function useVirtualScrollbar(propsInput: MaybeRefOrGetter<UseVirtualScrollbarProps>): {
     /** Viewport size as a percentage of total size (0 to 1). */
     viewportPercent: ComputedRef<number>;
     /** Current scroll position as a percentage of the scrollable range (0 to 1). */
@@ -1185,24 +1369,80 @@ export declare function useVirtualScrollbar(props: UseVirtualScrollbarProps): {
 /** Configuration properties for the `useVirtualScrollbar` composable. */
 export declare interface UseVirtualScrollbarProps {
     /** The axis for this scrollbar. */
-    axis: MaybeRefOrGetter<ScrollAxis>;
+    axis: ScrollAxis;
     /** Total size of the scrollable content area in display pixels (DU). */
-    totalSize: MaybeRefOrGetter<number>;
+    totalSize: number;
     /** Current scroll position in display pixels (DU). */
-    position: MaybeRefOrGetter<number>;
+    position: number;
     /** Viewport size in display pixels (DU). */
-    viewportSize: MaybeRefOrGetter<number>;
+    viewportSize: number;
     /**
      * Function to scroll to a specific display pixel offset (DU) on this axis.
      * @param offset - The display pixel offset to scroll to.
      */
     scrollToOffset: (offset: number) => void;
     /** The ID of the container element this scrollbar controls. */
-    containerId?: MaybeRefOrGetter<string | undefined>;
+    containerId?: string | undefined;
     /** Whether the scrollbar is in Right-to-Left (RTL) mode. */
-    isRtl?: MaybeRefOrGetter<boolean>;
+    isRtl?: boolean;
     /** Accessible label for the scrollbar. */
-    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabel?: string | undefined;
+}
+
+/**
+ * Composable for managing item and column sizes using Fenwick Trees.
+ * Handles prefix sum calculations, size updates, and scroll correction adjustments.
+ */
+export declare function useVirtualScrollSizes<T>(propsInput: MaybeRefOrGetter<UseVirtualScrollSizesProps<T>>): {
+    /** Fenwick Tree for horizontal item sizes. */
+    itemSizesX: FenwickTree;
+    /** Fenwick Tree for vertical item sizes. */
+    itemSizesY: FenwickTree;
+    /** Fenwick Tree for column widths. */
+    columnSizes: FenwickTree;
+    /** Measured item widths. */
+    measuredItemsX: ShallowRef<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    /** Measured item heights. */
+    measuredItemsY: ShallowRef<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    /** Measured column widths. */
+    measuredColumns: ShallowRef<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    /** Flag that updates when any tree changes. */
+    treeUpdateFlag: Ref<number, number>;
+    /** Whether sizes have been initialized. */
+    sizesInitialized: Ref<boolean, boolean>;
+    /** Base size of an item from props. */
+    getItemBaseSize: (item: T, index: number) => number;
+    /** Helper to get current size at index. */
+    getSizeAt: (index: number, sizeProp: number | number[] | ((...args: any[]) => number) | null | undefined, defaultSize: number, gap: number, tree: FenwickTree, isX: boolean) => number;
+    /** Initialize or update sizes from props. */
+    initializeSizes: (onScrollCorrection?: (addedX: number, addedY: number) => void) => void;
+    /** Update sizes of multiple items from measurements. */
+    updateItemSizes: (updates: Array<{
+        index: number;
+        inlineSize: number;
+        blockSize: number;
+        element?: HTMLElement | undefined;
+    }>, getRowIndexAt: (offset: number) => number, getColIndexAt: (offset: number) => number, relativeScrollX: number, relativeScrollY: number, onScrollCorrection: (deltaX: number, deltaY: number) => void) => void;
+    /** Reset all measurements. */
+    refresh: (onScrollCorrection?: (addedX: number, addedY: number) => void) => void;
+};
+
+/**
+ * Configuration properties for the `useVirtualScrollSizes` composable.
+ */
+export declare interface UseVirtualScrollSizesProps<T> {
+    /** Reactive reference to the virtual scroll configuration. */
+    props: VirtualScrollProps<T>;
+    /** Whether items have dynamic heights/widths. */
+    isDynamicItemSize: boolean;
+    /** Whether columns have dynamic widths. */
+    isDynamicColumnWidth: boolean;
+    /** Fallback size for items before they are measured. */
+    defaultSize: number;
+    /** Fixed item size if applicable. */
+    fixedItemSize: number | null;
+    /** Scroll direction. */
+    direction: 'vertical' | 'horizontal' | 'both';
 }
 
 export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
@@ -1281,16 +1521,28 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     */
     getItemSize: (index: number) => number;
     /**
+    * Helper to get the row (or item) index at a specific vertical (or horizontal in horizontal mode) virtual offset (VU).
+    * @param offset - The virtual pixel offset.
+    * @see useVirtualScroll
+    */
+    getRowIndexAt: (offset: number) => number;
+    /**
+    * Helper to get the column index at a specific horizontal virtual offset (VU).
+    * @param offset - The virtual pixel offset.
+    * @see useVirtualScroll
+    */
+    getColIndexAt: (offset: number) => number;
+    /**
     * Programmatically scroll to a specific row and/or column.
     *
-    * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
-    * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
+    * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally. Optional.
+    * @param colIndex - The column index to scroll to. Pass null to only scroll vertically. Optional.
     * @param options - Alignment and behavior options. Defaults to { align: 'auto', behavior: 'auto' }.
     * @see ScrollAlignment
     * @see ScrollToIndexOptions
     * @see useVirtualScroll
     */
-    scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
     /**
     * Programmatically scroll to a specific pixel offset.
     *
@@ -1369,6 +1621,7 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     role: Ref<string | undefined, string | undefined>;
     ariaLabel: Ref<string | undefined, string | undefined>;
     ariaLabelledby: Ref<string | undefined, string | undefined>;
+    snap: Ref<SnapMode | undefined, SnapMode | undefined>;
     direction: Ref<ScrollDirection, ScrollDirection>;
     bufferBefore: Ref<number, number>;
     bufferAfter: Ref<number, number>;
@@ -1563,7 +1816,7 @@ export declare interface VirtualScrollBaseProps<T = unknown> {
      */
     gap?: number | undefined;
     /**
-     * Gap between columns in VU.
+     * Gap between columns in virtual units (VU).
      * Applied in horizontal and bidirectional grid modes.
      */
     columnGap?: number | undefined;
@@ -1624,6 +1877,11 @@ export declare interface VirtualScrollBaseProps<T = unknown> {
      * Set to 'none' or 'presentation' to disable automatic role assignment on the wrapper.
      */
     itemRole?: string | undefined;
+    /**
+     * Whether to snap to items after scrolling stops.
+     * @default false
+     */
+    snap?: SnapMode | undefined;
 }
 
 /** Configuration properties for the `VirtualScroll` component. */
@@ -1654,6 +1912,12 @@ export declare interface VirtualScrollInstance<T = unknown> extends VirtualScrol
     getRowHeight: (index: number) => number;
     /** Helper to get ARIA attributes for a cell. */
     getCellAriaProps: (colIndex: number) => Record<string, string | number | undefined>;
+    /** Helper to get ARIA attributes for an item. */
+    getItemAriaProps: (index: number) => Record<string, string | number | undefined>;
+    /** The ARIA role of the items wrapper. */
+    wrapperRole: string | null;
+    /** The ARIA role of each cell. */
+    cellRole: string | null;
     /** Helper to get the virtual offset of a specific row. */
     getRowOffset: (index: number) => number;
     /** Helper to get the virtual offset of a specific column. */
@@ -1663,7 +1927,7 @@ export declare interface VirtualScrollInstance<T = unknown> extends VirtualScrol
     /** Helper to get the size of a specific item along the scroll axis. */
     getItemSize: (index: number) => number;
     /** Programmatically scroll to a specific row and/or column. */
-    scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
     /** Programmatically scroll to a specific pixel offset. */
     scrollToOffset: (x?: number | null, y?: number | null, options?: {
         behavior?: 'auto' | 'smooth';