virtua 0.51.3 → 0.52.0

package/lib/svelte/GridCell.svelte

@@ -0,0 +1,44 @@
+<script lang="ts" generics="R, C">
+  import { type Snippet } from "svelte";
+  import {
+    type GridCellState,
+    type GridDriver,
+    type VGridCell,
+    gridStyleToString,
+  } from "../core/index.js";
+
+  interface Props {
+    state: GridCellState;
+    children: Snippet<[row: R, col: C, cell: Readonly<VGridCell>]>;
+    row: R;
+    col: C;
+    rowIndex: number;
+    resizer: GridDriver["$observeItem"];
+  }
+
+  let { state, children, row, col, rowIndex, resizer }: Props = $props();
+
+  let elementRef: HTMLDivElement;
+
+  // Derived, so that a new state with the same indexes is a no-op.
+  let measureRowIndex = $derived(state.$measureRow);
+  let measureColIndex = $derived(state.$measureCol);
+  $effect(() => {
+    if (measureRowIndex == null && measureColIndex == null) return;
+    return resizer(elementRef, measureRowIndex, measureColIndex);
+  });
+
+  let style: string = $derived(gridStyleToString(state.$style));
+</script>
+
+<div
+  bind:this={elementRef}
+  role={state.$role}
+  aria-colindex={state.$col + 1}
+  aria-rowspan={state.$rowSpan}
+  aria-colspan={state.$colSpan}
+  aria-sort={state.$sort}
+  {style}
+>
+  {@render children(row, col, { rowIndex, colIndex: state.$col })}
+</div>

package/lib/svelte/GridRow.svelte

@@ -0,0 +1,42 @@
+<script lang="ts" generics="R, C">
+  import { type Snippet } from "svelte";
+  import {
+    getAxisItem,
+    getAxisLength,
+    type GridDriver,
+    type GridRowState,
+    type VGridAxis,
+    type VGridCell,
+    gridStyleToString,
+  } from "../core/index.js";
+  import GridCell from "./GridCell.svelte";
+
+  interface Props {
+    state: GridRowState;
+    children: Snippet<[row: R, col: C, cell: Readonly<VGridCell>]>;
+    row: R;
+    cols: VGridAxis<C>;
+    resizer: GridDriver["$observeItem"];
+  }
+
+  let { state, children, row, cols, resizer }: Props = $props();
+
+  let style: string = $derived(gridStyleToString(state.$style));
+</script>
+
+<div role="row" aria-rowindex={state.$row + 1} {style}>
+  {#each state.$cells as cell (cell.$col)}
+    <!-- Guard for experimental.async: true, which runs the each block before $effect.pre -->
+    <!-- https://github.com/inokawa/virtua/pull/847 -->
+    {#if cell.$col < getAxisLength(cols)}
+      <GridCell
+        state={cell}
+        {children}
+        {row}
+        col={getAxisItem(cols, cell.$col)}
+        rowIndex={state.$row}
+        {resizer}
+      />
+    {/if}
+  {/each}
+</div>

package/lib/svelte/GridRowGroup.svelte

@@ -0,0 +1,42 @@
+<script lang="ts" generics="R, C">
+  import { type Snippet } from "svelte";
+  import {
+    getAxisItem,
+    getAxisLength,
+    type GridDriver,
+    type GridRowGroupState,
+    type VGridAxis,
+    type VGridCell,
+    gridStyleToString,
+  } from "../core/index.js";
+  import GridRow from "./GridRow.svelte";
+
+  interface Props {
+    state: GridRowGroupState;
+    children: Snippet<[row: R, col: C, cell: Readonly<VGridCell>]>;
+    rows: VGridAxis<R>;
+    cols: VGridAxis<C>;
+    resizer: GridDriver["$observeItem"];
+  }
+
+  let { state, children, rows, cols, resizer }: Props = $props();
+
+  let style: string = $derived(gridStyleToString(state.$style));
+</script>
+
+<!-- https://www.w3.org/TR/wai-aria-1.2/#rowgroup -->
+<div role="rowgroup" {style}>
+  {#each state.$rows as row (row.$row)}
+    <!-- Guard for experimental.async: true, which runs the each block before $effect.pre -->
+    <!-- https://github.com/inokawa/virtua/pull/847 -->
+    {#if row.$row < getAxisLength(rows)}
+      <GridRow
+        state={row}
+        {children}
+        row={getAxisItem(rows, row.$row)}
+        {cols}
+        {resizer}
+      />
+    {/if}
+  {/each}
+</div>

package/lib/svelte/VGrid.svelte

@@ -0,0 +1,238 @@
+<script lang="ts" generics="R = number, C = number">
+  import { onMount, onDestroy } from "svelte";
+  import {
+    type StateVersion,
+    UPDATE_SCROLL_END_EVENT,
+    UPDATE_SCROLL_EVENT,
+    UPDATE_VIRTUAL_STATE,
+    createContainerGridDriver,
+    createGridLayout,
+    createGridPlan,
+    createVirtualStore,
+    getAxisItem,
+    getAxisLength,
+    getScrollSize,
+    gridScrollBy,
+    gridScrollTo,
+    gridScrollToIndex,
+    updateGridAxis,
+  } from "../core/index.js";
+  import { styleToString } from "./utils.js";
+  import GridRow from "./GridRow.svelte";
+  import GridRowGroup from "./GridRowGroup.svelte";
+  import type { VGridHandle, VGridProps } from "./VGrid.type.js";
+
+  interface Props extends VGridProps<R, C> {}
+
+  let {
+    children,
+    rows,
+    cols,
+    rowHeight,
+    colWidth,
+    headerRows,
+    sectionRows,
+    footerRows,
+    headerCols,
+    footerCols,
+    spans,
+    keepMounted,
+    bufferSize,
+    gap = 0,
+    ariaSort,
+    onverticalscroll,
+    onhorizontalscroll,
+    onscrollend,
+    ...rest
+  }: Props = $props();
+
+  const rowLayout = createGridLayout(rows, rowHeight, gap);
+  const colLayout = createGridLayout(cols, colWidth, gap);
+  const rowStore = createVirtualStore(rowLayout);
+  const colStore = createVirtualStore(colLayout);
+  const driver = createContainerGridDriver(rowStore, colStore);
+
+  let containerRef: HTMLDivElement | undefined = $state();
+
+  let stateVersion: StateVersion = $state(
+    rowStore.$getStateVersion() + colStore.$getStateVersion(),
+  );
+  const rerender = () => {
+    stateVersion = rowStore.$getStateVersion() + colStore.$getStateVersion();
+  };
+  rowStore.$subscribe(UPDATE_VIRTUAL_STATE, rerender);
+  colStore.$subscribe(UPDATE_VIRTUAL_STATE, rerender);
+
+  // Both stores observe both axes, so the end is notified once after both have ended.
+  let scrolled = false;
+  rowStore.$subscribe(UPDATE_SCROLL_EVENT, () => {
+    scrolled = true;
+    onverticalscroll && onverticalscroll(rowStore.$getScrollOffset());
+  });
+  colStore.$subscribe(UPDATE_SCROLL_EVENT, () => {
+    scrolled = true;
+    onhorizontalscroll && onhorizontalscroll(colStore.$getScrollOffset());
+  });
+  const notifyScrollEnd = () => {
+    if (scrolled && !rowStore.$isScrolling() && !colStore.$isScrolling()) {
+      scrolled = false;
+      onscrollend && onscrollend();
+    }
+  };
+  rowStore.$subscribe(UPDATE_SCROLL_END_EVENT, notifyScrollEnd);
+  colStore.$subscribe(UPDATE_SCROLL_END_EVENT, notifyScrollEnd);
+
+  // The sizes read from the items are tracked, so the items mutated in place are followed.
+  $effect.pre(() => {
+    updateGridAxis(rowStore, rowLayout, rows, rowHeight, true);
+  });
+  $effect.pre(() => {
+    updateGridAxis(colStore, colLayout, cols, colWidth, true);
+  });
+  let rowCount = $derived(stateVersion && rowStore.$getItemsLength());
+  let colCount = $derived(stateVersion && colStore.$getItemsLength());
+  let plan = $derived.by(() => {
+    stateVersion;
+    return createGridPlan(
+      rowLayout,
+      colLayout,
+      rowStore.$getRange(bufferSize),
+      colStore.$getRange(bufferSize),
+      headerRows,
+      sectionRows,
+      footerRows,
+      headerCols,
+      footerCols,
+      spans,
+      keepMounted,
+      ariaSort,
+    );
+  });
+  let isScrolling = $derived(
+    stateVersion && (rowStore.$isScrolling() || colStore.$isScrolling()),
+  );
+
+  onMount(() => {
+    driver.$observe(containerRef!);
+  });
+  onDestroy(() => {
+    rowStore.$dispose();
+    colStore.$dispose();
+    driver.$dispose();
+  });
+
+  let prevStateVersion: StateVersion | undefined;
+  $effect(() => {
+    if (prevStateVersion === stateVersion) return;
+    prevStateVersion = stateVersion;
+    driver.$effect();
+  });
+
+  export const getVerticalScrollOffset: VGridHandle["getVerticalScrollOffset"] =
+    rowStore.$getScrollOffset;
+  export const getHorizontalScrollOffset: VGridHandle["getHorizontalScrollOffset"] =
+    colStore.$getScrollOffset;
+  export const getScrollHeight: VGridHandle["getScrollHeight"] = () =>
+    getScrollSize(rowStore);
+  export const getScrollWidth: VGridHandle["getScrollWidth"] = () =>
+    getScrollSize(colStore);
+  export const getViewportHeight: VGridHandle["getViewportHeight"] =
+    rowStore.$getViewportSize;
+  export const getViewportWidth: VGridHandle["getViewportWidth"] =
+    colStore.$getViewportSize;
+  export const findRowIndex: VGridHandle["findRowIndex"] =
+    rowStore.$findItemIndex;
+  export const findColIndex: VGridHandle["findColIndex"] =
+    colStore.$findItemIndex;
+  export const getRowOffset: VGridHandle["getRowOffset"] =
+    rowStore.$getItemOffset;
+  export const getColOffset: VGridHandle["getColOffset"] =
+    colStore.$getItemOffset;
+  export const getRowSize: VGridHandle["getRowSize"] = rowStore.$getItemSize;
+  export const getColSize: VGridHandle["getColSize"] = colStore.$getItemSize;
+  export const scrollToIndex: VGridHandle["scrollToIndex"] = (opts) =>
+    gridScrollToIndex(
+      driver,
+      rowStore,
+      colStore,
+      headerRows,
+      sectionRows,
+      footerRows,
+      headerCols,
+      footerCols,
+      opts,
+    );
+  export const scrollTo: VGridHandle["scrollTo"] = ({ vertical, horizontal }) =>
+    gridScrollTo(driver, vertical, horizontal);
+  export const scrollBy: VGridHandle["scrollBy"] = ({ vertical, horizontal }) =>
+    gridScrollBy(driver, rowStore, colStore, vertical, horizontal);
+
+  const viewportStyle = styleToString({
+    overflow: "auto",
+    contain: "strict",
+    width: "100%",
+    height: "100%",
+  });
+  let containerStyle = $derived.by(() => {
+    const { $rowTemplate: rowTemplate, $colTemplate: colTemplate } = plan;
+    // A jump deferred during scrolling shifts the tracks, as it shifts the items of the lists.
+    const marginTop = rowStore.$getItemOffset(0);
+    const marginInlineStart = colStore.$getItemOffset(0);
+    return styleToString({
+      // https://github.com/inokawa/virtua/pull/775 https://github.com/inokawa/virtua/issues/800
+      contain: "size style",
+      "overflow-anchor": "none", // opt out browser's scroll anchoring because it will conflict to scroll anchoring of virtualizer
+      flex: "none", // flex style can break layout
+      display: "grid",
+      "grid-template-rows": rowTemplate,
+      "grid-template-columns": colTemplate,
+      gap: gap + "px",
+      "margin-top": marginTop + "px",
+      "margin-inline-start": marginInlineStart + "px",
+      // The width is left to the viewport, so the auto columns fill it as the columns of a table.
+      height: getScrollSize(rowStore) - marginTop + "px",
+      "pointer-events": isScrolling ? "none" : undefined,
+    });
+  });
+</script>
+
+<!--
+  @component
+  Virtualized grid component for tabular data. See {@link VGridProps} and {@link VGridHandle}.
+-->
+<!-- https://www.w3.org/WAI/ARIA/apg/patterns/table/ -->
+<!-- https://www.w3.org/TR/wai-aria-1.2/#table -->
+<!-- https://www.w3.org/TR/wai-aria-1.2/#aria-rowcount -->
+<div
+  role="table"
+  aria-rowcount={rowCount}
+  aria-colcount={colCount}
+  {...rest}
+  style="{viewportStyle} {rest.style || ''}"
+>
+  <div bind:this={containerRef} style={containerStyle}>
+    {#each plan.$groups as state ("$rows" in state ? state.$key : state.$row)}
+      {#if "$rows" in state}
+        <GridRowGroup
+          {state}
+          {children}
+          {rows}
+          {cols}
+          resizer={driver.$observeItem}
+        />
+      {:else}
+        <!-- Guard for experimental.async: true, which runs the each block before $effect.pre -->
+        <!-- https://github.com/inokawa/virtua/pull/847 -->
+        {#if state.$row < getAxisLength(rows)}
+          <GridRow
+            {state}
+            {children}
+            row={getAxisItem(rows, state.$row)}
+            {cols}
+            resizer={driver.$observeItem}
+          />
+        {/if}
+      {/if}
+    {/each}
+  </div>
+</div>

package/lib/svelte/VGrid.type.d.ts

@@ -0,0 +1,185 @@
+import { Snippet } from 'svelte';
+import { VGridScrollToIndexOpts, VGridAxis, VGridCell, VGridSize, VGridSpan } from '../core/index.js';
+import { ViewportComponentAttributes } from './types.js';
+/**
+ * Props of {@link VGrid}.
+ */
+export interface VGridProps<R = number, C = number> extends Omit<ViewportComponentAttributes, "role"> {
+    /**
+     * A snippet to create cell elements rendered by this component.
+     * @param row the item of {@link VGridProps.rows} at the row of the cell, or the row index if {@link VGridProps.rows} is a number
+     * @param col the item of {@link VGridProps.cols} at the column of the cell, or the column index if {@link VGridProps.cols} is a number
+     * @param cell the row index and the column index of the cell
+     */
+    children: Snippet<[row: R, col: C, cell: Readonly<VGridCell>]>;
+    /**
+     * The rows of the grid. See {@link VGridAxis} for the accepted values.
+     */
+    rows: VGridAxis<R>;
+    /**
+     * The columns of the grid. See {@link VGridAxis} for the accepted values.
+     */
+    cols: VGridAxis<C>;
+    /**
+     * The heights of the rows. See {@link VGridSize} for the accepted values.
+     */
+    rowHeight: NoInfer<VGridSize<R>>;
+    /**
+     * The widths of the columns. See {@link VGridSize} for the accepted values.
+     */
+    colWidth: NoInfer<VGridSize<C>>;
+    /**
+     * The number of the leading rows pinned to the start, which are the column headers (`role="columnheader"`).
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    headerRows?: number;
+    /**
+     * Indexes of the rows which start sections. A section lasts until the next section row or the footer rows, and its first row sticks below the header rows while the section is scrolled through.
+     *
+     * **The section rows are rendered over the other cells while they stick, so give them an opaque background.**
+     */
+    sectionRows?: readonly number[];
+    /**
+     * The number of the trailing rows pinned to the end.
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    footerRows?: number;
+    /**
+     * The number of the leading columns pinned to the start, the last of which is the row header (`role="rowheader"`).
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    headerCols?: number;
+    /**
+     * The number of the trailing columns pinned to the end.
+     *
+     * **The pinned cells are rendered over the other cells, so give them an opaque background.**
+     * @defaultValue 0
+     */
+    footerCols?: number;
+    /**
+     * Cells merged over multiple rows and/or columns. See {@link VGridSpan} for the accepted values.
+     *
+     * The cell at the origin is stretched over the merged area, and the other cells in it are not rendered. Spans must not overlap each other or cross the boundaries of the pinned rows/columns or the sections. A spanning cell is not measured for `"auto"` sizes on the axes it spans, and doesn't enlarge those tracks.
+     */
+    spans?: readonly VGridSpan[];
+    /**
+     * List of cells that should be always mounted, even when off screen.
+     */
+    keepMounted?: readonly VGridCell[];
+    /**
+     * Extra space in pixels to render before/after the viewport. The minimum value is 0. Lower value will give better performance but you can increase to avoid showing blank cells in fast scrolling.
+     * @defaultValue 200
+     */
+    bufferSize?: number;
+    /**
+     * The gap between the rows and the columns in pixels, which is not included in the sizes. Must not be changed after mount.
+     * @defaultValue 0
+     */
+    gap?: number;
+    /**
+     * The header cell of the sorted column or row, and the sort order (`aria-sort`).
+     */
+    ariaSort?: VGridCell & {
+        order: "ascending" | "descending" | "other";
+    };
+    /**
+     * Callback invoked whenever the vertical scroll offset changes.
+     * @param offset Current scrollTop.
+     */
+    onverticalscroll?: (offset: number) => void;
+    /**
+     * Callback invoked whenever the horizontal scroll offset changes.
+     * @param offset Current scrollLeft. Always positive even in RTL.
+     */
+    onhorizontalscroll?: (offset: number) => void;
+    /**
+     * Callback invoked when scrolling stops.
+     */
+    onscrollend?: () => void;
+}
+/**
+ * Methods of {@link VGrid}.
+ */
+export interface VGridHandle {
+    /**
+     * Get current scrollTop.
+     */
+    getVerticalScrollOffset(): number;
+    /**
+     * Get current scrollLeft. Always positive even in RTL.
+     */
+    getHorizontalScrollOffset(): number;
+    /**
+     * Get current scrollHeight.
+     */
+    getScrollHeight(): number;
+    /**
+     * Get current scrollWidth.
+     */
+    getScrollWidth(): number;
+    /**
+     * Get current clientHeight.
+     */
+    getViewportHeight(): number;
+    /**
+     * Get current clientWidth.
+     */
+    getViewportWidth(): number;
+    /**
+     * Find nearest row index from offset.
+     * @param offset offset in pixels from the top of the scroll container
+     */
+    findRowIndex(offset: number): number;
+    /**
+     * Find nearest column index from offset.
+     * @param offset offset in pixels from the start of the scroll container
+     */
+    findColIndex(offset: number): number;
+    /**
+     * Get offset of the row from the top.
+     * @param index index of row
+     */
+    getRowOffset(index: number): number;
+    /**
+     * Get offset of the column from the start.
+     * @param index index of column
+     */
+    getColOffset(index: number): number;
+    /**
+     * Get size of the row.
+     * @param index index of row
+     */
+    getRowSize(index: number): number;
+    /**
+     * Get size of the column.
+     * @param index index of column
+     */
+    getColSize(index: number): number;
+    /**
+     * Scroll to the cell specified by the indexes. The cell is not hidden behind the rows and the columns sticking over it.
+     * @param opts the indexes of the cell and the options. See {@link VGridScrollToIndexOpts}.
+     */
+    scrollToIndex(opts: VGridScrollToIndexOpts): void;
+    /**
+     * Scroll to the given offsets from the top/start of the scroll container.
+     * @param offset the offsets. The axis whose offset is omitted is not scrolled.
+     */
+    scrollTo(offset: {
+        vertical?: number;
+        horizontal?: number;
+    }): void;
+    /**
+     * Scroll by the given offsets from the current position.
+     * @param offset the offsets. The axis whose offset is omitted is not scrolled.
+     */
+    scrollBy(offset: {
+        vertical?: number;
+        horizontal?: number;
+    }): void;
+}

package/lib/svelte/index.d.ts

@@ -7,3 +7,6 @@ export { default as Virtualizer } from './Virtualizer.svelte';
 export type { VirtualizerProps, VirtualizerHandle, } from './Virtualizer.type.js';
 export { default as WindowVirtualizer } from './WindowVirtualizer.svelte';
 export type { WindowVirtualizerProps, WindowVirtualizerHandle, } from './WindowVirtualizer.type.js';
+export { default as VGrid } from './VGrid.svelte';
+export type { VGridProps, VGridHandle } from './VGrid.type.js';
+export type { VGridSize, VGridSpan } from '../core/index.js';

package/lib/svelte/index.js

@@ -1,4 +1,5 @@
 import VList from "./VList.svelte";
 import Virtualizer from "./Virtualizer.svelte";
 import WindowVirtualizer from "./WindowVirtualizer.svelte";
-export { VList, Virtualizer, WindowVirtualizer };
+import VGrid from "./VGrid.svelte";
+export { VGrid, VList, Virtualizer, WindowVirtualizer };