@fusion.dev/helix-headless 0.6.0 → 0.7.1

package/dist/data-table/root/data-table-root.js

@@ -5,13 +5,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessDataTable_1;
-import { customElement, HelixElement, HelixFilterEvent, HelixNavigateEvent, HelixSortEvent, hostAria, MixinCollection, requestChange, slotFilled, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, HelixFilterEvent, HelixNavigateEvent, HelixSortEvent, hostAria, MixinCollection, requestChange, slotFilled, VirtualizeController, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { html } from 'lit/static-html.js';
 import '../../pagination/index.js';
-import { cycle, format, ordered, parse } from './order.js';
+import { arranged, cycle, format, ordered, parse, window_, } from './order.js';
 let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
@@ -19,20 +19,35 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.defaultPage = 1;
         this.defaultPageSize = 0;
         this.defaultSort = '';
+        this.estimate = 32;
         this.key = '';
         this.label = '';
         this.mode = 'client';
         this.rows = [];
         this.total = 0;
+        this.windowed = false;
         this.sortState = undefined;
         this.filterState = undefined;
         this.pageState = undefined;
         this.pageSizeState = undefined;
         this.paginatedState = undefined;
+        this.virtualize = new VirtualizeController(this, {
+            container: () => this.windowed ? this.renderRoot.querySelector('[part="table"]') : null,
+            count: () => this.available,
+            estimate: () => this.estimate,
+            measured: () => this.windowed,
+            rows: () => (this.windowed ? this.drawn() : []),
+        });
         this.warnedAboutSize = false;
         this.handleSlotChange = () => {
             this.requestUpdate();
         };
+        this.measuredAgainst = '';
+        this.handleScroll = () => {
+            if (this.windowed) {
+                this.virtualize.measure();
+            }
+        };
         this.handleHeadClick = (event) => {
             const column = this.columnFrom(event);
             if (column?.canSort) {
@@ -103,6 +118,37 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.paginatedState = next;
         this.requestUpdate('paginated', previous);
     }
+    drawn() {
+        return [...this.renderRoot.querySelectorAll('[part="row"][data-index]')].map((element) => ({ element, index: Number(element.dataset.index) }));
+    }
+    get available() {
+        if (this.mode === 'server') {
+            return this.rows.length;
+        }
+        const matched = this.windowed ? this.arrange().rows.length : this.matched;
+        const size = this.pageSize;
+        if (size <= 0) {
+            return matched;
+        }
+        return Math.max(0, Math.min(size, matched - (this.page - 1) * size));
+    }
+    arrange() {
+        const axes = this.axes;
+        const key = `${this.filter}\u0000${this.sort}\u0000${axes.map((axis) => axis.field).join('\u0001')}`;
+        if (this.held?.key === key && this.held.source === this.rows) {
+            return this.held.value;
+        }
+        const value = arranged(this.rows, axes, { query: this.filter, spec: this.sort });
+        this.held = { key, source: this.rows, value };
+        return value;
+    }
+    windowOf(rows) {
+        if (!this.windowed) {
+            return rows;
+        }
+        const { first, last } = this.virtualize.window;
+        return rows.slice(first, last);
+    }
     get tableColumns() {
         return [...(this.children ?? [])].filter((child) => 'isTableColumn' in child && child.isTableColumn === true);
     }
@@ -131,16 +177,26 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
     get view() {
         if (this.mode === 'server') {
             const total = Math.max(this.total, this.rows.length);
-            return { matched: total, rows: [...this.rows], total };
+            return {
+                available: this.rows.length,
+                matched: total,
+                rows: this.windowOf([...this.rows]),
+                total,
+            };
         }
-        const view = ordered(this.rows, this.axes, {
-            page: this.page,
-            query: this.filter,
-            size: this.pageSize,
-            spec: this.sort,
-        });
-        this.warnIfCrowded(view.rows.length);
-        return view;
+        if (!this.windowed) {
+            const view = ordered(this.rows, this.axes, {
+                page: this.page,
+                query: this.filter,
+                size: this.pageSize,
+                spec: this.sort,
+            });
+            this.warnIfCrowded(view.rows.length);
+            return { ...view, available: view.rows.length };
+        }
+        const { rows: inOrder, total } = this.arrange();
+        const page = window_(inOrder, this.page, this.pageSize);
+        return { available: page.length, matched: inOrder.length, rows: this.windowOf(page), total };
     }
     get pages() {
         const size = this.pageSize;
@@ -237,6 +293,11 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label || 'Table', role: 'grid' });
+        const placement = this.placement;
+        if (changed.has('rows') || placement !== this.measuredAgainst) {
+            this.measuredAgainst = placement;
+            this.virtualize.forget();
+        }
     }
     markEmpty() {
         this.markRegion('toolbar', ['toolbar']);
@@ -253,6 +314,9 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.markEmpty();
         this.assign();
         this.announceSort();
+        if (this.windowed) {
+            this.virtualize.measure();
+        }
     }
     announceSort() {
         const current = parse(this.sort);
@@ -276,21 +340,38 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
     renderRows(rows) {
         const columns = this.tableColumns;
         const field = this.key;
-        return html `${repeat(rows, (row, index) => (field ? String(row[field] ?? index) : index), (row, index) => html `<div
+        const start = this.windowStart;
+        return html `${repeat(rows, (row, index) => (field ? String(row[field] ?? start + index) : start + index), (row, index) => html `<div
         part="row"
         role="row"
         aria-rowindex=${this.rowIndex(index)}
+        data-index=${this.windowed ? start + index : nothing}
       >
         ${columns.map((column) => this.renderCell(column, row))}
       </div>`)}`;
     }
     rowIndex(within) {
         const size = this.pageSize;
-        const offset = size > 0 ? (this.page - 1) * size : 0;
-        return offset + within + 2;
+        const page = size > 0 ? (this.page - 1) * size : 0;
+        return page + this.windowStart + within + 2;
+    }
+    get placement() {
+        return [this.mode, this.filter, this.sort, this.page, this.pageSize].join('\u0000');
+    }
+    get windowStart() {
+        return this.windowed ? this.virtualize.window.first : 0;
+    }
+    renderSpacer(end) {
+        if (!this.windowed) {
+            return nothing;
+        }
+        const { after, before } = this.virtualize.window;
+        return end === 'before'
+            ? html `<div part="before" role="presentation" style="block-size: ${before}px"></div>`
+            : html `<div part="after" role="presentation" style="block-size: ${after}px"></div>`;
     }
     render() {
-        const { matched, rows } = this.view;
+        const { available, matched, rows } = this.view;
         const template = this.template;
         const columns = this.tableColumns;
         const pagination = this.tag('pagination');
@@ -299,14 +380,16 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         part="table"
         role="rowgroup"
         aria-busy=${this.loading ? 'true' : nothing}
-        aria-rowcount=${this.mode === 'server' ? Math.max(this.total, rows.length) + 1 : matched + 1}
+        aria-rowcount=${this.mode === 'server' ? Math.max(this.total, available) + 1 : matched + 1}
         aria-colcount=${columns.length || nothing}
         style=${template ? `--data-table-template: ${template}` : nothing}
+        @scroll=${this.handleScroll}
       >
         <div part="head" role="row">
           <slot name="columns" @slotchange=${this.handleSlotChange}></slot>
         </div>
-        ${this.renderRows(rows)} ${this.renderStatus(rows.length > 0)}
+        ${this.renderSpacer('before')}${this.renderRows(rows)}${this.renderSpacer('after')}
+        ${this.renderStatus(available > 0)}
       </div>
       <div part="footer">
         <slot name="footer"></slot>
@@ -354,23 +437,26 @@ __decorate([
     property({ attribute: 'default-sort' })
 ], HelixHeadlessDataTable.prototype, "defaultSort", void 0);
 __decorate([
-    property()
-], HelixHeadlessDataTable.prototype, "key", void 0);
+    property({ type: Number })
+], HelixHeadlessDataTable.prototype, "estimate", void 0);
 __decorate([
     property()
 ], HelixHeadlessDataTable.prototype, "sort", null);
 __decorate([
     property()
-], HelixHeadlessDataTable.prototype, "label", void 0);
+], HelixHeadlessDataTable.prototype, "key", void 0);
 __decorate([
     property()
 ], HelixHeadlessDataTable.prototype, "filter", null);
 __decorate([
     property()
-], HelixHeadlessDataTable.prototype, "mode", void 0);
+], HelixHeadlessDataTable.prototype, "label", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessDataTable.prototype, "page", null);
+__decorate([
+    property()
+], HelixHeadlessDataTable.prototype, "mode", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessDataTable.prototype, "rows", void 0);
@@ -380,6 +466,9 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessDataTable.prototype, "total", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDataTable.prototype, "windowed", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessDataTable.prototype, "paginated", null);

package/dist/data-table/root/order.d.ts

@@ -92,6 +92,31 @@ export declare const sort: (rows: readonly DataRow[], spec: Sort | undefined, ax
  * same clamp `helix-pagination` already applies to what it reports.
  */
 export declare const window_: (rows: readonly DataRow[], page: number, size: number) => DataRow[];
+/** What arranging produces: the rows in order, with no page or window taken. */
+export interface Arranged {
+    /** Rows after filtering and sorting, in the order they are to be drawn. */
+    rows: DataRow[];
+    /** Rows before filtering, which is what tells a reader a filter is on. */
+    total: number;
+}
+/**
+ * Filtering and sorting, with nothing taken off the end.
+ *
+ * **Split out of `ordered` because a window moves and this does not.** A table
+ * drawing a window on a result re-renders every time a scroll reveals a row,
+ * and deriving that render from the whole result means filtering and sorting it
+ * again each time: 23.7ms at five thousand rows, a frame budget spent three
+ * times over before a cell is drawn. A caller that keeps this between renders
+ * pays it once per change to the data rather than once per frame.
+ *
+ * The two steps stay together for the reason `ordered` gives below: sorting a
+ * page is the classic bug, and one function doing both is what makes calling
+ * them in the wrong order impossible.
+ */
+export declare const arranged: (rows: readonly DataRow[], axes: readonly Axis[], { query, spec }: {
+    query: string;
+    spec: string;
+}) => Arranged;
 /** What one pass over the data produces: the window, and the counts around it. */
 export interface Ordered {
     /** Rows after filtering, before paging. The number a pagination must page. */

package/dist/data-table/root/order.js

@@ -66,8 +66,11 @@ const compare = (left, right, sign) => {
     }
     return (sign * text(left).localeCompare(text(right), undefined, { numeric: true, sensitivity: 'base' }));
 };
+export const arranged = (rows, axes, { query, spec }) => ({
+    rows: sort(filter(rows, query, axes), parse(spec), axes),
+    total: rows.length,
+});
 export const ordered = (rows, axes, { page, query, size, spec }) => {
-    const matched = filter(rows, query, axes);
-    const arranged = sort(matched, parse(spec), axes);
-    return { matched: matched.length, rows: window_(arranged, page, size), total: rows.length };
+    const { rows: inOrder, total } = arranged(rows, axes, { query, spec });
+    return { matched: inOrder.length, rows: window_(inOrder, page, size), total };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -45,14 +45,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.6.0",
-    "@fusion.dev/helix-icons": "0.6.0",
+    "@fusion.dev/helix-core": "0.7.1",
+    "@fusion.dev/helix-icons": "0.7.1",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.6.0",
-    "@fusion.dev/helix-testing": "0.6.0",
+    "@fusion.dev/helix-cem": "0.7.1",
+    "@fusion.dev/helix-testing": "0.7.1",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^3.3.0",

package/types/jsx.d.ts

@@ -3838,6 +3838,20 @@ export type HelixHeadlessDataTableProps = {
   "default-sort"?: (HelixHeadlessDataTable["defaultSort"]) | undefined;
   /** Order to open on, where nothing declared one. */
   defaultSort?: (HelixHeadlessDataTable["defaultSort"]) | undefined;
+  /** How tall a row is taken to be before it has been drawn, in pixels.
+
+Only read while `windowed`, and a starting guess rather than a claim: a
+cell that wraps makes its row taller than its neighbors, and the window
+replaces this with what each row came to as it draws. It still has to be
+close, because it is what the scrollbar is built from before anything has
+been measured. */
+  estimate?: (HelixHeadlessDataTable["estimate"]) | undefined;
+  /** The order, as `field:direction`.
+
+Set it and this element defers: a reader's click fires `helix-sort` and
+changes nothing until a new value arrives. `default-sort` seeds an order this
+element then owns. */
+  sort?: (HelixHeadlessDataTable["sort"]) | undefined;
   /** The field naming a row's stable identity.
 
 **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -3847,20 +3861,20 @@ attached to the row it belongs to. Left unset the index is the key, which is
 correct only while nothing reorders: it is why this defaults to something
 that works and is worth setting anyway. */
   key?: (HelixHeadlessDataTable["key"]) | undefined;
-  /** The order, as `field:direction`.
-
-Set it and this element defers: a reader's click fires `helix-sort` and
-changes nothing until a new value arrives. `default-sort` seeds an order this
-element then owns. */
-  sort?: (HelixHeadlessDataTable["sort"]) | undefined;
-  /** Accessible name for the grid. */
-  label?: (HelixHeadlessDataTable["label"]) | undefined;
   /** What the rows are narrowed to, as one query across every column.
 
 One query rather than a predicate per column, which is what a reader means
 by a search box above a table. It matches on each column's ordering value,
 so search and sort cannot disagree about what a column holds. */
   filter?: (HelixHeadlessDataTable["filter"]) | undefined;
+  /** Accessible name for the grid. */
+  label?: (HelixHeadlessDataTable["label"]) | undefined;
+  /** The page on show, from 1.
+
+Clamped on the way out, so what this reports is the page it drew: a
+bookmarked link to page 99 of a result that has since shrunk reads back as
+the last page rather than as 99. */
+  page?: (HelixHeadlessDataTable["page"]) | undefined;
   /** Whether this element does the work or asks the consumer to.
 
 `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -3870,12 +3884,6 @@ the client cannot hold the data, so this is not an optimization, it is the
 only mode that works, and it is here from the start because adding it later
 inverts the data flow. */
   mode?: (HelixHeadlessDataTable["mode"]) | undefined;
-  /** The page on show, from 1.
-
-Clamped on the way out, so what this reports is the page it drew: a
-bookmarked link to page 99 of a result that has since shrunk reads back as
-the last page rather than as 99. */
-  page?: (HelixHeadlessDataTable["page"]) | undefined;
   /** How many rows a page holds. Zero is every row, which is what "no paging" means.
 
 **It announces nothing, and that is not an omission.** Nothing in this
@@ -3899,6 +3907,24 @@ nothing about the result. Ignored in `client` mode rather than trusted,
 because two sources for one count is the mistake, and here the array is the
 one that cannot be stale. */
   total?: (HelixHeadlessDataTable["total"]) | undefined;
+  /** Draws the rows in view and stands empty space in for the rest.
+
+**Not a `mode`.** `mode` says where the rows come from and who filtered
+them; this says how many of the ones we hold get drawn. They are
+independent: a consumer fetching five thousand rows a chunk at a time wants
+`mode="server"` and this at once, and folding this into `mode` would be an
+API that forbids that combination for no reason.
+
+**Composes with `paginated` rather than excluding it.** A window over a
+page is coherent -- the page is the slice of the result, the window is the
+part of that slice on screen -- and the arithmetic is the same either way,
+so there is nothing to forbid. Together they suit a table paging at a
+thousand rows, where the page is a reasonable fetch and a poor render.
+
+Off by default. Windowing costs a scroll listener, a measurement per row
+drawn, and a `block-size` on the scrolling box, and a table of twenty rows
+should pay none of them. */
+  windowed?: (HelixHeadlessDataTable["windowed"]) | undefined;
   /** Whether to draw a pagination under the grid.
 
 On by default once a page size is set, because a paged table with no way to
@@ -3958,6 +3984,20 @@ export type HelixHeadlessDataTableSolidJsProps = {
   "attr:default-sort"?: (HelixHeadlessDataTable["defaultSort"]) | undefined;
   /** Order to open on, where nothing declared one. */
   "prop:defaultSort"?: (HelixHeadlessDataTable["defaultSort"]) | undefined;
+  /** How tall a row is taken to be before it has been drawn, in pixels.
+
+Only read while `windowed`, and a starting guess rather than a claim: a
+cell that wraps makes its row taller than its neighbors, and the window
+replaces this with what each row came to as it draws. It still has to be
+close, because it is what the scrollbar is built from before anything has
+been measured. */
+  "prop:estimate"?: (HelixHeadlessDataTable["estimate"]) | undefined;
+  /** The order, as `field:direction`.
+
+Set it and this element defers: a reader's click fires `helix-sort` and
+changes nothing until a new value arrives. `default-sort` seeds an order this
+element then owns. */
+  "prop:sort"?: (HelixHeadlessDataTable["sort"]) | undefined;
   /** The field naming a row's stable identity.
 
 **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -3967,20 +4007,20 @@ attached to the row it belongs to. Left unset the index is the key, which is
 correct only while nothing reorders: it is why this defaults to something
 that works and is worth setting anyway. */
   "prop:key"?: (HelixHeadlessDataTable["key"]) | undefined;
-  /** The order, as `field:direction`.
-
-Set it and this element defers: a reader's click fires `helix-sort` and
-changes nothing until a new value arrives. `default-sort` seeds an order this
-element then owns. */
-  "prop:sort"?: (HelixHeadlessDataTable["sort"]) | undefined;
-  /** Accessible name for the grid. */
-  "prop:label"?: (HelixHeadlessDataTable["label"]) | undefined;
   /** What the rows are narrowed to, as one query across every column.
 
 One query rather than a predicate per column, which is what a reader means
 by a search box above a table. It matches on each column's ordering value,
 so search and sort cannot disagree about what a column holds. */
   "prop:filter"?: (HelixHeadlessDataTable["filter"]) | undefined;
+  /** Accessible name for the grid. */
+  "prop:label"?: (HelixHeadlessDataTable["label"]) | undefined;
+  /** The page on show, from 1.
+
+Clamped on the way out, so what this reports is the page it drew: a
+bookmarked link to page 99 of a result that has since shrunk reads back as
+the last page rather than as 99. */
+  "prop:page"?: (HelixHeadlessDataTable["page"]) | undefined;
   /** Whether this element does the work or asks the consumer to.
 
 `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -3990,12 +4030,6 @@ the client cannot hold the data, so this is not an optimization, it is the
 only mode that works, and it is here from the start because adding it later
 inverts the data flow. */
   "prop:mode"?: (HelixHeadlessDataTable["mode"]) | undefined;
-  /** The page on show, from 1.
-
-Clamped on the way out, so what this reports is the page it drew: a
-bookmarked link to page 99 of a result that has since shrunk reads back as
-the last page rather than as 99. */
-  "prop:page"?: (HelixHeadlessDataTable["page"]) | undefined;
   /** How many rows a page holds. Zero is every row, which is what "no paging" means.
 
 **It announces nothing, and that is not an omission.** Nothing in this
@@ -4019,6 +4053,24 @@ nothing about the result. Ignored in `client` mode rather than trusted,
 because two sources for one count is the mistake, and here the array is the
 one that cannot be stale. */
   "prop:total"?: (HelixHeadlessDataTable["total"]) | undefined;
+  /** Draws the rows in view and stands empty space in for the rest.
+
+**Not a `mode`.** `mode` says where the rows come from and who filtered
+them; this says how many of the ones we hold get drawn. They are
+independent: a consumer fetching five thousand rows a chunk at a time wants
+`mode="server"` and this at once, and folding this into `mode` would be an
+API that forbids that combination for no reason.
+
+**Composes with `paginated` rather than excluding it.** A window over a
+page is coherent -- the page is the slice of the result, the window is the
+part of that slice on screen -- and the arithmetic is the same either way,
+so there is nothing to forbid. Together they suit a table paging at a
+thousand rows, where the page is a reasonable fetch and a poor render.
+
+Off by default. Windowing costs a scroll listener, a measurement per row
+drawn, and a `block-size` on the scrolling box, and a table of twenty rows
+should pay none of them. */
+  "prop:windowed"?: (HelixHeadlessDataTable["windowed"]) | undefined;
   /** Whether to draw a pagination under the grid.
 
 On by default once a page size is set, because a paged table with no way to
@@ -18758,6 +18810,18 @@ export type CustomElements = {
    * - `default-page`/`defaultPage`: Page to open on, where nothing declared one.
    * - `default-page-size`/`defaultPageSize`: Page size to open with, where nothing declared one.
    * - `default-sort`/`defaultSort`: Order to open on, where nothing declared one.
+   * - `estimate`: How tall a row is taken to be before it has been drawn, in pixels.
+   *
+   * Only read while `windowed`, and a starting guess rather than a claim: a
+   * cell that wraps makes its row taller than its neighbors, and the window
+   * replaces this with what each row came to as it draws. It still has to be
+   * close, because it is what the scrollbar is built from before anything has
+   * been measured.
+   * - `sort`: The order, as `field:direction`.
+   *
+   * Set it and this element defers: a reader's click fires `helix-sort` and
+   * changes nothing until a new value arrives. `default-sort` seeds an order this
+   * element then owns.
    * - `key`: The field naming a row's stable identity.
    *
    * **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -18766,17 +18830,17 @@ export type CustomElements = {
    * attached to the row it belongs to. Left unset the index is the key, which is
    * correct only while nothing reorders: it is why this defaults to something
    * that works and is worth setting anyway.
-   * - `sort`: The order, as `field:direction`.
-   *
-   * Set it and this element defers: a reader's click fires `helix-sort` and
-   * changes nothing until a new value arrives. `default-sort` seeds an order this
-   * element then owns.
-   * - `label`: Accessible name for the grid.
    * - `filter`: What the rows are narrowed to, as one query across every column.
    *
    * One query rather than a predicate per column, which is what a reader means
    * by a search box above a table. It matches on each column's ordering value,
    * so search and sort cannot disagree about what a column holds.
+   * - `label`: Accessible name for the grid.
+   * - `page`: The page on show, from 1.
+   *
+   * Clamped on the way out, so what this reports is the page it drew: a
+   * bookmarked link to page 99 of a result that has since shrunk reads back as
+   * the last page rather than as 99.
    * - `mode`: Whether this element does the work or asks the consumer to.
    *
    * `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -18785,11 +18849,6 @@ export type CustomElements = {
    * the client cannot hold the data, so this is not an optimization, it is the
    * only mode that works, and it is here from the start because adding it later
    * inverts the data flow.
-   * - `page`: The page on show, from 1.
-   *
-   * Clamped on the way out, so what this reports is the page it drew: a
-   * bookmarked link to page 99 of a result that has since shrunk reads back as
-   * the last page rather than as 99.
    * - `page-size`/`pageSize`: How many rows a page holds. Zero is every row, which is what "no paging" means.
    *
    * **It announces nothing, and that is not an omission.** Nothing in this
@@ -18803,6 +18862,23 @@ export type CustomElements = {
    * nothing about the result. Ignored in `client` mode rather than trusted,
    * because two sources for one count is the mistake, and here the array is the
    * one that cannot be stale.
+   * - `windowed`: Draws the rows in view and stands empty space in for the rest.
+   *
+   * **Not a `mode`.** `mode` says where the rows come from and who filtered
+   * them; this says how many of the ones we hold get drawn. They are
+   * independent: a consumer fetching five thousand rows a chunk at a time wants
+   * `mode="server"` and this at once, and folding this into `mode` would be an
+   * API that forbids that combination for no reason.
+   *
+   * **Composes with `paginated` rather than excluding it.** A window over a
+   * page is coherent -- the page is the slice of the result, the window is the
+   * part of that slice on screen -- and the arithmetic is the same either way,
+   * so there is nothing to forbid. Together they suit a table paging at a
+   * thousand rows, where the page is a reasonable fetch and a poor render.
+   *
+   * Off by default. Windowing costs a scroll listener, a measurement per row
+   * drawn, and a `block-size` on the scrolling box, and a table of twenty rows
+   * should pay none of them.
    * - `paginated`: Whether to draw a pagination under the grid.
    *
    * On by default once a page size is set, because a paged table with no way to
@@ -18885,6 +18961,8 @@ export type CustomElements = {
    *
    * Custom selectors for styling elements within the component.
    *
+   * - `after`: The room the rows below the window would have taken. Windowed only.
+   * - `before`: The room the rows above the window would have taken. Windowed only.
    * - `cell`: One cell.
    * - `empty`: Shown when no rows match.
    * - `footer`: The region below the grid.
@@ -32967,6 +33045,18 @@ export type CustomElementsSolidJs = {
    * - `default-page`/`defaultPage`: Page to open on, where nothing declared one.
    * - `default-page-size`/`defaultPageSize`: Page size to open with, where nothing declared one.
    * - `default-sort`/`defaultSort`: Order to open on, where nothing declared one.
+   * - `estimate`: How tall a row is taken to be before it has been drawn, in pixels.
+   *
+   * Only read while `windowed`, and a starting guess rather than a claim: a
+   * cell that wraps makes its row taller than its neighbors, and the window
+   * replaces this with what each row came to as it draws. It still has to be
+   * close, because it is what the scrollbar is built from before anything has
+   * been measured.
+   * - `sort`: The order, as `field:direction`.
+   *
+   * Set it and this element defers: a reader's click fires `helix-sort` and
+   * changes nothing until a new value arrives. `default-sort` seeds an order this
+   * element then owns.
    * - `key`: The field naming a row's stable identity.
    *
    * **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -32975,17 +33065,17 @@ export type CustomElementsSolidJs = {
    * attached to the row it belongs to. Left unset the index is the key, which is
    * correct only while nothing reorders: it is why this defaults to something
    * that works and is worth setting anyway.
-   * - `sort`: The order, as `field:direction`.
-   *
-   * Set it and this element defers: a reader's click fires `helix-sort` and
-   * changes nothing until a new value arrives. `default-sort` seeds an order this
-   * element then owns.
-   * - `label`: Accessible name for the grid.
    * - `filter`: What the rows are narrowed to, as one query across every column.
    *
    * One query rather than a predicate per column, which is what a reader means
    * by a search box above a table. It matches on each column's ordering value,
    * so search and sort cannot disagree about what a column holds.
+   * - `label`: Accessible name for the grid.
+   * - `page`: The page on show, from 1.
+   *
+   * Clamped on the way out, so what this reports is the page it drew: a
+   * bookmarked link to page 99 of a result that has since shrunk reads back as
+   * the last page rather than as 99.
    * - `mode`: Whether this element does the work or asks the consumer to.
    *
    * `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -32994,11 +33084,6 @@ export type CustomElementsSolidJs = {
    * the client cannot hold the data, so this is not an optimization, it is the
    * only mode that works, and it is here from the start because adding it later
    * inverts the data flow.
-   * - `page`: The page on show, from 1.
-   *
-   * Clamped on the way out, so what this reports is the page it drew: a
-   * bookmarked link to page 99 of a result that has since shrunk reads back as
-   * the last page rather than as 99.
    * - `page-size`/`pageSize`: How many rows a page holds. Zero is every row, which is what "no paging" means.
    *
    * **It announces nothing, and that is not an omission.** Nothing in this
@@ -33012,6 +33097,23 @@ export type CustomElementsSolidJs = {
    * nothing about the result. Ignored in `client` mode rather than trusted,
    * because two sources for one count is the mistake, and here the array is the
    * one that cannot be stale.
+   * - `windowed`: Draws the rows in view and stands empty space in for the rest.
+   *
+   * **Not a `mode`.** `mode` says where the rows come from and who filtered
+   * them; this says how many of the ones we hold get drawn. They are
+   * independent: a consumer fetching five thousand rows a chunk at a time wants
+   * `mode="server"` and this at once, and folding this into `mode` would be an
+   * API that forbids that combination for no reason.
+   *
+   * **Composes with `paginated` rather than excluding it.** A window over a
+   * page is coherent -- the page is the slice of the result, the window is the
+   * part of that slice on screen -- and the arithmetic is the same either way,
+   * so there is nothing to forbid. Together they suit a table paging at a
+   * thousand rows, where the page is a reasonable fetch and a poor render.
+   *
+   * Off by default. Windowing costs a scroll listener, a measurement per row
+   * drawn, and a `block-size` on the scrolling box, and a table of twenty rows
+   * should pay none of them.
    * - `paginated`: Whether to draw a pagination under the grid.
    *
    * On by default once a page size is set, because a paged table with no way to
@@ -33094,6 +33196,8 @@ export type CustomElementsSolidJs = {
    *
    * Custom selectors for styling elements within the component.
    *
+   * - `after`: The room the rows below the window would have taken. Windowed only.
+   * - `before`: The room the rows above the window would have taken. Windowed only.
    * - `cell`: One cell.
    * - `empty`: Shown when no rows match.
    * - `footer`: The region below the grid.