@indielayer/ui 1.16.0 → 1.18.0

package/src/virtual/components/virtualList/useDynamicRowHeight.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test, beforeEach, afterEach } from 'vitest'
+import { ref, nextTick } from 'vue'
+import { useDynamicRowHeight, DATA_ATTRIBUTE_LIST_INDEX } from './useDynamicRowHeight'
+import type { DynamicRowHeight } from './types'
+import { mockResizeObserver, setElementSize } from '../../test-utils/mockResizeObserver'
+
+describe('useDynamicRowHeight', () => {
+  let unmock: (() => void) | undefined
+  let instances: DynamicRowHeight[] = []
+
+  beforeEach(() => {
+    unmock = mockResizeObserver()
+    instances = []
+  })
+
+  afterEach(() => {
+    instances.forEach((instance) => instance.cleanup())
+    if (unmock) {
+      unmock()
+    }
+  })
+
+  function createDynamicRowHeight(
+    ...args: Parameters<typeof useDynamicRowHeight>
+  ): DynamicRowHeight {
+    const instance = useDynamicRowHeight(...args)
+
+    instances.push(instance)
+
+    return instance
+  }
+
+  describe('getAverageRowHeight', () => {
+    test('returns an initial estimate based on the defaultRowHeight', () => {
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(100)
+    })
+
+    test('returns an estimate based on measured rows', () => {
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      dynamicRowHeight.setRowHeight(0, 10)
+      dynamicRowHeight.setRowHeight(1, 20)
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(15)
+
+      dynamicRowHeight.setRowHeight(2, 30)
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(20)
+
+      dynamicRowHeight.setRowHeight(2, 15)
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(15)
+    })
+
+    test('resets when key changes', async () => {
+      const key = ref('a')
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+        key,
+      })
+
+      dynamicRowHeight.setRowHeight(0, 10)
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(10)
+
+      // Key hasn't changed
+      await nextTick()
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(10)
+
+      // Change key
+      key.value = 'b'
+      await nextTick()
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(100)
+    })
+  })
+
+  describe('getRowHeight', () => {
+    test('returns estimated height for a row that has not yet been measured', () => {
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(100)
+    })
+
+    test('returns the most recently measured size', () => {
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      dynamicRowHeight.setRowHeight(0, 15)
+      dynamicRowHeight.setRowHeight(1, 20)
+      dynamicRowHeight.setRowHeight(3, 25)
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(15)
+      expect(dynamicRowHeight.getRowHeight(1)).toBe(20)
+      expect(dynamicRowHeight.getRowHeight(2)).toBe(100)
+      expect(dynamicRowHeight.getRowHeight(3)).toBe(25)
+
+      dynamicRowHeight.setRowHeight(1, 25)
+      expect(dynamicRowHeight.getRowHeight(1)).toBe(25)
+    })
+
+    test('resets when key changes', async () => {
+      const key = ref('a')
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+        key,
+      })
+
+      dynamicRowHeight.setRowHeight(0, 10)
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(10)
+
+      // Key hasn't changed
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(10)
+
+      // Change key
+      key.value = 'b'
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(100)
+    })
+  })
+
+  describe('observeRowElements', () => {
+    function createRowElement(index: number) {
+      const element = document.createElement('div')
+
+      element.setAttribute(DATA_ATTRIBUTE_LIST_INDEX, '' + index)
+
+      return element
+    }
+
+    test('should update cache when an observed element is resized', async () => {
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      const elementA = createRowElement(0)
+      const elementB = createRowElement(1)
+
+      dynamicRowHeight.observeRowElements([elementA, elementB])
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(100)
+      expect(dynamicRowHeight.getRowHeight(1)).toBe(100)
+
+      setElementSize({
+        element: elementB,
+        width: 100,
+        height: 20,
+      })
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(100)
+      expect(dynamicRowHeight.getRowHeight(1)).toBe(20)
+
+      setElementSize({
+        element: elementA,
+        width: 100,
+        height: 15,
+      })
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(15)
+      expect(dynamicRowHeight.getRowHeight(1)).toBe(20)
+    })
+
+    test('should unobserve an element when requested', async () => {
+      const dynamicRowHeight = createDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      const element = createRowElement(0)
+
+      const unobserve = dynamicRowHeight.observeRowElements([element])
+
+      setElementSize({
+        element,
+        width: 100,
+        height: 10,
+      })
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(10)
+
+      unobserve()
+
+      setElementSize({
+        element,
+        width: 100,
+        height: 20,
+      })
+      await nextTick()
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(10)
+    })
+  })
+
+  // setRowHeight is tested indirectly by "getAverageRowHeight" and "getRowHeight" blocks above
+})

package/src/virtual/components/virtualList/useDynamicRowHeight.ts

@@ -0,0 +1,149 @@
+import { getCurrentInstance, onBeforeUnmount, ref, watch, type Ref } from 'vue'
+import { assert } from '../../utils/assert'
+import type { DynamicRowHeight } from './types'
+
+export const DATA_ATTRIBUTE_LIST_INDEX = 'data-virtual-index'
+
+export function useDynamicRowHeight({
+  defaultRowHeight,
+  key,
+}: {
+  defaultRowHeight: number;
+  key?: Ref<string | number | undefined> | string | number;
+}): DynamicRowHeight {
+  const map = ref<Map<number, number>>(new Map())
+  // Revision counter to trigger reactivity when map changes
+  const revision = ref(0)
+
+  // Handle reactive key changes
+  if (key !== undefined && typeof key === 'object' && 'value' in key) {
+    watch(key as Ref<string | number | undefined>, () => {
+      map.value = new Map()
+      revision.value++
+    })
+  }
+
+  const getAverageRowHeight = () => {
+    // Access revision to track dependency
+    revision.value
+
+    let totalHeight = 0
+
+    map.value.forEach((height) => {
+      totalHeight += height
+    })
+
+    if (totalHeight === 0) {
+      return defaultRowHeight
+    }
+
+    return totalHeight / map.value.size
+  }
+
+  const getRowHeight = (index: number) => {
+    // Access revision to track dependency
+    revision.value
+
+    const measuredHeight = map.value.get(index)
+
+    if (measuredHeight !== undefined) {
+      return measuredHeight
+    }
+
+    // Don't cache default height here - let ResizeObserver do the measuring
+    // This prevents stale default heights from blocking updates
+    return defaultRowHeight
+  }
+
+  const setRowHeight = (index: number, size: number) => {
+    if (map.value.get(index) === size) {
+      return
+    }
+
+    // Create a new Map to trigger reactivity
+    const newMap = new Map(map.value)
+
+    newMap.set(index, size)
+    map.value = newMap
+    revision.value++
+  }
+
+  const resizeObserverCallback = (entries: ResizeObserverEntry[]) => {
+    if (entries.length === 0) {
+      return
+    }
+
+    // Batch updates to avoid triggering multiple recalculations
+    let hasChanges = false
+    const updates: Array<{ index: number; height: number; }> = []
+
+    entries.forEach((entry) => {
+      const { borderBoxSize, target } = entry
+
+      const attribute = target.getAttribute(DATA_ATTRIBUTE_LIST_INDEX)
+
+      assert(
+        attribute !== null,
+        `Invalid ${DATA_ATTRIBUTE_LIST_INDEX} attribute value`,
+      )
+
+      const index = parseInt(attribute)
+
+      const { blockSize: height } = borderBoxSize[0]
+
+      if (!height) {
+        // Ignore heights that have not yet been measured (e.g. <img> elements that have not yet loaded)
+        return
+      }
+
+      // Check if height actually changed before updating
+      const currentHeight = map.value.get(index)
+
+      if (currentHeight !== height) {
+        updates.push({ index, height })
+        hasChanges = true
+      }
+    })
+
+    // Apply all updates at once
+    if (hasChanges) {
+      const newMap = new Map(map.value)
+
+      updates.forEach(({ index, height }) => {
+        newMap.set(index, height)
+      })
+      map.value = newMap
+      revision.value++
+    }
+  }
+
+  const resizeObserver = new ResizeObserver(resizeObserverCallback)
+
+  function cleanup() {
+    resizeObserver.disconnect()
+  }
+
+  if (getCurrentInstance()) {
+    onBeforeUnmount(cleanup)
+  }
+
+  const observeRowElements = (elements: Element[] | NodeListOf<Element>) => {
+    const elementsArray = Array.isArray(elements)
+      ? elements
+      : Array.from(elements)
+
+    elementsArray.forEach((element) => resizeObserver.observe(element))
+
+    return () => {
+      elementsArray.forEach((element) => resizeObserver.unobserve(element))
+    }
+  }
+
+  return {
+    getAverageRowHeight,
+    getRowHeight,
+    setRowHeight,
+    observeRowElements,
+    cleanup,
+  }
+}

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