@pdanpdan/virtual-scroll 0.4.0 → 0.6.0

package/src/types.ts

@@ -1,3 +1,44 @@
+/** Default fallback size for items (VU). */
+export const DEFAULT_ITEM_SIZE = 40;
+/** Default fallback width for columns (VU). */
+export const DEFAULT_COLUMN_WIDTH = 100;
+/** Default number of items to render outside the viewport. */
+export const DEFAULT_BUFFER = 5;
+
+/** Represents a point in 2D space. */
+export interface Point {
+  /** X coordinate. */
+  x: number;
+  /** Y coordinate. */
+  y: number;
+}
+
+/** Represents dimensions in 2D space. */
+export interface Size {
+  /** Width dimension. */
+  width: number;
+  /** Height dimension. */
+  height: number;
+}
+
+/** Initial empty state for scroll details. */
+export const EMPTY_SCROLL_DETAILS: ScrollDetails<unknown> = {
+  items: [],
+  currentIndex: 0,
+  currentColIndex: 0,
+  currentEndIndex: 0,
+  currentEndColIndex: 0,
+  scrollOffset: { x: 0, y: 0 },
+  displayScrollOffset: { x: 0, y: 0 },
+  viewportSize: { width: 0, height: 0 },
+  displayViewportSize: { width: 0, height: 0 },
+  totalSize: { width: 0, height: 0 },
+  isScrolling: false,
+  isProgrammaticScroll: false,
+  range: { start: 0, end: 0 },
+  columnRange: { start: 0, end: 0, padStart: 0, padEnd: 0 },
+};
+
 /**
  * The direction of the virtual scroll.
  * - 'vertical': Single-column vertical scrolling.
@@ -54,66 +95,60 @@ export interface RenderedItem<T = unknown> {
   item: T;
   /** The 0-based index of the item in the original array. */
   index: number;
-  /** The calculated pixel offset relative to the items wrapper. */
-  offset: {
-    /** Horizontal offset (left). */
-    x: number;
-    /** Vertical offset (top). */
-    y: number;
-  };
-  /** The current measured or estimated size of the item. */
-  size: {
-    /** Pixel width. */
-    width: number;
-    /** Pixel height. */
-    height: number;
-  };
-  /** The original horizontal pixel offset before any sticky adjustments. */
+  /** The calculated pixel offset relative to the items wrapper in display pixels (DU). */
+  offset: Point;
+  /** The current measured or estimated size of the item in virtual units (VU). */
+  size: Size;
+  /** The original horizontal pixel offset before any sticky adjustments in VU. */
   originalX: number;
-  /** The original vertical pixel offset before any sticky adjustments. */
+  /** The original vertical pixel offset before any sticky adjustments in VU. */
   originalY: number;
   /** Whether this item is configured to be sticky via the `stickyIndices` property. */
   isSticky?: boolean;
   /** Whether this item is currently in a stuck state at the viewport edge. */
   isStickyActive?: boolean;
-  /** The relative translation applied to the item for the sticky pushing effect. */
-  stickyOffset: {
-    /** Horizontal translation. */
-    x: number;
-    /** Vertical translation. */
-    y: number;
-  };
+  /** Whether this item is currently in a stuck state at the horizontal viewport edge. */
+  isStickyActiveX?: boolean;
+  /** Whether this item is currently in a stuck state at the vertical viewport edge. */
+  isStickyActiveY?: boolean;
+  /** The relative translation applied to the item for the sticky pushing effect in DU. */
+  stickyOffset: Point;
+}
+
+/** Information about the currently visible range of columns and their paddings. */
+export interface ColumnRange {
+  /** Inclusive start index. */
+  start: number;
+  /** Exclusive end index. */
+  end: number;
+  /** Pixel padding to maintain at the start of the row in VU. */
+  padStart: number;
+  /** Pixel padding to maintain at the end of the row in VU. */
+  padEnd: number;
 }
 
 /** Comprehensive state of the virtual scroll system. */
 export interface ScrollDetails<T = unknown> {
   /** List of items currently rendered in the DOM buffer. */
   items: RenderedItem<T>[];
-  /** Index of the first item partially or fully visible in the viewport. */
+  /** Index of the first item visible below any sticky header in the viewport. */
   currentIndex: number;
-  /** Index of the first column partially or fully visible (grid mode). */
+  /** Index of the first column visible after any sticky column in the viewport (grid mode). */
   currentColIndex: number;
-  /** Current relative pixel scroll position from the content start. */
-  scrollOffset: {
-    /** Horizontal position (X). */
-    x: number;
-    /** Vertical position (Y). */
-    y: number;
-  };
-  /** Current dimensions of the visible viewport area. */
-  viewportSize: {
-    /** Pixel width. */
-    width: number;
-    /** Pixel height. */
-    height: number;
-  };
-  /** Total calculated or estimated size of all items and gaps. */
-  totalSize: {
-    /** Total pixel width. */
-    width: number;
-    /** Total pixel height. */
-    height: number;
-  };
+  /** Index of the last item visible above any sticky footer in the viewport. */
+  currentEndIndex: number;
+  /** Index of the last column visible before any sticky end column in the viewport (grid mode). */
+  currentEndColIndex: number;
+  /** Current relative pixel scroll position from the content start in VU. */
+  scrollOffset: Point;
+  /** Current display pixel scroll position (before scaling) in DU. */
+  displayScrollOffset: Point;
+  /** Current dimensions of the visible viewport area in VU. */
+  viewportSize: Size;
+  /** Current dimensions of the visible viewport area in display pixels (DU). */
+  displayViewportSize: Size;
+  /** Total calculated or estimated size of all items and gaps in VU. */
+  totalSize: Size;
   /** Whether the container is currently being scrolled by the user or an animation. */
   isScrolling: boolean;
   /** Whether the current scroll operation was initiated programmatically. */
@@ -126,30 +161,37 @@ export interface ScrollDetails<T = unknown> {
     end: number;
   };
   /** The range of column indices and associated paddings currently being rendered. */
-  columnRange: {
-    /** Inclusive start index. */
-    start: number;
-    /** Exclusive end index. */
-    end: number;
-    /** Pixel padding to maintain at the start of the row. */
-    padStart: number;
-    /** Pixel padding to maintain at the end of the row. */
-    padEnd: number;
-  };
+  columnRange: ColumnRange;
 }
 
-/** Configuration properties for the `useVirtualScroll` composable. */
-export interface VirtualScrollProps<T = unknown> {
-  /**
-   * Array of data items to virtualize.
-   */
+/**
+ * Configuration for Server-Side Rendering.
+ * Defines which items are rendered statically on the server.
+ */
+export interface SSRRange {
+  /** First row index (for list or grid). */
+  start: number;
+  /** Exclusive last row index (for list or grid). */
+  end: number;
+  /** First column index (for grid mode). */
+  colStart?: number;
+  /** Exclusive last column index (for grid mode). */
+  colEnd?: number;
+}
+
+/** Pixel padding configuration in display pixels (DU). */
+export type PaddingValue = number | { x?: number; y?: number; };
+
+/** Base configuration properties shared between the component and the composable. */
+export interface VirtualScrollBaseProps<T = unknown> {
+  /** Array of data items to virtualize. */
   items: T[];
 
   /**
-   * Fixed size of each item (in pixels) or a function that returns the size of an item.
+   * Fixed size of each item in virtual units (VU) or a function that returns the size of an item.
    * Pass `0`, `null` or `undefined` for automatic dynamic size detection via `ResizeObserver`.
    */
-  itemSize?: number | ((item: T, index: number) => number) | undefined;
+  itemSize?: number | ((item: T, index: number) => number) | null | undefined;
 
   /**
    * Direction of the virtual scroll.
@@ -171,30 +213,15 @@ export interface VirtualScrollProps<T = unknown> {
 
   /**
    * The scrollable element or window object.
-   * If not provided, virtualization usually happens relative to the `hostElement`.
+   * If not provided, virtualization usually happens relative to the `hostRef`.
    */
   container?: HTMLElement | Window | null | undefined;
 
-  /**
-   * The host element that directly wraps the absolute-positioned items.
-   * Used for calculating relative offsets.
-   */
-  hostElement?: HTMLElement | null | undefined;
-
   /**
    * Configuration for Server-Side Rendering.
    * Defines which items are rendered statically on the server.
    */
-  ssrRange?: {
-    /** First row index. */
-    start: number;
-    /** Exclusive last row index. */
-    end: number;
-    /** First column index (grid mode). */
-    colStart?: number;
-    /** Exclusive last column index (grid mode). */
-    colEnd?: number;
-  } | undefined;
+  ssrRange?: SSRRange | undefined;
 
   /**
    * Number of columns for bidirectional grid scrolling.
@@ -202,29 +229,29 @@ export interface VirtualScrollProps<T = unknown> {
   columnCount?: number | undefined;
 
   /**
-   * Fixed width of columns (in pixels), an array of widths, or a function returning widths.
+   * Fixed width of columns in VU, an array of widths, or a function returning widths.
    * Pass `0`, `null` or `undefined` for dynamic column detection.
    */
-  columnWidth?: number | number[] | ((index: number) => number) | undefined;
+  columnWidth?: number | number[] | ((index: number) => number) | null | undefined;
 
   /**
-   * Pixel padding at the start of the scroll container.
+   * Pixel padding at the start of the scroll container in display pixels (DU).
    */
-  scrollPaddingStart?: number | { x?: number; y?: number; } | undefined;
+  scrollPaddingStart?: PaddingValue | undefined;
 
   /**
-   * Pixel padding at the end of the scroll container.
+   * Pixel padding at the end of the scroll container in DU.
    */
-  scrollPaddingEnd?: number | { x?: number; y?: number; } | undefined;
+  scrollPaddingEnd?: PaddingValue | undefined;
 
   /**
-   * Gap between items in pixels.
+   * Gap between items in virtual units (VU).
    * Applied vertically in list/grid mode, horizontally in horizontal list mode.
    */
   gap?: number | undefined;
 
   /**
-   * Gap between columns in pixels.
+   * Gap between columns in VU.
    * Applied in horizontal and bidirectional grid modes.
    */
   columnGap?: number | undefined;
@@ -235,7 +262,7 @@ export interface VirtualScrollProps<T = unknown> {
   stickyIndices?: number[] | undefined;
 
   /**
-   * Threshold distance from the end (in pixels) to emit the 'load' event.
+   * Threshold distance from the end in display pixels (DU) to emit the 'load' event.
    * @default 200
    */
   loadDistance?: number | undefined;
@@ -246,7 +273,7 @@ export interface VirtualScrollProps<T = unknown> {
   loading?: boolean | undefined;
 
   /**
-   * Whether to automatically restore and lock scroll position when items are prepended to the array.
+   * Whether to automatically restore and maintain scroll position when items are prepended to the array.
    */
   restoreScrollOnPrepend?: boolean | undefined;
 
@@ -262,12 +289,12 @@ export interface VirtualScrollProps<T = unknown> {
   initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions | undefined;
 
   /**
-   * Default fallback size for items before they are measured.
+   * Default fallback size for items before they are measured in VU.
    */
   defaultItemSize?: number | undefined;
 
   /**
-   * Default fallback width for columns before they are measured.
+   * Default fallback width for columns before they are measured in VU.
    */
   defaultColumnWidth?: number | undefined;
 
@@ -277,6 +304,124 @@ export interface VirtualScrollProps<T = unknown> {
   debug?: boolean | undefined;
 }
 
+/** Configuration properties for the `useVirtualScroll` composable. */
+export interface VirtualScrollProps<T = unknown> extends VirtualScrollBaseProps<T> {
+  /**
+   * The host element that directly wraps the absolute-positioned items.
+   * Used for calculating relative offsets in display pixels (DU).
+   */
+  hostElement?: HTMLElement | null | undefined;
+
+  /**
+   * The root element of the VirtualScroll component.
+   * Used for calculating relative offsets in display pixels (DU).
+   */
+  hostRef?: HTMLElement | null | undefined;
+
+  /**
+   * Size of sticky elements at the start of the viewport (top or left) in DU.
+   * Used to adjust the visible range and item positioning without increasing content size.
+   */
+  stickyStart?: PaddingValue | undefined;
+
+  /**
+   * Size of sticky elements at the end of the viewport (bottom or right) in DU.
+   * Used to adjust the visible range without increasing content size.
+   */
+  stickyEnd?: PaddingValue | undefined;
+
+  /**
+   * Extra padding (display pixels - DU) at the start of the flow (e.g. non-sticky header).
+   */
+  flowPaddingStart?: PaddingValue | undefined;
+
+  /**
+   * Extra padding (DU) at the end of the flow (e.g. non-sticky footer).
+   */
+  flowPaddingEnd?: PaddingValue | undefined;
+}
+
+/** Help provide axis specific information to the scrollbar. */
+export type ScrollAxis = 'vertical' | 'horizontal';
+
+/** Properties for the `VirtualScrollbar` component. */
+export interface VirtualScrollbarProps {
+  /**
+   * The axis for this scrollbar.
+   * - 'vertical': Vertical scrollbar.
+   * - 'horizontal': Horizontal scrollbar.
+   * @default 'vertical'
+   */
+  axis?: ScrollAxis;
+
+  /**
+   * Total size of the scrollable content in pixels.
+   */
+  totalSize: number;
+
+  /**
+   * Current scroll position in pixels.
+   */
+  position: number;
+
+  /**
+   * Viewport size in pixels.
+   */
+  viewportSize: number;
+
+  /**
+   * Function to scroll to a specific pixel offset on this axis.
+   * @param offset - The pixel offset to scroll to.
+   */
+  scrollToOffset?: (offset: number) => void;
+
+  /**
+   * The ID of the container element this scrollbar controls.
+   */
+  containerId?: string;
+
+  /**
+   * Whether the scrollbar is in Right-to-Left (RTL) mode.
+   * @default false
+   */
+  isRtl?: boolean;
+}
+
+/** Properties passed to the 'scrollbar' scoped slot. */
+export interface ScrollbarSlotProps {
+  /** The axis for this scrollbar. */
+  axis: ScrollAxis;
+  /** Current scroll position as a percentage (0 to 1). */
+  positionPercent: number;
+  /** Viewport size as a percentage of total size (0 to 1). */
+  viewportPercent: number;
+  /** Calculated thumb size as a percentage of the track size (0 to 100). */
+  thumbSizePercent: number;
+  /** Calculated thumb position as a percentage of the track size (0 to 100). */
+  thumbPositionPercent: number;
+
+  /**
+   * Attributes and event listeners to be bound to the scrollbar track element.
+   * Use `v-bind="trackProps"` on your track element.
+   */
+  trackProps: Record<string, unknown>;
+
+  /**
+   * Attributes and event listeners to be bound to the scrollbar thumb element.
+   * Use `v-bind="thumbProps"` on your thumb element.
+   */
+  thumbProps: Record<string, unknown>;
+
+  /**
+   * Grouped props for the `VirtualScrollbar` component.
+   * Useful for passing directly to `<VirtualScrollbar v-bind="scrollbarProps" />`.
+   */
+  scrollbarProps: VirtualScrollbarProps;
+
+  /** Whether the thumb is currently being dragged. */
+  isDragging: boolean;
+}
+
 /** Properties passed to the 'item' scoped slot. */
 export interface ItemSlotProps<T = unknown> {
   /** The original data item being rendered. */
@@ -284,22 +429,92 @@ export interface ItemSlotProps<T = unknown> {
   /** The 0-based index of the item. */
   index: number;
   /** Information about the currently visible range of columns. */
-  columnRange: {
-    /** First rendered column. */
-    start: number;
-    /** Last rendered column (exclusive). */
-    end: number;
-    /** Pixel space before first column. */
-    padStart: number;
-    /** Pixel space after last column. */
-    padEnd: number;
-  };
+  columnRange: ColumnRange;
   /** Helper to get the current calculated width of any column index. */
   getColumnWidth: (index: number) => number;
+  /** Vertical gap between items. */
+  gap: number;
+  /** Horizontal gap between columns. */
+  columnGap: number;
   /** Whether this item index is configured as sticky. */
   isSticky?: boolean | undefined;
   /** Whether this item is currently in a sticky state at the edge. */
   isStickyActive?: boolean | undefined;
+  /** Whether this item is currently in a sticky state at the horizontal edge. */
+  isStickyActiveX?: boolean | undefined;
+  /** Whether this item is currently in a sticky state at the vertical edge. */
+  isStickyActiveY?: boolean | undefined;
+  /** The calculated pixel offset relative to the items wrapper in display pixels (DU). */
+  offset: {
+    /** Horizontal offset (left) in DU. */
+    x: number;
+    /** Vertical offset (top) in DU. */
+    y: number;
+  };
+}
+
+/** Configuration properties for the `VirtualScroll` component. */
+export interface VirtualScrollComponentProps<T = unknown> extends VirtualScrollBaseProps<T> {
+  /** The HTML tag to use for the root container. */
+  containerTag?: string;
+  /** The HTML tag to use for the items wrapper. */
+  wrapperTag?: string;
+  /** The HTML tag to use for each item. */
+  itemTag?: string;
+  /** Whether the content in the 'header' slot is sticky. */
+  stickyHeader?: boolean;
+  /** Whether the content in the 'footer' slot is sticky. */
+  stickyFooter?: boolean;
+  /** Whether to use virtual scrollbars for styling purposes. */
+  virtualScrollbar?: boolean;
+}
+
+/** Exposed methods and properties of the `VirtualScroll` component instance. */
+export interface VirtualScrollInstance<T = unknown> extends VirtualScrollComponentProps<T> {
+  /** Detailed information about the current scroll state. */
+  scrollDetails: ScrollDetails<T>;
+  /** Information about the current visible range of columns. */
+  columnRange: ScrollDetails<T>[ 'columnRange' ];
+  /** Helper to get the width of a specific column. */
+  getColumnWidth: (index: number) => number;
+  /** Helper to get the height of a specific row. */
+  getRowHeight: (index: number) => number;
+  /** Helper to get the virtual offset of a specific row. */
+  getRowOffset: (index: number) => number;
+  /** Helper to get the virtual offset of a specific column. */
+  getColumnOffset: (index: number) => number;
+  /** Helper to get the virtual offset of a specific item. */
+  getItemOffset: (index: number) => number;
+  /** 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;
+  /** Programmatically scroll to a specific pixel offset. */
+  scrollToOffset: (x?: number | null, y?: number | null, options?: { behavior?: 'auto' | 'smooth'; }) => void;
+  /** Resets all dynamic measurements and re-initializes from props. */
+  refresh: () => void;
+  /** Immediately stops any currently active smooth scroll animation and clears pending corrections. */
+  stopProgrammaticScroll: () => void;
+  /** Detects the current direction (LTR/RTL) of the scroll container. */
+  updateDirection: () => void;
+  /** Whether the scroll container is in Right-to-Left (RTL) mode. */
+  isRtl: boolean;
+  /** Whether the component has finished its first client - side mount and hydration. */
+  isHydrated: boolean;
+  /** Coordinate scaling factor for X axis. */
+  scaleX: number;
+  /** Coordinate scaling factor for Y axis. */
+  scaleY: number;
+  /** Physical width of the content in the DOM (clamped to browser limits). */
+  renderedWidth: number;
+  /** Physical height of the content in the DOM (clamped to browser limits). */
+  renderedHeight: number;
+  /** Absolute offset of the component within its container. */
+  componentOffset: Point;
+  /** Properties for the vertical scrollbar. */
+  scrollbarPropsVertical: ScrollbarSlotProps | null;
+  /** Properties for the horizontal scrollbar. */
+  scrollbarPropsHorizontal: ScrollbarSlotProps | null;
 }
 
 /** Parameters for calculating the scroll target position. */
@@ -310,16 +525,12 @@ export interface ScrollTargetParams {
   colIndex: number | null | undefined;
   /** Scroll options. */
   options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions | undefined;
-  /** Total items count. */
-  itemsLength: number;
-  /** Total columns count. */
-  columnCount: number;
   /** Current scroll direction. */
   direction: ScrollDirection;
-  /** Usable viewport width (excluding padding). */
-  usableWidth: number;
-  /** Usable viewport height (excluding padding). */
-  usableHeight: number;
+  /** Current viewport width. */
+  viewportWidth: number;
+  /** Current viewport height. */
+  viewportHeight: number;
   /** Current total estimated width. */
   totalWidth: number;
   /** Current total estimated height. */
@@ -348,8 +559,36 @@ export interface ScrollTargetParams {
   getColumnSize: (index: number) => number;
   /** Prefix sum resolver for column width. */
   getColumnQuery: (index: number) => number;
+  /** Coordinate scaling factor for X axis. */
+  scaleX: number;
+  /** Coordinate scaling factor for Y axis. */
+  scaleY: number;
+  /** Host offset on X axis in display pixels. */
+  hostOffsetX: number;
+  /** Host offset on Y axis in display pixels. */
+  hostOffsetY: number;
   /** List of sticky indices. */
   stickyIndices?: number[] | undefined;
+  /** Sticky start offset on X axis. */
+  stickyStartX?: number | undefined;
+  /** Sticky start offset on Y axis. */
+  stickyStartY?: number | undefined;
+  /** Sticky end offset on X axis. */
+  stickyEndX?: number | undefined;
+  /** Sticky end offset on Y axis. */
+  stickyEndY?: number | undefined;
+  /** Flow padding start on X axis. */
+  flowPaddingStartX?: number | undefined;
+  /** Flow padding start on Y axis. */
+  flowPaddingStartY?: number | undefined;
+  /** Scroll padding start on X axis. */
+  paddingStartX?: number | undefined;
+  /** Scroll padding start on Y axis. */
+  paddingStartY?: number | undefined;
+  /** Scroll padding end on X axis. */
+  paddingEndX?: number | undefined;
+  /** Scroll padding end on Y axis. */
+  paddingEndY?: number | undefined;
 }
 
 /** Calculated scroll target result. */
@@ -486,6 +725,8 @@ export interface ItemPositionParams {
   getSizeY: (idx: number) => number;
   /** Width resolver. */
   getSizeX: (idx: number) => number;
+  /** Current column range (for grid mode). */
+  columnRange?: ColumnRange | undefined;
 }
 
 /** Parameters for calculating an item's style object. */
@@ -504,6 +745,8 @@ export interface ItemStyleParams<T = unknown> {
   paddingStartY: number;
   /** Hydration state. */
   isHydrated: boolean;
+  /** Whether the container is in Right-to-Left (RTL) mode. */
+  isRtl: boolean;
 }
 
 /** Parameters for calculating the total size of the scrollable area. */