@fusion.dev/helix 0.6.0 → 0.7.1

package/custom-elements.json

@@ -22900,9 +22900,13 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Hairline rules between rows and no fill, per the rule that depth comes from a\nsingle border rather than from elevation. A header band would be elevation\nspelled differently, so the headings are weight and color instead.\n\nThe grid scrolls its own box and the toolbar and footer sit outside it: a\nsearch field that slides sideways when a reader scrolls the columns is a\nsearch field they lose.\n\n**The cell values do not server-render**, which is the headless tier's\nlimitation and worth repeating where a consumer chooses between the two: use\n`helix-table` where the content has to be in the served HTML.",
+          "description": "Hairline rules between rows and no fill, per the rule that depth comes from a\nsingle border rather than from elevation. A header band would be elevation\nspelled differently, so the headings are weight and color instead.\n\nThe grid scrolls its own box and the toolbar and footer sit outside it: a\nsearch field that slides sideways when a reader scrolls the columns is a\nsearch field they lose.\n\n`windowed` draws only the rows in view, for a result too long to lay out at\nonce, and the headings stay put while they scroll. It is independent of\n`paginated` and of `mode`, so a page can be windowed and a server-fed chunk\ncan be too.\n\n**The cell values do not server-render**, which is the headless tier's\nlimitation and worth repeating where a consumer chooses between the two: use\n`helix-table` where the content has to be in the served HTML.",
           "name": "HelixDataTable",
           "cssProperties": [
+            {
+              "description": "How tall the scrolling box is while `windowed`. Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a maximum, so a short result under `windowed` keeps the full box with space below it: a maximum would leave the height a function of the rows drawn, and the rows drawn a function of the height, which is the loop the window controller has to guard against rather than one worth entering on purpose.",
+              "name": "--data-table-block-size"
+            },
             {
               "description": "Ink in a cell.",
               "name": "--data-table-color"
@@ -22911,6 +22915,10 @@
               "description": "Track list for the columns, which wins over the one the columns worked out.",
               "name": "--data-table-columns"
             },
+            {
+              "description": "Fill behind a heading while `windowed`. Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them through. Unset otherwise, so the headings stay weight rather than a band.",
+              "name": "--data-table-heading-background-color"
+            },
             {
               "description": "Ink in a heading.",
               "name": "--data-table-heading-color"
@@ -22957,6 +22965,22 @@
                 "module": "src/data-table/root/data-table-root.ts"
               }
             },
+            {
+              "description": "The room the rows below the window would have taken. Windowed only.",
+              "name": "after",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "description": "The room the rows above the window would have taken. Windowed only.",
+              "name": "before",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
             {
               "description": "Shown when no rows match.",
               "name": "empty",
@@ -23258,13 +23282,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",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -23285,13 +23309,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",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -23312,13 +23336,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",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -23337,6 +23361,20 @@
                 "module": "src/data-table/root/data-table-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "rows",
@@ -23377,6 +23415,21 @@
                 "module": "src/data-table/root/data-table-root.ts"
               }
             },
+            {
+              "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,
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "paginated",
@@ -23455,6 +23508,96 @@
                 "module": "src/data-table/root/data-table-root.ts"
               }
             },
+            {
+              "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() : []), })",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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,
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "arrange",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Arranged"
+                }
+              },
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "tableColumns",
@@ -23543,7 +23686,7 @@
                   }
                 }
               ],
-              "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.",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -23553,7 +23696,7 @@
               "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.",
@@ -23869,7 +24012,83 @@
                   }
                 }
               ],
-              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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,
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "measuredAgainst",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "The signature the recorded heights were measured against.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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,
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "handleScroll",
+              "privacy": "private",
+              "readonly": true,
+              "description": "The controller owns the geometry; this is only what tells it to look again.",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -24113,9 +24332,21 @@
                 "min": 420,
                 "slug": "events"
               },
+              {
+                "description": "Eight rows at a time, with a pagination the table draws itself.",
+                "slug": "paging"
+              },
               {
                 "description": "One query across every column, from a search field the page owns.",
                 "slug": "searching"
+              },
+              {
+                "description": "Pages of five hundred, each drawn a window at a time.",
+                "slug": "windowed-paging"
+              },
+              {
+                "description": "Five thousand rows, drawing only the ones in view.",
+                "slug": "windowing"
               }
             ],
             "source": "helix/styled/src/data-table"
@@ -24215,13 +24446,13 @@
               }
             },
             {
-              "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",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -24240,13 +24471,13 @@
               }
             },
             {
-              "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",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -24265,13 +24496,13 @@
               }
             },
             {
-              "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",
               "inheritedFrom": {
                 "name": "HelixHeadlessDataTable",
                 "module": "src/data-table/root/data-table-root.ts"
@@ -24289,6 +24520,19 @@
                 "module": "src/data-table/root/data-table-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
             {
               "name": "page-size",
               "type": {
@@ -24314,6 +24558,19 @@
                 "module": "src/data-table/root/data-table-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessDataTable",
+                "module": "src/data-table/root/data-table-root.ts"
+              }
+            },
             {
               "name": "paginated",
               "type": {

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

@@ -76,6 +76,24 @@ padding-inline: var(--helix-space-sm);
 text-align: center;
 }
 
+:host([windowed]) [part="table"] {
+block-size: var(--data-table-block-size, 24em);
+overflow-y: auto;
+overscroll-behavior: contain;
+}
+
+:host([windowed]) ::slotted(helix-table-column) {
+background-color: var(--data-table-heading-background-color, var(--helix-color-background));
+inset-block-start: 0;
+position: sticky;
+z-index: 1;
+}
+
+[part="before"],
+[part="after"] {
+grid-column: 1 / -1;
+}
+
 :host([loading]) [part="table"] {
 opacity: 0.5;
 }
@@ -90,6 +108,11 @@ box-shadow: none;
 overflow-x: visible;
 }
 
+:host([windowed]) [part="table"] {
+block-size: auto;
+overflow-y: visible;
+}
+
 [part="footer"] {
 display: none;
 }

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

@@ -14,6 +14,11 @@ import '../../table/index.js';
  * search field that slides sideways when a reader scrolls the columns is a
  * search field they lose.
  *
+ * `windowed` draws only the rows in view, for a result too long to lay out at
+ * once, and the headings stay put while they scroll. It is independent of
+ * `paginated` and of `mode`, so a page can be windowed and a server-fed chunk
+ * can be too.
+ *
  * **The cell values do not server-render**, which is the headless tier's
  * limitation and worth repeating where a consumer chooses between the two: use
  * `helix-table` where the content has to be in the served HTML.
@@ -30,8 +35,17 @@ import '../../table/index.js';
  * @csspart cell - One cell.
  * @csspart table - The grid.
  *
+ * @cssproperty --data-table-block-size - How tall the scrolling box is while `windowed`.
+ * Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a
+ * maximum, so a short result under `windowed` keeps the full box with space below it: a
+ * maximum would leave the height a function of the rows drawn, and the rows drawn a function
+ * of the height, which is the loop the window controller has to guard against rather than
+ * one worth entering on purpose.
  * @cssproperty --data-table-color - Ink in a cell.
  * @cssproperty --data-table-columns - Track list for the columns, which wins over the one the columns worked out.
+ * @cssproperty --data-table-heading-background-color - Fill behind a heading while `windowed`.
+ * Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them
+ * through. Unset otherwise, so the headings stay weight rather than a band.
  * @cssproperty --data-table-heading-color - Ink in a heading.
  * @cssproperty --data-table-padding-block - Space above and below a cell's content.
  * @cssproperty --data-table-padding-inline - Space either side of a cell's content.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.6.0",
-    "@fusion.dev/helix-headless": "0.6.0",
-    "@fusion.dev/helix-styles": "0.6.0"
+    "@fusion.dev/helix-core": "0.7.1",
+    "@fusion.dev/helix-headless": "0.7.1",
+    "@fusion.dev/helix-styles": "0.7.1"
   },
   "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

@@ -4962,6 +4962,20 @@ say that without the component knowing what a row looks like. */
   "default-sort"?: (HelixDataTable["defaultSort"]) | undefined;
   /** Order to open on, where nothing declared one. */
   defaultSort?: (HelixDataTable["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?: (HelixDataTable["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?: (HelixDataTable["sort"]) | undefined;
   /** The field naming a row's stable identity.
 
 **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -4971,20 +4985,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?: (HelixDataTable["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?: (HelixDataTable["sort"]) | undefined;
-  /** Accessible name for the grid. */
-  label?: (HelixDataTable["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?: (HelixDataTable["filter"]) | undefined;
+  /** Accessible name for the grid. */
+  label?: (HelixDataTable["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?: (HelixDataTable["page"]) | undefined;
   /** Whether this element does the work or asks the consumer to.
 
 `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -4994,12 +5008,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?: (HelixDataTable["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?: (HelixDataTable["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
@@ -5023,6 +5031,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?: (HelixDataTable["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?: (HelixDataTable["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
@@ -5080,6 +5106,20 @@ say that without the component knowing what a row looks like. */
   "attr:default-sort"?: (HelixDataTable["defaultSort"]) | undefined;
   /** Order to open on, where nothing declared one. */
   "prop:defaultSort"?: (HelixDataTable["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"?: (HelixDataTable["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"?: (HelixDataTable["sort"]) | undefined;
   /** The field naming a row's stable identity.
 
 **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -5089,20 +5129,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"?: (HelixDataTable["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"?: (HelixDataTable["sort"]) | undefined;
-  /** Accessible name for the grid. */
-  "prop:label"?: (HelixDataTable["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"?: (HelixDataTable["filter"]) | undefined;
+  /** Accessible name for the grid. */
+  "prop:label"?: (HelixDataTable["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"?: (HelixDataTable["page"]) | undefined;
   /** Whether this element does the work or asks the consumer to.
 
 `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -5112,12 +5152,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"?: (HelixDataTable["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"?: (HelixDataTable["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
@@ -5141,6 +5175,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"?: (HelixDataTable["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"?: (HelixDataTable["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
@@ -21811,6 +21863,11 @@ export type CustomElements = {
    * search field that slides sideways when a reader scrolls the columns is a
    * search field they lose.
    *
+   * `windowed` draws only the rows in view, for a result too long to lay out at
+   * once, and the headings stay put while they scroll. It is independent of
+   * `paginated` and of `mode`, so a page can be windowed and a server-fed chunk
+   * can be too.
+   *
    * **The cell values do not server-render**, which is the headless tier's
    * limitation and worth repeating where a consumer chooses between the two: use
    * `helix-table` where the content has to be in the served HTML.
@@ -21830,6 +21887,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
@@ -21838,17 +21907,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
@@ -21857,11 +21926,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
@@ -21875,6 +21939,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
@@ -21944,8 +22025,10 @@ export type CustomElements = {
    *
    * CSS variables available for styling the component.
    *
+   * - `--data-table-block-size`: How tall the scrolling box is while `windowed`. Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a maximum, so a short result under `windowed` keeps the full box with space below it: a maximum would leave the height a function of the rows drawn, and the rows drawn a function of the height, which is the loop the window controller has to guard against rather than one worth entering on purpose. (default: `undefined`)
    * - `--data-table-color`: Ink in a cell. (default: `undefined`)
    * - `--data-table-columns`: Track list for the columns, which wins over the one the columns worked out. (default: `undefined`)
+   * - `--data-table-heading-background-color`: Fill behind a heading while `windowed`. Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them through. Unset otherwise, so the headings stay weight rather than a band. (default: `undefined`)
    * - `--data-table-heading-color`: Ink in a heading. (default: `undefined`)
    * - `--data-table-padding-block`: Space above and below a cell's content. (default: `undefined`)
    * - `--data-table-padding-inline`: Space either side of a cell's content. (default: `undefined`)
@@ -21959,6 +22042,8 @@ export type CustomElements = {
    *
    * - `cell`: One cell.
    * - `table`: The grid.
+   * - `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.
    * - `empty`: Shown when no rows match.
    * - `footer`: The region below the grid.
    * - `head`: The row the column headings sit in. `display: contents`, so it takes no space.
@@ -37485,6 +37570,11 @@ export type CustomElementsSolidJs = {
    * search field that slides sideways when a reader scrolls the columns is a
    * search field they lose.
    *
+   * `windowed` draws only the rows in view, for a result too long to lay out at
+   * once, and the headings stay put while they scroll. It is independent of
+   * `paginated` and of `mode`, so a page can be windowed and a server-fed chunk
+   * can be too.
+   *
    * **The cell values do not server-render**, which is the headless tier's
    * limitation and worth repeating where a consumer chooses between the two: use
    * `helix-table` where the content has to be in the served HTML.
@@ -37504,6 +37594,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
@@ -37512,17 +37614,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
@@ -37531,11 +37633,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
@@ -37549,6 +37646,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
@@ -37618,8 +37732,10 @@ export type CustomElementsSolidJs = {
    *
    * CSS variables available for styling the component.
    *
+   * - `--data-table-block-size`: How tall the scrolling box is while `windowed`. Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a maximum, so a short result under `windowed` keeps the full box with space below it: a maximum would leave the height a function of the rows drawn, and the rows drawn a function of the height, which is the loop the window controller has to guard against rather than one worth entering on purpose. (default: `undefined`)
    * - `--data-table-color`: Ink in a cell. (default: `undefined`)
    * - `--data-table-columns`: Track list for the columns, which wins over the one the columns worked out. (default: `undefined`)
+   * - `--data-table-heading-background-color`: Fill behind a heading while `windowed`. Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them through. Unset otherwise, so the headings stay weight rather than a band. (default: `undefined`)
    * - `--data-table-heading-color`: Ink in a heading. (default: `undefined`)
    * - `--data-table-padding-block`: Space above and below a cell's content. (default: `undefined`)
    * - `--data-table-padding-inline`: Space either side of a cell's content. (default: `undefined`)
@@ -37633,6 +37749,8 @@ export type CustomElementsSolidJs = {
    *
    * - `cell`: One cell.
    * - `table`: The grid.
+   * - `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.
    * - `empty`: Shown when no rows match.
    * - `footer`: The region below the grid.
    * - `head`: The row the column headings sit in. `display: contents`, so it takes no space.
@@ -49745,10 +49863,14 @@ export type CustomCssProperties = {
   "--icon-button-shadow"?: (string) | undefined;
   /** Edge length of the control. */
   "--icon-button-size"?: (string) | undefined;
+  /** How tall the scrolling box is while `windowed`. Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a maximum, so a short result under `windowed` keeps the full box with space below it: a maximum would leave the height a function of the rows drawn, and the rows drawn a function of the height, which is the loop the window controller has to guard against rather than one worth entering on purpose. */
+  "--data-table-block-size"?: (string) | undefined;
   /** Ink in a cell. */
   "--data-table-color"?: (string) | undefined;
   /** Track list for the columns, which wins over the one the columns worked out. */
   "--data-table-columns"?: (string) | undefined;
+  /** Fill behind a heading while `windowed`. Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them through. Unset otherwise, so the headings stay weight rather than a band. */
+  "--data-table-heading-background-color"?: (string) | undefined;
   /** Ink in a heading. */
   "--data-table-heading-color"?: (string) | undefined;
   /** Space above and below a cell's content. */

package/types/vue.d.ts

@@ -2557,6 +2557,20 @@ say that without the component knowing what a row looks like. */
   "default-sort"?: (HelixDataTable["defaultSort"]) | undefined;
   /** Order to open on, where nothing declared one. */
   defaultSort?: (HelixDataTable["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?: (HelixDataTable["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?: (HelixDataTable["sort"]) | undefined;
   /** The field naming a row's stable identity.
 
 **Needed before selection exists, not after.** Lit keys the rendered rows by
@@ -2566,20 +2580,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?: (HelixDataTable["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?: (HelixDataTable["sort"]) | undefined;
-  /** Accessible name for the grid. */
-  label?: (HelixDataTable["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?: (HelixDataTable["filter"]) | undefined;
+  /** Accessible name for the grid. */
+  label?: (HelixDataTable["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?: (HelixDataTable["page"]) | undefined;
   /** Whether this element does the work or asks the consumer to.
 
 `client` filters, sorts and pages `rows` itself. `server` applies none of
@@ -2589,12 +2603,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?: (HelixDataTable["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?: (HelixDataTable["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
@@ -2618,6 +2626,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?: (HelixDataTable["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?: (HelixDataTable["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
@@ -9423,10 +9449,14 @@ export type CustomCssProperties = {
   "--icon-button-shadow"?: (string) | undefined;
   /** Edge length of the control. */
   "--icon-button-size"?: (string) | undefined;
+  /** How tall the scrolling box is while `windowed`. Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a maximum, so a short result under `windowed` keeps the full box with space below it: a maximum would leave the height a function of the rows drawn, and the rows drawn a function of the height, which is the loop the window controller has to guard against rather than one worth entering on purpose. */
+  "--data-table-block-size"?: (string) | undefined;
   /** Ink in a cell. */
   "--data-table-color"?: (string) | undefined;
   /** Track list for the columns, which wins over the one the columns worked out. */
   "--data-table-columns"?: (string) | undefined;
+  /** Fill behind a heading while `windowed`. Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them through. Unset otherwise, so the headings stay weight rather than a band. */
+  "--data-table-heading-background-color"?: (string) | undefined;
   /** Ink in a heading. */
   "--data-table-heading-color"?: (string) | undefined;
   /** Space above and below a cell's content. */
@@ -10271,7 +10301,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixCopyButtonVueProps,
     HelixCopyButtonVueEvents
   >;
-  /** Hairline rules between rows and no fill, per the rule that depth comes from a single border rather than from elevation. A header band would be elevation spelled differently, so the headings are weight and color instead.  The grid scrolls its own box and the toolbar and footer sit outside it: a search field that slides sideways when a reader scrolls the columns is a search field they lose.  **The cell values do not server-render**, which is the headless tier's limitation and worth repeating where a consumer chooses between the two: use 'helix-table' where the content has to be in the served HTML. */
+  /** Hairline rules between rows and no fill, per the rule that depth comes from a single border rather than from elevation. A header band would be elevation spelled differently, so the headings are weight and color instead.  The grid scrolls its own box and the toolbar and footer sit outside it: a search field that slides sideways when a reader scrolls the columns is a search field they lose.  'windowed' draws only the rows in view, for a result too long to lay out at once, and the headings stay put while they scroll. It is independent of 'paginated' and of 'mode', so a page can be windowed and a server-fed chunk can be too.  **The cell values do not server-render**, which is the headless tier's limitation and worth repeating where a consumer chooses between the two: use 'helix-table' where the content has to be in the served HTML. */
   "helix-data-table": DefineCustomElement<
     HelixDataTable,
     HelixDataTableVueProps,