feat: add virtualize utility

Author: metonym

src/utils/virtualize.d.ts

@@ -0,0 +1,39 @@
+export interface VirtualizeConfig<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Full array of items to virtualize */
+  items: T[];
+  /** Height of each item in pixels */
+  itemHeight: number;
+  /** Visible container height in pixels */
+  containerHeight: number;
+  /** Current scroll position */
+  scrollTop: number;
+  /** Extra items to render above/below viewport (default: 3) */
+  overscan?: number;
+  /** Cap maximum rendered items */
+  maxItems?: number;
+  /** Minimum items before virtualization activates (default: 100) */
+  threshold?: number;
+}
+
+export interface VirtualizeResult<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Items to render in the current viewport */
+  visibleItems: T[];
+  /** Index of first visible item */
+  startIndex: number;
+  /** Index after last visible item */
+  endIndex: number;
+  /** Y offset for positioning visible items */
+  offsetY: number;
+  /** Total height of all items */
+  totalHeight: number;
+  /** Whether virtualization is active */
+  isVirtualized: boolean;
+}
+
+export function virtualize<
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(config: VirtualizeConfig<T>): VirtualizeResult<T>;

src/utils/virtualize.js

@@ -0,0 +1,68 @@
+/**
+ * Virtualizes a list to render only visible items for performance.
+ *
+ * @template {Record<string, unknown>} T The type of items in the array (must be a Record)
+ * @param {Object} config
+ * @param {T[]} config.items - Full array of items to virtualize
+ * @param {number} config.itemHeight - Height of each item in pixels
+ * @param {number} config.containerHeight - Visible container height in pixels
+ * @param {number} config.scrollTop - Current scroll position
+ * @param {number} [config.overscan=3] - Extra items to render above/below viewport
+ * @param {number} [config.maxItems] - Cap maximum rendered items
+ * @param {number} [config.threshold=100] - Minimum items before virtualization activates
+ *
+ * @returns {{
+ *   visibleItems: T[],
+ *   startIndex: number,
+ *   endIndex: number,
+ *   offsetY: number,
+ *   totalHeight: number,
+ *   isVirtualized: boolean
+ * }}
+ */
+export function virtualize({
+  items,
+  itemHeight,
+  containerHeight,
+  scrollTop,
+  overscan = 3,
+  maxItems = undefined,
+  threshold = 100,
+}) {
+  // Auto-disable if below threshold
+  if (items.length < threshold) {
+    return {
+      visibleItems: items,
+      startIndex: 0,
+      endIndex: items.length,
+      offsetY: 0,
+      totalHeight: items.length * itemHeight,
+      isVirtualized: false,
+    };
+  }
+
+  const totalHeight = items.length * itemHeight;
+
+  // Calculate visible range
+  const startIndex = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
+  let endIndex = Math.min(
+    items.length,
+    Math.ceil((scrollTop + containerHeight) / itemHeight) + overscan,
+  );
+
+  // Apply maxItems cap if specified
+  if (maxItems && endIndex - startIndex > maxItems) {
+    endIndex = startIndex + maxItems;
+  }
+
+  const offsetY = startIndex * itemHeight;
+
+  return {
+    visibleItems: items.slice(startIndex, endIndex),
+    startIndex,
+    endIndex,
+    offsetY,
+    totalHeight,
+    isVirtualized: true,
+  };
+}