@indielayer/ui 1.16.0 → 1.18.0

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

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { h, nextTick, type CSSProperties } from 'vue'
+import VirtualList from './VirtualList.vue'
+import { useDynamicRowHeight, DATA_ATTRIBUTE_LIST_INDEX } from './useDynamicRowHeight'
+import { mockResizeObserver, setElementSize } from '../../test-utils/mockResizeObserver'
+import type { DynamicRowHeight } from './types'
+
+interface RowSlotProps {
+  index: number;
+  style: CSSProperties;
+}
+
+const listStyle = { height: '400px' } as const
+
+function mountVirtualList(
+  props: Record<string, unknown>,
+  dynamicRowHeight?: DynamicRowHeight,
+) {
+  return mount(VirtualList, {
+    props: {
+      rowCount: 100,
+      rowHeight: dynamicRowHeight ?? 50,
+      style: listStyle,
+      ...props,
+    },
+    slots: {
+      row: ({ index, style }: RowSlotProps) =>
+        h('div', { style, class: 'test-row' }, `Row ${index}`),
+    },
+  })
+}
+
+function createMockDynamicRowHeight(defaultRowHeight = 50) {
+  const unobserve = vi.fn<[], void>()
+
+  const dynamicRowHeight: DynamicRowHeight = {
+    getAverageRowHeight: vi.fn(() => defaultRowHeight),
+    getRowHeight: vi.fn(() => undefined),
+    setRowHeight: vi.fn(),
+    observeRowElements: vi.fn(() => unobserve),
+    cleanup: vi.fn(),
+  }
+
+  return { dynamicRowHeight, unobserve }
+}
+
+describe('VirtualList', () => {
+  it('renders correctly', () => {
+    const wrapper = mountVirtualList({})
+
+    expect(wrapper.exists()).toBe(true)
+    expect(wrapper.attributes('role')).toBe('list')
+  })
+
+  it('renders visible rows', () => {
+    const wrapper = mountVirtualList({})
+
+    const rows = wrapper.findAll('.test-row')
+
+    expect(rows.length).toBeGreaterThan(0)
+  })
+
+  describe('dynamic row height watch', () => {
+    it('does not observe row elements when rowHeight is fixed', async () => {
+      const { dynamicRowHeight } = createMockDynamicRowHeight()
+
+      mountVirtualList({ rowHeight: 50 })
+
+      await flushPromises()
+      await nextTick()
+
+      expect(dynamicRowHeight.observeRowElements).not.toHaveBeenCalled()
+    })
+
+    it('observes visible row elements and sets data-virtual-index', async () => {
+      const { dynamicRowHeight } = createMockDynamicRowHeight()
+
+      const wrapper = mountVirtualList({ rowHeight: dynamicRowHeight })
+
+      await flushPromises()
+      await nextTick()
+
+      expect(dynamicRowHeight.observeRowElements).toHaveBeenCalled()
+
+      const observedElements = vi.mocked(dynamicRowHeight.observeRowElements).mock
+        .calls[0]?.[0] as Element[]
+
+      expect(observedElements.length).toBeGreaterThan(0)
+      expect(
+        observedElements.every((element) => !element.hasAttribute('aria-hidden')),
+      ).toBe(true)
+
+      const listElement = wrapper.element as HTMLElement
+      const rowElements = Array.from(listElement.children).filter(
+        (child) => !child.hasAttribute('aria-hidden'),
+      )
+
+      expect(rowElements.length).toBe(observedElements.length)
+      rowElements.forEach((element) => {
+        expect(element.hasAttribute(DATA_ATTRIBUTE_LIST_INDEX)).toBe(true)
+      })
+    })
+
+    it('runs previous unobserve when the observed range changes', async () => {
+      const { dynamicRowHeight, unobserve } = createMockDynamicRowHeight()
+
+      const wrapper = mountVirtualList({ rowHeight: dynamicRowHeight })
+
+      await flushPromises()
+      await nextTick()
+
+      expect(dynamicRowHeight.observeRowElements).toHaveBeenCalledTimes(1)
+      expect(unobserve).not.toHaveBeenCalled()
+
+      const listElement = wrapper.element as HTMLDivElement
+
+      listElement.scrollTop = 2500
+      listElement.dispatchEvent(new Event('scroll'))
+      await flushPromises()
+      await nextTick()
+
+      expect(unobserve).toHaveBeenCalledTimes(1)
+      expect(dynamicRowHeight.observeRowElements).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('dynamic row height integration', () => {
+    let unmockResizeObserver: (() => void) | undefined
+    let dynamicRowHeight: DynamicRowHeight | undefined
+
+    beforeEach(() => {
+      unmockResizeObserver = mockResizeObserver()
+      dynamicRowHeight = useDynamicRowHeight({ defaultRowHeight: 50 })
+    })
+
+    afterEach(() => {
+      dynamicRowHeight?.cleanup()
+      unmockResizeObserver?.()
+    })
+
+    it('updates measured heights when observed rows resize', async () => {
+      const wrapper = mountVirtualList({ rowHeight: dynamicRowHeight })
+
+      await flushPromises()
+      await nextTick()
+
+      const rowElement = wrapper.find('.test-row').element as HTMLElement
+
+      setElementSize({
+        element: rowElement,
+        width: 100,
+        height: 72,
+      })
+
+      await flushPromises()
+      await nextTick()
+
+      const index = Number(rowElement.getAttribute(DATA_ATTRIBUTE_LIST_INDEX))
+
+      expect(dynamicRowHeight?.getRowHeight(index)).toBe(72)
+    })
+  })
+})

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

@@ -0,0 +1,227 @@
+<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], _old, onCleanup) => {
+    if (!el || !isDynamic) {
+      return
+    }
+
+    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
+
+    onCleanup(dynamicHeight.observeRowElements(rows))
+  },
+  { 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;
+}