@indielayer/ui 1.15.3 → 1.17.0

package/src/virtual/composables/infinite-loader/scanForUnloadedIndices.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test, vi } from 'vitest'
+import { scanForUnloadedIndices } from './scanForUnloadedIndices'
+
+describe('scanForUnloadedIndices', () => {
+  test('should return an empty array for a range of rows that have all been loaded', () => {
+    const isRowLoaded = vi.fn((index: number) => {
+      expect(index).toBeGreaterThanOrEqual(0)
+      expect(index).toBeLessThanOrEqual(2)
+
+      return true
+    })
+
+    expect(
+      scanForUnloadedIndices({
+        minimumBatchSize: 0,
+        isRowLoaded,
+        rowCount: 3,
+        startIndex: 0,
+        stopIndex: 2,
+      }),
+    ).toEqual([])
+
+    expect(isRowLoaded).toHaveBeenCalledTimes(3)
+  })
+
+  test('return a range of only 1 unloaded row', () => {
+    const isRowLoaded = vi.fn((index: number) => {
+      expect(index).toBeGreaterThanOrEqual(0)
+      expect(index).toBeLessThanOrEqual(2)
+
+      return index !== 1
+    })
+
+    expect(
+      scanForUnloadedIndices({
+        minimumBatchSize: 0,
+        isRowLoaded,
+        rowCount: 3,
+        startIndex: 0,
+        stopIndex: 2,
+      }),
+    ).toEqual([{ startIndex: 1, stopIndex: 1 }])
+
+    expect(isRowLoaded).toHaveBeenCalledTimes(3)
+  })
+
+  test('return a range of multiple unloaded rows', () => {
+    const isRowLoaded = vi.fn((index: number) => {
+      expect(index).toBeGreaterThanOrEqual(0)
+      expect(index).toBeLessThanOrEqual(2)
+
+      return index === 2
+    })
+
+    expect(
+      scanForUnloadedIndices({
+        minimumBatchSize: 0,
+        isRowLoaded,
+        rowCount: 3,
+        startIndex: 0,
+        stopIndex: 2,
+      }),
+    ).toEqual([{ startIndex: 0, stopIndex: 1 }])
+
+    expect(isRowLoaded).toHaveBeenCalledTimes(3)
+  })
+
+  test('return multiple ranges of unloaded rows', () => {
+    const isRowLoaded = vi.fn((index: number) => {
+      expect(index).toBeGreaterThanOrEqual(0)
+      expect(index).toBeLessThanOrEqual(6)
+      switch (index) {
+        case 0:
+        case 3:
+        case 5: {
+          return true
+        }
+      }
+
+      return false
+    })
+
+    expect(
+      scanForUnloadedIndices({
+        minimumBatchSize: 0,
+        isRowLoaded,
+        rowCount: 7,
+        startIndex: 0,
+        stopIndex: 6,
+      }),
+    ).toEqual([
+      { startIndex: 1, stopIndex: 2 },
+      { startIndex: 4, stopIndex: 4 },
+      { startIndex: 6, stopIndex: 6 },
+    ])
+
+    expect(isRowLoaded).toHaveBeenCalledTimes(7)
+  })
+
+  test('return respect the minimum batch size param when fetching rows ahead', () => {
+    const isRowLoaded = vi.fn((index: number) => {
+      expect(index).toBeGreaterThanOrEqual(0)
+      expect(index).toBeLessThanOrEqual(9)
+
+      return index < 4
+    })
+
+    expect(
+      scanForUnloadedIndices({
+        minimumBatchSize: 4,
+        isRowLoaded,
+        rowCount: 10,
+        startIndex: 0,
+        stopIndex: 4,
+      }),
+    ).toEqual([{ startIndex: 4, stopIndex: 7 }])
+
+    expect(isRowLoaded).toHaveBeenCalledTimes(8)
+  })
+
+  test('return respect the minimum batch size param when fetching rows behind', () => {
+    const isRowLoaded = vi.fn((index: number) => {
+      expect(index).toBeGreaterThanOrEqual(0)
+      expect(index).toBeLessThanOrEqual(9)
+
+      return index > 6
+    })
+
+    expect(
+      scanForUnloadedIndices({
+        minimumBatchSize: 4,
+        isRowLoaded,
+        rowCount: 10,
+        startIndex: 6,
+        stopIndex: 9,
+      }),
+    ).toEqual([{ startIndex: 3, stopIndex: 6 }])
+
+    expect(isRowLoaded).toHaveBeenCalledTimes(7)
+  })
+})

package/src/virtual/composables/infinite-loader/scanForUnloadedIndices.ts

@@ -0,0 +1,82 @@
+import type { Indices } from './types'
+
+export function scanForUnloadedIndices({
+  isRowLoaded,
+  minimumBatchSize,
+  rowCount,
+  startIndex,
+  stopIndex,
+}: {
+  isRowLoaded: (index: number) => boolean;
+  minimumBatchSize: number;
+  rowCount: number;
+  startIndex: number;
+  stopIndex: number;
+}): Indices[] {
+  const indices: Indices[] = []
+
+  let currentStartIndex = -1
+  let currentStopIndex = -1
+
+  for (let index = startIndex; index <= stopIndex; index++) {
+    if (!isRowLoaded(index)) {
+      currentStopIndex = index
+      if (currentStartIndex < 0) {
+        currentStartIndex = index
+      }
+    } else if (currentStopIndex >= 0) {
+      indices.push({
+        startIndex: currentStartIndex,
+        stopIndex: currentStopIndex,
+      })
+
+      currentStartIndex = currentStopIndex = -1
+    }
+  }
+
+  // Scan forward to satisfy the minimum batch size.
+  if (currentStopIndex >= 0) {
+    const potentialStopIndex = Math.min(
+      Math.max(currentStopIndex, currentStartIndex + minimumBatchSize - 1),
+      rowCount - 1,
+    )
+
+    for (
+      let index = currentStopIndex + 1;
+      index <= potentialStopIndex;
+      index++
+    ) {
+      if (!isRowLoaded(index)) {
+        currentStopIndex = index
+      } else {
+        break
+      }
+    }
+
+    indices.push({
+      startIndex: currentStartIndex,
+      stopIndex: currentStopIndex,
+    })
+  }
+
+  // Check to see if our first range ended prematurely.
+  // In this case we should scan backwards to satisfy the minimum batch size.
+  if (indices.length) {
+    const firstIndices = indices[0]
+
+    while (
+      firstIndices.stopIndex - firstIndices.startIndex + 1 < minimumBatchSize &&
+      firstIndices.startIndex > 0
+    ) {
+      const index = firstIndices.startIndex - 1
+
+      if (!isRowLoaded(index)) {
+        firstIndices.startIndex = index
+      } else {
+        break
+      }
+    }
+  }
+
+  return indices
+}

package/src/virtual/composables/infinite-loader/types.ts

@@ -0,0 +1,36 @@
+export type Indices = {
+  startIndex: number;
+  stopIndex: number;
+};
+
+export type OnRowsRendered = (indices: Indices) => void;
+
+export type InfiniteLoaderProps = {
+  /**
+   * Function responsible for tracking the loaded state of each item.
+   */
+  isRowLoaded: (index: number) => boolean;
+
+  /**
+   * Callback to be invoked when more rows must be loaded.
+   * It should return a Promise that is resolved once all data has finished loading.
+   */
+  loadMoreRows: (startIndex: number, stopIndex: number) => Promise<void>;
+
+  /**
+   * Minimum number of rows to be loaded at a time; defaults to 10.
+   * This property can be used to batch requests to reduce HTTP requests.
+   */
+  minimumBatchSize?: number;
+
+  /**
+   * Threshold at which to pre-fetch data; defaults to 15.
+   * A threshold of 15 means that data will start loading when a user scrolls within 15 rows.
+   */
+  threshold?: number;
+
+  /**
+   * Number of rows in list; can be arbitrary high number if actual number is unknown.
+   */
+  rowCount: number;
+};

package/src/virtual/composables/infinite-loader/useInfiniteLoader.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, test, vi } from 'vitest'
+import { ref } from 'vue'
+import { useInfiniteLoader } from './useInfiniteLoader'
+import type { InfiniteLoaderProps } from './types'
+
+describe('useInfiniteLoader', () => {
+  test('should not load rows that have already been loaded', () => {
+    const isRowLoaded = vi.fn(() => true)
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded,
+      loadMoreRows,
+      rowCount: 10,
+    }
+
+    const { onRowsRendered } = useInfiniteLoader(props)
+
+    expect(isRowLoaded).not.toHaveBeenCalled()
+
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 9,
+    })
+
+    expect(isRowLoaded).toHaveBeenCalled()
+    expect(loadMoreRows).not.toHaveBeenCalled()
+  })
+
+  test('should call loadMoreRows when needed', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded: (index) => index <= 2,
+      loadMoreRows,
+      rowCount: 5,
+    }
+
+    const { onRowsRendered } = useInfiniteLoader(props)
+
+    expect(loadMoreRows).not.toHaveBeenCalled()
+
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 4,
+    })
+
+    expect(loadMoreRows).toHaveBeenCalled()
+    expect(loadMoreRows).toHaveBeenLastCalledWith(3, 4)
+  })
+
+  test('should work with reactive props', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+    const rowCount = ref(5)
+
+    const props = ref<InfiniteLoaderProps>({
+      isRowLoaded: (index) => index <= 2,
+      loadMoreRows,
+      rowCount: rowCount.value,
+    })
+
+    const { onRowsRendered } = useInfiniteLoader(props)
+
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 4,
+    })
+
+    expect(loadMoreRows).toHaveBeenCalledWith(3, 4)
+
+    // Update rowCount
+    rowCount.value = 10
+    props.value = {
+      ...props.value,
+      rowCount: rowCount.value,
+    }
+
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 9,
+    })
+
+    // Should now load indices 3-9 (excluding already pending 3-4)
+    expect(loadMoreRows).toHaveBeenLastCalledWith(5, 9)
+  })
+
+  test('should respect minimumBatchSize', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded: (index) => index < 4,
+      loadMoreRows,
+      rowCount: 10,
+      minimumBatchSize: 4,
+      threshold: 0, // Disable threshold for this test
+    }
+
+    const { onRowsRendered } = useInfiniteLoader(props)
+
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 4,
+    })
+
+    // Should load at least minimumBatchSize (4) rows
+    expect(loadMoreRows).toHaveBeenCalledWith(4, 7)
+  })
+
+  test('should respect threshold for pre-fetching', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded: (index) => index < 5,
+      loadMoreRows,
+      rowCount: 100,
+      threshold: 10,
+    }
+
+    const { onRowsRendered } = useInfiniteLoader(props)
+
+    // User is viewing rows 10-20
+    onRowsRendered({
+      startIndex: 10,
+      stopIndex: 20,
+    })
+
+    // With threshold 10, should check indices 0-30
+    // Rows 5-30 should be loaded
+    expect(loadMoreRows).toHaveBeenCalledWith(5, 30)
+  })
+
+  test('should track pending rows', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded: (index) => index <= 2,
+      loadMoreRows,
+      rowCount: 10,
+    }
+
+    const { onRowsRendered, pendingRowsCache } = useInfiniteLoader(props)
+
+    expect(pendingRowsCache.size).toBe(0)
+
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 5,
+    })
+
+    // Rows 3, 4, 5 should be marked as pending
+    expect(pendingRowsCache.has(3)).toBe(true)
+    expect(pendingRowsCache.has(4)).toBe(true)
+    expect(pendingRowsCache.has(5)).toBe(true)
+    expect(pendingRowsCache.has(2)).toBe(false)
+  })
+
+  test('should not load rows that are already pending', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded: (index) => index <= 2,
+      loadMoreRows,
+      rowCount: 10,
+      threshold: 0, // Disable threshold for this test
+      minimumBatchSize: 0, // Disable minimum batch size for this test
+    }
+
+    const { onRowsRendered } = useInfiniteLoader(props)
+
+    // First call loads rows 3-5
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 5,
+    })
+
+    expect(loadMoreRows).toHaveBeenCalledTimes(1)
+    expect(loadMoreRows).toHaveBeenLastCalledWith(3, 5)
+
+    // Second call with same range shouldn't load again
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 5,
+    })
+
+    // Should still be called only once
+    expect(loadMoreRows).toHaveBeenCalledTimes(1)
+  })
+
+  test('should clean up pending cache when rows are loaded', () => {
+    const loadMoreRows = vi.fn(() => Promise.resolve())
+    const loadedRows = new Set<number>([0, 1, 2])
+
+    const props: InfiniteLoaderProps = {
+      isRowLoaded: (index) => loadedRows.has(index),
+      loadMoreRows,
+      rowCount: 10,
+      threshold: 0,
+      minimumBatchSize: 0,
+    }
+
+    const { onRowsRendered, pendingRowsCache } = useInfiniteLoader(props)
+
+    // First call loads rows 3-5
+    onRowsRendered({
+      startIndex: 0,
+      stopIndex: 5,
+    })
+
+    expect(pendingRowsCache.size).toBe(3) // Rows 3, 4, 5 are pending
+    expect(pendingRowsCache.has(3)).toBe(true)
+    expect(pendingRowsCache.has(4)).toBe(true)
+    expect(pendingRowsCache.has(5)).toBe(true)
+
+    // Simulate rows 3 and 4 being loaded
+    loadedRows.add(3)
+    loadedRows.add(4)
+
+    // Next call should clean up loaded rows from pending cache
+    onRowsRendered({
+      startIndex: 3,
+      stopIndex: 7,
+    })
+
+    // Rows 3 and 4 should be removed from pending cache
+    expect(pendingRowsCache.has(3)).toBe(false)
+    expect(pendingRowsCache.has(4)).toBe(false)
+    // Row 5 should still be pending
+    expect(pendingRowsCache.has(5)).toBe(true)
+    // Rows 6 and 7 should now be pending
+    expect(pendingRowsCache.has(6)).toBe(true)
+    expect(pendingRowsCache.has(7)).toBe(true)
+
+    // Total should be 3 (rows 5, 6, 7)
+    expect(pendingRowsCache.size).toBe(3)
+  })
+})

package/src/virtual/composables/infinite-loader/useInfiniteLoader.ts

@@ -0,0 +1,88 @@
+import { computed, reactive, toValue, type MaybeRefOrGetter } from 'vue'
+import { scanForUnloadedIndices } from './scanForUnloadedIndices'
+import type { Indices, OnRowsRendered, InfiniteLoaderProps } from './types'
+
+export function useInfiniteLoader(
+  props: MaybeRefOrGetter<InfiniteLoaderProps>,
+) {
+  // Create a reactive Set to track pending rows
+  const pendingRowsCache = reactive(new Set<number>())
+
+  // Computed values that react to props changes
+  const isRowLoaded = computed(
+    () => toValue(props).isRowLoaded,
+  )
+  const loadMoreRows = computed(
+    () => toValue(props).loadMoreRows,
+  )
+  const minimumBatchSize = computed(
+    () => toValue(props).minimumBatchSize ?? 10,
+  )
+  const rowCount = computed(
+    () => toValue(props).rowCount,
+  )
+  const threshold = computed(
+    () => toValue(props).threshold ?? 15,
+  )
+
+  // Check if a row is loaded or pending
+  const isRowLoadedOrPending = (index: number): boolean => {
+    if (isRowLoaded.value(index)) {
+      // Clean up: remove from pending cache if it's now loaded
+      if (pendingRowsCache.has(index)) {
+        pendingRowsCache.delete(index)
+      }
+
+      return true
+    }
+
+    return pendingRowsCache.has(index)
+  }
+
+  // Main callback to be passed to VList's onRowsRendered
+  const onRowsRendered: OnRowsRendered = ({ startIndex, stopIndex }: Indices) => {
+    // Clean up: remove loaded rows from pending cache
+    // This prevents unbounded memory growth in long-running apps
+    if (pendingRowsCache.size > 0) {
+      const loadedIndices: number[] = []
+
+      pendingRowsCache.forEach((index) => {
+        if (isRowLoaded.value(index)) {
+          loadedIndices.push(index)
+        }
+      })
+
+      loadedIndices.forEach((index) => pendingRowsCache.delete(index))
+    }
+
+    const unloadedIndices = scanForUnloadedIndices({
+      isRowLoaded: isRowLoadedOrPending,
+      minimumBatchSize: minimumBatchSize.value,
+      rowCount: rowCount.value,
+      startIndex: Math.max(0, startIndex - threshold.value),
+      stopIndex: Math.min(rowCount.value - 1, stopIndex + threshold.value),
+    })
+
+    for (let index = 0; index < unloadedIndices.length; index++) {
+      const { startIndex: unloadedStartIndex, stopIndex: unloadedStopIndex } =
+        unloadedIndices[index]
+
+      // Mark all indices in this range as pending
+      for (
+        let idx = unloadedStartIndex;
+        idx <= unloadedStopIndex;
+        idx++
+      ) {
+        pendingRowsCache.add(idx)
+      }
+
+      // Fire the load request (fire-and-forget pattern)
+      loadMoreRows.value(unloadedStartIndex, unloadedStopIndex)
+    }
+  }
+
+  return {
+    onRowsRendered,
+    pendingRowsCache,
+  }
+}

package/src/virtual/core/createCachedBounds.ts

@@ -0,0 +1,72 @@
+import { assert } from '../utils/assert'
+import type { Bounds, CachedBounds, SizeFunction } from './types'
+
+export function createCachedBounds<Props extends object>({
+  itemCount,
+  itemProps,
+  itemSize,
+}: {
+  itemCount: number;
+  itemProps: Props;
+  itemSize: number | SizeFunction<Props>;
+}): CachedBounds {
+  const cache = new Map<number, Bounds>()
+
+  return {
+    get(index: number) {
+      assert(index < itemCount, `Invalid index ${index}`)
+
+      while (cache.size - 1 < index) {
+        const currentIndex = cache.size
+
+        let size: number
+
+        switch (typeof itemSize) {
+          case 'function': {
+            size = itemSize(currentIndex, itemProps)
+            break
+          }
+          case 'number': {
+            size = itemSize
+            break
+          }
+        }
+
+        if (currentIndex === 0) {
+          cache.set(currentIndex, {
+            size,
+            scrollOffset: 0,
+          })
+        } else {
+          const previousRowBounds = cache.get(currentIndex - 1)
+
+          assert(
+            previousRowBounds !== undefined,
+            `Unexpected bounds cache miss for index ${index}`,
+          )
+
+          cache.set(currentIndex, {
+            scrollOffset:
+              previousRowBounds.scrollOffset + previousRowBounds.size,
+            size,
+          })
+        }
+      }
+
+      const bounds = cache.get(index)
+
+      assert(
+        bounds !== undefined,
+        `Unexpected bounds cache miss for index ${index}`,
+      )
+
+      return bounds
+    },
+    set(index: number, bounds: Bounds) {
+      cache.set(index, bounds)
+    },
+    get size() {
+      return cache.size
+    },
+  }
+}

package/src/virtual/core/getEstimatedSize.ts

@@ -0,0 +1,29 @@
+import type { CachedBounds, SizeFunction } from './types'
+import { assert } from '../utils/assert'
+
+export function getEstimatedSize<Props extends object>({
+  cachedBounds,
+  itemCount,
+  itemSize,
+}: {
+  cachedBounds: CachedBounds;
+  itemCount: number;
+  itemSize: number | SizeFunction<Props>;
+}) {
+  if (itemCount === 0) {
+    return 0
+  } else if (typeof itemSize === 'number') {
+    return itemCount * itemSize
+  } else {
+    const bounds = cachedBounds.get(
+      cachedBounds.size === 0 ? 0 : cachedBounds.size - 1,
+    )
+
+    assert(bounds !== undefined, 'Unexpected bounds cache miss')
+
+    const averageItemSize =
+      (bounds.scrollOffset + bounds.size) / cachedBounds.size
+
+    return itemCount * averageItemSize
+  }
+}