@lumiose/ui 0.1.2 → 0.2.0

package/docs/llms.txt

@@ -12,6 +12,7 @@ props, events and styling hooks. The Lumiose docs: `node_modules/lumiose/docs/ll
 - [UI components](README.md): `@lumiose/ui`: accessible, unstyled UI primitives built on native elements (`<dialog>`, popover, invoker commands, CSS anchor positioning), server-rendered without hydration. Style them with your own CSS or the optional default theme.
 - [Installation](installation.md): Add `@lumiose/ui` to a Lumiose app and import its stylesheets, and the default theme if you want its look. The components then render in server HTML, without an island, and a page loads only the small scripts of the components it renders.
 - [Theming](theming.md): `@lumiose/ui` is unstyled: its stylesheets hold only what the components need to work. The optional default theme gives them a look, light and dark, through `--lu-` custom properties you can change; or style the parts with your own CSS.
+- [Virtualizer](virtualizer.md): 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 Grid or Virtual Table, which run on it.
 
 ## Components
 
@@ -51,3 +52,6 @@ props, events and styling hooks. The Lumiose docs: `node_modules/lumiose/docs/ll
 - [Toggle Group](toggle-group.md): A set of Toggles with one value, after Base UI's ToggleGroup: text alignment (one pressed at a time) or text style (several). `<lu-toggle-group role="group">` presses its toggles and gives the group one tab stop that the arrow keys, Home and End move, following the orientation and the direction, on server pages and in islands. `bind:value` keeps a signal in sync.
 - [Toolbar](toolbar.md): A set of controls with one tab stop, after Base UI's Toolbar and the APG toolbar pattern: `<lu-toolbar role="toolbar">` moves focus between its items with the arrow keys, Home and End, following the orientation and the text direction. Its items are native: buttons that stay focusable when disabled, links, inputs, and the toggles of a Toggle Group inside it. In the server HTML every item is a tab stop, so each is reachable without JavaScript; a 1.2 kB script makes them one tab stop and moves it.
 - [Tooltip](tooltip.md): A short tip next to its trigger, on hover or keyboard focus: a native `popover="hint"` with `role="tooltip"`, placed with CSS anchor positioning. The trigger is described by the tip in server HTML, so screen readers announce it without hovering; a 2.1 kB script opens and closes it as Base UI's tooltip does. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+- [Virtual Grid](virtual-grid.md): 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. 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.
+- [Virtual List](virtual-list.md): A long list that renders only the rows near the viewport, in islands: a `<ul>` whose rows are `<li>`s placed by createVirtualizer, 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.
+- [Virtual Table](virtual-table.md): 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. 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.

package/docs/virtual-grid.md

@@ -0,0 +1,136 @@
+# 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).

package/docs/virtual-list.md

@@ -0,0 +1,121 @@
+# 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).

package/docs/virtual-table.md

@@ -0,0 +1,142 @@
+# 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).