@indielayer/ui 1.16.0 → 1.17.0

package/src/virtual/components/virtualGrid/VirtualGrid.vue

@@ -0,0 +1,322 @@
+<script lang="ts">
+export default {
+  name: 'XVirtualGrid',
+}
+</script>
+
+<script setup lang="ts">
+import { computed, ref, watch, type CSSProperties } from 'vue'
+import { useIsRtl } from '../../core/useIsRtl'
+import { useVirtualizer } from '../../core/useVirtualizer'
+import type { Align } from '../../types'
+import type { VirtualGridProps, VirtualGridImperativeAPI } from './types'
+
+const props = withDefaults(defineProps<VirtualGridProps>(), {
+  defaultHeight: 0,
+  defaultWidth: 0,
+  overscanCount: 3,
+  tag: 'div',
+})
+
+const element = ref<HTMLDivElement | null>(null)
+
+const cellProps = computed(() => props.cellProps || ({} as Record<string, unknown>))
+
+const isRtl = useIsRtl(element, props.dir)
+
+const {
+  getCellBounds: getColumnBounds,
+  getEstimatedSize: getEstimatedWidth,
+  startIndexOverscan: columnStartIndexOverscan,
+  startIndexVisible: columnStartIndexVisible,
+  scrollToIndex: scrollToColumnIndex,
+  stopIndexOverscan: columnStopIndexOverscan,
+  stopIndexVisible: columnStopIndexVisible,
+} = useVirtualizer({
+  containerElement: element,
+  containerStyle: props.style,
+  defaultContainerSize: props.defaultWidth,
+  direction: 'horizontal',
+  isRtl: isRtl.value,
+  itemCount: props.columnCount,
+  itemProps: cellProps.value,
+  itemSize: props.columnWidth,
+  onResize: props.onResize,
+  overscanCount: props.overscanCount,
+})
+
+const {
+  getCellBounds: getRowBounds,
+  getEstimatedSize: getEstimatedHeight,
+  startIndexOverscan: rowStartIndexOverscan,
+  startIndexVisible: rowStartIndexVisible,
+  scrollToIndex: scrollToRowIndex,
+  stopIndexOverscan: rowStopIndexOverscan,
+  stopIndexVisible: rowStopIndexVisible,
+} = useVirtualizer({
+  containerElement: element,
+  containerStyle: props.style,
+  defaultContainerSize: props.defaultHeight,
+  direction: 'vertical',
+  itemCount: props.rowCount,
+  itemProps: cellProps.value,
+  itemSize: props.rowHeight,
+  onResize: props.onResize,
+  overscanCount: props.overscanCount,
+})
+
+// Expose imperative API
+defineExpose<VirtualGridImperativeAPI>({
+  get element() {
+    return element.value
+  },
+
+  scrollToCell({
+    behavior = 'auto',
+    columnAlign = 'auto',
+    columnIndex,
+    rowAlign = 'auto',
+    rowIndex,
+  }: {
+    behavior?: ScrollBehavior;
+    columnAlign?: Align;
+    columnIndex: number;
+    rowAlign?: Align;
+    rowIndex: number;
+  }) {
+    const left = scrollToColumnIndex({
+      align: columnAlign,
+      containerScrollOffset: element.value?.scrollLeft ?? 0,
+      index: columnIndex,
+    })
+    const top = scrollToRowIndex({
+      align: rowAlign,
+      containerScrollOffset: element.value?.scrollTop ?? 0,
+      index: rowIndex,
+    })
+
+    if (typeof element.value?.scrollTo === 'function' && left !== undefined && top !== undefined) {
+      element.value.scrollTo({
+        behavior,
+        left,
+        top,
+      })
+    }
+  },
+
+  scrollToColumn({
+    align = 'auto',
+    behavior = 'auto',
+    index,
+  }: {
+    align?: Align;
+    behavior?: ScrollBehavior;
+    index: number;
+  }) {
+    const left = scrollToColumnIndex({
+      align,
+      containerScrollOffset: element.value?.scrollLeft ?? 0,
+      index,
+    })
+
+    if (typeof element.value?.scrollTo === 'function' && left !== undefined) {
+      element.value.scrollTo({
+        behavior,
+        left,
+      })
+    }
+  },
+
+  scrollToRow({
+    align = 'auto',
+    behavior = 'auto',
+    index,
+  }: {
+    align?: Align;
+    behavior?: ScrollBehavior;
+    index: number;
+  }) {
+    const top = scrollToRowIndex({
+      align,
+      containerScrollOffset: element.value?.scrollTop ?? 0,
+      index,
+    })
+
+    if (typeof element.value?.scrollTo === 'function' && top !== undefined) {
+      element.value.scrollTo({
+        behavior,
+        top,
+      })
+    }
+  },
+})
+
+// Notify when visible cells change
+watch(
+  [
+    columnStartIndexOverscan,
+    columnStartIndexVisible,
+    columnStopIndexOverscan,
+    columnStopIndexVisible,
+    rowStartIndexOverscan,
+    rowStartIndexVisible,
+    rowStopIndexOverscan,
+    rowStopIndexVisible,
+  ],
+  ([
+    colStartOverscan,
+    colStartVisible,
+    colStopOverscan,
+    colStopVisible,
+    rowStartOverscan,
+    rowStartVisible,
+    rowStopOverscan,
+    rowStopVisible,
+  ]) => {
+    if (
+      colStartOverscan >= 0 &&
+      colStopOverscan >= 0 &&
+      rowStartOverscan >= 0 &&
+      rowStopOverscan >= 0 &&
+      props.onCellsRendered
+    ) {
+      props.onCellsRendered(
+        {
+          columnStartIndex: colStartVisible,
+          columnStopIndex: colStopVisible,
+          rowStartIndex: rowStartVisible,
+          rowStopIndex: rowStopVisible,
+        },
+        {
+          columnStartIndex: colStartOverscan,
+          columnStopIndex: colStopOverscan,
+          rowStartIndex: rowStartOverscan,
+          rowStopIndex: rowStopOverscan,
+        },
+      )
+    }
+  },
+)
+
+interface CellData {
+  key: number;
+  columnIndex: number;
+  rowIndex: number;
+  style: CSSProperties;
+  ariaAttributes: {
+    'aria-colindex': number;
+    role: 'gridcell';
+  };
+}
+
+interface RowData {
+  key: number;
+  rowIndex: number;
+  columns: CellData[];
+  ariaRowIndex: number;
+}
+
+// Generate cells
+const rows = computed(() => {
+  const result: RowData[] = []
+
+  if (props.columnCount > 0 && props.rowCount > 0) {
+    for (
+      let rowIndex = rowStartIndexOverscan.value;
+      rowIndex <= rowStopIndexOverscan.value;
+      rowIndex++
+    ) {
+      const rowBounds = getRowBounds(rowIndex)
+
+      const columns: CellData[] = []
+
+      for (
+        let columnIndex = columnStartIndexOverscan.value;
+        columnIndex <= columnStopIndexOverscan.value;
+        columnIndex++
+      ) {
+        const columnBounds = getColumnBounds(columnIndex)
+
+        const cellStyle: CSSProperties = {
+          position: 'absolute',
+          left: isRtl.value ? undefined : 0,
+          right: isRtl.value ? 0 : undefined,
+          transform: `translate(${isRtl.value ? -columnBounds.scrollOffset : columnBounds.scrollOffset}px, ${rowBounds.scrollOffset}px)`,
+          height: `${rowBounds.size}px`,
+          width: `${columnBounds.size}px`,
+        }
+
+        columns.push({
+          key: columnIndex,
+          columnIndex,
+          rowIndex,
+          style: cellStyle,
+          ariaAttributes: {
+            'aria-colindex': columnIndex + 1,
+            role: 'gridcell',
+          },
+        })
+      }
+
+      result.push({
+        key: rowIndex,
+        rowIndex,
+        columns,
+        ariaRowIndex: rowIndex + 1,
+      })
+    }
+  }
+
+  return result
+})
+</script>
+
+<template>
+  <component
+    :is="tag"
+    ref="element"
+    :class="$props.class"
+    :style="{
+      position: 'relative',
+      maxHeight: '100%',
+      maxWidth: '100%',
+      flexGrow: 1,
+      overflow: 'auto',
+      ...style
+    }"
+    :dir="dir"
+    role="grid"
+    :aria-colcount="columnCount"
+    :aria-rowcount="rowCount"
+  >
+    <div
+      v-for="row in rows"
+      :key="row.key"
+      role="row"
+      :aria-rowindex="row.ariaRowIndex"
+    >
+      <template v-for="cell in row.columns" :key="cell.key">
+        <slot
+          name="cell"
+          :column-index="cell.columnIndex"
+          :row-index="cell.rowIndex"
+          :style="cell.style"
+          :aria-attributes="cell.ariaAttributes"
+          :props="cellProps"
+        ></slot>
+      </template>
+    </div>
+
+    <slot ></slot>
+
+    <!-- Sizing element -->
+    <div
+      aria-hidden
+      :style="{
+        height: `${getEstimatedHeight}px`,
+        width: `${getEstimatedWidth}px`,
+        zIndex: -1
+      }"
+    ></div>
+  </component>
+</template>

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

@@ -0,0 +1,160 @@
+import type { CSSProperties } from 'vue'
+import type { TagNames } from '../../types'
+
+type ForbiddenKeys = 'ariaAttributes' | 'columnIndex' | 'rowIndex' | 'style';
+type ExcludeForbiddenKeys<Type> = {
+  [Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
+};
+
+export interface VirtualGridProps {
+  /**
+   * Additional props to be passed to the cell-rendering component via slots.
+   */
+  cellProps?: ExcludeForbiddenKeys<Record<string, unknown>>;
+
+  /**
+   * CSS class name.
+   */
+  class?: string;
+
+  /**
+   * Number of columns to be rendered in the grid.
+   */
+  columnCount: number;
+
+  /**
+   * Column width; the following formats are supported:
+   * - number of pixels (number)
+   * - percentage of the grid's current width (string)
+   * - function that returns the column width (in pixels) given an index and `cellProps`
+   */
+  columnWidth:
+  | number
+  | string
+  | ((index: number, cellProps: Record<string, unknown>) => number);
+
+  /**
+   * Default height of grid for initial render.
+   * This value is important for server rendering.
+   */
+  defaultHeight?: number;
+
+  /**
+   * Default width of grid for initial render.
+   * This value is important for server rendering.
+   */
+  defaultWidth?: number;
+
+  /**
+   * Indicates the directionality of grid cells.
+   */
+  dir?: 'ltr' | 'rtl' | 'auto';
+
+  /**
+   * Callback notified when the range of rendered cells changes.
+   */
+  onCellsRendered?: (
+    visibleCells: {
+      columnStartIndex: number;
+      columnStopIndex: number;
+      rowStartIndex: number;
+      rowStopIndex: number;
+    },
+    allCells: {
+      columnStartIndex: number;
+      columnStopIndex: number;
+      rowStartIndex: number;
+      rowStopIndex: number;
+    }
+  ) => void;
+
+  /**
+   * Callback notified when the Grid's outermost HTMLElement resizes.
+   * This may be used to (re)scroll a cell into view.
+   */
+  onResize?: (
+    size: { height: number; width: number; },
+    prevSize: { height: number; width: number; }
+  ) => void;
+
+  /**
+   * How many additional rows/columns to render outside of the visible area.
+   * This can reduce visual flickering near the edges of a grid when scrolling.
+   */
+  overscanCount?: number;
+
+  /**
+   * Number of rows to be rendered in the grid.
+   */
+  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`
+   */
+  rowHeight: number | string | ((index: number, cellProps: Record<string, unknown>) => number);
+
+  /**
+   * Optional CSS properties.
+   * The grid of cells will fill the height and width defined by this style.
+   */
+  style?: CSSProperties;
+
+  /**
+   * Can be used to override the root HTML element rendered by the Grid component.
+   * The default value is "div", meaning that Grid renders an HTMLDivElement as its root.
+   */
+  tag?: TagNames;
+}
+
+export interface CellSlotProps {
+  ariaAttributes: {
+    'aria-colindex': number;
+    role: 'gridcell';
+  };
+  columnIndex: number;
+  rowIndex: number;
+  style: CSSProperties;
+  props?: Record<string, unknown>;
+}
+
+/**
+ * Imperative Grid API.
+ */
+export interface VirtualGridImperativeAPI {
+  /**
+   * Outermost HTML element for the grid if mounted and null (if not mounted.
+   */
+  readonly element: HTMLDivElement | null;
+
+  /**
+   * Scrolls the grid so that the specified cell is visible.
+   */
+  scrollToCell(config: {
+    behavior?: ScrollBehavior;
+    columnAlign?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+    columnIndex: number;
+    rowAlign?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+    rowIndex: number;
+  }): void;
+
+  /**
+   * Scrolls the grid so that the specified column is visible.
+   */
+  scrollToColumn(config: {
+    align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+    behavior?: ScrollBehavior;
+    index: number;
+  }): void;
+
+  /**
+   * Scrolls the grid so that the specified row is visible.
+   */
+  scrollToRow(config: {
+    align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+    behavior?: ScrollBehavior;
+    index: number;
+  }): void;
+}

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

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { h, type CSSProperties } from 'vue'
+import VirtualList from './VirtualList.vue'
+
+interface RowSlotProps {
+  index: number;
+  style: CSSProperties;
+}
+
+describe('VirtualList', () => {
+  it('renders correctly', () => {
+    const wrapper = mount(VirtualList, {
+      props: {
+        rowCount: 100,
+        rowHeight: 50,
+        style: { height: '400px' },
+      },
+      slots: {
+        row: ({ index, style }: RowSlotProps) =>
+          h('div', { style }, `Row ${index}`),
+      },
+    })
+
+    expect(wrapper.exists()).toBe(true)
+    expect(wrapper.attributes('role')).toBe('list')
+  })
+
+  it('renders visible rows', () => {
+    const wrapper = mount(VirtualList, {
+      props: {
+        rowCount: 100,
+        rowHeight: 50,
+        style: { height: '400px' },
+      },
+      slots: {
+        row: ({ index, style }: RowSlotProps) =>
+          h('div', { style, class: 'test-row' }, `Row ${index}`),
+      },
+    })
+
+    // Should render some rows (visible + overscan)
+    const rows = wrapper.findAll('.test-row')
+
+    expect(rows.length).toBeGreaterThan(0)
+  })
+})