@fusion.dev/helix-headless 0.6.0 → 0.7.0

package/custom-elements.json

@@ -17182,6 +17182,14 @@
             }
           ],
           "cssParts": [
+            {
+              "description": "The room the rows below the window would have taken. Windowed only.",
+              "name": "after"
+            },
+            {
+              "description": "The room the rows above the window would have taken. Windowed only.",
+              "name": "before"
+            },
             {
               "description": "One cell.",
               "name": "cell"
@@ -17286,13 +17294,13 @@
             },
             {
               "kind": "field",
-              "name": "key",
+              "name": "estimate",
               "type": {
-                "text": "string"
+                "text": "number"
               },
-              "default": "''",
-              "description": "The field naming a row's stable identity.\n\n**Needed before selection exists, not after.** Lit keys the rendered rows by\nit, so a sort moves a row's element rather than rewriting every cell in\nplace, which is what keeps focus inside a cell and keeps a CSS transition\nattached to the row it belongs to. Left unset the index is the key, which is\ncorrect only while nothing reorders: it is why this defaults to something\nthat works and is worth setting anyway.",
-              "attribute": "key"
+              "default": "32",
+              "description": "How tall a row is taken to be before it has been drawn, in pixels.\n\nOnly read while `windowed`, and a starting guess rather than a claim: a\ncell that wraps makes its row taller than its neighbors, and the window\nreplaces this with what each row came to as it draws. It still has to be\nclose, because it is what the scrollbar is built from before anything has\nbeen measured.",
+              "attribute": "estimate"
             },
             {
               "kind": "field",
@@ -17305,13 +17313,13 @@
             },
             {
               "kind": "field",
-              "name": "label",
+              "name": "key",
               "type": {
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible name for the grid.",
-              "attribute": "label"
+              "description": "The field naming a row's stable identity.\n\n**Needed before selection exists, not after.** Lit keys the rendered rows by\nit, so a sort moves a row's element rather than rewriting every cell in\nplace, which is what keeps focus inside a cell and keeps a CSS transition\nattached to the row it belongs to. Left unset the index is the key, which is\ncorrect only while nothing reorders: it is why this defaults to something\nthat works and is worth setting anyway.",
+              "attribute": "key"
             },
             {
               "kind": "field",
@@ -17324,13 +17332,13 @@
             },
             {
               "kind": "field",
-              "name": "mode",
+              "name": "label",
               "type": {
-                "text": "'client' | 'server'"
+                "text": "string"
               },
-              "default": "'client'",
-              "description": "Whether this element does the work or asks the consumer to.\n\n`client` filters, sorts and pages `rows` itself. `server` applies none of\nthem: `rows` is the page, `total` is the size of the whole result, and the\nthree events are requests the consumer answers by fetching. Past some size\nthe client cannot hold the data, so this is not an optimization, it is the\nonly mode that works, and it is here from the start because adding it later\ninverts the data flow.",
-              "attribute": "mode"
+              "default": "''",
+              "description": "Accessible name for the grid.",
+              "attribute": "label"
             },
             {
               "kind": "field",
@@ -17341,6 +17349,16 @@
               "description": "The page on show, from 1.\n\nClamped on the way out, so what this reports is the page it drew: a\nbookmarked link to page 99 of a result that has since shrunk reads back as\nthe last page rather than as 99.",
               "attribute": "page"
             },
+            {
+              "kind": "field",
+              "name": "mode",
+              "type": {
+                "text": "'client' | 'server'"
+              },
+              "default": "'client'",
+              "description": "Whether this element does the work or asks the consumer to.\n\n`client` filters, sorts and pages `rows` itself. `server` applies none of\nthem: `rows` is the page, `total` is the size of the whole result, and the\nthree events are requests the consumer answers by fetching. Past some size\nthe client cannot hold the data, so this is not an optimization, it is the\nonly mode that works, and it is here from the start because adding it later\ninverts the data flow.",
+              "attribute": "mode"
+            },
             {
               "kind": "field",
               "name": "rows",
@@ -17369,6 +17387,17 @@
               "description": "How many rows the whole result has, where this element cannot count them.\n\nOnly read in `server` mode, where `rows` is one page and its length says\nnothing about the result. Ignored in `client` mode rather than trusted,\nbecause two sources for one count is the mistake, and here the array is the\none that cannot be stale.",
               "attribute": "total"
             },
+            {
+              "kind": "field",
+              "name": "windowed",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Draws the rows in view and stands empty space in for the rest.\n\n**Not a `mode`.** `mode` says where the rows come from and who filtered\nthem; this says how many of the ones we hold get drawn. They are\nindependent: a consumer fetching five thousand rows a chunk at a time wants\n`mode=\"server\"` and this at once, and folding this into `mode` would be an\nAPI that forbids that combination for no reason.\n\n**Composes with `paginated` rather than excluding it.** A window over a\npage is coherent -- the page is the slice of the result, the window is the\npart of that slice on screen -- and the arithmetic is the same either way,\nso there is nothing to forbid. Together they suit a table paging at a\nthousand rows, where the page is a reasonable fetch and a poor render.\n\nOff by default. Windowing costs a scroll listener, a measurement per row\ndrawn, and a `block-size` on the scrolling box, and a table of twenty rows\nshould pay none of them.",
+              "attribute": "windowed",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "paginated",
@@ -17423,6 +17452,72 @@
               "privacy": "private",
               "default": "undefined"
             },
+            {
+              "kind": "field",
+              "name": "virtualize",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new VirtualizeController(this, { /* Null while `windowed` is off, which is what keeps the controller inert rather than conditionally constructed: a controller is built once and this property can change at runtime. */ container: () => this.windowed ? this.renderRoot.querySelector<HTMLElement>('[part=\"table\"]') : null, count: () => this.available, estimate: () => this.estimate, /* Always measured when windowing at all. The uniform path converts offset to index by division and is right when rows are one height; a grid whose cells wrap is the case it is wrong for. */ measured: () => this.windowed, rows: () => (this.windowed ? this.drawn() : []), })"
+            },
+            {
+              "kind": "method",
+              "name": "drawn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ element: HTMLElement; index: number }[]"
+                }
+              },
+              "description": "The rows in the shadow tree, each with the row of the page it drew.\n\n**Read off `data-index` rather than counted.** `hostUpdated` runs before\n`updated`, so what is in the tree when the controller asks is the previous\nwindow; counting from the current one would record the right heights\nagainst the wrong rows every time the window moved."
+            },
+            {
+              "kind": "field",
+              "name": "available",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "description": "How many rows there are to window over: the page, or the result.\n\n**Read off the held arrangement rather than counted afresh**, because the\ncontroller asks this on every scroll and `matched` walks the whole result\nwhenever a filter is on. Held, a scroll through a filtered table of five\nthousand rows costs a lookup; counted, it costs five thousand comparisons a\nframe, which is the cost windowing was added to avoid.\n\n`matched` still answers where nothing is windowing, which is the path that\nholds nothing and should not start.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "held",
+              "type": {
+                "text": "{ key: string; source: readonly DataRow[]; value: Arranged } | undefined"
+              },
+              "privacy": "private",
+              "description": "The arranged result, kept between renders.\n\n**A window moves and the order does not.** Every scroll that reveals a row\nre-renders, and deriving that render from `rows` would filter and sort the\nwhole result again each time: 23.7ms at five thousand rows, three frames\nspent before a cell is drawn. Held against the inputs that change it, a\nscroll costs a slice.\n\nOnly the windowed path uses this. A paged table re-renders when the reader\nasks for a page, which is rare enough that holding a second copy of the\nresult to save a sort is the wrong trade."
+            },
+            {
+              "kind": "method",
+              "name": "arrange",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Arranged"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "windowOf",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "DataRow[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "rows",
+                  "type": {
+                    "text": "DataRow[]"
+                  }
+                }
+              ],
+              "description": "The part of a page the reader can see, which is every row when not windowed."
+            },
             {
               "kind": "field",
               "name": "tableColumns",
@@ -17491,13 +17586,13 @@
                   }
                 }
               ],
-              "description": "Says so when a table is asked to draw more than it comfortably can.\n\n**The component renders every row it is given and defaults to doing so.**\n`defaultPageSize` is `0`, so `paginated` is false unless a consumer asks,\nwhich means the out-of-the-box arrangement is the unbounded one and nothing\nabout it says that a result of any size will simply be drawn.\n\n**Windowing was refused**, which is worth recording because it is the\nobvious answer. This element already has two mechanisms: `paginated` with a\n`page-size`, and `mode=\"server\"` where `rows` is one page, `total` is the\nwhole result and `aria-rowcount` already reports the result rather than the\nwindow, which is the hard half of virtualization done correctly. A third\nwould fight the first two, and virtualizing a grid means variable row\nheights, a sticky header and keeping `aria-rowindex` honest against a result\nthe element is no longer holding. `VirtualizeController` exists for the case\nwhere the rows are a flat list and this is not that.\n\nWarned once per element, in a browser only: a warning during a server render\nis one nobody can act on and one that would print per request."
+              "description": "Says so when a table is asked to draw more than it comfortably can.\n\n**The component renders every row it is given and defaults to doing so.**\n`defaultPageSize` is `0`, so `paginated` is false unless a consumer asks,\nwhich means the out-of-the-box arrangement is the unbounded one and nothing\nabout it says that a result of any size will simply be drawn.\n\n**Windowing was refused here, and is now `windowed`.** The refusal is kept\nbecause most of it was right, and because what changed is not that somebody\ndisagreed with it. It rested on four claims: that a third mechanism would\nfight `paginated` and `mode=\"server\"`; that a grid has rows of different\nheights; that it needs a sticky header; and that `aria-rowindex` has to keep\ndescribing a result the element no longer holds in full.\n\nThree stopped being true. `VirtualizeController` learnt to measure each row\nand place the next by what the one above came to, which is the variable\nheights. `aria-rowindex` was already result-relative because paging needed\nit, so a window is a second offset on arithmetic that existed. And the\nsticky header is one `position: sticky` on the heading cells rather than on\n`[part=\"head\"]`, which is `display: contents` and generates no box to stick\n-- that is why it looked hard and is not.\n\nThe first was avoided rather than answered. `windowed` is not a `mode` and\ndoes not exclude `paginated`: it says how much of what we hold gets drawn,\nwhere `mode` says where it came from, so there is no third axis to fight the\nother two. What survives is the cost, which is why windowing is off by\ndefault and why this warning still fires for a table that has none of them.\n\nWarned once per element, in a browser only: a warning during a server render\nis one nobody can act on and one that would print per request."
             },
             {
               "kind": "field",
               "name": "view",
               "type": {
-                "text": "{ matched: number; rows: DataRow[]; total: number }"
+                "text": "{\n    available: number\n    matched: number\n    rows: DataRow[]\n    total: number\n  }"
               },
               "privacy": "private",
               "description": "The rows to draw, and the counts around them.\n\nIn `server` mode this element applies nothing: `rows` is already the page,\n`total` is the result, and both counts come from the consumer. Anything else\nwould be this element filtering a page it was handed, which narrows one\nscreen and calls it a search.",
@@ -17767,7 +17862,63 @@
                   }
                 }
               ],
-              "description": "A row's place in the whole result, counting the header as row 1.\n\n**The number describes the result and not the window**, which is the whole\nreason a virtualized or paged grid needs `aria-rowindex` at all: a screen\nreader on page three should hear row 41, and a grid whose indices restart at\nevery page tells a reader the result is twenty rows long however many it has."
+              "description": "A row's place in the whole result, counting the header as row 1.\n\n**The number describes the result and not the window**, which is the whole\nreason a virtualized or paged grid needs `aria-rowindex` at all: a screen\nreader on page three should hear row 41, and a grid whose indices restart at\nevery page tells a reader the result is twenty rows long however many it has.\n\nA window is the second offset and stacks on the page: with both on, row one\nof the window is the page's start plus how far down the page it begins."
+            },
+            {
+              "kind": "field",
+              "name": "placement",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "description": "What decides which row is at which index, as one comparable value.\n\nNot the rows themselves: those are compared by identity beside this, and a\nconsumer handing back an equal array is handing back the same rows in the\nsame order whatever object it is.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "measuredAgainst",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "The signature the recorded heights were measured against."
+            },
+            {
+              "kind": "field",
+              "name": "windowStart",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "description": "Where the window begins in the page, which is the top when there is none.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "renderSpacer",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "end",
+                  "type": {
+                    "text": "'after' | 'before'"
+                  }
+                }
+              ],
+              "description": "The room the rows outside the window would have taken.\n\n**`role=\"presentation\"`, because this is geometry standing inside a\n`rowgroup`.** A bare `div` there is a child the role does not allow, and a\nscreen reader walking the rows would meet something that is not one. The\nroom itself is what keeps the scrollbar honest: a box that scrolls twenty\nrows while claiming ten thousand gives a thumb the size of its track."
+            },
+            {
+              "kind": "field",
+              "name": "handleScroll",
+              "privacy": "private",
+              "readonly": true,
+              "description": "The controller owns the geometry; this is only what tells it to look again."
             },
             {
               "kind": "field",
@@ -18163,13 +18314,13 @@
               "fieldName": "defaultSort"
             },
             {
-              "name": "key",
+              "name": "estimate",
               "type": {
-                "text": "string"
+                "text": "number"
               },
-              "default": "''",
-              "description": "The field naming a row's stable identity.\n\n**Needed before selection exists, not after.** Lit keys the rendered rows by\nit, so a sort moves a row's element rather than rewriting every cell in\nplace, which is what keeps focus inside a cell and keeps a CSS transition\nattached to the row it belongs to. Left unset the index is the key, which is\ncorrect only while nothing reorders: it is why this defaults to something\nthat works and is worth setting anyway.",
-              "fieldName": "key"
+              "default": "32",
+              "description": "How tall a row is taken to be before it has been drawn, in pixels.\n\nOnly read while `windowed`, and a starting guess rather than a claim: a\ncell that wraps makes its row taller than its neighbors, and the window\nreplaces this with what each row came to as it draws. It still has to be\nclose, because it is what the scrollbar is built from before anything has\nbeen measured.",
+              "fieldName": "estimate"
             },
             {
               "name": "sort",
@@ -18180,13 +18331,13 @@
               "fieldName": "sort"
             },
             {
-              "name": "label",
+              "name": "key",
               "type": {
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible name for the grid.",
-              "fieldName": "label"
+              "description": "The field naming a row's stable identity.\n\n**Needed before selection exists, not after.** Lit keys the rendered rows by\nit, so a sort moves a row's element rather than rewriting every cell in\nplace, which is what keeps focus inside a cell and keeps a CSS transition\nattached to the row it belongs to. Left unset the index is the key, which is\ncorrect only while nothing reorders: it is why this defaults to something\nthat works and is worth setting anyway.",
+              "fieldName": "key"
             },
             {
               "name": "filter",
@@ -18197,13 +18348,13 @@
               "fieldName": "filter"
             },
             {
-              "name": "mode",
+              "name": "label",
               "type": {
-                "text": "'client' | 'server'"
+                "text": "string"
               },
-              "default": "'client'",
-              "description": "Whether this element does the work or asks the consumer to.\n\n`client` filters, sorts and pages `rows` itself. `server` applies none of\nthem: `rows` is the page, `total` is the size of the whole result, and the\nthree events are requests the consumer answers by fetching. Past some size\nthe client cannot hold the data, so this is not an optimization, it is the\nonly mode that works, and it is here from the start because adding it later\ninverts the data flow.",
-              "fieldName": "mode"
+              "default": "''",
+              "description": "Accessible name for the grid.",
+              "fieldName": "label"
             },
             {
               "name": "page",
@@ -18213,6 +18364,15 @@
               "description": "The page on show, from 1.\n\nClamped on the way out, so what this reports is the page it drew: a\nbookmarked link to page 99 of a result that has since shrunk reads back as\nthe last page rather than as 99.",
               "fieldName": "page"
             },
+            {
+              "name": "mode",
+              "type": {
+                "text": "'client' | 'server'"
+              },
+              "default": "'client'",
+              "description": "Whether this element does the work or asks the consumer to.\n\n`client` filters, sorts and pages `rows` itself. `server` applies none of\nthem: `rows` is the page, `total` is the size of the whole result, and the\nthree events are requests the consumer answers by fetching. Past some size\nthe client cannot hold the data, so this is not an optimization, it is the\nonly mode that works, and it is here from the start because adding it later\ninverts the data flow.",
+              "fieldName": "mode"
+            },
             {
               "name": "page-size",
               "type": {
@@ -18230,6 +18390,15 @@
               "description": "How many rows the whole result has, where this element cannot count them.\n\nOnly read in `server` mode, where `rows` is one page and its length says\nnothing about the result. Ignored in `client` mode rather than trusted,\nbecause two sources for one count is the mistake, and here the array is the\none that cannot be stale.",
               "fieldName": "total"
             },
+            {
+              "name": "windowed",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Draws the rows in view and stands empty space in for the rest.\n\n**Not a `mode`.** `mode` says where the rows come from and who filtered\nthem; this says how many of the ones we hold get drawn. They are\nindependent: a consumer fetching five thousand rows a chunk at a time wants\n`mode=\"server\"` and this at once, and folding this into `mode` would be an\nAPI that forbids that combination for no reason.\n\n**Composes with `paginated` rather than excluding it.** A window over a\npage is coherent -- the page is the slice of the result, the window is the\npart of that slice on screen -- and the arithmetic is the same either way,\nso there is nothing to forbid. Together they suit a table paging at a\nthousand rows, where the page is a reasonable fetch and a poor render.\n\nOff by default. Windowing costs a scroll listener, a measurement per row\ndrawn, and a `block-size` on the scrolling box, and a table of twenty rows\nshould pay none of them.",
+              "fieldName": "windowed"
+            },
             {
               "name": "paginated",
               "type": {
@@ -18490,6 +18659,36 @@
           ],
           "description": "One page of rows, clamped.\n\nA page past the end returns the last page rather than nothing, because the\nusual way to be past the end is a bookmarked link after the result shrank, and\nan empty table is a worse answer than the last page of a smaller one. The\nsame clamp `helix-pagination` already applies to what it reports."
         },
+        {
+          "kind": "function",
+          "name": "arranged",
+          "return": {
+            "type": {
+              "text": "Arranged"
+            }
+          },
+          "parameters": [
+            {
+              "name": "rows",
+              "type": {
+                "text": "readonly DataRow[]"
+              }
+            },
+            {
+              "name": "axes",
+              "type": {
+                "text": "readonly Axis[]"
+              }
+            },
+            {
+              "name": "{ query, spec }",
+              "type": {
+                "text": "{ query: string; spec: string }"
+              }
+            }
+          ],
+          "description": "Filtering and sorting, with nothing taken off the end.\n\n**Split out of `ordered` because a window moves and this does not.** A table\ndrawing a window on a result re-renders every time a scroll reveals a row,\nand deriving that render from the whole result means filtering and sorting it\nagain each time: 23.7ms at five thousand rows, a frame budget spent three\ntimes over before a cell is drawn. A caller that keeps this between renders\npays it once per change to the data rather than once per frame.\n\nThe two steps stay together for the reason `ordered` gives below: sorting a\npage is the classic bug, and one function doing both is what makes calling\nthem in the wrong order impossible."
+        },
         {
           "kind": "function",
           "name": "ordered",
@@ -18570,6 +18769,14 @@
             "module": "src/data-table/root/order.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "arranged",
+          "declaration": {
+            "name": "arranged",
+            "module": "src/data-table/root/order.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "ordered",

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

@@ -46,6 +46,8 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * @event {HelixNavigateEvent} helix-navigate - Fired when a reader asks for another page, and cancelable.
  * @event {HelixSortEvent} helix-sort - Fired when a reader asks for a different order, and cancelable.
  *
+ * @csspart after - The room the rows below the window would have taken. Windowed only.
+ * @csspart before - The room the rows above the window would have taken. Windowed only.
  * @csspart cell - One cell.
  * @csspart empty - Shown when no rows match.
  * @csspart footer - The region below the grid.
@@ -86,16 +88,15 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     defaultSort: string;
     /**
-     * The field naming a row's stable identity.
+     * How tall a row is taken to be before it has been drawn, in pixels.
      *
-     * **Needed before selection exists, not after.** Lit keys the rendered rows by
-     * it, so a sort moves a row's element rather than rewriting every cell in
-     * place, which is what keeps focus inside a cell and keeps a CSS transition
-     * 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.
+     * 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.
      */
-    key: string;
+    estimate: number;
     /**
      * The order, as `field:direction`.
      *
@@ -106,9 +107,16 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get sort(): string;
     set sort(next: string);
     /**
-     * Accessible name for the grid.
+     * The field naming a row's stable identity.
+     *
+     * **Needed before selection exists, not after.** Lit keys the rendered rows by
+     * it, so a sort moves a row's element rather than rewriting every cell in
+     * place, which is what keeps focus inside a cell and keeps a CSS transition
+     * 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.
      */
-    label: string;
+    key: string;
     /**
      * What the rows are narrowed to, as one query across every column.
      *
@@ -119,16 +127,9 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get filter(): string;
     set filter(next: string);
     /**
-     * Whether this element does the work or asks the consumer to.
-     *
-     * `client` filters, sorts and pages `rows` itself. `server` applies none of
-     * them: `rows` is the page, `total` is the size of the whole result, and the
-     * three events are requests the consumer answers by fetching. Past some size
-     * 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.
+     * Accessible name for the grid.
      */
-    mode: 'client' | 'server';
+    label: string;
     /**
      * The page on show, from 1.
      *
@@ -138,6 +139,17 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     get page(): number;
     set page(next: number);
+    /**
+     * Whether this element does the work or asks the consumer to.
+     *
+     * `client` filters, sorts and pages `rows` itself. `server` applies none of
+     * them: `rows` is the page, `total` is the size of the whole result, and the
+     * three events are requests the consumer answers by fetching. Past some size
+     * 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: 'client' | 'server';
     /**
      * The whole result, in the order it arrived.
      *
@@ -170,6 +182,26 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * one that cannot be stale.
      */
     total: number;
+    /**
+     * 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: boolean;
     /**
      * Whether to draw a pagination under the grid.
      *
@@ -185,6 +217,46 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private pageState;
     private pageSizeState;
     private paginatedState;
+    private readonly virtualize;
+    /**
+     * The rows in the shadow tree, each with the row of the page it drew.
+     *
+     * **Read off `data-index` rather than counted.** `hostUpdated` runs before
+     * `updated`, so what is in the tree when the controller asks is the previous
+     * window; counting from the current one would record the right heights
+     * against the wrong rows every time the window moved.
+     */
+    private drawn;
+    /**
+     * How many rows there are to window over: the page, or the result.
+     *
+     * **Read off the held arrangement rather than counted afresh**, because the
+     * controller asks this on every scroll and `matched` walks the whole result
+     * whenever a filter is on. Held, a scroll through a filtered table of five
+     * thousand rows costs a lookup; counted, it costs five thousand comparisons a
+     * frame, which is the cost windowing was added to avoid.
+     *
+     * `matched` still answers where nothing is windowing, which is the path that
+     * holds nothing and should not start.
+     */
+    private get available();
+    /**
+     * The arranged result, kept between renders.
+     *
+     * **A window moves and the order does not.** Every scroll that reveals a row
+     * re-renders, and deriving that render from `rows` would filter and sort the
+     * whole result again each time: 23.7ms at five thousand rows, three frames
+     * spent before a cell is drawn. Held against the inputs that change it, a
+     * scroll costs a slice.
+     *
+     * Only the windowed path uses this. A paged table re-renders when the reader
+     * asks for a page, which is rare enough that holding a second copy of the
+     * result to save a sort is the wrong trade.
+     */
+    private held;
+    private arrange;
+    /** The part of a page the reader can see, which is every row when not windowed. */
+    private windowOf;
     /** The columns declared as children, in the order they are written. */
     get tableColumns(): HelixHeadlessTableColumn[];
     /** The columns reduced to what the ordering needs. */
@@ -212,15 +284,26 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * which means the out-of-the-box arrangement is the unbounded one and nothing
      * about it says that a result of any size will simply be drawn.
      *
-     * **Windowing was refused**, which is worth recording because it is the
-     * obvious answer. This element already has two mechanisms: `paginated` with a
-     * `page-size`, and `mode="server"` where `rows` is one page, `total` is the
-     * whole result and `aria-rowcount` already reports the result rather than the
-     * window, which is the hard half of virtualization done correctly. A third
-     * would fight the first two, and virtualizing a grid means variable row
-     * heights, a sticky header and keeping `aria-rowindex` honest against a result
-     * the element is no longer holding. `VirtualizeController` exists for the case
-     * where the rows are a flat list and this is not that.
+     * **Windowing was refused here, and is now `windowed`.** The refusal is kept
+     * because most of it was right, and because what changed is not that somebody
+     * disagreed with it. It rested on four claims: that a third mechanism would
+     * fight `paginated` and `mode="server"`; that a grid has rows of different
+     * heights; that it needs a sticky header; and that `aria-rowindex` has to keep
+     * describing a result the element no longer holds in full.
+     *
+     * Three stopped being true. `VirtualizeController` learnt to measure each row
+     * and place the next by what the one above came to, which is the variable
+     * heights. `aria-rowindex` was already result-relative because paging needed
+     * it, so a window is a second offset on arithmetic that existed. And the
+     * sticky header is one `position: sticky` on the heading cells rather than on
+     * `[part="head"]`, which is `display: contents` and generates no box to stick
+     * -- that is why it looked hard and is not.
+     *
+     * The first was avoided rather than answered. `windowed` is not a `mode` and
+     * does not exclude `paginated`: it says how much of what we hold gets drawn,
+     * where `mode` says where it came from, so there is no third axis to fight the
+     * other two. What survives is the cost, which is why windowing is off by
+     * default and why this warning still fires for a table that has none of them.
      *
      * Warned once per element, in a browser only: a warning during a server render
      * is one nobody can act on and one that would print per request.
@@ -327,8 +410,35 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * reason a virtualized or paged grid needs `aria-rowindex` at all: a screen
      * reader on page three should hear row 41, and a grid whose indices restart at
      * every page tells a reader the result is twenty rows long however many it has.
+     *
+     * A window is the second offset and stacks on the page: with both on, row one
+     * of the window is the page's start plus how far down the page it begins.
      */
     private rowIndex;
+    /**
+     * What decides which row is at which index, as one comparable value.
+     *
+     * Not the rows themselves: those are compared by identity beside this, and a
+     * consumer handing back an equal array is handing back the same rows in the
+     * same order whatever object it is.
+     */
+    private get placement();
+    /** The signature the recorded heights were measured against. */
+    private measuredAgainst;
+    /** Where the window begins in the page, which is the top when there is none. */
+    private get windowStart();
+    /**
+     * The room the rows outside the window would have taken.
+     *
+     * **`role="presentation"`, because this is geometry standing inside a
+     * `rowgroup`.** A bare `div` there is a child the role does not allow, and a
+     * screen reader walking the rows would meet something that is not one. The
+     * room itself is what keeps the scrollbar honest: a box that scrolls twenty
+     * rows while claiming ten thousand gives a thumb the size of its track.
+     */
+    private renderSpacer;
+    /** The controller owns the geometry; this is only what tells it to look again. */
+    private readonly handleScroll;
     protected render(): TemplateResult;
     /**
      * Listens on the host, not on the slot the columns are assigned to.