@lumiose/ui 0.1.2 → 0.2.0

package/docs/llms-full.txt

@@ -42,7 +42,13 @@ Anatomy, API, Example, Styling, Keyboard and focus, Without JavaScript, Browser
   runtime.
 - **Parts.** Each component is a set of parts named as in Base UI (`Dialog.Root`,
   `Dialog.Trigger`, `Dialog.Popup`, …). Every part that renders an element takes that element's
-  props (`class`, `style`, `aria-*`, events) and passes them through.
+  props (`class`, `style`, `aria-*`, events) and passes them through. A part finds its `Root`
+  through context, so a `Root` and its parts render on the same side of an island boundary, even
+  where the JSX nests them. A part the page passes to an island as a slot (children or a JSX prop)
+  renders in the page, outside the `Root` the island renders, and the server throws "Combobox
+  parts must be inside <Combobox.Root>"; an island inside a `Root` the page renders does not see
+  that `Root` either. Pass the data as props and render the `Root` and its parts inside the
+  island ([Islands](https://itsjavi.com/lumiose/docs/concepts/islands/)).
 - **Signals.** A component's state is a prop and a callback: `open` with `onOpenChange`, `checked`
   with `onCheckedChange`, `value` with `onValueChange`. Pass a signal's value and write it back in
   the callback to keep both in sync, or leave both out and the element keeps its own state. Custom
@@ -112,6 +118,10 @@ custom properties, named as in shadcn/ui, are listed in [Theming](theming.md#the
 | [Avatar](avatar.md)                   | Available: an image over its fallback, `<lu-avatar>` follows its loading status           |
 | [Menubar](menubar.md)                 | Available: Menus in a `role="menubar"`, `<lu-menubar>` moves between them                 |
 | [Navigation Menu](navigation-menu.md) | Available: a `<nav>` whose triggers open panels of links, works without JavaScript        |
+| [Virtual List](virtual-list.md)       | Available: a `<ul>` that renders the rows near the viewport, in islands                   |
+| [Virtual Grid](virtual-grid.md)       | Available: cells in auto-fill columns, fixed or measured rows, in islands                 |
+| [Virtual Table](virtual-table.md)     | Available: table rows between spacer rows, with `aria-rowcount` and `aria-rowindex`       |
+| [Virtualizer](virtualizer.md)         | Available: `createVirtualizer()`, the headless primitive under the three, in islands      |
 
 ## Ids
 
@@ -390,6 +400,315 @@ Each component's page has an example stylesheet to start from.
 - [Installation](installation.md): adding the package and importing its stylesheets.
 - [Styles](https://itsjavi.com/lumiose/docs/concepts/styles/): scoped CSS and global stylesheets in Lumiose.
 
+<!-- source: virtualizer.md -->
+
+# Virtualizer
+
+> A headless virtualizer for long lists, tables and grids in islands: `createVirtualizer()` computes which rows are near the viewport and where they go, and your component renders, places and styles them. The window or an element scrolls; rows have a fixed or an estimated size, or are measured as they render (one ResizeObserver for all of them); grids fit their columns to the container's width. The server renders the first items, and the island takes those same keyed rows over. 1.6 kB brotli, no script and no CSS of its own. For a list, a grid of cells or a table, start with [Virtual List](virtual-list.md), [Virtual Grid](virtual-grid.md) or [Virtual Table](virtual-table.md), which run on it.
+
+```ts
+import { createVirtualizer } from "@lumiose/ui"; // or "@lumiose/ui/virtualizer"
+```
+
+## Usage
+
+A virtualizer works in rows (decision-84): a list is a grid of one column, where each item is a row. Call it in a
+component's body, give the element that holds the rows `ref={v.container}`, and render the rows it
+lists, keyed by the record's id:
+
+```tsx
+const v = createVirtualizer({ count: () => items().length, size: 48 });
+
+<ul ref={v.container} style={{ position: "relative", height: `${v.total()}px` }}>
+  {v.items().map((i) => (
+    <li
+      key={items()[i]!.id}
+      style={{ position: "absolute", inset: "0 0 auto", transform: `translateY(${v.start(i)}px)` }}
+    >
+      {items()[i]!.name}
+    </li>
+  ))}
+</ul>;
+```
+
+| Piece                       | What it is                                                                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref={v.container}`         | The element that holds the rows. Its top is where row 0 starts; its width sets `{ minWidth }` columns.                                                                        |
+| `v.rows()`, `v.items()`     | The indexes to render: rows (for a row element around several items) or items, in order.                                                                                      |
+| `v.start(row)`, `v.total()` | Placed rows: each row's offset from the container's top, and the container's height.                                                                                          |
+| `v.before()`, `v.after()`   | Rows in flow: the px of the rows before and after the window, for spacers or a padding.                                                                                       |
+| `data-row={row}`            | On a row element that is measured, or that `keepFocused` keeps: the row's index. Several elements may share a row (a grid's cells): a measured row is as tall as its tallest. |
+| `attach={[v.measure]}`      | On a measured row: its size replaces the estimate.                                                                                                                            |
+
+## API
+
+### createVirtualizer(options)
+
+A value marked `Value<T>` is the value or a function that returns it, read reactively: a function
+that reads signals or props recomputes the window when they change.
+
+| Option        | Type                                                         | Default |                                                                                                                                                                                                                     |
+| ------------- | ------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `count`       | `Value<number>`                                              |         | How many items.                                                                                                                                                                                                     |
+| `size`        | `number \| (row: number) => number`                          |         | A row's size along the scroll axis, in px: fixed, or the estimate of a row not measured yet. A function gets the row's index and may read signals (`v.itemWidth()`).                                                |
+| `columns`     | `Value<number> \| { minWidth: Value<number>; min?: number }` | `1`     | Items per row. `{ minWidth }` fits as many items of at least `minWidth` px as the container's width does, with `columnGap` between them, and at least `min` (default 1), like CSS's `repeat(auto-fill, minmax(…))`. |
+| `gap`         | `Value<number>`                                              | `0`     | The px between rows.                                                                                                                                                                                                |
+| `columnGap`   | `Value<number>`                                              | `gap`   | The px between columns, for `{ minWidth }` and `itemWidth()`.                                                                                                                                                       |
+| `overscan`    | `Value<number>`                                              | `4`     | Rows rendered past each edge of the viewport.                                                                                                                                                                       |
+| `scroller`    | `() => Element \| null \| undefined`                         | window  | The element that scrolls, read once mounted.                                                                                                                                                                        |
+| `initial`     | `Value<number>`                                              | `0`     | How many items render before the virtualizer mounts: in the server's HTML and while the island hydrates (see [Server rendering](#server-rendering)).                                                                |
+| `keepFocused` | `boolean`                                                    | `false` | Keeps the row that holds focus rendered while the window scrolls away from it. For placed rows only (see [Keyboard and focus](#keyboard-and-focus)).                                                                |
+
+### The virtualizer
+
+| Member                       | Returns                                                                                                                                                                                                                                                                                                                                      |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container`                  | A `ref` callback for the element that holds the rows.                                                                                                                                                                                                                                                                                        |
+| `measure`                    | An `attach` function for a measured row element, which carries `data-row`.                                                                                                                                                                                                                                                                   |
+| `rows()`                     | The indexes of the rows to render, in order. The same array while the window does not move, so measuring or scrolling inside the overscan renders no list.                                                                                                                                                                                   |
+| `items()`                    | The indexes of the items of those rows, in order, never past `count`.                                                                                                                                                                                                                                                                        |
+| `range()`                    | `{ start, end }`: the window's items, `end` excluded (without a kept focused row), for `array.slice(start, end)`.                                                                                                                                                                                                                            |
+| `start(row)`, `size(row)`    | Where a row starts, in px from the container's top, and its size (measured, or the estimate).                                                                                                                                                                                                                                                |
+| `total()`                    | Every row and gap: the container's height.                                                                                                                                                                                                                                                                                                   |
+| `before()`, `after()`        | The px of the rows before and after the window, gaps included.                                                                                                                                                                                                                                                                               |
+| `columns()`                  | Items per row.                                                                                                                                                                                                                                                                                                                               |
+| `width()`, `itemWidth()`     | The container's width (0 until mounted), and an item's: the width less the column gaps, per column.                                                                                                                                                                                                                                          |
+| `mounted()`                  | `false` on the server and while hydrating, then `true`: switch between the server's layout and the virtual one with it.                                                                                                                                                                                                                      |
+| `scrollToIndex(i, options?)` | Scrolls the scroller to show item `i`. `align`: `"auto"` (default: only as far as it takes), `"start"`, `"center"` or `"end"`; `behavior` as in `scrollTo`. It honours the scroller's `scroll-padding` (a sticky header), and checks the position again for a few frames while rows on the way are measured (not with `behavior: "smooth"`). |
+
+## Example
+
+A list of people the server renders the first 20 of; the island takes them over:
+
+```tsx check
+import { createVirtualizer } from "@lumiose/ui";
+
+type Person = { id: string; name: string };
+
+export function People(props: { people: Person[] }) {
+  const list = createVirtualizer({ count: () => props.people.length, size: 40, initial: 20 });
+  return (
+    <ul
+      ref={list.container}
+      aria-label="People"
+      style={{
+        "padding-block-start": `${list.before()}px`,
+        "padding-block-end": `${list.after()}px`,
+      }}
+    >
+      {props.people.slice(list.range().start, list.range().end).map((person, offset) => (
+        <li
+          key={person.id}
+          aria-setsize={props.people.length}
+          aria-posinset={list.range().start + offset + 1}
+          style={{ height: "40px" }}
+        >
+          {person.name}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+A grid of cards whose rows have different heights, as many columns of at least 12rem as fit:
+
+```tsx check
+import { createVirtualizer } from "@lumiose/ui";
+
+type Card = { id: string; title: string; body: string };
+
+export function Cards(props: { cards: Card[] }) {
+  const grid = createVirtualizer({
+    count: () => props.cards.length,
+    columns: { minWidth: 192 },
+    gap: 16,
+    size: 120, // the estimate, until a row is measured
+  });
+  const cardsOf = (row: number) =>
+    props.cards.slice(row * grid.columns(), (row + 1) * grid.columns());
+  return (
+    <div
+      ref={grid.container}
+      role="list"
+      aria-label="Cards"
+      style={{ position: "relative", height: `${grid.total()}px` }}
+    >
+      {grid.rows().map((row) => (
+        <div
+          key={row}
+          role="none"
+          data-row={row}
+          attach={[grid.measure]}
+          style={{
+            position: "absolute",
+            inset: "0 0 auto",
+            display: "grid",
+            gap: "16px",
+            "grid-template-columns": `repeat(${grid.columns()}, minmax(0, 1fr))`,
+            transform: `translateY(${grid.start(row)}px)`,
+          }}
+        >
+          {cardsOf(row).map((card, i) => (
+            <div
+              key={card.id}
+              role="listitem"
+              aria-setsize={props.cards.length}
+              aria-posinset={row * grid.columns() + i + 1}
+            >
+              <h3>{card.title}</h3>
+              <p>{card.body}</p>
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+A table in its own scroller, with spacer rows:
+
+```tsx check
+import { createVirtualizer } from "@lumiose/ui";
+
+type Release = { id: string; version: string };
+
+export function Releases(props: { releases: Release[] }) {
+  let scroller: HTMLDivElement | undefined;
+  const table = createVirtualizer({
+    count: () => props.releases.length,
+    size: 32,
+    scroller: () => scroller,
+    initial: 15,
+  });
+  return (
+    <div
+      ref={(el) => (scroller = el)}
+      role="region"
+      aria-label="Releases"
+      tabindex={0}
+      style={{ height: "16rem", overflow: "auto" }}
+    >
+      <table aria-rowcount={props.releases.length + 1} style={{ "border-collapse": "collapse" }}>
+        <thead>
+          <tr aria-rowindex={1}>
+            <th scope="col">Version</th>
+          </tr>
+        </thead>
+        <tbody ref={table.container}>
+          {table.before() > 0 ? (
+            <tr aria-hidden="true">
+              <td style={{ height: `${table.before()}px`, padding: "0" }} />
+            </tr>
+          ) : null}
+          {props.releases.slice(table.range().start, table.range().end).map((release, offset) => (
+            <tr
+              key={release.id}
+              aria-rowindex={table.range().start + offset + 2}
+              style={{ height: "32px" }}
+            >
+              <td>{release.version}</td>
+            </tr>
+          ))}
+          {table.after() > 0 ? (
+            <tr aria-hidden="true">
+              <td style={{ height: `${table.after()}px`, padding: "0" }} />
+            </tr>
+          ) : null}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+```
+
+## Styling
+
+Nothing is styled: the virtualizer only computes. Lay the rows out one of two ways.
+
+- **Placed rows**: the container is `position: relative` and `total()` tall; each row is
+  `position: absolute` at `transform: translateY(${start(row)}px)` (a cell of a grid adds its
+  column: `translate(${column * (itemWidth() + gap)}px, …)`). A row out of order (`keepFocused`)
+  still sits in its place, and a size that changes moves only the rows after it.
+- **Rows in flow**: the rows of the window stay in the document's flow between `before()` and
+  `after()`, as a padding of the container or as spacer elements. Tables need this (a `<tr>` cannot
+  be placed), and it is the simplest server-rendered list: the same layout before and after mount.
+  In a CSS grid, use a padding: a spacer element would add a gap.
+
+Measured rows are placed in the frame they are measured in, before it paints: the observer's
+callback writes their sizes and the rows move at once, so they never show at their estimates. A
+row rendered by that move (the window grew) is measured in the next frame, which browsers report
+as an `error` event, "ResizeObserver loop completed with undelivered notifications". It is
+harmless, and error trackers ignore it.
+
+`size` must match the CSS: a fixed size is exactly the row's height, without the gap (that is
+`gap`), and an estimate only has to be close (measured rows correct it). When the CSS sets the
+height, such as a custom property that a breakpoint changes, keep it in a signal that a
+ResizeObserver updates, and return that from `size`.
+
+## Server rendering
+
+Before it mounts, on the server and while an island hydrates, the virtualizer reads nothing from
+the browser: `mounted()` is `false`, `width()` is 0, `{ minWidth }` columns are `min`, and it
+renders the first `initial` items (in whole rows). Both sides render the same HTML, so hydration
+matches. Once mounted it measures the container and the viewport, and renders the window instead:
+rows keyed by the same ids are kept, so the server's elements stay and only move. Options that
+change the pre-mount window (`count`, `initial`, `columns`) must not read the browser either.
+
+- **No layout jump.** The server's rows should take the place the virtual layout gives them. With
+  rows in flow and a fixed size, it holds by itself: render `after()` as a padding before mount too.
+  A server-only layout (a CSS grid with `auto-fill`, say) works when its geometry is the
+  virtualizer's: switch the container's class or style on `mounted()`, keep the same keyed rows.
+- **Every item on the server.** For a list that must be complete in the HTML (indexing, find in
+  page, no JavaScript), render all of it on the server into an island's `children` slot and let the
+  island virtualize once its data loads, or skip the virtualizer and give the rows
+  `content-visibility: auto` with a `contain-intrinsic-size`: the browser skips their rendering
+  while they are off screen, with no script.
+
+## Keyboard and focus
+
+- **Key rows by the record's id**, never by the index: a kept row is the same record, so its
+  focus, selection and typed text stay with it ([Lists and keys](https://itsjavi.com/lumiose/docs/concepts/jsx/#lists-and-keys)).
+  A row element that only wraps a grid's items may be keyed by its row index (`key={row}`): its
+  items keep their own keys.
+- **Tab** moves through the rendered rows in DOM order; the browser scrolls the next one into view,
+  and the window follows it. The overscan keeps the next rows rendered.
+- **`keepFocused`**: scrolled away with the wheel or the scrollbar, a focused row would leave the
+  document and focus would fall back to the page. With `keepFocused`, the row of the focused
+  element (its closest `[data-row]`) stays in `rows()` until focus leaves the container, placed
+  where it belongs. Rows in flow cannot hold a row outside their window: leave it off there.
+- **`scrollToIndex`** moves the scroller, not focus: focus the row afterwards when the user asked
+  to go to it.
+
+## Accessibility
+
+- **Lists**: give each rendered item `aria-setsize` (the count) and `aria-posinset` (its position
+  from 1), so assistive technology announces "3 of 1,000" rather than the rows rendered.
+- **Tables**: `aria-rowcount` on the table (rows plus the header rows) and `aria-rowindex` on every
+  row, the header's too. Spacer rows are `aria-hidden="true"`.
+- **Grids of items**: a row element that only lays out items gets `role="none"`, so the items are
+  the list's (`role="list"` on the container, `role="listitem"` on the items).
+- Find in page and assistive technology reach only the rendered rows. Render everything on the
+  server when they must reach every row (above).
+
+## Without JavaScript
+
+Only the server's first `initial` items render. Link to a full page, or render every item on the
+server, when the list must work without JavaScript.
+
+## Browser support
+
+ResizeObserver with `borderBoxSize`, and `scroll-padding`: every supported browser. The virtualizer
+scrolls along the block axis only (vertical in horizontal writing modes).
+
+## Related
+
+- [Virtual List](virtual-list.md), [Virtual Grid](virtual-grid.md) and
+  [Virtual Table](virtual-table.md): the three layouts as components on this primitive.
+- [Scroll Area](scroll-area.md): custom scrollbars over a scroller; give its `Viewport` as `scroller`.
+- [Lists and keys](https://itsjavi.com/lumiose/docs/concepts/jsx/#lists-and-keys): how keyed rows update in place.
+
 <!-- source: accordion.md -->
 
 # Accordion
@@ -6956,3 +7275,411 @@ in browsers without CSS anchor positioning.
 - [UI components](README.md): the approach, styling, the default theme and the other components.
 - [Popover](popover.md): a popup with interactive content, opened by a click.
 
+<!-- source: virtual-grid.md -->
+
+# Virtual Grid
+
+> A long grid that renders only the rows near the viewport, in islands: a `<ul>` of `<li>` cells placed in rows of as many columns as the width fits (`minItemWidth`, like CSS's `auto-fill`) or of `columns`, by [createVirtualizer](virtualizer.md). Rows have a fixed height, or each is as tall as its tallest measured cell. The server renders the first `initial` cells in flow for your CSS grid to lay out, and the island takes those same keyed cells over. 2.3 kB brotli with the virtualizer.
+
+```ts
+import { VirtualGrid } from "@lumiose/ui"; // or "@lumiose/ui/virtualizer"
+```
+
+## Anatomy
+
+```tsx
+<VirtualGrid items={cards()} itemKey={(card) => card.id} minItemWidth={192} gap={16} size={160}>
+  {(cell) => <Card card={cell.item} />}
+</VirtualGrid>
+```
+
+| Part          | Renders                                                                                                    |
+| ------------- | ---------------------------------------------------------------------------------------------------------- |
+| `VirtualGrid` | `<ul>`, `total()` tall once mounted; an `<li data-row aria-posinset aria-setsize>` per cell, a column wide |
+
+## API
+
+### VirtualGrid
+
+| Prop           | Type                                    | Default |                                                                                                                                       |
+| -------------- | --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`        | `readonly T[]`                          |         | The items.                                                                                                                            |
+| `itemKey`      | `(item: T) => string \| number`         |         | The item's identity: a cell stays while its key does.                                                                                 |
+| `children`     | `(cell: VirtualItem<T>) => JSX.Element` |         | A cell's content, rendered once per cell; `cell.item` and `cell.index` are getters.                                                   |
+| `size`         | `number \| (row: number) => number`     |         | A row's height in px: fixed (each cell gets it), or with `measure` the estimate. A function may read the virtualizer's `itemWidth()`. |
+| `measure`      | `boolean`                               | `false` | Measures the cells: each row is as tall as its tallest.                                                                               |
+| `minItemWidth` | `number`                                |         | As many columns of at least this many px as the container's width fits.                                                               |
+| `minColumns`   | `number`                                | `1`     | The fewest columns with `minItemWidth`, before mount too.                                                                             |
+| `columns`      | `number`                                | `1`     | A fixed number of columns, without `minItemWidth`.                                                                                    |
+| `gap`          | `number`                                | `0`     | The px between rows.                                                                                                                  |
+| `columnGap`    | `number`                                | `gap`   | The px between columns.                                                                                                               |
+| `overscan`     | `number`                                | `4`     | Rows rendered past each edge of the viewport.                                                                                         |
+| `scroller`     | `() => Element \| null \| undefined`    | window  | The element that scrolls.                                                                                                             |
+| `initial`      | `number`                                | `0`     | The cells rendered before mount (in whole rows of `minColumns`): the server's HTML.                                                   |
+| `keepFocused`  | `boolean`                               | `true`  | Keeps the row of the focused cell rendered while the grid scrolls away from it.                                                       |
+| `itemProps`    | `(item: T, index: number) => li props`  |         | Attributes of each `<li>`. Not `style`, which places the cell.                                                                        |
+| `virtualizer`  | `(virtualizer: Virtualizer) => void`    |         | Receives the [virtualizer](virtualizer.md): `scrollToIndex()`, `itemWidth()`, `columns()`.                                            |
+
+Every other `<ul>` prop passes through. A `style` lays out the server's cells before mount (a
+CSS grid); once mounted, a `style` object stays under the grid's own position and height.
+
+## Example
+
+1,200 entries in a scroll box. The server renders the first 48 in a CSS grid of the same columns
+(the `style`, kept until the grid mounts), and the island places the same cells:
+
+```tsx check
+import { VirtualGrid } from "@lumiose/ui";
+
+const ENTRIES = Array.from({ length: 1200 }, (_, i) => ({ id: `e${i + 1}`, label: `#${i + 1}` }));
+
+export function EntryGrid() {
+  let box: HTMLDivElement | undefined;
+  return (
+    <div
+      ref={(el) => (box = el)}
+      role="region"
+      aria-label="Entries"
+      tabindex={0}
+      style={{ "inline-size": "100%", "max-block-size": "18rem", overflow: "auto" }}
+    >
+      <VirtualGrid
+        aria-label="Entries"
+        style={{
+          margin: "0",
+          padding: "0",
+          "list-style": "none",
+          display: "grid",
+          "grid-template-columns": "repeat(auto-fill, minmax(96px, 1fr))",
+          gap: "8px",
+        }}
+        items={ENTRIES}
+        itemKey={(entry) => entry.id}
+        minItemWidth={96}
+        gap={8}
+        size={64}
+        initial={48}
+        scroller={() => box}
+      >
+        {(cell) => (
+          <button type="button" style={{ "inline-size": "100%", "block-size": "64px" }}>
+            {cell.item.label}
+          </button>
+        )}
+      </VirtualGrid>
+    </div>
+  );
+}
+```
+
+The same server layout in CSS, for a grid whose columns change at breakpoints:
+
+```css
+.entries:not([data-mounted]) {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(96px, 1fr));
+  gap: 8px;
+}
+```
+
+## Styling
+
+Unstyled. Before mount the cells are in flow: lay them out with a CSS grid, in the grid's `style`
+or under `:not([data-mounted])`, with the columns and gaps the grid computes (`repeat(auto-fill,
+minmax(<minItemWidth>px, 1fr))` and `gap`), and the cells take the same places once mounted.
+Mounted, the `<ul>` gets `data-mounted`, `position: relative` and its total height, and each `<li>`
+`position: absolute`, its column as `left`, the column's width, its row as a `translateY`, and with
+a fixed `size` the row's height. Give the content `block-size: 100%` to fill a fixed cell. The cells
+are the component's elements: reach them from the grid's class with `:deep()`
+(`.entries :deep(li)`); `[data-row]` is each cell's row.
+
+## Keyboard and focus
+
+Cells are in DOM order, row by row, so Tab moves through them and the window follows. The row of
+the focused cell stays rendered while the grid scrolls away (`keepFocused`, on by default, decision-84). Cells are keyed by
+the record, so focus and state stay with their record through a filter, a sort or a refetch.
+
+## Without JavaScript
+
+The server renders the first `initial` cells, which your CSS lays out. See
+[Virtualizer](virtualizer.md#server-rendering) for grids that must be complete in the HTML.
+
+## Browser support
+
+ResizeObserver (for `measure` and the width): every supported browser. Cells are placed left to
+right.
+
+## Related
+
+- [Virtualizer](virtualizer.md): the primitive the grid runs on.
+- [Virtual List](virtual-list.md) and [Virtual Table](virtual-table.md).
+
+<!-- source: virtual-list.md -->
+
+# Virtual List
+
+> A long list that renders only the rows near the viewport, in islands: a `<ul>` whose rows are `<li>`s placed by [createVirtualizer](virtualizer.md), each keyed by `itemKey` and carrying `aria-posinset` and `aria-setsize`. The children function renders a row's content once; a row kept under its key keeps its DOM and state while its item updates in place. The server renders the first `initial` rows in flow. 2.2 kB brotli with the virtualizer.
+
+```ts
+import { VirtualList } from "@lumiose/ui"; // or "@lumiose/ui/virtualizer"
+```
+
+## Anatomy
+
+```tsx
+<VirtualList items={people()} itemKey={(person) => person.id} size={40}>
+  {(row) => <a href={`/people/${row.item.id}`}>{row.item.name}</a>}
+</VirtualList>
+```
+
+| Part          | Renders                                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `VirtualList` | `<ul>`, `total()` tall and `position: relative` once mounted; an `<li data-row aria-posinset aria-setsize>` per row |
+
+## API
+
+### VirtualList
+
+| Prop          | Type                                   | Default |                                                                                                                |
+| ------------- | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `items`       | `readonly T[]`                         |         | The items.                                                                                                     |
+| `itemKey`     | `(item: T) => string \| number`        |         | The item's identity, such as its record's id: a row stays while its key does.                                  |
+| `children`    | `(row: VirtualItem<T>) => JSX.Element` |         | A row's content, rendered once per row. `row.item` and `row.index` are getters: read them where they are used. |
+| `size`        | `number \| (row: number) => number`    |         | A row's height in px: fixed (the `<li>` gets it), or with `measure` the estimate.                              |
+| `measure`     | `boolean`                              | `false` | Measures the rendered rows (one ResizeObserver): their heights replace `size`.                                 |
+| `gap`         | `number`                               | `0`     | The px between rows.                                                                                           |
+| `overscan`    | `number`                               | `4`     | Rows rendered past each edge of the viewport.                                                                  |
+| `scroller`    | `() => Element \| null \| undefined`   | window  | The element that scrolls.                                                                                      |
+| `initial`     | `number`                               | `0`     | The rows rendered before mount: the server's HTML.                                                             |
+| `keepFocused` | `boolean`                              | `true`  | Keeps the row that holds focus rendered while the list scrolls away from it.                                   |
+| `itemProps`   | `(item: T, index: number) => li props` |         | Attributes of each `<li>`: data attributes, a title. Not `style`, which places the row.                        |
+| `virtualizer` | `(virtualizer: Virtualizer) => void`   |         | Receives the [virtualizer](virtualizer.md), for `scrollToIndex()` and `range()`.                               |
+
+Every other `<ul>` prop passes through: `class`, `aria-label`, `aria-labelledby`, `id`. A `style`
+object applies too, with the list's own properties (its padding, position and height) over it.
+
+## Example
+
+A thousand people in a scroll box, the first 20 in the server's HTML:
+
+```tsx check
+import { VirtualList, type Virtualizer } from "@lumiose/ui";
+
+const PEOPLE = Array.from({ length: 1000 }, (_, i) => ({
+  id: `p${i + 1}`,
+  name: `Person ${i + 1}`,
+}));
+
+export function PeopleList() {
+  let box: HTMLDivElement | undefined;
+  let list: Virtualizer | undefined;
+  return (
+    <>
+      <button type="button" onClick={() => list?.scrollToIndex(499, { align: "start" })}>
+        Go to person 500
+      </button>
+      <div
+        ref={(el) => (box = el)}
+        role="region"
+        aria-label="People"
+        tabindex={0}
+        style={{ "inline-size": "100%", "max-block-size": "16rem", overflow: "auto" }}
+      >
+        <VirtualList
+          aria-label="People"
+          style={{ margin: "0", padding: "0", "list-style": "none" }}
+          items={PEOPLE}
+          itemKey={(person) => person.id}
+          size={40}
+          initial={20}
+          scroller={() => box}
+          virtualizer={(v) => (list = v)}
+        >
+          {(row) => (
+            <span>
+              {row.index + 1}. {row.item.name}
+            </span>
+          )}
+        </VirtualList>
+      </div>
+    </>
+  );
+}
+```
+
+## Styling
+
+Unstyled. Before mount the rows are in flow (each `size` tall, the rest of the list's height a
+`padding-block-end`), so the server's list already has its full height. Once mounted the `<ul>`
+gets `data-mounted`, `position: relative` and its total height, and each `<li>` `position:
+absolute`, `inset: 0 0 auto` and a `transform`. Style with `class` on the list, `[data-mounted]`,
+and the rows through the list's class: they are the component's elements, so a scoped selector
+reaches them with `:deep()`, as in `.people :deep(li)`. The content you render is yours to style.
+
+## Keyboard and focus
+
+The rows are in DOM order, so Tab moves through them, and the browser scrolls the next one into
+view. A focused row stays rendered while the list scrolls away from it (`keepFocused`, on by default for placed rows, decision-84), so focus
+never falls back to the page. Rows are keyed by the record: a row's focus, typed text or toggled
+state stays with its record when items are added, removed, reordered or fetched again.
+
+## Without JavaScript
+
+The server renders the first `initial` rows, in flow, with the list's full height reserved. See
+[Virtualizer](virtualizer.md#server-rendering) for the takeover and for lists that must be
+complete in the HTML.
+
+## Browser support
+
+ResizeObserver (for `measure`): every supported browser.
+
+## Related
+
+- [Virtualizer](virtualizer.md): the primitive the list runs on, for other layouts.
+- [Virtual Grid](virtual-grid.md) and [Virtual Table](virtual-table.md).
+
+<!-- source: virtual-table.md -->
+
+# Virtual Table
+
+> A long table that renders only the rows near its scroller's viewport, in islands: a `<table>` with `aria-rowcount`, your head, and a body whose `<tr aria-rowindex>` rows sit between two spacer rows, by [createVirtualizer](virtualizer.md). The children function renders a row's cells once; a row kept under its key updates in place. The server renders the first `initial` rows and a spacer for the rest. 2.3 kB brotli with the virtualizer.
+
+```ts
+import { VirtualTable } from "@lumiose/ui"; // or "@lumiose/ui/virtualizer"
+```
+
+## Anatomy
+
+```tsx
+<VirtualTable
+  items={releases()}
+  itemKey={(release) => release.id}
+  size={32}
+  scroller={() => box}
+  head={
+    <thead>
+      <tr aria-rowindex={1}>
+        <th scope="col">Version</th>
+      </tr>
+    </thead>
+  }
+>
+  {(row) => <td>{row.item.version}</td>}
+</VirtualTable>
+```
+
+| Part           | Renders                                                                                                                            |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `VirtualTable` | `<table aria-rowcount>`, `head`, and a `<tbody>` of `<tr data-row aria-rowindex>` rows between `<tr aria-hidden data-spacer>` rows |
+
+## API
+
+### VirtualTable
+
+| Prop          | Type                                   | Default |                                                                                                         |
+| ------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `items`       | `readonly T[]`                         |         | The items.                                                                                              |
+| `itemKey`     | `(item: T) => string \| number`        |         | The item's identity: a row stays while its key does.                                                    |
+| `children`    | `(row: VirtualItem<T>) => JSX.Element` |         | A row's cells, rendered once per row; `row.item` and `row.index` are getters.                           |
+| `size`        | `number \| (row: number) => number`    |         | A row's height in px: fixed, or with `measure` the estimate. It must match the CSS's row height.        |
+| `measure`     | `boolean`                              | `false` | Measures the rendered rows: their heights replace `size`.                                               |
+| `scroller`    | `() => Element \| null \| undefined`   | window  | The element that scrolls, usually a `role="region"` box around the table.                               |
+| `head`        | `JSX.Element`                          |         | What comes before the body: `<caption>`, `<colgroup>`, `<thead>`. Give its rows `aria-rowindex` from 1. |
+| `headerRows`  | `number`                               | `1`     | How many rows `head` has: `aria-rowcount` is the items plus these, and the body's indexes follow.       |
+| `colSpan`     | `number`                               | `1`     | The columns a spacer row spans.                                                                         |
+| `empty`       | `JSX.Element`                          |         | A row shown in the body while there are no items.                                                       |
+| `overscan`    | `number`                               | `4`     | Rows rendered past each edge of the viewport.                                                           |
+| `initial`     | `number`                               | `0`     | The rows rendered before mount: the server's HTML.                                                      |
+| `rowProps`    | `(item: T, index: number) => tr props` |         | Attributes of each row: data attributes, a title.                                                       |
+| `virtualizer` | `(virtualizer: Virtualizer) => void`   |         | Receives the [virtualizer](virtualizer.md), for `scrollToIndex()`.                                      |
+
+Every other `<table>` prop passes through: `class`, `aria-label`, `id`.
+
+## Example
+
+```tsx check
+import { VirtualTable } from "@lumiose/ui";
+
+const RELEASES = Array.from({ length: 2000 }, (_, i) => ({
+  id: `r${i + 1}`,
+  version: `1.${Math.floor(i / 10)}.${i % 10}`,
+  downloads: (i * 7919) % 10007,
+}));
+
+export function ReleaseTable() {
+  let box: HTMLDivElement | undefined;
+  return (
+    <div
+      ref={(el) => (box = el)}
+      role="region"
+      aria-label="Releases"
+      tabindex={0}
+      style={{ "inline-size": "100%", "max-block-size": "20rem", overflow: "auto" }}
+    >
+      <VirtualTable
+        style={{ "border-collapse": "collapse" }}
+        items={RELEASES}
+        itemKey={(release) => release.id}
+        size={32}
+        scroller={() => box}
+        initial={15}
+        colSpan={2}
+        head={
+          <thead>
+            <tr aria-rowindex={1}>
+              <th scope="col">Version</th>
+              <th scope="col">Downloads</th>
+            </tr>
+          </thead>
+        }
+        rowProps={() => ({ style: "block-size: 32px" })}
+        empty={
+          <tr>
+            <td colspan={2}>No releases yet.</td>
+          </tr>
+        }
+      >
+        {(row) => (
+          <>
+            <td>{row.item.version}</td>
+            <td>{row.item.downloads}</td>
+          </>
+        )}
+      </VirtualTable>
+    </div>
+  );
+}
+```
+
+## Styling
+
+Unstyled. Rows stay in the table's flow, so the table lays out its columns as usual; set the rows'
+height in CSS to match `size` (`block-size` on the rows, or a custom property that `size` reads),
+and collapse the borders (`border-collapse: collapse`), or the default `border-spacing` puts 2px
+between rows that `size` does not count.
+The spacer rows (`[data-spacer]`) have no padding or border. The rows are the component's `<tr>`s:
+reach them from the table's class with `:deep()`, as in `.releases :deep(tr[data-row])`. The cells
+you render are yours to style; a sticky `<thead>` works as in any scroller.
+
+## Keyboard and focus
+
+Focus the scroller (`tabindex="0"`) and the arrow keys, Page Up and Down, Home and End scroll it; the
+rows follow. Rows are keyed by the record, so a link focused in a row keeps focus through a sort or
+a refetch while it stays in the window. The table has no `keepFocused` (decision-84): a row outside the window
+cannot sit between the spacers.
+
+## Without JavaScript
+
+The server renders the head, the first `initial` rows and a spacer for the rest, so the scroller has
+its full height. See [Virtualizer](virtualizer.md#server-rendering) for tables that must be complete
+in the HTML.
+
+## Browser support
+
+ResizeObserver: every supported browser.
+
+## Related
+
+- [Virtualizer](virtualizer.md): the primitive the table runs on.
+- [Virtual List](virtual-list.md) and [Virtual Grid](virtual-grid.md).
+