svelte-kit-vice/src/uix/soma/components/virtual-grid/README.md

# VirtualGrid

2D windowing primitive. Virtualises rows **and** columns — renders only the cells inside the visible rectangle plus row / column overscan. Keeps DOM size constant regardless of `rowCount × columnCount`. A 1000 × 1000 grid (1M cells) renders ~100 DOM nodes, not a million.

Scope is fixed-size per axis (`rowSize` + `columnSize`). Dynamic per-cell sizing in 2D is genuinely ambiguous — a measured cell tells you about its row AND column at the same time, and the delta has to be attributed somehow. Most virtualisers sidestep this by forcing fixed axis sizes. Follow the same convention.

## Anatomy

```svelte
<VirtualGrid.Provider
	rowCount={1000}
	columnCount={50}
	rowSize={32}
	columnSize={120}
>
	{#snippet children({ virtualCells, totalHeight, totalWidth })}
		<VirtualGrid.Viewport style:height="500px" style:width="100%">
			<div style:height="{totalHeight}px" style:width="{totalWidth}px" style:position="relative">
				{#each virtualCells as cell (cell.key)}
					<VirtualGrid.Cell {...cell}>
						{data[cell.rowIndex][cell.columnIndex]}
					</VirtualGrid.Cell>
				{/each}
			</div>
		</VirtualGrid.Viewport>
	{/snippet}
</VirtualGrid.Provider>
```

## Parts

| Part       | Element    | Description                                                                 |
| ---------- | ---------- | --------------------------------------------------------------------------- |
| `Provider` | `<div>`    | Root context. Tracks both scroll axes, viewport size, 2D range derivation.  |
| `Viewport` | `<div>`    | 2D scroll container (`overflow: auto` on both axes).                         |
| `Cell`     | `<div>`    | One virtualised cell. Absolutely positioned via `translate3d(col, row, 0)`. |

## Props

### `Provider`

| Prop             | Type                                 | Default       | Description                                   |
| ---------------- | ------------------------------------ | ------------- | --------------------------------------------- |
| `rowCount`       | `number`                             | required      | Total number of rows.                          |
| `columnCount`    | `number`                             | required      | Total number of columns.                       |
| `rowSize`        | `number`                             | `40`          | Fixed row height (px).                         |
| `columnSize`     | `number`                             | `120`         | Fixed column width (px).                       |
| `rowOverscan`    | `number`                             | `2`           | Extra rows above / below the visible range.    |
| `columnOverscan` | `number`                             | `2`           | Extra columns left / right of the visible range.|
| `getRowKey`      | `(index: number) => string \| number`| `(i) => i`    | Stable key per row.                            |
| `getColumnKey`   | `(index: number) => string \| number`| `(i) => i`    | Stable key per column.                         |

### `Cell`

Pass every field of the `virtualCell` snippet value through to the Cell — `rowIndex`, `columnIndex`, `rowStart`, `columnStart`, `rowSize`, `columnSize`.

### Snippet props

```ts
{
	virtualCells: Array<{
		rowIndex: number;
		columnIndex: number;
		rowStart: number;
		columnStart: number;
		rowSize: number;
		columnSize: number;
		key: string | number;
	}>;
	totalHeight: number;   // sum of row sizes
	totalWidth: number;    // sum of column sizes
	isEmpty: boolean;
	scrollToCell: (
		rowIndex: number,
		columnIndex: number,
		opts?: {
			rowAlign?: 'start' | 'center' | 'end' | 'auto';
			columnAlign?: 'start' | 'center' | 'end' | 'auto';
			behavior?: ScrollBehavior;
		}
	) => void;
}
```

## Data Attributes

| Part       | Attribute                   | Values           |
| ---------- | --------------------------- | ---------------- |
| Provider   | `data-virtual-grid`         | Always present   |
| Viewport   | `data-virtual-grid-viewport`| Always present   |
| Cell       | `data-virtual-grid-cell`    | Always present   |
| Cell       | `data-row-index`            | Row index        |
| Cell       | `data-column-index`         | Column index     |

## ARIA

VirtualGrid is a rendering optimisation; it carries no ARIA roles. For a semantic table / grid, wrap the `Provider` in the appropriate outer element (e.g. `role="grid"`) and set `role="row"` / `role="gridcell"` on `Cell` yourself.

## Sema events

| Event                    | Family   | Verb       | Target     | Intent    | Emitted? | When                                               |
| ------------------------ | -------- | ---------- | ---------- | --------- | -------- | -------------------------------------------------- |
| `handle-scroll-row`      | `handle` | `scroll`   | `viewport` | —         | NO       | Row-axis scroll. Same buzz reasoning as virtual-list — soma does NOT emit. |
| `handle-scroll-column`   | `handle` | `scroll`   | `viewport` | —         | NO       | Column-axis scroll. Same as above.                  |
| `shift-navigate-to-cell` | `shift`  | `navigate` | `viewport` | —         | YES      | `scrollToCell(rowIndex, columnIndex)` — programmatic discrete navigation. |
| `commit-set-resize`      | `commit` | `set`      | `provider` | `neutral` | YES      | `rowCount` or `columnCount` changed (real dimension change, not initial). |

See virtual-list README for the rationale on skipping `handle-scroll*` emission. No per-component pack — falls back to family bases.

## Comparison

| Feature                                   | Soma | Ark UI | TanStack | React Aria |
| ----------------------------------------- | :--: | :----: | :------: | :--------: |
| Dedicated 2D component                    |  ✅  |   ❌   |    ✅    |     ⚠️     |
| Fixed row / column sizes                  |  ✅  |   —    |    ✅    |     ✅     |
| Dynamic row heights                       |  ❌¹ |   —    |    ✅    |     ⚠️     |
| Dynamic column widths                     |  ❌¹ |   —    |    ✅    |     ⚠️     |
| Row + column overscan                     |  ✅  |   —    |    ✅    |     ✅     |
| `scrollToCell(row, col, align)`           |  ✅  |   —    |    ✅    |     ✅     |
| Independent getRowKey / getColumnKey      |  ✅  |   —    |    ✅    |     ✅     |
| ARIA-agnostic                             |  ✅  |   —    |    ✅    |     ❌     |
| Zero external dependencies                |  ✅  |   —    |    ✅    |     ❌     |

¹ Fixed-size only. See notes at the top — dynamic 2D is ambiguous enough that most virtualisers don't offer it. TanStack does, at the cost of complex axis-delta attribution. Not planned.

## Usage

### 100 × 100 spreadsheet

```svelte
<script lang="ts">
	import { VirtualGrid } from '$soma/components';

	const rows = 100;
	const cols = 100;
	const cell = (r: number, c: number) => `R${r}·C${c}`;
</script>

<VirtualGrid.Provider
	rowCount={rows}
	columnCount={cols}
	rowSize={32}
	columnSize={100}
>
	{#snippet children({ virtualCells, totalHeight, totalWidth })}
		<VirtualGrid.Viewport style:height="400px" style:width="600px">
			<div style:height="{totalHeight}px" style:width="{totalWidth}px" style:position="relative">
				{#each virtualCells as c (c.key)}
					<VirtualGrid.Cell {...c}>
						{cell(c.rowIndex, c.columnIndex)}
					</VirtualGrid.Cell>
				{/each}
			</div>
		</VirtualGrid.Viewport>
	{/snippet}
</VirtualGrid.Provider>
```

### Thumbnail grid with `scrollToCell`

```svelte
<button onclick={() => api?.(500, 3, { rowAlign: 'center' })}>
	Jump to image 500-3
</button>

<VirtualGrid.Provider rowCount={1000} columnCount={5} rowSize={180} columnSize={200}>
	{#snippet children({ virtualCells, totalHeight, totalWidth, scrollToCell })}
		{(() => { api = scrollToCell; return ''; })()}
		<VirtualGrid.Viewport style:height="600px">
			<div style:height="{totalHeight}px" style:width="{totalWidth}px" style:position="relative">
				{#each virtualCells as c (c.key)}
					<VirtualGrid.Cell {...c}>
						<img src={images[c.rowIndex * 5 + c.columnIndex]} alt="" />
					</VirtualGrid.Cell>
				{/each}
			</div>
		</VirtualGrid.Viewport>
	{/snippet}
</VirtualGrid.Provider>
```

## Implementation notes

- **Total size** is `rowCount × rowSize` × `columnCount × columnSize` — the inner canvas sets its height/width to these values so the `Viewport`'s native scrollbar reflects the real scrollable area.
- **Visible range** is computed per axis independently (two 1D problems). The cartesian product of visible rows × visible columns gives the cells to render.
- **No ResizeObserver on Cell** — fixed sizes mean we never need to measure. That's the main reason VirtualGrid skips dynamic — measuring would change the axes non-orthogonally.
- **One `Viewport` only** — unlike VirtualList, there's no window-scroll variant for VirtualGrid. 2D window-scroll is niche and the scroll semantics are confusing.