@pdanpdan/virtual-scroll 0.6.0 → 0.7.0

package/dist/virtual-scroll.css

@@ -1,2 +1,2 @@
-@layer components{.virtual-scrollbar-track{--vsi-scrollbar-bg:var(--vs-scrollbar-bg,var(--lightningcss-light,#e6e6e6e6)var(--lightningcss-dark,#1e1e1ee6));--vsi-scrollbar-thumb-bg:var(--vs-scrollbar-thumb-bg,var(--lightningcss-light,#0000004d)var(--lightningcss-dark,#ffffff4d));--vsi-scrollbar-thumb-hover-bg:var(--vs-scrollbar-thumb-hover-bg,var(--lightningcss-light,#0009)var(--lightningcss-dark,#fff9));--vsi-scrollbar-radius:var(--vs-scrollbar-radius,4px);--vsi-scrollbar-size:var(--vs-scrollbar-size,8px);contain:layout;background-color:var(--vsi-scrollbar-bg);border-radius:var(--vsi-scrollbar-radius);z-index:30;-webkit-user-select:none;user-select:none;pointer-events:auto;transition:opacity .2s;position:absolute}.virtual-scrollbar-track.virtual-scrollbar-track--vertical{inline-size:var(--vsi-scrollbar-size);inset-block-start:2px;inset-inline-end:2px}.virtual-scrollbar-track.virtual-scrollbar-track--horizontal{block-size:var(--vsi-scrollbar-size);inset-block-end:2px;inset-inline-start:2px}.virtual-scrollbar-thumb{background-color:var(--vsi-scrollbar-thumb-bg);border-radius:var(--vsi-scrollbar-radius);touch-action:none;pointer-events:auto;cursor:pointer;position:absolute}.virtual-scrollbar-thumb:hover,.virtual-scrollbar-thumb:active,.virtual-scrollbar-thumb.virtual-scrollbar-thumb--active{background-color:var(--vsi-scrollbar-thumb-hover-bg)}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--vertical{inline-size:100%}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--horizontal{block-size:100%}.virtual-scroll-container[data-v-408dd72c]{outline-offset:1px;block-size:100%;inline-size:100%;position:relative}.virtual-scroll-container[data-v-408dd72c]:not(.virtual-scroll--window){overscroll-behavior:contain;overflow:auto}.virtual-scroll-container.virtual-scroll--table[data-v-408dd72c]{display:block}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-408dd72c]{scrollbar-width:none;-ms-overflow-style:none}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-408dd72c]::-webkit-scrollbar{display:none}.virtual-scroll-container.virtual-scroll--horizontal[data-v-408dd72c],.virtual-scroll-container.virtual-scroll--both[data-v-408dd72c]{white-space:nowrap}.virtual-scroll-scrollbar-container[data-v-408dd72c]{z-index:30;pointer-events:none;block-size:0;inline-size:100%;position:sticky;inset-block-start:0;inset-inline-start:0;overflow:visible}.virtual-scroll-scrollbar-viewport[data-v-408dd72c]{pointer-events:none;position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-wrapper[data-v-408dd72c]{contain:layout;position:relative}:where(.virtual-scroll--hydrated>.virtual-scroll-wrapper>.virtual-scroll-item[data-v-408dd72c]){position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-item[data-v-408dd72c]{box-sizing:border-box;will-change:transform;display:grid}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-408dd72c]{background-color:#ff00000d;outline:1px dashed #ff000080}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-408dd72c]:where(:hover){z-index:100;background-color:#ff00001a}.virtual-scroll-debug-info[data-v-408dd72c]{color:#fff;pointer-events:none;z-index:100;background:#000000b3;border-radius:4px;padding:2px 4px;font-family:monospace;font-size:10px;position:absolute;inset-block-start:2px;inset-inline-end:2px}.virtual-scroll-spacer[data-v-408dd72c]{pointer-events:none}.virtual-scroll-header[data-v-408dd72c],.virtual-scroll-footer[data-v-408dd72c]{z-index:20;position:relative}.virtual-scroll--sticky[data-v-408dd72c]{position:sticky}.virtual-scroll--sticky[data-v-408dd72c]:where(.virtual-scroll-header){box-sizing:border-box;min-inline-size:100%;inset-block-start:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-408dd72c]:where(.virtual-scroll-footer){box-sizing:border-box;min-inline-size:100%;inset-block-end:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-408dd72c]:where(.virtual-scroll-item){z-index:10}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-408dd72c]{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-408dd72c]>tr{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-408dd72c]>tr>:is(td,th){align-items:center;display:inline-block}}
+@layer components{.virtual-scrollbar-track{--vsi-scrollbar-bg:var(--vs-scrollbar-bg,var(--lightningcss-light,#e6e6e6e6)var(--lightningcss-dark,#1e1e1ee6));--vsi-scrollbar-thumb-bg:var(--vs-scrollbar-thumb-bg,var(--lightningcss-light,#0000004d)var(--lightningcss-dark,#ffffff4d));--vsi-scrollbar-thumb-hover-bg:var(--vs-scrollbar-thumb-hover-bg,var(--lightningcss-light,#0009)var(--lightningcss-dark,#fff9));--vsi-scrollbar-radius:var(--vs-scrollbar-radius,4px);--vsi-scrollbar-size:var(--vs-scrollbar-size,8px);contain:layout;background-color:var(--vsi-scrollbar-bg);border-radius:var(--vsi-scrollbar-radius);z-index:30;-webkit-user-select:none;user-select:none;pointer-events:auto;transition:opacity .2s;position:absolute}.virtual-scrollbar-track.virtual-scrollbar-track--vertical{inline-size:var(--vsi-scrollbar-size);inset-block-start:2px;inset-inline-end:2px}.virtual-scrollbar-track.virtual-scrollbar-track--horizontal{block-size:var(--vsi-scrollbar-size);inset-block-end:2px;inset-inline-start:2px}.virtual-scrollbar-thumb{background-color:var(--vsi-scrollbar-thumb-bg);border-radius:var(--vsi-scrollbar-radius);touch-action:none;pointer-events:auto;cursor:pointer;position:absolute}.virtual-scrollbar-thumb:hover,.virtual-scrollbar-thumb:active,.virtual-scrollbar-thumb.virtual-scrollbar-thumb--active{background-color:var(--vsi-scrollbar-thumb-hover-bg)}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--vertical{inline-size:100%}.virtual-scrollbar-thumb.virtual-scrollbar-thumb--horizontal{block-size:100%}.virtual-scroll-container[data-v-184bc0a9]{outline-offset:1px;block-size:100%;inline-size:100%;position:relative}.virtual-scroll-container[data-v-184bc0a9]:not(.virtual-scroll--window){overscroll-behavior:contain;overflow:auto}.virtual-scroll-container.virtual-scroll--table[data-v-184bc0a9]{display:block}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-184bc0a9]{scrollbar-width:none;-ms-overflow-style:none}.virtual-scroll-container.virtual-scroll--hide-scrollbar[data-v-184bc0a9]::-webkit-scrollbar{display:none}.virtual-scroll-container.virtual-scroll--horizontal[data-v-184bc0a9],.virtual-scroll-container.virtual-scroll--both[data-v-184bc0a9]{white-space:nowrap}.virtual-scroll-scrollbar-container[data-v-184bc0a9]{z-index:30;pointer-events:none;block-size:0;inline-size:100%;position:sticky;inset-block-start:0;inset-inline-start:0;overflow:visible}.virtual-scroll-scrollbar-viewport[data-v-184bc0a9]{pointer-events:none;position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-wrapper[data-v-184bc0a9]{contain:layout;position:relative}:where(.virtual-scroll--hydrated>.virtual-scroll-wrapper>.virtual-scroll-item[data-v-184bc0a9]){position:absolute;inset-block-start:0;inset-inline-start:0}.virtual-scroll-item[data-v-184bc0a9]{box-sizing:border-box;will-change:transform;display:grid}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-184bc0a9]{background-color:#ff00000d;outline:1px dashed #ff000080}.virtual-scroll-item:where(.virtual-scroll--debug)[data-v-184bc0a9]:where(:hover){z-index:100;background-color:#ff00001a}.virtual-scroll-debug-info[data-v-184bc0a9]{color:#fff;pointer-events:none;z-index:100;background:#000000b3;border-radius:4px;padding:2px 4px;font-family:monospace;font-size:10px;position:absolute;inset-block-start:2px;inset-inline-end:2px}.virtual-scroll-spacer[data-v-184bc0a9]{pointer-events:none}.virtual-scroll-header[data-v-184bc0a9],.virtual-scroll-footer[data-v-184bc0a9]{z-index:20;position:relative}.virtual-scroll--sticky[data-v-184bc0a9]{position:sticky}.virtual-scroll--sticky[data-v-184bc0a9]:where(.virtual-scroll-header){box-sizing:border-box;min-inline-size:100%;inset-block-start:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-184bc0a9]:where(.virtual-scroll-footer){box-sizing:border-box;min-inline-size:100%;inset-block-end:0;inset-inline-start:0}.virtual-scroll--sticky[data-v-184bc0a9]:where(.virtual-scroll-item){z-index:10}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-184bc0a9]{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-184bc0a9]>tr{min-inline-size:100%;display:inline-flex}:is(tbody.virtual-scroll-wrapper,thead.virtual-scroll-header,tfoot.virtual-scroll-footer)[data-v-184bc0a9]>tr>:is(td,th){align-items:center;display:inline-block}}
 /*$vite$:1*/

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@pdanpdan/virtual-scroll",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A high-performance virtual scroll component for Vue 3",
   "author": "",
   "license": "MIT",
-  "homepage": "https://github.com/pdanpdan/virtual-scroll#readme",
+  "homepage": "https://pdanpdan.github.io/virtual-scroll",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pdanpdan/virtual-scroll.git",
@@ -38,8 +38,6 @@
   "jsdelivr": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "!src/**/*.test.ts",
-    "!src/**/__tests__",
     "dist",
     "src"
   ],

package/src/components/VirtualScroll.vue

@@ -49,6 +49,7 @@ const props = withDefaults(defineProps<Props<T>>(), {
   restoreScrollOnPrepend: false,
   debug: false,
   virtualScrollbar: false,
+  itemRole: undefined,
 });
 
 const emit = defineEmits<{
@@ -871,6 +872,7 @@ const verticalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
     scrollToOffset: handleVerticalScrollbarScrollToOffset,
     containerId: containerId.value,
     isRtl: isRtl.value,
+    ariaLabel: 'Vertical scroll',
   };
 
   return {
@@ -903,6 +905,7 @@ const horizontalScrollbarProps = computed<ScrollbarSlotProps | null>(() => {
     scrollToOffset: handleHorizontalScrollbarScrollToOffset,
     containerId: containerId.value,
     isRtl: isRtl.value,
+    ariaLabel: 'Horizontal scroll',
   };
 
   return {
@@ -989,6 +992,112 @@ const isTable = computed(() => props.containerTag === 'table');
 const headerTag = computed(() => isTable.value ? 'thead' : 'div');
 const footerTag = computed(() => isTable.value ? 'tfoot' : 'div');
 
+const effectiveRole = computed(() => {
+  if (props.role) {
+    return props.role;
+  }
+  return isTable.value ? null : (props.direction === 'both' ? 'grid' : 'list');
+});
+
+const isGrid = computed(() => effectiveRole.value === 'grid' || isTable.value);
+
+const containerRole = computed(() => isTable.value
+  ? null
+  : ((props.ariaLabel || props.ariaLabelledby) ? 'region' : 'none'));
+const wrapperRole = computed(() => isTable.value ? null : effectiveRole.value);
+const internalItemRole = computed(() => {
+  if (isGrid.value) {
+    return 'row';
+  }
+
+  const role = effectiveRole.value;
+  if (role === 'tree') {
+    return 'treeitem';
+  }
+  if (role === 'listbox') {
+    return 'option';
+  }
+  if (role === 'menu') {
+    return 'menuitem';
+  }
+  return 'listitem';
+});
+const itemRole = computed(() => props.itemRole != null ? props.itemRole : internalItemRole.value);
+const cellRole = computed(() => {
+  if (props.role === 'grid' || (!props.role && props.direction === 'both')) {
+    return 'gridcell';
+  }
+  return isTable.value ? 'cell' : null;
+});
+
+const shouldBindItemAria = computed(() => {
+  const role = itemRole.value;
+  return role == null || (role !== 'none' && role !== 'presentation');
+});
+
+const rootAriaProps = computed(() => ({
+  'aria-label': props.ariaLabel,
+  'aria-labelledby': props.ariaLabelledby,
+  'aria-busy': props.loading ? 'true' : undefined,
+}));
+
+const wrapperAriaProps = computed(() => {
+  const aria: Record<string, string | number | undefined> = {};
+
+  const role = effectiveRole.value;
+  const supportsOrientation = role && [ 'grid', 'tree', 'listbox', 'menu', 'tablist' ].includes(role);
+
+  if (supportsOrientation) {
+    aria[ 'aria-orientation' ] = props.direction === 'both' ? undefined : props.direction;
+  }
+
+  if (isGrid.value) {
+    aria[ 'aria-rowcount' ] = props.items.length;
+    if (props.columnCount > 0) {
+      aria[ 'aria-colcount' ] = props.columnCount;
+    }
+  }
+
+  return aria;
+});
+
+function getItemAriaProps(index: number) {
+  const aria: Record<string, string | number | undefined> = {};
+
+  if (isGrid.value) {
+    aria[ 'aria-rowindex' ] = index + 1;
+  } else {
+    aria[ 'aria-setsize' ] = props.items.length;
+    aria[ 'aria-posinset' ] = index + 1;
+  }
+
+  const role = itemRole.value;
+  if (role !== null) {
+    aria.role = (role === 'none' || role === 'presentation')
+      ? internalItemRole.value
+      : role;
+  }
+
+  return aria;
+}
+
+function getCellAriaProps(colIndex: number) {
+  const role = cellRole.value;
+  if (!role) {
+    return {};
+  }
+
+  const aria: Record<string, string | number | undefined> = {
+    role,
+  };
+
+  if (isGrid.value) {
+    aria[ 'aria-colindex' ] = colIndex + 1;
+  }
+
+  return aria;
+}
+
 defineExpose({
   ...toRefs(props),
 
@@ -1020,6 +1129,18 @@ defineExpose({
    */
   getRowHeight,
 
+  /**
+   * Helper to get ARIA attributes for a cell.
+   * @param colIndex - The column index.
+   */
+  getCellAriaProps,
+
+  /**
+   * Helper to get ARIA attributes for an item.
+   * @param index - The item index.
+   */
+  getItemAriaProps,
+
   /**
    * Helper to get the virtual offset of a specific row.
    * @param index - The row index.
@@ -1156,6 +1277,8 @@ defineExpose({
     ]"
     :style="containerStyle"
     tabindex="0"
+    :role="isTable ? undefined : containerRole"
+    v-bind="isTable ? { ...rootAriaProps, ...wrapperAriaProps } : rootAriaProps"
     @keydown="handleKeyDown"
     @pointerdown="handlePointerDown"
     @pointermove="handlePointerMove"
@@ -1165,6 +1288,7 @@ defineExpose({
     <div
       v-if="showVirtualScrollbars"
       class="virtual-scroll-scrollbar-container"
+      aria-hidden="true"
     >
       <div
         class="virtual-scroll-scrollbar-viewport"
@@ -1188,6 +1312,7 @@ defineExpose({
       ref="headerRef"
       class="virtual-scroll-header"
       :class="{ 'virtual-scroll--sticky': stickyHeader }"
+      :role="isTable ? undefined : 'none'"
     >
       <slot name="header" />
     </component>
@@ -1197,6 +1322,8 @@ defineExpose({
       ref="wrapperRef"
       class="virtual-scroll-wrapper"
       :style="wrapperStyle"
+      :role="isTable ? undefined : wrapperRole"
+      v-bind="isTable ? {} : wrapperAriaProps"
     >
       <!-- Phantom element to push scroll height -->
       <component
@@ -1220,13 +1347,16 @@ defineExpose({
           'virtual-scroll--debug': isDebug,
         }"
         :style="getItemStyle(renderedItem)"
+        v-bind="shouldBindItemAria ? getItemAriaProps(renderedItem.index) : { role: 'none' }"
       >
         <slot
           name="item"
           :item="renderedItem.item"
           :index="renderedItem.index"
+          :get-item-aria-props="getItemAriaProps"
           :column-range="slotColumnRange"
           :get-column-width="getColumnWidth"
+          :get-cell-aria-props="getCellAriaProps"
           :gap="props.gap"
           :column-gap="props.columnGap"
           :is-sticky="renderedItem.isSticky"
@@ -1246,6 +1376,8 @@ defineExpose({
       v-if="loading && slots.loading"
       class="virtual-scroll-loading"
       :style="loadingStyle"
+      aria-live="polite"
+      aria-atomic="true"
     >
       <slot name="loading" />
     </div>
@@ -1256,6 +1388,7 @@ defineExpose({
       ref="footerRef"
       class="virtual-scroll-footer"
       :class="{ 'virtual-scroll--sticky': stickyFooter }"
+      :role="isTable ? undefined : 'none'"
     >
       <slot name="footer" />
     </component>

package/src/composables/useVirtualScrollbar.ts

@@ -27,6 +27,8 @@ export interface UseVirtualScrollbarProps {
   containerId?: MaybeRefOrGetter<string | undefined>;
   /** Whether the scrollbar is in Right-to-Left (RTL) mode. */
   isRtl?: MaybeRefOrGetter<boolean>;
+  /** Accessible label for the scrollbar. */
+  ariaLabel?: MaybeRefOrGetter<string | undefined>;
 }
 
 /**
@@ -197,6 +199,7 @@ export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
     ],
     style: trackStyle.value,
     role: 'scrollbar',
+    'aria-label': toValue(props.ariaLabel),
     'aria-orientation': axis.value,
     'aria-valuenow': Math.round(position.value),
     'aria-valuemin': 0,

package/src/types.ts

@@ -164,6 +164,9 @@ export interface ScrollDetails<T = unknown> {
   columnRange: ColumnRange;
 }
 
+/** Helper to get ARIA attributes for an item. */
+export type GetItemAriaProps = (index: number) => Record<string, string | number | undefined>;
+
 /**
  * Configuration for Server-Side Rendering.
  * Defines which items are rendered statically on the server.
@@ -302,6 +305,29 @@ export interface VirtualScrollBaseProps<T = unknown> {
    * Enable debug visualization of buffers and indices.
    */
   debug?: boolean | undefined;
+
+  /**
+   * ARIA role for the scroll container.
+   * Defaults to 'list' for vertical/horizontal and 'grid' for both.
+   */
+  role?: string | undefined;
+
+  /**
+   * ARIA label for the scroll container.
+   */
+  ariaLabel?: string | undefined;
+
+  /**
+   * ID of the element that labels the scroll container.
+   */
+  ariaLabelledby?: string | undefined;
+
+  /**
+   * ARIA role for each rendered item.
+   * Defaults to 'listitem' for list roles and 'row' for grid roles.
+   * Set to 'none' or 'presentation' to disable automatic role assignment on the wrapper.
+   */
+  itemRole?: string | undefined;
 }
 
 /** Configuration properties for the `useVirtualScroll` composable. */
@@ -385,6 +411,11 @@ export interface VirtualScrollbarProps {
    * @default false
    */
   isRtl?: boolean;
+
+  /**
+   * Accessible label for the scrollbar.
+   */
+  ariaLabel?: string;
 }
 
 /** Properties passed to the 'scrollbar' scoped slot. */
@@ -428,10 +459,14 @@ export interface ItemSlotProps<T = unknown> {
   item: T;
   /** The 0-based index of the item. */
   index: number;
+  /** Helper to get ARIA attributes for the item. */
+  getItemAriaProps: GetItemAriaProps;
   /** Information about the currently visible range of columns. */
   columnRange: ColumnRange;
   /** Helper to get the current calculated width of any column index. */
   getColumnWidth: (index: number) => number;
+  /** Helper to get ARIA attributes for a cell. */
+  getCellAriaProps: (colIndex: number) => Record<string, string | number | undefined>;
   /** Vertical gap between items. */
   gap: number;
   /** Horizontal gap between columns. */
@@ -479,6 +514,8 @@ export interface VirtualScrollInstance<T = unknown> extends VirtualScrollCompone
   getColumnWidth: (index: number) => number;
   /** Helper to get the height of a specific row. */
   getRowHeight: (index: number) => number;
+  /** Helper to get ARIA attributes for a cell. */
+  getCellAriaProps: (colIndex: number) => Record<string, string | number | undefined>;
   /** Helper to get the virtual offset of a specific row. */
   getRowOffset: (index: number) => number;
   /** Helper to get the virtual offset of a specific column. */