@indielayer/ui 1.16.0 → 1.18.0

package/src/virtual/core/useItemSize.ts

@@ -0,0 +1,34 @@
+import { assert } from '../utils/assert'
+import type { SizeFunction } from './types'
+
+export function useItemSize<Props extends object>({
+  containerSize,
+  itemSize: itemSizeProp,
+}: {
+  containerSize: number;
+  itemSize: number | string | SizeFunction<Props>;
+}) {
+  let itemSize: number | SizeFunction<Props>
+
+  switch (typeof itemSizeProp) {
+    case 'string': {
+      assert(
+        itemSizeProp.endsWith('%'),
+        `Invalid item size: "${itemSizeProp}"; string values must be percentages (e.g. "100%")`,
+      )
+      assert(
+        containerSize !== undefined,
+        'Container size must be defined if a percentage item size is specified',
+      )
+
+      itemSize = (containerSize * parseInt(itemSizeProp)) / 100
+      break
+    }
+    default: {
+      itemSize = itemSizeProp
+      break
+    }
+  }
+
+  return itemSize
+}

package/src/virtual/core/useVirtualizer.ts

@@ -0,0 +1,294 @@
+import {
+  computed,
+  isRef,
+  ref,
+  watch,
+  type ComputedRef,
+  type CSSProperties,
+  type Ref,
+} from 'vue'
+import { useEventListener, useResizeObserver } from '@vueuse/core'
+import type { Align } from '../types'
+import { parseNumericStyleValue } from '../utils/parseNumericStyleValue'
+import { adjustScrollOffsetForRtl } from '../utils/adjustScrollOffsetForRtl'
+import { shallowCompare } from '../utils/shallowCompare'
+import { getEstimatedSize as getEstimatedSizeUtil } from './getEstimatedSize'
+import { getOffsetForIndex } from './getOffsetForIndex'
+import { getStartStopIndices as getStartStopIndicesUtil } from './getStartStopIndices'
+import type { Direction, SizeFunction } from './types'
+import { useCachedBounds } from './useCachedBounds'
+import { useItemSize } from './useItemSize'
+
+export function useVirtualizer<Props extends object>({
+  containerElement,
+  containerStyle,
+  defaultContainerSize = 0,
+  direction,
+  isRtl = false,
+  itemCount: itemCountInput,
+  itemProps: itemPropsInput,
+  itemSize: itemSizeProp,
+  onResize,
+  overscanCount,
+}: {
+  containerElement: Ref<HTMLElement | null>;
+  containerStyle?: CSSProperties;
+  defaultContainerSize?: number;
+  direction: Direction;
+  isRtl?: boolean;
+  itemCount: number | Ref<number> | ComputedRef<number>;
+  itemProps: Props | ComputedRef<Props>;
+  itemSize: number | string | SizeFunction<Props> | Ref<number | string | SizeFunction<Props>> | ComputedRef<number | string | SizeFunction<Props>>;
+  onResize:
+  | ((
+    size: { height: number; width: number; },
+    prevSize: { height: number; width: number; }
+  ) => void)
+  | undefined;
+  overscanCount: number;
+}) {
+  const itemCount = computed(() => {
+    return isRef(itemCountInput) ? itemCountInput.value : itemCountInput
+  })
+
+  const itemProps = computed(() => {
+    return isRef(itemPropsInput) ? itemPropsInput.value : itemPropsInput
+  })
+
+  const itemSizeNormalized = computed(() => {
+    return isRef(itemSizeProp) ? itemSizeProp.value : itemSizeProp
+  })
+
+  const styleHeight = computed(() => parseNumericStyleValue(containerStyle?.height))
+  const styleWidth = computed(() => parseNumericStyleValue(containerStyle?.width))
+
+  const sizeState = ref<{
+    height: number | undefined;
+    width: number | undefined;
+  }>({
+    height: direction === 'vertical' ? defaultContainerSize : undefined,
+    width: direction === 'horizontal' ? defaultContainerSize : undefined,
+  })
+
+  const observerDisabled = computed(
+    () =>
+      (direction === 'vertical' && styleHeight.value !== undefined) ||
+      (direction === 'horizontal' && styleWidth.value !== undefined),
+  )
+
+  useResizeObserver(
+    containerElement,
+    (entries) => {
+      if (observerDisabled.value) return
+
+      for (const entry of entries) {
+        const { contentRect } = entry
+        const prevState = sizeState.value
+
+        if (
+          prevState.height === contentRect.height &&
+          prevState.width === contentRect.width
+        ) {
+          return
+        }
+
+        sizeState.value = {
+          height: contentRect.height,
+          width: contentRect.width,
+        }
+      }
+    },
+  )
+
+  const size = computed(() => ({
+    height: styleHeight.value ?? sizeState.value.height,
+    width: styleWidth.value ?? sizeState.value.width,
+  }))
+
+  const prevSize = ref<{ height: number; width: number; }>({
+    height: 0,
+    width: 0,
+  })
+
+  watch(
+    size,
+    (newSize) => {
+      if (typeof onResize === 'function') {
+        const prev = prevSize.value
+        const height = newSize.height ?? 0
+        const width = newSize.width ?? 0
+
+        if (prev.height !== height || prev.width !== width) {
+          onResize({ height, width }, { ...prev })
+
+          prevSize.value = { height, width }
+        }
+      }
+    },
+    { immediate: true },
+  )
+
+  const containerSize = computed(() =>
+    direction === 'vertical'
+      ? size.value.height ?? defaultContainerSize
+      : size.value.width ?? defaultContainerSize,
+  )
+
+  const itemSize = computed(() =>
+    useItemSize({ containerSize: containerSize.value, itemSize: itemSizeNormalized.value }),
+  )
+
+  const cachedBounds = computed(() =>
+    useCachedBounds({
+      itemCount: itemCount.value,
+      itemProps: itemProps.value,
+      itemSize: itemSize.value,
+    }).value,
+  )
+
+  const getCellBounds = (index: number) => cachedBounds.value.get(index)
+
+  const indices = ref<{
+    startIndexVisible: number;
+    stopIndexVisible: number;
+    startIndexOverscan: number;
+    stopIndexOverscan: number;
+  }>(
+    getStartStopIndicesUtil({
+      cachedBounds: cachedBounds.value,
+      containerScrollOffset: 0,
+      containerSize: containerSize.value,
+      itemCount: itemCount.value,
+      overscanCount,
+    }),
+  )
+
+  const safeIndices = computed(() => {
+    const ind = indices.value
+
+    return {
+      startIndexVisible: Math.min(itemCount.value - 1, ind.startIndexVisible),
+      startIndexOverscan: Math.min(itemCount.value - 1, ind.startIndexOverscan),
+      stopIndexVisible: Math.min(itemCount.value - 1, ind.stopIndexVisible),
+      stopIndexOverscan: Math.min(itemCount.value - 1, ind.stopIndexOverscan),
+    }
+  })
+
+  const getEstimatedSize = computed(() =>
+    getEstimatedSizeUtil({
+      cachedBounds: cachedBounds.value,
+      itemCount: itemCount.value,
+      itemSize: itemSize.value,
+    }),
+  )
+
+  const getStartStopIndices = (scrollOffset: number) => {
+    const containerScrollOffset = adjustScrollOffsetForRtl({
+      containerElement: containerElement.value,
+      direction,
+      isRtl,
+      scrollOffset,
+    })
+
+    return getStartStopIndicesUtil({
+      cachedBounds: cachedBounds.value,
+      containerScrollOffset,
+      containerSize: containerSize.value,
+      itemCount: itemCount.value,
+      overscanCount,
+    })
+  }
+
+  watch(
+    [containerElement, () => direction, () => cachedBounds.value],
+    ([el]) => {
+      const scrollOffset =
+        (direction === 'vertical' ? el?.scrollTop : el?.scrollLeft) ?? 0
+
+      indices.value = getStartStopIndices(scrollOffset)
+    },
+    { immediate: true },
+  )
+
+  const onScroll = () => {
+    const el = containerElement.value
+
+    if (!el) return
+
+    const { scrollLeft, scrollTop } = el
+
+    const scrollOffset = adjustScrollOffsetForRtl({
+      containerElement: el,
+      direction,
+      isRtl,
+      scrollOffset: direction === 'vertical' ? scrollTop : scrollLeft,
+    })
+
+    const next = getStartStopIndicesUtil({
+      cachedBounds: cachedBounds.value,
+      containerScrollOffset: scrollOffset,
+      containerSize: containerSize.value,
+      itemCount: itemCount.value,
+      overscanCount,
+    })
+
+    if (!shallowCompare(next, indices.value)) {
+      indices.value = next
+    }
+  }
+
+  useEventListener(containerElement, 'scroll', onScroll)
+
+  const scrollToIndex = ({
+    align = 'auto',
+    containerScrollOffset,
+    index,
+  }: {
+    align?: Align;
+    containerScrollOffset: number;
+    index: number;
+  }) => {
+    let scrollOffset = getOffsetForIndex({
+      align,
+      cachedBounds: cachedBounds.value,
+      containerScrollOffset,
+      containerSize: containerSize.value,
+      index,
+      itemCount: itemCount.value,
+      itemSize: itemSize.value,
+    })
+
+    const el = containerElement.value
+
+    if (el) {
+      scrollOffset = adjustScrollOffsetForRtl({
+        containerElement: el,
+        direction,
+        isRtl,
+        scrollOffset,
+      })
+
+      if (typeof el.scrollTo !== 'function') {
+        const next = getStartStopIndices(scrollOffset)
+
+        if (!shallowCompare(indices.value, next)) {
+          indices.value = next
+        }
+      }
+
+      return scrollOffset
+    }
+
+    return undefined
+  }
+
+  return {
+    getCellBounds,
+    getEstimatedSize,
+    scrollToIndex,
+    startIndexOverscan: computed(() => safeIndices.value.startIndexOverscan),
+    startIndexVisible: computed(() => safeIndices.value.startIndexVisible),
+    stopIndexOverscan: computed(() => safeIndices.value.stopIndexOverscan),
+    stopIndexVisible: computed(() => safeIndices.value.stopIndexVisible),
+  }
+}

package/src/virtual/index.ts

@@ -0,0 +1,25 @@
+export { default as XVirtualGrid } from './components/virtualGrid/VirtualGrid.vue'
+export type {
+  CellSlotProps,
+  VirtualGridImperativeAPI,
+  VirtualGridProps,
+} from './components/virtualGrid/types'
+
+export { default as XVirtualList } from './components/virtualList/VirtualList.vue'
+export { useDynamicRowHeight } from './components/virtualList/useDynamicRowHeight'
+export type {
+  DynamicRowHeight,
+  VirtualListImperativeAPI,
+  VirtualListProps,
+  RowSlotProps,
+} from './components/virtualList/types'
+
+export { default as XInfiniteLoader } from './components/infiniteLoader/InfiniteLoader.vue'
+export { useInfiniteLoader } from './composables/infinite-loader/useInfiniteLoader'
+export type {
+  Indices,
+  OnRowsRendered,
+  InfiniteLoaderProps,
+} from './composables/infinite-loader/types'
+
+export { getScrollbarSize } from './utils/getScrollbarSize'

package/src/virtual/test-utils/mockResizeObserver.ts

@@ -0,0 +1,162 @@
+import EventEmitter from 'node:events'
+
+type GetDOMRect = (element: HTMLElement) => DOMRectReadOnly | undefined | void;
+
+const emitter = new EventEmitter()
+
+emitter.setMaxListeners(100)
+
+const elementToDOMRect = new Map<HTMLElement, DOMRect>()
+
+let defaultDomRect: DOMRectReadOnly = new DOMRect(0, 0, 0, 0)
+let disabled: boolean = false
+let getDOMRect: GetDOMRect | undefined = undefined
+
+export function disableResizeObserverForCurrentTest() {
+  disabled = true
+}
+
+export function setDefaultElementSize({
+  height,
+  width,
+}: {
+  height: number;
+  width: number;
+}) {
+  defaultDomRect = new DOMRect(0, 0, width, height)
+
+  emitter.emit('change')
+}
+
+export function setElementSizeFunction(value: GetDOMRect) {
+  getDOMRect = value
+
+  emitter.emit('change')
+}
+
+export function setElementSize({
+  element,
+  height,
+  width,
+}: {
+  element: HTMLElement;
+  height: number;
+  width: number;
+}) {
+  elementToDOMRect.set(element, new DOMRect(0, 0, width, height))
+
+  emitter.emit('change', element)
+}
+
+export function simulateUnsupportedEnvironmentForTest() {
+  // @ts-expect-error Simulate API being unsupported
+  window.ResizeObserver = null
+}
+
+export function mockResizeObserver() {
+  disabled = false
+
+  const originalResizeObserver = window.ResizeObserver
+
+  window.ResizeObserver = MockResizeObserver
+
+  return function unmockResizeObserver() {
+    window.ResizeObserver = originalResizeObserver
+
+    defaultDomRect = new DOMRect(0, 0, 0, 0)
+    disabled = false
+    getDOMRect = undefined
+
+    elementToDOMRect.clear()
+  }
+}
+
+class MockResizeObserver implements ResizeObserver {
+  readonly #callback: ResizeObserverCallback
+  #disconnected: boolean = false
+  #elements: Set<HTMLElement> = new Set()
+
+  constructor(callback: ResizeObserverCallback) {
+    this.#callback = callback
+
+    emitter.addListener('change', this.#onChange)
+  }
+
+  observe(element: HTMLElement) {
+    if (this.#disconnected) {
+      return
+    }
+
+    this.#elements.add(element)
+    this.#notify([element])
+  }
+
+  unobserve(element: HTMLElement) {
+    this.#elements.delete(element)
+  }
+
+  disconnect() {
+    this.#disconnected = true
+    this.#elements.clear()
+
+    emitter.removeListener('change', this.#onChange)
+  }
+
+  #notify(elements: HTMLElement[]) {
+    if (disabled) {
+      return
+    }
+
+    const entries = elements.map((element) => {
+      const computedStyle = window.getComputedStyle(element)
+      const writingMode = computedStyle.writingMode
+
+      let contentRect: DOMRectReadOnly =
+        elementToDOMRect.get(element) ?? defaultDomRect
+
+      if (getDOMRect) {
+        const contentRectOverride = getDOMRect(element)
+
+        if (contentRectOverride) {
+          contentRect = contentRectOverride
+        }
+      }
+
+      let blockSize = 0
+      let inlineSize = 0
+
+      if (writingMode.includes('vertical')) {
+        blockSize = contentRect.width
+        inlineSize = contentRect.height
+      } else {
+        blockSize = contentRect.height
+        inlineSize = contentRect.width
+      }
+
+      return {
+        borderBoxSize: [
+          {
+            blockSize,
+            inlineSize,
+          },
+        ],
+        contentBoxSize: [],
+        contentRect,
+        devicePixelContentBoxSize: [],
+        target: element,
+      }
+    })
+
+    this.#callback(entries, this)
+  }
+
+  #onChange = (target?: HTMLElement) => {
+    if (target) {
+      if (this.#elements.has(target)) {
+        this.#notify([target])
+      }
+    } else {
+      this.#notify(Array.from(this.#elements))
+    }
+  }
+}

package/src/virtual/types.ts

@@ -0,0 +1,3 @@
+export type Align = 'auto' | 'center' | 'end' | 'smart' | 'start';
+
+export type TagNames = keyof HTMLElementTagNameMap;

package/src/virtual/utils/adjustScrollOffsetForRtl.ts

@@ -0,0 +1,37 @@
+import type { Direction } from '../core/types'
+import { getRTLOffsetType } from './getRTLOffsetType'
+
+export function adjustScrollOffsetForRtl({
+  containerElement,
+  direction,
+  isRtl,
+  scrollOffset,
+}: {
+  containerElement: HTMLElement | null;
+  direction: Direction;
+  isRtl: boolean;
+  scrollOffset: number;
+}) {
+  // TRICKY According to the spec, scrollLeft should be negative for RTL aligned elements.
+  // This is not the case for all browsers though (e.g. Chrome reports values as positive, measured relative to the left).
+  // So we need to determine which browser behavior we're dealing with, and mimic it.
+  if (direction === 'horizontal') {
+    if (isRtl) {
+      switch (getRTLOffsetType()) {
+        case 'negative': {
+          return -scrollOffset
+        }
+        case 'positive-descending': {
+          if (containerElement) {
+            const { clientWidth, scrollLeft, scrollWidth } = containerElement
+
+            return scrollWidth - clientWidth - scrollLeft
+          }
+          break
+        }
+      }
+    }
+  }
+
+  return scrollOffset
+}

package/src/virtual/utils/areArraysEqual.ts

@@ -0,0 +1,13 @@
+export function areArraysEqual(a: unknown[], b: unknown[]) {
+  if (a.length !== b.length) {
+    return false
+  }
+
+  for (let index = 0; index < a.length; index++) {
+    if (!Object.is(a[index], b[index])) {
+      return false
+    }
+  }
+
+  return true
+}

package/src/virtual/utils/assert.ts

@@ -0,0 +1,10 @@
+export function assert(
+  expectedCondition: unknown,
+  message: string = 'Assertion error',
+): asserts expectedCondition {
+  if (!expectedCondition) {
+    console.error(message)
+
+    throw Error(message)
+  }
+}

package/src/virtual/utils/getRTLOffsetType.ts

@@ -0,0 +1,51 @@
+export type RTLOffsetType =
+  | 'negative'
+  | 'positive-descending'
+  | 'positive-ascending';
+
+let cachedRTLResult: RTLOffsetType | null = null
+
+// TRICKY According to the spec, scrollLeft should be negative for RTL aligned elements.
+// Chrome does not seem to adhere; its scrollLeft values are positive (measured relative to the left).
+// Safari's elastic bounce makes detecting this even more complicated wrt potential false positives.
+// The safest way to check this is to intentionally set a negative offset,
+// and then verify that the subsequent "scroll" event matches the negative offset.
+// If it does not match, then we can assume a non-standard RTL scroll implementation.
+export function getRTLOffsetType(recalculate: boolean = false): RTLOffsetType {
+  if (cachedRTLResult === null || recalculate) {
+    const outerDiv = document.createElement('div')
+    const outerStyle = outerDiv.style
+
+    outerStyle.width = '50px'
+    outerStyle.height = '50px'
+    outerStyle.overflow = 'scroll'
+    outerStyle.direction = 'rtl'
+
+    const innerDiv = document.createElement('div')
+    const innerStyle = innerDiv.style
+
+    innerStyle.width = '100px'
+    innerStyle.height = '100px'
+
+    outerDiv.appendChild(innerDiv)
+
+    document.body.appendChild(outerDiv)
+
+    if (outerDiv.scrollLeft > 0) {
+      cachedRTLResult = 'positive-descending'
+    } else {
+      outerDiv.scrollLeft = 1
+      if (outerDiv.scrollLeft === 0) {
+        cachedRTLResult = 'negative'
+      } else {
+        cachedRTLResult = 'positive-ascending'
+      }
+    }
+
+    document.body.removeChild(outerDiv)
+
+    return cachedRTLResult
+  }
+
+  return cachedRTLResult
+}

package/src/virtual/utils/getScrollbarSize.ts

@@ -0,0 +1,24 @@
+let size: number = -1
+
+export function getScrollbarSize(recalculate: boolean = false): number {
+  if (size === -1 || recalculate) {
+    const div = document.createElement('div')
+    const style = div.style
+
+    style.width = '50px'
+    style.height = '50px'
+    style.overflow = 'scroll'
+
+    document.body.appendChild(div)
+
+    size = div.offsetWidth - div.clientWidth
+
+    document.body.removeChild(div)
+  }
+
+  return size
+}
+
+export function setScrollbarSizeForTests(value: number) {
+  size = value
+}

package/src/virtual/utils/isRtl.ts

@@ -0,0 +1,13 @@
+export function isRtl(element: HTMLElement) {
+  let currentElement: HTMLElement | null = element
+
+  while (currentElement) {
+    if (currentElement.dir) {
+      return currentElement.dir === 'rtl'
+    }
+
+    currentElement = currentElement.parentElement
+  }
+
+  return false
+}

package/src/virtual/utils/parseNumericStyleValue.ts

@@ -0,0 +1,21 @@
+import type { CSSProperties } from 'vue'
+
+export function parseNumericStyleValue(
+  value: CSSProperties['height'],
+): number | undefined {
+  if (value !== undefined) {
+    switch (typeof value) {
+      case 'number': {
+        return value
+      }
+      case 'string': {
+        if (value.endsWith('px')) {
+          return parseFloat(value)
+        }
+        break
+      }
+    }
+  }
+
+  return undefined
+}