@indielayer/ui 1.15.3 → 1.17.0

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

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'