@indielayer/ui 1.16.0 → 1.17.0

package/src/virtual/components/virtualList/VirtualList.vue

@@ -0,0 +1,233 @@
+<script lang="ts">
+export default {
+  name: 'XVirtualList',
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch, type CSSProperties } from 'vue'
+import { useVirtualizer } from '../../core/useVirtualizer'
+import type { Align } from '../../types'
+import { isDynamicRowHeight as isDynamicRowHeightUtil } from './isDynamicRowHeight'
+import type { VirtualListProps, VirtualListImperativeAPI, DynamicRowHeight } from './types'
+import { DATA_ATTRIBUTE_LIST_INDEX } from './useDynamicRowHeight'
+
+const props = withDefaults(defineProps<VirtualListProps>(), {
+  defaultHeight: 0,
+  overscanCount: 3,
+  tag: 'div',
+})
+
+const element = ref<HTMLDivElement | null>(null)
+
+const rowProps = computed(() => props.rowProps || ({} as Record<string, unknown>))
+
+const itemCount = computed(() => props.rowCount)
+
+const isDynamicRowHeight = computed(() => isDynamicRowHeightUtil(props.rowHeight))
+
+const rowHeight = computed<number | string | ((index: number, cellProps: Record<string, unknown>) => number)>(() => {
+  if (isDynamicRowHeight.value) {
+    const dynamicHeight = props.rowHeight as DynamicRowHeight
+    const avgHeight = dynamicHeight.getAverageRowHeight()
+
+    return (index: number) => {
+      return (
+        dynamicHeight.getRowHeight(index) ??
+        avgHeight
+      )
+    }
+  }
+
+  return props.rowHeight as number | string | ((index: number, cellProps: Record<string, unknown>) => number)
+})
+
+const {
+  getCellBounds,
+  getEstimatedSize,
+  scrollToIndex,
+  startIndexOverscan,
+  startIndexVisible,
+  stopIndexOverscan,
+  stopIndexVisible,
+} = useVirtualizer({
+  containerElement: element,
+  containerStyle: props.style,
+  defaultContainerSize: props.defaultHeight,
+  direction: 'vertical',
+  itemCount,
+  itemProps: rowProps,
+  itemSize: rowHeight,
+  onResize: props.onResize,
+  overscanCount: props.overscanCount,
+})
+
+// Expose imperative API
+defineExpose<VirtualListImperativeAPI>({
+  get element() {
+    return element.value
+  },
+
+  scrollToRow({
+    align = 'auto',
+    behavior = 'auto',
+    index,
+  }: {
+    align?: Align;
+    behavior?: ScrollBehavior;
+    index: number;
+  }) {
+    const top = scrollToIndex({
+      align,
+      containerScrollOffset: element.value?.scrollTop ?? 0,
+      index,
+    })
+
+    if (typeof element.value?.scrollTo === 'function' && top !== undefined) {
+      element.value.scrollTo({
+        behavior,
+        top,
+      })
+    }
+  },
+})
+
+// Watch for dynamic row heights - run after DOM updates
+watch(
+  [element, startIndexOverscan, stopIndexOverscan, isDynamicRowHeight, () => props.rowHeight],
+  ([el, start, stop, isDynamic]) => {
+    if (!el || !isDynamic) {
+      return
+    }
+
+    // Use nextTick to ensure DOM is fully updated
+    const setupObserver = () => {
+      const rows = Array.from(el.children).filter((item, index) => {
+        if (item.hasAttribute('aria-hidden')) {
+          // Ignore sizing element
+          return false
+        }
+
+        const attribute = `${start + index}`
+
+        item.setAttribute(DATA_ATTRIBUTE_LIST_INDEX, attribute)
+
+        return true
+      })
+
+      const dynamicHeight = props.rowHeight as DynamicRowHeight
+
+      return dynamicHeight.observeRowElements(rows)
+    }
+
+    // Return cleanup function
+    return setupObserver()
+  },
+  { flush: 'post' }, // Run after DOM updates
+)
+
+// Notify when visible rows change
+watch(
+  [startIndexOverscan, startIndexVisible, stopIndexOverscan, stopIndexVisible],
+  ([startOverscan, startVisible, stopOverscan, stopVisible]) => {
+    if (startOverscan >= 0 && stopOverscan >= 0 && props.onRowsRendered) {
+      props.onRowsRendered(
+        {
+          startIndex: startVisible,
+          stopIndex: stopVisible,
+        },
+        {
+          startIndex: startOverscan,
+          stopIndex: stopOverscan,
+        },
+      )
+    }
+  },
+)
+
+interface RowData {
+  key: number;
+  index: number;
+  style: CSSProperties;
+  ariaAttributes: {
+    'aria-posinset': number;
+    'aria-setsize': number;
+    role: 'listitem';
+  };
+}
+
+// Generate rows
+const rows = computed(() => {
+  const result: RowData[] = []
+
+  if (props.rowCount > 0) {
+    for (
+      let index = startIndexOverscan.value;
+      index <= stopIndexOverscan.value;
+      index++
+    ) {
+      const bounds = getCellBounds(index)
+
+      const rowStyle: CSSProperties = {
+        position: 'absolute',
+        left: 0,
+        transform: `translateY(${bounds.scrollOffset}px)`,
+        // In case of dynamic row heights, don't specify a height style
+        height: isDynamicRowHeight.value ? undefined : `${bounds.size}px`,
+        width: '100%',
+      }
+
+      result.push({
+        key: index,
+        index,
+        style: rowStyle,
+        ariaAttributes: {
+          'aria-posinset': index + 1,
+          'aria-setsize': props.rowCount,
+          role: 'listitem',
+        },
+      })
+    }
+  }
+
+  return result
+})
+</script>
+
+<template>
+  <component
+    :is="tag"
+    ref="element"
+    :class="$props.class"
+    :style="{
+      position: 'relative',
+      maxHeight: '100%',
+      flexGrow: 1,
+      overflowY: 'auto',
+      ...style
+    }"
+    role="list"
+  >
+    <template v-for="row in rows" :key="row.key">
+      <slot
+        name="row"
+        :index="row.index"
+        :style="row.style"
+        :aria-attributes="row.ariaAttributes"
+        :props="rowProps"
+      ></slot>
+    </template>
+
+    <slot ></slot>
+
+    <!-- Sizing element -->
+    <div
+      aria-hidden
+      :style="{
+        height: `${getEstimatedSize}px`,
+        width: '100%',
+        zIndex: -1
+      }"
+    ></div>
+  </component>
+</template>

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

@@ -0,0 +1,13 @@
+import type { DynamicRowHeight } from './types'
+
+export function isDynamicRowHeight(
+  value: unknown,
+): value is DynamicRowHeight {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'getAverageRowHeight' in value &&
+    'getRowHeight' in value &&
+    'setRowHeight' in value
+  )
+}

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

@@ -0,0 +1,127 @@
+import type { CSSProperties } from 'vue'
+import type { TagNames } from '../../types'
+
+export type DynamicRowHeight = {
+  getAverageRowHeight(): number;
+  getRowHeight(index: number): number | undefined;
+  setRowHeight(index: number, size: number): void;
+  observeRowElements: (elements: Element[] | NodeListOf<Element>) => () => void;
+  cleanup: () => void;
+};
+
+type ForbiddenKeys = 'ariaAttributes' | 'index' | 'style';
+type ExcludeForbiddenKeys<Type> = {
+  [Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
+};
+
+export interface VirtualListProps {
+  /**
+   * CSS class name.
+   */
+  class?: string;
+
+  /**
+   * Default height of list for initial render.
+   * This value is important for server rendering.
+   */
+  defaultHeight?: number;
+
+  /**
+   * Callback notified when the List's outermost HTMLElement resizes.
+   * This may be used to (re)scroll a row into view.
+   */
+  onResize?: (
+    size: { height: number; width: number; },
+    prevSize: { height: number; width: number; }
+  ) => void;
+
+  /**
+   * Callback notified when the range of visible rows changes.
+   */
+  onRowsRendered?: (
+    visibleRows: { startIndex: number; stopIndex: number; },
+    allRows: { startIndex: number; stopIndex: number; }
+  ) => void;
+
+  /**
+   * How many additional rows to render outside of the visible area.
+   * This can reduce visual flickering near the edges of a list when scrolling.
+   */
+  overscanCount?: number;
+
+  /**
+   * Number of items to be rendered in the list.
+   */
+  rowCount: number;
+
+  /**
+   * Row height; the following formats are supported:
+   * - number of pixels (number)
+   * - percentage of the grid's current height (string)
+   * - function that returns the row height (in pixels) given an index and `cellProps`
+   * - dynamic row height cache returned by the `useDynamicRowHeight` hook
+   *
+   * ⚠️ Dynamic row heights are not as efficient as predetermined sizes.
+   * It's recommended to provide your own height values if they can be determined ahead of time.
+   */
+  rowHeight:
+  | number
+  | string
+  | ((index: number, cellProps: Record<string, unknown>) => number)
+  | DynamicRowHeight;
+
+  /**
+   * Additional props to be passed to the row-rendering component via slots.
+   */
+  rowProps?: ExcludeForbiddenKeys<Record<string, unknown>>;
+
+  /**
+   * Optional CSS properties.
+   * The list of rows will fill the height defined by this style.
+   */
+  style?: CSSProperties;
+
+  /**
+   * Can be used to override the root HTML element rendered by the List component.
+   * The default value is "div", meaning that List renders an HTMLDivElement as its root.
+   *
+   * ⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
+   */
+  tag?: TagNames;
+}
+
+export interface RowSlotProps {
+  ariaAttributes: {
+    'aria-posinset': number;
+    'aria-setsize': number;
+    role: 'listitem';
+  };
+  index: number;
+  style: CSSProperties;
+  props?: Record<string, unknown>;
+}
+
+/**
+ * Imperative List API.
+ */
+export interface VirtualListImperativeAPI {
+  /**
+   * Outermost HTML element for the list if mounted and null (if not mounted.
+   */
+  readonly element: HTMLDivElement | null;
+
+  /**
+   * Scrolls the list so that the specified row is visible.
+   *
+   * @param align Determines the vertical alignment of the element within the list
+   * @param behavior Determines whether scrolling is instant or animates smoothly
+   * @param index Index of the row to scroll to (0-based)
+   *
+   * @throws RangeError if an invalid row index is provided
+   */
+  scrollToRow(config: {
+    align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+    behavior?: 'auto' | 'instant' | 'smooth';
+    index: number;
+  }): void;
+}

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

@@ -0,0 +1,183 @@
+import { describe, expect, test, beforeEach, afterEach } from 'vitest'
+import { ref, nextTick } from 'vue'
+import { useDynamicRowHeight, DATA_ATTRIBUTE_LIST_INDEX } from './useDynamicRowHeight'
+import { mockResizeObserver, setElementSize } from '../../test-utils/mockResizeObserver'
+
+describe('useDynamicRowHeight', () => {
+  let unmock: (() => void) | undefined
+
+  beforeEach(() => {
+    unmock = mockResizeObserver()
+  })
+
+  afterEach(() => {
+    if (unmock) {
+      unmock()
+    }
+  })
+
+  describe('getAverageRowHeight', () => {
+    test('returns an initial estimate based on the defaultRowHeight', () => {
+      const dynamicRowHeight = useDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      expect(dynamicRowHeight.getAverageRowHeight()).toBe(100)
+    })
+
+    test('returns an estimate based on measured rows', () => {
+      const dynamicRowHeight = useDynamicRowHeight({
+        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 = useDynamicRowHeight({
+        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 = useDynamicRowHeight({
+        defaultRowHeight: 100,
+      })
+
+      expect(dynamicRowHeight.getRowHeight(0)).toBe(100)
+    })
+
+    test('returns the most recently measured size', () => {
+      const dynamicRowHeight = useDynamicRowHeight({
+        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 = useDynamicRowHeight({
+        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 = useDynamicRowHeight({
+        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 = useDynamicRowHeight({
+        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,147 @@
+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)
+
+  onBeforeUnmount(cleanup)
+
+  function cleanup() {
+    resizeObserver.disconnect()
+  }
+
+  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,
+  }
+}