@pdanpdan/virtual-scroll 0.1.0

package/src/index.ts

@@ -0,0 +1,4 @@
+export { default as VirtualScroll } from './components/VirtualScroll.vue';
+export * from './composables/useVirtualScroll.js';
+export * from './utils/fenwick-tree.js';
+export * from './utils/scroll.js';

package/src/utils/fenwick-tree.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+
+import { FenwickTree } from './fenwick-tree';
+
+describe('fenwickTree', () => {
+  it('should initialize with correct size', () => {
+    const tree = new FenwickTree(5);
+    expect(tree.query(5)).toBe(0);
+  });
+
+  it('should update and query values', () => {
+    const tree = new FenwickTree(5);
+    tree.update(0, 10);
+    tree.update(1, 20);
+    tree.update(2, 30);
+
+    expect(tree.query(0)).toBe(0);
+    expect(tree.query(1)).toBe(10);
+    expect(tree.query(2)).toBe(30);
+    expect(tree.query(3)).toBe(60);
+  });
+
+  it('should handle updates to existing indices', () => {
+    const tree = new FenwickTree(3);
+    tree.update(1, 10);
+    expect(tree.query(2)).toBe(10);
+    tree.update(1, 5); // Add 5 to index 1
+    expect(tree.query(2)).toBe(15);
+  });
+
+  it('should find lower bound correctly', () => {
+    const tree = new FenwickTree(5);
+    tree.update(0, 10); // sum up to 1: 10
+    tree.update(1, 10); // sum up to 2: 20
+    tree.update(2, 10); // sum up to 3: 30
+
+    expect(tree.findLowerBound(5)).toBe(0);
+    expect(tree.findLowerBound(15)).toBe(1);
+    expect(tree.findLowerBound(25)).toBe(2);
+    expect(tree.findLowerBound(35)).toBe(5); // Returns size when not found
+  });
+
+  it('should resize and preserve existing values', () => {
+    const tree = new FenwickTree(5);
+    tree.update(0, 10);
+    tree.resize(10);
+    expect(tree.query(1)).toBe(10);
+    expect(tree.query(10)).toBe(10);
+    tree.resize(10); // same size
+  });
+
+  it('should ignore updates for out of bounds indices', () => {
+    const tree = new FenwickTree(5);
+    tree.update(-1, 10);
+    tree.update(5, 10);
+    expect(tree.query(5)).toBe(0);
+  });
+
+  it('should set and rebuild correctly', () => {
+    const tree = new FenwickTree(5);
+    tree.set(0, 10);
+    tree.set(1, 20);
+    tree.set(2, 30);
+    tree.set(-1, 40); // ignore
+    tree.set(5, 50); // ignore
+    expect(tree.query(3)).toBe(0); // not rebuilt yet
+    tree.rebuild();
+    expect(tree.query(3)).toBe(60);
+  });
+
+  it('should return the underlying values array', () => {
+    const tree = new FenwickTree(3);
+    expect(tree.length).toBe(3);
+    tree.update(0, 10);
+    tree.update(1, 20);
+    const values = tree.getValues();
+    expect(values).toBeInstanceOf(Float64Array);
+    expect(values[ 0 ]).toBe(10);
+    expect(values[ 1 ]).toBe(20);
+    expect(values[ 2 ]).toBe(0);
+    expect(tree.get(0)).toBe(10);
+    expect(tree.get(-1)).toBe(0);
+    expect(tree.get(10)).toBe(0);
+  });
+
+  describe('shift', () => {
+    it('should do nothing when offset is 0', () => {
+      const tree = new FenwickTree(3);
+      tree.update(0, 10);
+      tree.shift(0);
+      expect(tree.get(0)).toBe(10);
+    });
+
+    it('should shift values forward when offset is positive', () => {
+      const tree = new FenwickTree(5);
+      tree.update(0, 10);
+      tree.update(1, 20);
+      tree.shift(2);
+      expect(tree.get(0)).toBe(0);
+      expect(tree.get(1)).toBe(0);
+      expect(tree.get(2)).toBe(10);
+      expect(tree.get(3)).toBe(20);
+      expect(tree.query(3)).toBe(10);
+      expect(tree.query(4)).toBe(30);
+    });
+
+    it('should shift values backward when offset is negative', () => {
+      const tree = new FenwickTree(5);
+      tree.update(2, 10);
+      tree.update(3, 20);
+      tree.shift(-2);
+      expect(tree.get(0)).toBe(10);
+      expect(tree.get(1)).toBe(20);
+      expect(tree.get(2)).toBe(0);
+      expect(tree.query(1)).toBe(10);
+      expect(tree.query(2)).toBe(30);
+    });
+  });
+});

package/src/utils/fenwick-tree.ts

@@ -0,0 +1,155 @@
+/**
+ * Fenwick Tree (Binary Indexed Tree) implementation for efficient
+ * prefix sum calculations and updates.
+ */
+export class FenwickTree {
+  private tree: Float64Array;
+  private values: Float64Array;
+
+  constructor(size: number) {
+    this.tree = new Float64Array(size + 1);
+    this.values = new Float64Array(size);
+  }
+
+  /**
+   * 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 {
+    if (index < 0 || index >= this.values.length) {
+      return;
+    }
+    this.values[ index ] = this.values[ index ]! + delta;
+
+    index++; // 1-based index
+    while (index < this.tree.length) {
+      this.tree[ index ] = this.tree[ index ]! + delta;
+      index += index & -index;
+    }
+  }
+
+  /**
+   * 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 {
+    let sum = 0;
+    while (index > 0) {
+      sum += this.tree[ index ] || 0;
+      index -= index & -index;
+    }
+    return sum;
+  }
+
+  /**
+   * 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 {
+    if (index < 0 || index >= this.values.length) {
+      return;
+    }
+    this.values[ index ] = value;
+  }
+
+  /**
+   * Get the number of items in the tree.
+   */
+  get length(): number {
+    return this.values.length;
+  }
+
+  /**
+   * Get the individual value at an index.
+   */
+  get(index: number): number {
+    return this.values[ index ] || 0;
+  }
+
+  /**
+   * Get the underlying values array.
+   */
+  getValues(): Readonly<Float64Array> {
+    return this.values;
+  }
+
+  /**
+   * 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 {
+    let index = 0;
+    const len = this.tree.length;
+    let power = 1 << Math.floor(Math.log2(len - 1));
+
+    while (power > 0) {
+      const nextIndex = index + power;
+      if (nextIndex < len) {
+        const treeVal = this.tree[ nextIndex ] || 0;
+        if (treeVal <= value) {
+          index = nextIndex;
+          value -= treeVal;
+        }
+      }
+      power >>= 1;
+    }
+    return index;
+  }
+
+  /**
+   * Rebuild the entire tree from the current values array in O(N).
+   * Useful after bulk updates to the values array.
+   */
+  rebuild(): void {
+    this.tree.fill(0);
+    for (let i = 0; i < this.values.length; i++) {
+      this.tree[ i + 1 ] = this.values[ i ] || 0;
+    }
+    for (let i = 1; i < this.tree.length; i++) {
+      const j = i + (i & -i);
+      if (j < this.tree.length) {
+        this.tree[ j ] = this.tree[ j ]! + this.tree[ i ]!;
+      }
+    }
+  }
+
+  /**
+   * Resize the tree while preserving existing values.
+   * @param size New size of the tree
+   */
+  resize(size: number): void {
+    if (size === this.values.length) {
+      return;
+    }
+    const newValues = new Float64Array(size);
+    newValues.set(this.values.subarray(0, Math.min(size, this.values.length)));
+
+    this.values = newValues;
+    this.tree = new Float64Array(size + 1);
+    this.rebuild();
+  }
+
+  /**
+   * 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 {
+    if (offset === 0) {
+      return;
+    }
+    const size = this.values.length;
+    const newValues = new Float64Array(size);
+    if (offset > 0) {
+      newValues.set(this.values.subarray(0, Math.min(size - offset, this.values.length)), offset);
+    } else {
+      newValues.set(this.values.subarray(-offset));
+    }
+    this.values = newValues;
+    this.rebuild();
+  }
+}

package/src/utils/scroll.ts

@@ -0,0 +1,59 @@
+import type { ScrollDirection, ScrollToIndexOptions } from '../composables/useVirtualScroll.js';
+
+/**
+ * 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 function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement {
+  return !!container && 'getBoundingClientRect' in container;
+}
+
+/**
+ * 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 function isScrollableElement(target: EventTarget | null): target is HTMLElement {
+  return !!target && 'scrollLeft' in target;
+}
+
+/**
+ * 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 function isScrollToIndexOptions(options: unknown): options is ScrollToIndexOptions {
+  return typeof options === 'object' && options !== null && ('align' in options || 'behavior' in options || 'isCorrection' in options);
+}
+
+/**
+ * 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 function getPaddingX(p: number | { x?: number; y?: number; } | undefined, direction?: ScrollDirection) {
+  if (typeof p === 'object' && p !== null) {
+    return p.x || 0;
+  }
+  return direction === 'horizontal' ? (p || 0) : 0;
+}
+
+/**
+ * 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 function getPaddingY(p: number | { x?: number; y?: number; } | undefined, direction?: ScrollDirection) {
+  if (typeof p === 'object' && p !== null) {
+    return p.y || 0;
+  }
+  return (direction === 'vertical' || direction === 'both') ? (p || 0) : 0;
+}