@fusion.dev/helix-headless 0.5.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",
@@ -74918,7 +75125,7 @@
                 "text": "number"
               },
               "default": "32",
-              "description": "How tall one row is, in pixels, used to map scroll offset to an index.",
+              "description": "How tall one row is, in pixels, used to map scroll offset to an index.\n\nAn estimate rather than a measurement while `measured` is off, which is\nright whenever the rows really are one height and is the cheaper of the two.",
               "attribute": "estimate"
             },
             {
@@ -74941,6 +75148,16 @@
               "description": "What the list is called, since the rendered rows are only a window on it.",
               "attribute": "label"
             },
+            {
+              "kind": "field",
+              "name": "measured",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Places rows by what they came to rather than by `estimate`.\n\n**Off by default, because the straight line is better when it holds.** One\nestimate makes offset and index convert by division, which can never\ndisagree with itself; measuring is what a set of genuinely different\nheights needs and costs a read of each row as it renders. A list of\none-line rows should leave this alone.",
+              "attribute": "measured"
+            },
             {
               "kind": "field",
               "name": "rows",
@@ -74956,7 +75173,18 @@
               "name": "virtualize",
               "privacy": "private",
               "readonly": true,
-              "default": "new VirtualizeController(this, { container: () => this.renderRoot.querySelector<HTMLElement>('[part=\"viewport\"]'), count: () => this.rows.length, estimate: () => this.estimate, })"
+              "default": "new VirtualizeController(this, { container: () => this.renderRoot.querySelector<HTMLElement>('[part=\"viewport\"]'), count: () => this.rows.length, estimate: () => this.estimate, measured: () => this.measured, rows: () => this.drawn(), })"
+            },
+            {
+              "kind": "method",
+              "name": "drawn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ element: HTMLElement; index: number }[]"
+                }
+              },
+              "description": "The rows in the tree, each with the item it drew.\n\n**Read off `data-index` rather than counted**, because what is in the tree\nwhen the controller asks is what `place` appended on the *previous* pass:\n`hostUpdated` runs before `updated`, so counting from the current window\nwould record the right heights against the wrong items every time the\nwindow moved."
             },
             {
               "kind": "method",
@@ -75160,7 +75388,7 @@
                 "text": "number"
               },
               "default": "32",
-              "description": "How tall one row is, in pixels, used to map scroll offset to an index.",
+              "description": "How tall one row is, in pixels, used to map scroll offset to an index.\n\nAn estimate rather than a measurement while `measured` is off, which is\nright whenever the rows really are one height and is the cheaper of the two.",
               "fieldName": "estimate"
             },
             {
@@ -75180,6 +75408,15 @@
               "default": "''",
               "description": "What the list is called, since the rendered rows are only a window on it.",
               "fieldName": "label"
+            },
+            {
+              "name": "measured",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Places rows by what they came to rather than by `estimate`.\n\n**Off by default, because the straight line is better when it holds.** One\nestimate makes offset and index convert by division, which can never\ndisagree with itself; measuring is what a set of genuinely different\nheights needs and costs a read of each row as it renders. A list of\none-line rows should leave this alone.",
+              "fieldName": "measured"
             }
           ],
           "superclass": {