@pdanpdan/virtual-scroll 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { PublicProps } from 'vue';
 import { Ref } from 'vue';
 import { ShallowUnwrapRef } from 'vue';
 import { VNode } from 'vue';
+import { VNodeChild } from 'vue';
 import { VNodeProps } from 'vue';
 
 declare type __VLS_PrettifyLocal<T> = {
@@ -13,9 +14,9 @@ declare type __VLS_PrettifyLocal<T> = {
 
 export declare const DEFAULT_BUFFER = 5;
 
-export declare const DEFAULT_COLUMN_WIDTH = 150;
+export declare const DEFAULT_COLUMN_WIDTH = 100;
 
-export declare const DEFAULT_ITEM_SIZE = 50;
+export declare const DEFAULT_ITEM_SIZE = 40;
 
 /**
  * Fenwick Tree (Binary Indexed Tree) implementation for efficient
@@ -195,21 +196,31 @@ declare interface Props<T = unknown> {
     debug?: boolean;
 }
 
+/** Represents an item currently rendered in the virtual scroll area. */
 export declare interface RenderedItem<T = unknown> {
+    /** The original data item. */
     item: T;
+    /** The index of the item in the original array. */
     index: number;
+    /** The calculated offset relative to the host element. */
     offset: {
         x: number;
         y: number;
     };
+    /** The current measured or estimated size. */
     size: {
         width: number;
         height: number;
     };
+    /** The original X offset before sticky adjustments. */
     originalX: number;
+    /** The original Y offset before sticky adjustments. */
     originalY: number;
+    /** Whether this item is configured to be sticky. */
     isSticky?: boolean;
+    /** Whether this item is currently stuck at the threshold. */
     isStickyActive?: boolean;
+    /** The offset applied for the sticky pushing effect. */
     stickyOffset: {
         x: number;
         y: number;
@@ -218,35 +229,47 @@ export declare interface RenderedItem<T = unknown> {
 
 export declare type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
 
+/** Options for scroll alignment in a single axis or both axes. */
 export declare interface ScrollAlignmentOptions {
+    /** Alignment on the X axis. */
     x?: ScrollAlignment;
+    /** Alignment on the Y axis. */
     y?: ScrollAlignment;
 }
 
+/** Comprehensive state of the virtual scroll system. */
 export declare interface ScrollDetails<T = unknown> {
+    /** List of items currently rendered. */
     items: RenderedItem<T>[];
+    /** Index of the first item partially or fully visible in the viewport. */
     currentIndex: number;
+    /** Index of the first column partially or fully visible. */
     currentColIndex: number;
+    /** Current scroll position relative to content start. */
     scrollOffset: {
         x: number;
         y: number;
     };
+    /** Dimensions of the visible viewport. */
     viewportSize: {
         width: number;
         height: number;
     };
+    /** Total calculated size of all items and gaps. */
     totalSize: {
         width: number;
         height: number;
     };
+    /** Whether the container is currently being scrolled. */
     isScrolling: boolean;
+    /** Whether the current scroll was initiated by a method call. */
     isProgrammaticScroll: boolean;
-    /** Range of items currently being rendered */
+    /** Range of items currently being rendered. */
     range: {
         start: number;
         end: number;
     };
-    /** Range of columns currently being rendered (for grid mode) */
+    /** Range of columns currently being rendered (for grid mode). */
     columnRange: {
         start: number;
         end: number;
@@ -257,9 +280,13 @@ export declare interface ScrollDetails<T = unknown> {
 
 export declare type ScrollDirection = 'vertical' | 'horizontal' | 'both';
 
+/** Options for the scrollToIndex method. */
 export declare interface ScrollToIndexOptions {
+    /** Where to align the item in the viewport. */
     align?: ScrollAlignment | ScrollAlignmentOptions;
+    /** Scroll behavior. */
     behavior?: 'auto' | 'smooth';
+    /** Internal flag for recursive correction calls. */
     isCorrection?: boolean;
 }
 
@@ -381,23 +408,60 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     stopProgrammaticScroll: () => void;
     }>): void;
     attrs: any;
-    slots: {
-        header?(_: {}): any;
-        item?(_: {
+    slots: Readonly<{
+        /** Content rendered at the top of the scrollable area. Can be made sticky. */
+        header?: (props: Record<string, never>) => VNodeChild;
+        /** Slot for rendering each individual item. */
+        item?: (props: {
+            /** The data item being rendered. */
             item: T;
+            /** The index of the item in the items array. */
             index: number;
+            /** The current visible range of columns (for grid mode). */
             columnRange: {
                 start: number;
                 end: number;
                 padStart: number;
                 padEnd: number;
             };
+            /** Function to get the width of a specific column. */
             getColumnWidth: (index: number) => number;
-            isSticky: boolean | undefined;
-            isStickyActive: boolean | undefined;
-        }): any;
-        loading?(_: {}): any;
-        footer?(_: {}): any;
+            /** Whether this item is configured to be sticky. */
+            isSticky?: boolean | undefined;
+            /** Whether this item is currently in a sticky state. */
+            isStickyActive?: boolean | undefined;
+        }) => VNodeChild;
+        /** Content shown when `loading` prop is true. */
+        loading?: (props: Record<string, never>) => VNodeChild;
+        /** Content rendered at the bottom of the scrollable area. Can be made sticky. */
+        footer?: (props: Record<string, never>) => VNodeChild;
+    }> & {
+        /** Content rendered at the top of the scrollable area. Can be made sticky. */
+        header?: (props: Record<string, never>) => VNodeChild;
+        /** Slot for rendering each individual item. */
+        item?: (props: {
+            /** The data item being rendered. */
+            item: T;
+            /** The index of the item in the items array. */
+            index: number;
+            /** The current visible range of columns (for grid mode). */
+            columnRange: {
+                start: number;
+                end: number;
+                padStart: number;
+                padEnd: number;
+            };
+            /** Function to get the width of a specific column. */
+            getColumnWidth: (index: number) => number;
+            /** Whether this item is configured to be sticky. */
+            isSticky?: boolean | undefined;
+            /** Whether this item is currently in a sticky state. */
+            isStickyActive?: boolean | undefined;
+        }) => VNodeChild;
+        /** Content shown when `loading` prop is true. */
+        loading?: (props: Record<string, never>) => VNodeChild;
+        /** Content rendered at the bottom of the scrollable area. Can be made sticky. */
+        footer?: (props: Record<string, never>) => VNodeChild;
     };
     emit: {
         (e: "scroll", details: ScrollDetails<T>): void;
@@ -413,63 +477,64 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     __ctx?: Awaited<typeof __VLS_setup>;
 };
 
+/** Configuration properties for the useVirtualScroll composable. */
 export declare interface VirtualScrollProps<T = unknown> {
-    /** Array of items to be virtualized */
+    /** Array of items to be virtualized. */
     items: T[];
-    /** Fixed size of each item or a function that returns the size of an item */
+    /** 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 of the scroll: 'vertical', 'horizontal', or 'both'. */
     direction?: ScrollDirection | undefined;
-    /** Number of items to render before the visible viewport */
+    /** Number of items to render before the visible viewport. */
     bufferBefore?: number | undefined;
-    /** Number of items to render after the visible viewport */
+    /** Number of items to render after the visible viewport. */
     bufferAfter?: number | undefined;
-    /** The scrollable container element or window */
+    /** The scrollable container element or window. */
     container?: HTMLElement | Window | null | undefined;
-    /** The host element that contains the items */
+    /** The host element that contains the items. */
     hostElement?: HTMLElement | null | undefined;
-    /** Range of items to render for SSR */
+    /** Range of items to render for SSR. */
     ssrRange?: {
         start: number;
         end: number;
         colStart?: number;
         colEnd?: number;
     } | undefined;
-    /** Number of columns for bidirectional scroll */
+    /** Number of columns for bidirectional scroll. */
     columnCount?: number | undefined;
-    /** Fixed width of columns or an array of widths for alternating columns */
+    /** Fixed width of columns or an array/function for column widths. */
     columnWidth?: number | number[] | ((index: number) => number) | undefined;
-    /** Padding at the start of the scroll container (e.g. for sticky headers) */
+    /** Padding at the start of the scroll container. */
     scrollPaddingStart?: number | {
         x?: number;
         y?: number;
     } | undefined;
-    /** Padding at the end of the scroll container */
+    /** Padding at the end of the scroll container. */
     scrollPaddingEnd?: number | {
         x?: number;
         y?: number;
     } | undefined;
-    /** Gap between items in pixels (vertical) */
+    /** Gap between items in pixels (vertical). */
     gap?: number | undefined;
-    /** Gap between columns in pixels (horizontal/grid) */
+    /** Gap between columns in pixels (horizontal/grid). */
     columnGap?: number | undefined;
-    /** Indices of items that should stick to the top/start */
+    /** 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 */
+    /** Distance from the end of the scrollable area to trigger 'load' event. */
     loadDistance?: number | undefined;
-    /** Whether items are currently being loaded */
+    /** Whether items are currently being loaded. */
     loading?: boolean | undefined;
-    /** Whether to restore scroll position when items are prepended */
+    /** Whether to restore scroll position when items are prepended. */
     restoreScrollOnPrepend?: boolean | undefined;
-    /** Initial scroll index to jump to on mount */
+    /** Initial scroll index to jump to on mount. */
     initialScrollIndex?: number | undefined;
-    /** Alignment for the initial scroll index */
+    /** Alignment for the initial scroll index. */
     initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions | undefined;
-    /** Default size for items before they are measured */
+    /** Default size for items before they are measured. */
     defaultItemSize?: number | undefined;
-    /** Default width for columns before they are measured */
+    /** Default width for columns before they are measured. */
     defaultColumnWidth?: number | undefined;
-    /** Whether to enable debug mode (e.g. showing offsets) */
+    /** Whether to enable debug mode. */
     debug?: boolean | undefined;
 }