@pdanpdan/virtual-scroll 0.1.0 → 0.2.0

package/dist/index.css

@@ -1 +1,2 @@
-.virtual-scroll-container[data-v-654a1d54]{position:relative;block-size:100%;inline-size:100%;outline-offset:1px}.virtual-scroll-container[data-v-654a1d54]:not(.virtual-scroll--window){overflow:auto;overscroll-behavior:contain}.virtual-scroll-container.virtual-scroll--table[data-v-654a1d54]{display:block}.virtual-scroll--horizontal[data-v-654a1d54]{white-space:nowrap}.virtual-scroll-wrapper[data-v-654a1d54]{contain:layout;position:relative}:where(.virtual-scroll--hydrated>.virtual-scroll-wrapper>.virtual-scroll-item[data-v-654a1d54]){position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-item[data-v-654a1d54]{box-sizing:border-box;will-change:transform}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-654a1d54]{outline:1px dashed rgba(255,0,0,.5);background-color:#ff00000d}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-654a1d54]:where(:hover){background-color:#ff00001a;z-index:100}.virtual-scroll-debug-info[data-v-654a1d54]{position:absolute;inset-block-start:2px;inset-inline-end:2px;background:#000000b3;color:#fff;font-size:10px;padding:2px 4px;border-radius:4px;pointer-events:none;z-index:100;font-family:monospace}.virtual-scroll-spacer[data-v-654a1d54]{pointer-events:none}.virtual-scroll-header[data-v-654a1d54],.virtual-scroll-footer[data-v-654a1d54]{position:relative;z-index:20}.virtual-scroll--sticky[data-v-654a1d54]{position:sticky}.virtual-scroll--sticky[data-v-654a1d54]:where(.virtual-scroll-header){inset-block-start:0;inset-inline-start:0;min-inline-size:100%;box-sizing:border-box}.virtual-scroll--sticky[data-v-654a1d54]:where(.virtual-scroll-footer){inset-block-end:0;inset-inline-start:0;min-inline-size:100%;box-sizing:border-box}.virtual-scroll--sticky[data-v-654a1d54]:where(.virtual-scroll-item){z-index:10}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-654a1d54]{display:inline-flex;min-inline-size:100%}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-654a1d54]>tr{display:inline-flex;min-inline-size:100%}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-654a1d54]>tr>:is(td,th){display:inline-block;align-items:center}
+.virtual-scroll-container[data-v-8d960026]{outline-offset:1px;block-size:100%;inline-size:100%;position:relative}.virtual-scroll-container[data-v-8d960026]:not(.virtual-scroll--window){overscroll-behavior:contain;overflow:auto}.virtual-scroll-container.virtual-scroll--table[data-v-8d960026]{display:block}.virtual-scroll--horizontal[data-v-8d960026]{white-space:nowrap}.virtual-scroll-wrapper[data-v-8d960026]{contain:layout;position:relative}:where(.virtual-scroll--hydrated>.virtual-scroll-wrapper>.virtual-scroll-item[data-v-8d960026]){position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-item[data-v-8d960026]{box-sizing:border-box;will-change:transform}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-8d960026]{background-color:#ff00000d;outline:1px dashed #ff000080}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-8d960026]:where(:hover){z-index:100;background-color:#ff00001a}.virtual-scroll-debug-info[data-v-8d960026]{color:#fff;pointer-events:none;z-index:100;background:#000000b3;border-radius:4px;padding:2px 4px;font-family:monospace;font-size:10px;position:absolute;inset-block-start:2px;inset-inline-end:2px}.virtual-scroll-spacer[data-v-8d960026]{pointer-events:none}.virtual-scroll-header[data-v-8d960026],.virtual-scroll-footer[data-v-8d960026]{z-index:20;position:relative}.virtual-scroll--sticky[data-v-8d960026]{position:sticky}.virtual-scroll--sticky[data-v-8d960026]:where(.virtual-scroll-header){box-sizing:border-box;min-inline-size:100%;inset-block-start:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-8d960026]:where(.virtual-scroll-footer){box-sizing:border-box;min-inline-size:100%;inset-block-end:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-8d960026]:where(.virtual-scroll-item){z-index:10}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-8d960026]{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-8d960026]>tr{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-8d960026]>tr>:is(td,th){align-items:center;display:inline-block}
+/*$vite$:1*/

package/dist/index.d.ts

@@ -0,0 +1,476 @@
+import { AllowedComponentProps } from 'vue';
+import { ComponentCustomProps } from 'vue';
+import { ComputedRef } from 'vue';
+import { PublicProps } from 'vue';
+import { Ref } from 'vue';
+import { ShallowUnwrapRef } from 'vue';
+import { VNode } from 'vue';
+import { VNodeProps } from 'vue';
+
+declare type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+export declare const DEFAULT_BUFFER = 5;
+
+export declare const DEFAULT_COLUMN_WIDTH = 150;
+
+export declare const DEFAULT_ITEM_SIZE = 50;
+
+/**
+ * Fenwick Tree (Binary Indexed Tree) implementation for efficient
+ * prefix sum calculations and updates.
+ */
+export declare class FenwickTree {
+    private tree;
+    private values;
+    constructor(size: number);
+    /**
+     * Update the value at a specific index and propagate changes.
+     * @param index 0-based index
+     * @param delta The change in value (new value - old value)
+     */
+    update(index: number, delta: number): void;
+    /**
+     * Get the prefix sum up to a specific index (exclusive).
+     * @param index 0-based index. query(n) returns sum of values from 0 to n-1.
+     * @returns Sum of values in range [0, index)
+     */
+    query(index: number): number;
+    /**
+     * Set the individual value at an index without updating the tree.
+     * Call rebuild() after multiple sets to update the tree efficiently.
+     */
+    set(index: number, value: number): void;
+    /**
+     * Get the number of items in the tree.
+     */
+    get length(): number;
+    /**
+     * Get the individual value at an index.
+     */
+    get(index: number): number;
+    /**
+     * Get the underlying values array.
+     */
+    getValues(): Readonly<Float64Array>;
+    /**
+     * Find the largest index such that the prefix sum is less than or equal to the given value.
+     * Useful for finding which item is at a specific scroll offset.
+     * @param value The prefix sum value to search for
+     * @returns The 0-based index
+     */
+    findLowerBound(value: number): number;
+    /**
+     * Rebuild the entire tree from the current values array in O(N).
+     * Useful after bulk updates to the values array.
+     */
+    rebuild(): void;
+    /**
+     * Resize the tree while preserving existing values.
+     * @param size New size of the tree
+     */
+    resize(size: number): void;
+    /**
+     * Shift values by a given offset and rebuild the tree.
+     * Useful when items are prepended to the list.
+     * @param offset Number of positions to shift (positive for prepending)
+     */
+    shift(offset: number): void;
+}
+
+/**
+ * Extracts the horizontal padding from a padding value or object.
+ *
+ * @param p - The padding value (number or object with x/y).
+ * @param direction - The current scroll direction.
+ * @returns The horizontal padding in pixels.
+ */
+export declare function getPaddingX(p: number | {
+    x?: number;
+    y?: number;
+} | undefined, direction?: ScrollDirection): number;
+
+/**
+ * Extracts the vertical padding from a padding value or object.
+ *
+ * @param p - The padding value (number or object with x/y).
+ * @param direction - The current scroll direction.
+ * @returns The vertical padding in pixels.
+ */
+export declare function getPaddingY(p: number | {
+    x?: number;
+    y?: number;
+} | undefined, direction?: ScrollDirection): number;
+
+/**
+ * Checks if the container has a bounding client rect method.
+ *
+ * @param container - The container element or window to check.
+ * @returns True if the container is an HTMLElement with getBoundingClientRect.
+ */
+export declare function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement;
+
+/**
+ * Checks if the target is an element with scroll properties.
+ *
+ * @param target - The event target to check.
+ * @returns True if the target is an HTMLElement with scroll properties.
+ */
+export declare function isScrollableElement(target: EventTarget | null): target is HTMLElement;
+
+/**
+ * Helper to determine if an options argument is the full ScrollToIndexOptions object.
+ *
+ * @param options - The options object to check.
+ * @returns True if the options object contains scroll-to-index specific properties.
+ */
+export declare function isScrollToIndexOptions(options: unknown): options is ScrollToIndexOptions;
+
+declare interface Props<T = unknown> {
+    /** Array of items to be virtualized. */
+    items: T[];
+    /** Fixed size of each item or a function that returns the size of an item. Pass 0, null or undefined for dynamic size detection. */
+    itemSize?: number | ((item: T, index: number) => number) | null;
+    /** Direction of the scroll: 'vertical', 'horizontal', or 'both' (grid). */
+    direction?: 'vertical' | 'horizontal' | 'both';
+    /** Number of items to render before the visible viewport. */
+    bufferBefore?: number;
+    /** Number of items to render after the visible viewport. */
+    bufferAfter?: number;
+    /** The scrollable container element or window. If not provided, the host element is used. */
+    container?: HTMLElement | Window | null;
+    /** Range of items to render for SSR. */
+    ssrRange?: {
+        start: number;
+        end: number;
+        colStart?: number;
+        colEnd?: number;
+    };
+    /** Number of columns for bidirectional (grid) scroll. */
+    columnCount?: number;
+    /** Fixed width of columns or an array/function for column widths. Pass 0, null or undefined for dynamic width. */
+    columnWidth?: number | number[] | ((index: number) => number) | null;
+    /** The HTML tag to use for the container. */
+    containerTag?: string;
+    /** The HTML tag to use for the items wrapper. */
+    wrapperTag?: string;
+    /** The HTML tag to use for each item. */
+    itemTag?: string;
+    /** Padding at the start of the scroll container. */
+    scrollPaddingStart?: number | {
+        x?: number;
+        y?: number;
+    };
+    /** Padding at the end of the scroll container. */
+    scrollPaddingEnd?: number | {
+        x?: number;
+        y?: number;
+    };
+    /** Whether the header slot content is sticky and should be accounted for in scroll padding. If true, header size is automatically measured. */
+    stickyHeader?: boolean;
+    /** Whether the footer slot content is sticky and should be accounted for in scroll padding. If true, footer size is automatically measured. */
+    stickyFooter?: boolean;
+    /** Gap between items in pixels (vertical). */
+    gap?: number;
+    /** Gap between columns in pixels (horizontal/grid). */
+    columnGap?: number;
+    /** Indices of items that should stick to the top/start. Supports iOS-style pushing effect. */
+    stickyIndices?: number[];
+    /** Distance from the end of the scrollable area to trigger 'load' event in pixels. */
+    loadDistance?: number;
+    /** Whether items are currently being loaded. Prevents multiple 'load' events and shows 'loading' slot. */
+    loading?: boolean;
+    /** Whether to automatically restore scroll position when items are prepended to the list. */
+    restoreScrollOnPrepend?: boolean;
+    /** Initial scroll index to jump to on mount. */
+    initialScrollIndex?: number;
+    /** Alignment for the initial scroll index. */
+    initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions;
+    /** Default size for items before they are measured. */
+    defaultItemSize?: number;
+    /** Default width for columns before they are measured. */
+    defaultColumnWidth?: number;
+    /** Whether to show debug information (buffers and offsets). */
+    debug?: boolean;
+}
+
+export declare interface RenderedItem<T = unknown> {
+    item: T;
+    index: number;
+    offset: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    originalX: number;
+    originalY: number;
+    isSticky?: boolean;
+    isStickyActive?: boolean;
+    stickyOffset: {
+        x: number;
+        y: number;
+    };
+}
+
+export declare type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
+
+export declare interface ScrollAlignmentOptions {
+    x?: ScrollAlignment;
+    y?: ScrollAlignment;
+}
+
+export declare interface ScrollDetails<T = unknown> {
+    items: RenderedItem<T>[];
+    currentIndex: number;
+    currentColIndex: number;
+    scrollOffset: {
+        x: number;
+        y: number;
+    };
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    totalSize: {
+        width: number;
+        height: number;
+    };
+    isScrolling: boolean;
+    isProgrammaticScroll: boolean;
+    /** Range of items currently being rendered */
+    range: {
+        start: number;
+        end: number;
+    };
+    /** Range of columns currently being rendered (for grid mode) */
+    columnRange: {
+        start: number;
+        end: number;
+        padStart: number;
+        padEnd: number;
+    };
+}
+
+export declare type ScrollDirection = 'vertical' | 'horizontal' | 'both';
+
+export declare interface ScrollToIndexOptions {
+    align?: ScrollAlignment | ScrollAlignmentOptions;
+    behavior?: 'auto' | 'smooth';
+    isCorrection?: boolean;
+}
+
+/**
+ * Composable for virtual scrolling logic.
+ * Handles calculation of visible items, scroll events, and dynamic item sizes.
+ *
+ * @param props - Reactive properties for virtual scroll configuration
+ */
+export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>): {
+    /**
+     * Array of items to be rendered with their calculated offsets and sizes.
+     */
+    renderedItems: ComputedRef<RenderedItem<T>[]>;
+    /**
+     * Total calculated width of all items including gaps.
+     */
+    totalWidth: ComputedRef<number>;
+    /**
+     * Total calculated height of all items including gaps.
+     */
+    totalHeight: ComputedRef<number>;
+    /**
+     * Detailed information about the current scroll state.
+     * Includes currentIndex, scrollOffset, viewportSize, totalSize, and isScrolling.
+     */
+    scrollDetails: ComputedRef<ScrollDetails<T>>;
+    /**
+     * Programmatically scroll to a specific row and/or column.
+     * @param rowIndex - The row index to scroll to
+     * @param colIndex - The column index to scroll to
+     * @param options - Alignment and behavior options
+     */
+    scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    /**
+     * Programmatically scroll to a specific pixel offset.
+     * @param x - The pixel offset to scroll to on the X axis
+     * @param y - The pixel offset to scroll to on the Y axis
+     * @param options - Behavior options
+     */
+    scrollToOffset: (x?: number | null, y?: number | null, options?: {
+        behavior?: "auto" | "smooth";
+    }) => void;
+    /**
+     * Stops any currently active programmatic scroll and clears pending corrections.
+     */
+    stopProgrammaticScroll: () => void;
+    /**
+     * Updates the stored size of an item. Should be called when an item is measured (e.g., via ResizeObserver).
+     * @param index - The item index
+     * @param width - The measured width
+     * @param height - The measured height
+     * @param element - The measured element (optional, used for grid column detection)
+     */
+    updateItemSize: (index: number, inlineSize: number, blockSize: number, element?: HTMLElement) => void;
+    /**
+     * Updates the stored size of multiple items. Should be called when items are measured (e.g., via ResizeObserver).
+     * @param updates - Array of item updates
+     */
+    updateItemSizes: (updates: Array<{
+        index: number;
+        inlineSize: number;
+        blockSize: number;
+        element?: HTMLElement | undefined;
+    }>) => void;
+    /**
+     * Recalculates the host element's offset relative to the scroll container.
+     */
+    updateHostOffset: () => void;
+    /**
+     * Information about the current visible range of columns.
+     */
+    columnRange: ComputedRef<    {
+    start: number;
+    end: number;
+    padStart: number;
+    padEnd: number;
+    }>;
+    /**
+     * Helper to get the width of a specific column based on current configuration.
+     * @param index - The column index
+     */
+    getColumnWidth: (index: number) => number;
+    /**
+     * Resets all dynamic measurements and re-initializes from props.
+     */
+    refresh: () => void;
+    /**
+     * Whether the component has finished its first client-side mount and hydration.
+     */
+    isHydrated: Ref<boolean, boolean>;
+};
+
+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<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onLoad?: (direction: "vertical" | "horizontal") => any;
+        readonly onScroll?: (details: ScrollDetails<T>) => any;
+        readonly onVisibleRangeChange?: (range: {
+            start: number;
+            end: number;
+            colStart: number;
+            colEnd: number;
+        }) => any;
+    } & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, "onLoad" | "onScroll" | "onVisibleRangeChange"> & Props<T> & Partial<{}>> & PublicProps;
+    expose(exposed: ShallowUnwrapRef<    {
+    scrollDetails: ComputedRef<ScrollDetails<T>>;
+    columnRange: ComputedRef<    {
+    start: number;
+    end: number;
+    padStart: number;
+    padEnd: number;
+    }>;
+    getColumnWidth: (index: number) => number;
+    scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    scrollToOffset: (x?: number | null, y?: number | null, options?: {
+    behavior?: "auto" | "smooth";
+    } | undefined) => void;
+    refresh: () => void;
+    stopProgrammaticScroll: () => void;
+    }>): void;
+    attrs: any;
+    slots: {
+        header?(_: {}): any;
+        item?(_: {
+            item: T;
+            index: number;
+            columnRange: {
+                start: number;
+                end: number;
+                padStart: number;
+                padEnd: number;
+            };
+            getColumnWidth: (index: number) => number;
+            isSticky: boolean | undefined;
+            isStickyActive: boolean | undefined;
+        }): any;
+        loading?(_: {}): any;
+        footer?(_: {}): any;
+    };
+    emit: {
+        (e: "scroll", details: ScrollDetails<T>): void;
+        (e: "load", direction: "vertical" | "horizontal"): void;
+        (e: "visibleRangeChange", range: {
+            start: number;
+            end: number;
+            colStart: number;
+            colEnd: number;
+        }): void;
+    };
+}>) => VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+
+export declare interface VirtualScrollProps<T = unknown> {
+    /** Array of items to be virtualized */
+    items: T[];
+    /** Fixed size of each item or a function that returns the size of an item */
+    itemSize?: number | ((item: T, index: number) => number) | undefined;
+    /** Direction of the scroll: 'vertical', 'horizontal', or 'both' */
+    direction?: ScrollDirection | undefined;
+    /** Number of items to render before the visible viewport */
+    bufferBefore?: number | undefined;
+    /** Number of items to render after the visible viewport */
+    bufferAfter?: number | undefined;
+    /** The scrollable container element or window */
+    container?: HTMLElement | Window | null | undefined;
+    /** The host element that contains the items */
+    hostElement?: HTMLElement | null | undefined;
+    /** Range of items to render for SSR */
+    ssrRange?: {
+        start: number;
+        end: number;
+        colStart?: number;
+        colEnd?: number;
+    } | undefined;
+    /** Number of columns for bidirectional scroll */
+    columnCount?: number | undefined;
+    /** Fixed width of columns or an array of widths for alternating columns */
+    columnWidth?: number | number[] | ((index: number) => number) | undefined;
+    /** Padding at the start of the scroll container (e.g. for sticky headers) */
+    scrollPaddingStart?: number | {
+        x?: number;
+        y?: number;
+    } | undefined;
+    /** Padding at the end of the scroll container */
+    scrollPaddingEnd?: number | {
+        x?: number;
+        y?: number;
+    } | undefined;
+    /** Gap between items in pixels (vertical) */
+    gap?: number | undefined;
+    /** Gap between columns in pixels (horizontal/grid) */
+    columnGap?: number | undefined;
+    /** Indices of items that should stick to the top/start */
+    stickyIndices?: number[] | undefined;
+    /** Distance from the end of the scrollable area to trigger 'load' event */
+    loadDistance?: number | undefined;
+    /** Whether items are currently being loaded */
+    loading?: boolean | undefined;
+    /** Whether to restore scroll position when items are prepended */
+    restoreScrollOnPrepend?: boolean | undefined;
+    /** Initial scroll index to jump to on mount */
+    initialScrollIndex?: number | undefined;
+    /** Alignment for the initial scroll index */
+    initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions | undefined;
+    /** Default size for items before they are measured */
+    defaultItemSize?: number | undefined;
+    /** Default width for columns before they are measured */
+    defaultColumnWidth?: number | undefined;
+    /** Whether to enable debug mode (e.g. showing offsets) */
+    debug?: boolean | undefined;
+}
+
+export { }