@indielayer/ui 1.16.0 → 1.18.0

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
+  }
+}

package/src/virtual/core/getOffsetForIndex.ts

@@ -0,0 +1,90 @@
+import type { Align } from '../types'
+import { getEstimatedSize } from './getEstimatedSize'
+import type { CachedBounds, SizeFunction } from './types'
+
+export function getOffsetForIndex<Props extends object>({
+  align,
+  cachedBounds,
+  index,
+  itemCount,
+  itemSize,
+  containerScrollOffset,
+  containerSize,
+}: {
+  align: Align;
+  cachedBounds: CachedBounds;
+  index: number;
+  itemCount: number;
+  itemSize: number | SizeFunction<Props>;
+  containerScrollOffset: number;
+  containerSize: number;
+}) {
+  if (index < 0 || index >= itemCount) {
+    throw new RangeError(
+      `Invalid index specified: ${index}. Index ${index} is not within the range of 0 - ${itemCount - 1}`,
+    )
+  }
+
+  const estimatedTotalSize = getEstimatedSize({
+    cachedBounds,
+    itemCount,
+    itemSize,
+  })
+
+  const bounds = cachedBounds.get(index)
+  const maxOffset = Math.max(
+    0,
+    Math.min(estimatedTotalSize - containerSize, bounds.scrollOffset),
+  )
+  const minOffset = Math.max(
+    0,
+    bounds.scrollOffset - containerSize + bounds.size,
+  )
+
+  if (align === 'smart') {
+    if (
+      containerScrollOffset >= minOffset &&
+      containerScrollOffset <= maxOffset
+    ) {
+      align = 'auto'
+    } else {
+      align = 'center'
+    }
+  }
+
+  switch (align) {
+    case 'start': {
+      return maxOffset
+    }
+    case 'end': {
+      return minOffset
+    }
+    case 'center': {
+      if (bounds.scrollOffset <= containerSize / 2) {
+        // Too near the beginning to center-align
+        return 0
+      } else if (
+        bounds.scrollOffset + bounds.size / 2 >=
+        estimatedTotalSize - containerSize / 2
+      ) {
+        // Too near the end to center-align
+        return estimatedTotalSize - containerSize
+      } else {
+        return bounds.scrollOffset + bounds.size / 2 - containerSize / 2
+      }
+    }
+    case 'auto':
+    default: {
+      if (
+        containerScrollOffset >= minOffset &&
+        containerScrollOffset <= maxOffset
+      ) {
+        return containerScrollOffset
+      } else if (containerScrollOffset < minOffset) {
+        return minOffset
+      } else {
+        return maxOffset
+      }
+    }
+  }
+}

package/src/virtual/core/getStartStopIndices.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest'
+import { getStartStopIndices } from './getStartStopIndices'
+import { createCachedBounds } from './createCachedBounds'
+
+describe('getStartStopIndices', () => {
+  it('calculates visible indices correctly', () => {
+    const cachedBounds = createCachedBounds({
+      itemCount: 100,
+      itemProps: {},
+      itemSize: 50,
+    })
+
+    const result = getStartStopIndices({
+      cachedBounds,
+      containerScrollOffset: 0,
+      containerSize: 400,
+      itemCount: 100,
+      overscanCount: 3,
+    })
+
+    expect(result.startIndexVisible).toBe(0)
+    expect(result.startIndexOverscan).toBe(0)
+    expect(result.stopIndexVisible).toBeGreaterThanOrEqual(0)
+    expect(result.stopIndexOverscan).toBeGreaterThanOrEqual(result.stopIndexVisible)
+  })
+
+  it('handles scrolled position', () => {
+    const cachedBounds = createCachedBounds({
+      itemCount: 100,
+      itemProps: {},
+      itemSize: 50,
+    })
+
+    const result = getStartStopIndices({
+      cachedBounds,
+      containerScrollOffset: 500,
+      containerSize: 400,
+      itemCount: 100,
+      overscanCount: 3,
+    })
+
+    expect(result.startIndexVisible).toBeGreaterThan(0)
+    expect(result.startIndexOverscan).toBeLessThanOrEqual(result.startIndexVisible)
+  })
+})

package/src/virtual/core/getStartStopIndices.ts

@@ -0,0 +1,71 @@
+import type { CachedBounds } from './types'
+
+export function getStartStopIndices({
+  cachedBounds,
+  containerScrollOffset,
+  containerSize,
+  itemCount,
+  overscanCount,
+}: {
+  cachedBounds: CachedBounds;
+  containerScrollOffset: number;
+  containerSize: number;
+  itemCount: number;
+  overscanCount: number;
+}): {
+    startIndexVisible: number;
+    stopIndexVisible: number;
+    startIndexOverscan: number;
+    stopIndexOverscan: number;
+  } {
+  const maxIndex = itemCount - 1
+
+  let startIndexVisible = 0
+  let stopIndexVisible = -1
+  let startIndexOverscan = 0
+  let stopIndexOverscan = -1
+  let currentIndex = 0
+
+  while (currentIndex < maxIndex) {
+    const bounds = cachedBounds.get(currentIndex)
+
+    if (bounds.scrollOffset + bounds.size > containerScrollOffset) {
+      break
+    }
+
+    currentIndex++
+  }
+
+  startIndexVisible = currentIndex
+  startIndexOverscan = Math.max(0, startIndexVisible - overscanCount)
+
+  while (currentIndex < maxIndex) {
+    const bounds = cachedBounds.get(currentIndex)
+
+    if (
+      bounds.scrollOffset + bounds.size >=
+      containerScrollOffset + containerSize
+    ) {
+      break
+    }
+
+    currentIndex++
+  }
+
+  stopIndexVisible = Math.min(maxIndex, currentIndex)
+  stopIndexOverscan = Math.min(itemCount - 1, stopIndexVisible + overscanCount)
+
+  if (startIndexVisible < 0) {
+    startIndexVisible = 0
+    stopIndexVisible = -1
+    startIndexOverscan = 0
+    stopIndexOverscan = -1
+  }
+
+  return {
+    startIndexVisible,
+    stopIndexVisible,
+    startIndexOverscan,
+    stopIndexOverscan,
+  }
+}

package/src/virtual/core/types.ts

@@ -0,0 +1,17 @@
+export type Bounds = {
+  size: number;
+  scrollOffset: number;
+};
+
+export type CachedBounds = {
+  get(index: number): Bounds;
+  set(index: number, bounds: Bounds): void;
+  size: number;
+};
+
+export type Direction = 'horizontal' | 'vertical';
+
+export type SizeFunction<Props extends object> = (
+  index: number,
+  props: Props
+) => number;

package/src/virtual/core/useCachedBounds.ts

@@ -0,0 +1,21 @@
+import { computed, type ComputedRef } from 'vue'
+import { createCachedBounds } from './createCachedBounds'
+import type { CachedBounds, SizeFunction } from './types'
+
+export function useCachedBounds<Props extends object>({
+  itemCount,
+  itemProps,
+  itemSize,
+}: {
+  itemCount: number;
+  itemProps: Props;
+  itemSize: number | SizeFunction<Props>;
+}): ComputedRef<CachedBounds> {
+  return computed(() =>
+    createCachedBounds({
+      itemCount,
+      itemProps,
+      itemSize,
+    }),
+  )
+}

package/src/virtual/core/useIsRtl.ts

@@ -0,0 +1,25 @@
+import { ref, watch, type Ref } from 'vue'
+import { isRtl } from '../utils/isRtl'
+
+export function useIsRtl(
+  element: Ref<HTMLElement | null>,
+  dir?: 'ltr' | 'rtl' | 'auto',
+) {
+  const value = ref(dir === 'rtl')
+
+  watch(
+    [element, () => dir],
+    ([el, direction]) => {
+      if (el) {
+        if (!direction || direction === 'auto') {
+          value.value = isRtl(el)
+        } else {
+          value.value = direction === 'rtl'
+        }
+      }
+    },
+    { immediate: true },
+  )
+
+  return value
+}