@fusion.dev/helix-headless 0.182.2 → 0.184.0

package/custom-elements.json

@@ -7132,6 +7132,10 @@
               "description": "A far end below zero, whose far end is its bottom, or its inline start when the bars run across. Set together with `bar-end`.",
               "name": "bar-end-negative"
             },
+            {
+              "description": "A bar below zero, standing alone or any segment of a stack below it, whose base is its top, or its inline end when the bars run across. Set together with `bar`.",
+              "name": "bar-negative"
+            },
             {
               "description": "The far stop of a bar's gradient, where one is used.",
               "name": "bar-wash-end"
@@ -31988,9 +31992,34 @@
       "kind": "javascript-module",
       "path": "src/code-block/root/code-block-root.ts",
       "declarations": [
+        {
+          "kind": "function",
+          "name": "registerHighlighter",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "highlighter",
+              "type": {
+                "text": "CodeBlockHighlighter | undefined"
+              }
+            },
+            {
+              "name": "sheet",
+              "optional": true,
+              "type": {
+                "text": "CSSResult"
+              }
+            }
+          ],
+          "description": "Gives every Code Block of both tiers a highlighter, for the blocks that set\nno `highlight` of their own, and the sheet that colors what it returns.\n\n**Opt-in, so a page that shows plain code carries no grammar.** Code Block\nships none: a grammar is the larger part of any highlighter, and a block\nthat registers one for every page makes every page pay for it. A page that\nwants color imports one entry that calls this, such as\n`@fusion.dev/helix-sandbox/code-block`, which reads `css`, `html`, `js`,\n`jsx`, `sh`, `ts` and `tsx` with the sandbox's Lezer grammars and colors\nthem from the `--helix-color-syntax-*` tokens.\n\nA block's own `highlight` wins over this. Blocks already on the page draw\nagain with it, and every block built after has it. `undefined` takes it\naway again."
+        },
         {
           "kind": "class",
-          "description": "Renders a `<pre><code>` pair: `pre` keeps the whitespace, and `code` marks it\nas code. Long lines scroll inside the block and do not wrap, because a line\nbreak can be significant in code.\n\nA copy button is on by default. Set `no-copy` to remove it. The button copies\nthe slotted text, so there is no second copy of the code to keep in sync.\n\nFor a fragment of code inside a sentence, use `Code`.\n\nSet `line-numbers` to number the lines in a gutter beside the code, hidden\nfrom the accessibility tree and left out of a copy. Set `mark-lines` to\nmark lines a reader should look at, such as `2, 4-6`: the block draws a\nband behind each run, placed where the lines are laid out, so it follows a\nhighlighter's markup and lines that wrap. `added-lines` and\n`removed-lines` mark lines the same way as inserted and deleted, as\nExpressive Code's `ins` and `del` do, in code that is not a diff. The bands\nare drawn and hidden from screen readers, so say in the text around the\nblock what a marked line means. Set `wrap` to wrap long lines\nrather than scroll them; a gutter then numbers each line where it starts.\nSet `wrappable` for a button in the header that turns `wrap` on and off,\npressed while the lines wrap.\n\nThe header holds the name, the `actions` slot, and the copy button. Slot a\ncontrol into `actions`, such as a button that sets `wrap` or one that opens\nthe code in an editor, and the block draws a header for it even with no\nname. `copy-icon` and `copied-icon` replace the copy button's two icons. Set `highlight` to a\nfunction that turns the code into highlighted markup, such as one wrapping\nShiki or Prism, and the block draws what it returns; it is handed the\nblock's `language`, so one function serves every block. The code stays in\nthe slot, so the copy button and the page's own text are the code as\nwritten.\n\nSet `expandable` on a block whose height is capped, such as by\n`--code-block-max-block-size`, and a button under it shows every line and\nthen fewer again, as a docs site's long example does. The button is drawn\nonly while the cap hides something, says whether the block is expanded with\n`aria-expanded`, names the block it opens with `aria-controls`, and the block\ncarries `:state(expanded)` while it is.\n\nSet `diff` to show a change. Put a unified diff, the output of `git diff` or\n`diff -u`, in the same slot, and the block draws the lines it added and\nremoved. The block never computes a diff itself. Line numbers come from the\nhunk headers and are hidden from the accessibility tree. Changed lines are\n`<ins>` and `<del>` with the `+` and `-` kept as text, so the change does not\ndepend on color. Where a removed line is paired with the added line that\nreplaced it, the words each does not share with the other are the `changed`\npart, so the eye goes to what changed within the line. Each file in the patch is its own block under its own name,\nand its copy button copies the new version of the file. `variant=\"split\"`\nshows the old version beside the new, each removal opposite its replacement.\n`context-lines` folds each long run of unchanged lines, keeping that many\nbeside each change, behind a button that shows them and hides them again,\nas a code host draws a diff written with more context than a reader needs.\n\n**A block that scrolls is a tab stop.** While its lines run past its width or\nits cap, the scroller is a region named for the block, such as \"Code,\napp.ts\", that Tab reaches, so a keyboard scrolls it with the arrow keys in\nevery browser. Chromium and Firefox make a scrolling box focusable on their\nown, and Safari does not. A block that fits is no stop at all.\n\n**The code the block draws is marked untranslated**, `translate=\"no\"` on\nits `<pre>`, so a page translator leaves highlighted lines and a diff as\nwritten. Code in the slot takes its translation mode from the element, which\nwrites nothing onto itself, so set `translate=\"no\"` on the element to keep a\ntranslator off plain code too.\n\nOn the server, the slot renders as ordinary code, so a diff first appears as\nthe patch text in a `<pre>`. The client makes the same first render, which\nkeeps hydration clean, and draws the diff once it can read the content. Diff\nmode is experimental. The rest of the family is stable.\n\n**Several blocks are files**, one shown at a time under a row of tabs, as\nSandbox shows its source panes. Put Code Blocks in the default slot of a\nCode Block, and each is a file named on its tab by its `label` or, without\none, its `language`. `file` holds the name of the file shown. The tabs are a\ntab list: the arrow keys move to a tab and show its file, the two swapping\non a right-to-left page, and Home and End go to the first and the last.\nChoosing one sends `helix-before-change` with the file's name, which you can\ncancel, and `change` once `file` holds it. The files not shown carry\n`hidden`, and the one shown draws no name of its own, its tab naming it. One\nblock draws no tabs. A server cannot see the blocks inside, so the client\ndraws the tabs once it upgrades.",
+          "description": "Renders a `<pre><code>` pair: `pre` keeps the whitespace, and `code` marks it\nas code. Long lines scroll inside the block and do not wrap, because a line\nbreak can be significant in code.\n\nA copy button is on by default. Set `no-copy` to remove it. The button copies\nthe slotted text, so there is no second copy of the code to keep in sync.\n\nFor a fragment of code inside a sentence, use `Code`.\n\nSet `line-numbers` to number the lines in a gutter beside the code, hidden\nfrom the accessibility tree and left out of a copy. Set `mark-lines` to\nmark lines a reader should look at, such as `2, 4-6`: the block draws a\nband behind each run, placed where the lines are laid out, so it follows a\nhighlighter's markup and lines that wrap. `added-lines` and\n`removed-lines` mark lines the same way as inserted and deleted, as\nExpressive Code's `ins` and `del` do, in code that is not a diff. The bands\nare drawn and hidden from screen readers, so say in the text around the\nblock what a marked line means. Set `wrap` to wrap long lines\nrather than scroll them; a gutter then numbers each line where it starts.\nSet `wrappable` for a button in the header that turns `wrap` on and off,\npressed while the lines wrap.\n\nThe header holds the name, the `actions` slot, and the copy button. Slot a\ncontrol into `actions`, such as a button that sets `wrap` or one that opens\nthe code in an editor, and the block draws a header for it even with no\nname. `copy-icon` and `copied-icon` replace the copy button's two icons. Set `highlight` to a\nfunction that turns the code into highlighted markup, such as one wrapping\nShiki or Prism, and the block draws what it returns; it is handed the\nblock's `language`, so one function serves every block. The code stays in\nthe slot, so the copy button and the page's own text are the code as\nwritten.\n\n**Code Block ships no grammar**, so plain code costs you no parser. To color\ncode without a highlighter of your own, import one more entry beside the\nblock's. It colors every block by its `language` (`css`, `html`, `js`,\n`jsx`, `sh`, `ts`, or `tsx`) with the Lezer grammars of the sandbox's\neditor, in the editor's colors:\n\n```js\nimport '@fusion.dev/helix/code-block'\nimport '@fusion.dev/helix-sandbox/code-block'\n```\n\nThat entry calls `registerHighlighter`, which you can also call yourself to\ngive every block one highlighter of your own.\n\nSet `expandable` on a block whose height is capped, such as by\n`--code-block-max-block-size`, and a button under it shows every line and\nthen fewer again, as a docs site's long example does. The button is drawn\nonly while the cap hides something, says whether the block is expanded with\n`aria-expanded`, names the block it opens with `aria-controls`, and the block\ncarries `:state(expanded)` while it is.\n\nSet `diff` to show a change. Put a unified diff, the output of `git diff` or\n`diff -u`, in the same slot, and the block draws the lines it added and\nremoved. The block never computes a diff itself. Line numbers come from the\nhunk headers and are hidden from the accessibility tree. Changed lines are\n`<ins>` and `<del>` with the `+` and `-` kept as text, so the change does not\ndepend on color. Where a removed line is paired with the added line that\nreplaced it, the words each does not share with the other are the `changed`\npart, so the eye goes to what changed within the line. Each file in the patch is its own block under its own name,\nand its copy button copies the new version of the file. `variant=\"split\"`\nshows the old version beside the new, each removal opposite its replacement.\n`context-lines` folds each long run of unchanged lines, keeping that many\nbeside each change, behind a button that shows them and hides them again,\nas a code host draws a diff written with more context than a reader needs.\n\n**A block that scrolls is a tab stop.** While its lines run past its width or\nits cap, the scroller is a region named for the block, such as \"Code,\napp.ts\", that Tab reaches, so a keyboard scrolls it with the arrow keys in\nevery browser. Chromium and Firefox make a scrolling box focusable on their\nown, and Safari does not. A block that fits is no stop at all.\n\n**The code the block draws is marked untranslated**, `translate=\"no\"` on\nits `<pre>`, so a page translator leaves highlighted lines and a diff as\nwritten. Code in the slot takes its translation mode from the element, which\nwrites nothing onto itself, so set `translate=\"no\"` on the element to keep a\ntranslator off plain code too.\n\nOn the server, the slot renders as ordinary code, so a diff first appears as\nthe patch text in a `<pre>`. The client makes the same first render, which\nkeeps hydration clean, and draws the diff once it can read the content. Diff\nmode is experimental. The rest of the family is stable.\n\n**Several blocks are files**, one shown at a time under a row of tabs, as\nSandbox shows its source panes. Put Code Blocks in the default slot of a\nCode Block, and each is a file named on its tab by its `label` or, without\none, its `language`. `file` holds the name of the file shown. The tabs are a\ntab list: the arrow keys move to a tab and show its file, the two swapping\non a right-to-left page, and Home and End go to the first and the last.\nChoosing one sends `helix-before-change` with the file's name, which you can\ncancel, and `change` once `file` holds it. The files not shown carry\n`hidden`, and the one shown draws no name of its own, its tab naming it. One\nblock draws no tabs. A server cannot see the blocks inside, so the client\ndraws the tabs once it upgrades.",
           "name": "HelixHeadlessCodeBlock",
           "cssProperties": [
             {
@@ -32397,7 +32426,7 @@
               "type": {
                 "text": "(code: string, language: string) => string | undefined"
               },
-              "description": "Turns the code into highlighted markup, which the block draws in place of\nthe plain text.\n\nCalled with the code as written and the block's `language`, and returning\nHTML, such as the output of Shiki's `codeToHtml` or Prism's `highlight`.\nOne function serves every block on a page, each block saying its own\nlanguage:\n\n```js\nfor (const block of document.querySelectorAll('helix-code-block')) {\n  block.highlight = (code, lang) => codeToHtml(code, { lang, theme: 'github-light' })\n}\n```\n\n**The markup is drawn as given**, so it has to escape the code it was\nhanded, which those highlighters do. A `<pre>` and `<code>` around the\nwhole of it, which Shiki writes, are taken off, so the lines sit level\nwith the gutter's numbers and the block keeps one tab stop. The code stays\nin the slot, so the copy button copies it as written and a reader without\nthe script still has it. Not called on a server, which has no code to\nread, nor for a diff."
+              "description": "Turns the code into highlighted markup, which the block draws in place of\nthe plain text.\n\nCalled with the code as written and the block's `language`, and returning\nHTML, such as the output of Shiki's `codeToHtml` or Prism's `highlight`.\nOne function serves every block on a page, each block saying its own\nlanguage:\n\n```js\nfor (const block of document.querySelectorAll('helix-code-block')) {\n  block.highlight = (code, lang) => codeToHtml(code, { lang, theme: 'github-light' })\n}\n```\n\n**The markup is drawn as given**, so it has to escape the code it was\nhanded, which those highlighters do. A `<pre>` and `<code>` around the\nwhole of it, which Shiki writes, are taken off, so the lines sit level\nwith the gutter's numbers and the block keeps one tab stop. The code stays\nin the slot, so the copy button copies it as written and a reader without\nthe script still has it. Not called on a server, which has no code to\nread, nor for a diff.\n\nAbsent, the block draws with the highlighter `registerHighlighter` gave\nevery block, where an entry such as `@fusion.dev/helix-sandbox/code-block`\nregistered one, and plain otherwise."
             },
             {
               "kind": "field",
@@ -33788,6 +33817,14 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "registerHighlighter",
+          "declaration": {
+            "name": "registerHighlighter",
+            "module": "src/code-block/root/code-block-root.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixHeadlessCodeBlock",
@@ -80378,7 +80415,7 @@
               },
               "privacy": "private",
               "default": "-1",
-              "description": "Where a range taken in with Shift starts: the cell last pressed, or none."
+              "description": "Where a range taken in with Shift starts: the row of the table whose cell\nwas last pressed, or none.\n\n**The row, and not the cell's place among those drawn.** A narrow strip\ndraws the newest whole columns, so a resize that drops or adds a column\nmoves every cell's place, and an anchor kept as a place started the next\nrange on another day."
             },
             {
               "kind": "field",
@@ -80586,6 +80623,16 @@
               "description": "The readings actually drawn, newest kept.\n\nThe tail rather than the head: a status strip that drops the newest days to\nkeep the oldest is answering a question nobody asked.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "dropped",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "description": "How many of the oldest rows a narrow strip leaves undrawn.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "readings",
@@ -85781,6 +85828,14 @@
             "module": "src/megamenu/index.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/menu/filter/index.js"
+          }
+        },
         {
           "kind": "js",
           "name": "*",
@@ -111666,6 +111721,392 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/menu/filter/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "filterMenu",
+          "declaration": {
+            "name": "filterMenu",
+            "module": "./menu-filter.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MenuFilterController",
+          "declaration": {
+            "name": "MenuFilterController",
+            "module": "./menu-filter.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/menu/filter/menu-filter.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "drawFilter",
+          "return": {
+            "type": {
+              "text": "TemplateResult"
+            }
+          },
+          "parameters": [
+            {
+              "name": "host",
+              "type": {
+                "text": "HelixHeadlessMenu"
+              }
+            },
+            {
+              "name": "rows",
+              "type": {
+                "text": "TemplateResult"
+              }
+            },
+            {
+              "name": "busy",
+              "type": {
+                "text": "string | typeof nothing"
+              }
+            },
+            {
+              "name": "onInput",
+              "type": {
+                "text": "(event: Event) => void"
+              }
+            }
+          ],
+          "description": "The field and then the `menu`: a menu holds menu items and nothing else, so\nthe field stands beside it, as React Aria's `Autocomplete` puts its search\nfield beside its menu. The menu calls it through its filter, so the parts it\nwrites are the menu's."
+        },
+        {
+          "kind": "class",
+          "description": "Narrows a `filterable` menu's rows as the reader types in a field above\nthem, with focus staying in the field and the highlight moving through the\nrows that are left.\n\n**Its own entry**, `@fusion.dev/helix-headless/menu/filter`, so a menu that\nnever filters carries none of this. Importing the entry gives every menu of\nthe tier one, and `filterable` turns it on. Menu's description says what a\nreader gets; this is the part of it the menu does not hold:\n\n- the field and the `menu` after it, which the menu draws in its surface\n- which rows the filter keeps, and the words each matched, marked\n- the keys the field answers: Up and Down move the highlight, Enter presses\n  the highlighted row, and Escape clears the filter before it closes\n- `helix-filter`, sent as the text changes, which a listener cancels to\n  keep every row showing\n- how many rows are kept, or `no-results-text`, said in the live region\n\nThe styled tier's entry hands in the sheet that draws the field, which the\nmenu adopts while it filters.",
+          "name": "MenuFilterController",
+          "members": [
+            {
+              "kind": "field",
+              "name": "host",
+              "type": {
+                "text": "HelixHeadlessMenu"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "default": "host"
+            },
+            {
+              "kind": "field",
+              "name": "inside",
+              "type": {
+                "text": "Inside"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "The same menu, read through what it keeps to itself."
+            },
+            {
+              "kind": "field",
+              "name": "sheet",
+              "type": {
+                "text": "CSSResult | undefined"
+              },
+              "description": "The sheet the menu adopts while it filters, from the styled tier.",
+              "default": "sheet"
+            },
+            {
+              "kind": "field",
+              "name": "highlighted",
+              "type": {
+                "text": "Row | undefined"
+              },
+              "description": "The row the keys reached while focus stays in the field."
+            },
+            {
+              "kind": "field",
+              "name": "page",
+              "type": {
+                "text": "Row | null"
+              },
+              "privacy": "private",
+              "default": "null",
+              "description": "The submenu the filter narrows, or null for the top page."
+            },
+            {
+              "kind": "field",
+              "name": "refused",
+              "type": {
+                "text": "string | undefined"
+              },
+              "privacy": "private",
+              "description": "The filter a listener refused, which narrows nothing."
+            },
+            {
+              "kind": "field",
+              "name": "seen",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "The filter the last update saw, so a change moves a highlight it hid."
+            },
+            {
+              "kind": "method",
+              "name": "hostConnected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "hostDisconnected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "field",
+              "name": "field",
+              "type": {
+                "text": "HTMLInputElement | null"
+              },
+              "description": "The field, while it is drawn.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "filtering",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the filter is narrowing the rows.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "kept",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "row",
+                  "type": {
+                    "text": "Row"
+                  }
+                }
+              ],
+              "description": "Whether the filter keeps a row: one of another page, or one whose words it matches."
+            },
+            {
+              "kind": "field",
+              "name": "keptRows",
+              "type": {
+                "text": "Row[]"
+              },
+              "privacy": "private",
+              "description": "The rows of the page the filter narrows that it keeps.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "request",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "value",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Asks to filter by new text, which the field and `filter` then hold. A\nrefusal keeps every row showing, for a page that narrows them itself."
+            },
+            {
+              "kind": "method",
+              "name": "by",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "value",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Filters by what the reader typed, and highlights the first row kept."
+            },
+            {
+              "kind": "method",
+              "name": "highlight",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "row",
+                  "type": {
+                    "text": "Row | undefined"
+                  }
+                }
+              ],
+              "description": "Puts the highlight on a row, which the field names with\n`aria-activedescendant`. An element reference, because the field is in\nthe menu's shadow root and the row in the tree around it, the one\ndirection a reference crosses."
+            },
+            {
+              "kind": "method",
+              "name": "keydown",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                },
+                {
+                  "name": "items",
+                  "type": {
+                    "text": "Row[]"
+                  }
+                },
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Answers a key the field takes, and returns whether it did: Up and Down\nmove the highlight through the rows kept, Enter presses the highlighted\nrow, and Escape over text empties the filter, the next one going back or\nclosing."
+            },
+            {
+              "kind": "field",
+              "name": "handleMouseDown",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Keeps focus in the field through a press on a row or the way back, as\nReact Aria's virtual focus does: the press still chooses."
+            },
+            {
+              "kind": "field",
+              "name": "handleInput",
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "status",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | undefined"
+                }
+              },
+              "description": "What a filter that keeps no rows shows, or nothing where it keeps some.\n\nIt sets what the live region says as well: `no-results-text` where the\nfilter keeps no rows, and how many it keeps where it keeps some, as React\nAria and Web Awesome say the count. Only \"No matches\" was said before\nthat, so a filter that kept forty rows and one that kept one sounded the\nsame."
+            },
+            {
+              "kind": "method",
+              "name": "drawFilter",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "rows",
+                  "type": {
+                    "text": "TemplateResult"
+                  }
+                },
+                {
+                  "name": "busy",
+                  "type": {
+                    "text": "string | typeof nothing"
+                  }
+                }
+              ],
+              "description": "The field and then the `menu`, for the menu to draw in its surface. See `drawFilter`."
+            }
+          ],
+          "helix": {}
+        },
+        {
+          "kind": "function",
+          "name": "filterMenu",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "typeof HelixHeadlessMenu"
+              }
+            },
+            {
+              "name": "sheet",
+              "optional": true,
+              "type": {
+                "text": "CSSResult"
+              }
+            }
+          ],
+          "description": "Gives every menu of a class a `MenuFilterController`, which `filterable`\nturns on.\n\nThe entries call it for their own tier's class: the headless entry for\n`HelixHeadlessMenu`, and the styled one for `HelixMenu`, with the sheet that\ndraws the field. **Menus already on the page are given one too**, and drawn\nagain, so a page that imports the menu and then this entry gets the field."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "drawFilter",
+          "declaration": {
+            "name": "drawFilter",
+            "module": "src/menu/filter/menu-filter.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MenuFilterController",
+          "declaration": {
+            "name": "MenuFilterController",
+            "module": "src/menu/filter/menu-filter.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "filterMenu",
+          "declaration": {
+            "name": "filterMenu",
+            "module": "src/menu/filter/menu-filter.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/menu/index.ts",
@@ -112722,7 +113163,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The trigger is slotted and stays your own element, as with the tooltip. The\nmenu renders its surface in the top layer with the popover API, so an\nancestor with `overflow: hidden` does not clip it and it needs no `z-index`.\n\nSlot a `helix-button` or `helix-icon-button` as the trigger, and the menu\ntells it that it opens a menu and whether the menu is open, inside its own\nshadow root. On a plain element, such as a `<button>`, the menu writes\n`aria-haspopup=\"menu\"` and `aria-expanded`, from a frame after its own first\nrender, so a server's markup is never changed while a framework hydrates it.\nIt never writes `aria-expanded` where you wrote it yourself.\n\nSubmenus drill down by default. A submenu replaces the panel's content, and a\nback row returns to the previous page. One panel stays inside a narrow\nwindow, and works on touch screens, which have no hover. Focus follows a\nmouse resting on a row in either mode, and a drilled page is a `menu` named\nby the row that opened it.\n\n**`submenus=\"flyout\"` opens each submenu in a panel of its own beside its\nrow**, as React Aria's `SubmenuTrigger` and Radix's `Sub` do. Resting the\npointer on the row opens it, and a pointer crossing toward the open panel\nover the rows between keeps it open, as Radix's grace area does. Right Arrow\nopens a row's submenu on its first row, and Left Arrow or Escape closes it\nand returns focus to the row, the two arrows swapping on a right-to-left\npage. The row says `aria-expanded`, and the panel is a `menu` named by the\nrow.\n\nThe root holds which page is open, because only one page shows at a time. It\nsets this on items as a property, never as an attribute. An attribute written\nonto your element after it upgrades causes a hydration mismatch.\n\nGroup rows under a heading with `Menu.Section`, which is a `group` named by\nits heading. Between runs of rows, a `<helix-divider>` is a separator a\nscreen reader announces.\n\nKeys: Enter, Space or Down Arrow on the trigger opens the menu on its first\nrow, and Up Arrow on its last. In the menu, Up and Down Arrow move between\nrows, Home and End go to the first and the last, a typed letter moves to\nthe next row whose name starts with it, Enter and Space choose (Space on a\nchoice row changes it and leaves the menu open), Right Arrow\nopens a row's submenu and Left Arrow goes back, the two swapping on a\nright-to-left page. Left Arrow on the top page does nothing. Escape closes\nthe menu and returns focus to the trigger. Tab closes it and moves on.\n\nWhile it is open, the surface carries the trigger's width as\n`--floating-anchor-inline-size` and the room left below it as\n`--floating-available-block-size`, as Radix's dropdown menu publishes its\ntrigger's width, for a menu as wide as its trigger:\n`helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.\n\n**The choices in one place.** `checkedValues` holds the values of the rows\nthat are checked, anywhere in the menu, and setting it checks exactly\nthose rows, as React Aria's `selectedKeys` does. `change` is sent on the\nmenu when a reader's choice changes it.\n\nWith `context`, the trigger is an area and the menu is its context menu: a\nright-click, a long press, Shift+F10 or the menu key over the area opens it\nat the pointer, or at the area's corner from the keyboard, as Radix's context\nmenu does. A press on the area does not open it, and closing it returns focus\nto where it was. A touch or a pen held still on the area opens it too, on\nevery browser, since iOS sends no `contextmenu` for one.\n\n**A trigger with its own action.** With `open-on=\"long-press\"`, a press on\nthe trigger is the trigger's own, and a press held for half a second opens\nthe menu, as React Aria's `trigger=\"longPress\"` does. Alt+Down or Alt+Up\nopens it from the keyboard, and the trigger is described by\n`long-press-label`, which says so.\n\n**A filter field.** With `filterable`, the menu opens with focus in a field\nabove its rows, and typing narrows the rows of the page the keys move in,\nas React Aria's `Autocomplete` around a `Menu` does. A row is kept where its\nwords hold the filter, in any case, or where `filterMatch` says so. Each\npage starts unfiltered, and the filter is cleared as the menu closes. Where\ntyping keeps no row, the menu shows `no-results-text`. Focus stays in the\nfield: Up and Down Arrow move the highlight through the rows that are left,\nEnter chooses the highlighted row, Right Arrow opens its submenu, Left Arrow\non a submenu goes back, and Escape clears the filter and then closes the\nmenu. A screen reader hears how many rows the filter keeps\n(`results-label`). Home, End and the other keys move the caret and type. The field names\nthe highlighted row with `aria-activedescendant`, and the rows are a `menu`\nafter the field. Cancel `helix-filter` to keep every row\nshowing and narrow the rows yourself, such as by replacing them with rows\nfrom a server.",
+          "description": "The trigger is slotted and stays your own element, as with the tooltip. The\nmenu renders its surface in the top layer with the popover API, so an\nancestor with `overflow: hidden` does not clip it and it needs no `z-index`.\n\nSlot a `helix-button` or `helix-icon-button` as the trigger, and the menu\ntells it that it opens a menu and whether the menu is open, inside its own\nshadow root. On a plain element, such as a `<button>`, the menu writes\n`aria-haspopup=\"menu\"` and `aria-expanded`, from a frame after its own first\nrender, so a server's markup is never changed while a framework hydrates it.\nIt never writes `aria-expanded` where you wrote it yourself.\n\nSubmenus drill down by default. A submenu replaces the panel's content, and a\nback row returns to the previous page. One panel stays inside a narrow\nwindow, and works on touch screens, which have no hover. Focus follows a\nmouse resting on a row in either mode, and a drilled page is a `menu` named\nby the row that opened it.\n\n**`submenus=\"flyout\"` opens each submenu in a panel of its own beside its\nrow**, as React Aria's `SubmenuTrigger` and Radix's `Sub` do. Resting the\npointer on the row opens it, and a pointer crossing toward the open panel\nover the rows between keeps it open, as Radix's grace area does. Right Arrow\nopens a row's submenu on its first row, and Left Arrow or Escape closes it\nand returns focus to the row, the two arrows swapping on a right-to-left\npage. The row says `aria-expanded`, and the panel is a `menu` named by the\nrow.\n\nThe root holds which page is open, because only one page shows at a time. It\nsets this on items as a property, never as an attribute. An attribute written\nonto your element after it upgrades causes a hydration mismatch.\n\nGroup rows under a heading with `Menu.Section`, which is a `group` named by\nits heading. Between runs of rows, a `<helix-divider>` is a separator a\nscreen reader announces.\n\nKeys: Enter, Space or Down Arrow on the trigger opens the menu on its first\nrow, and Up Arrow on its last. In the menu, Up and Down Arrow move between\nrows, Home and End go to the first and the last, a typed letter moves to\nthe next row whose name starts with it, Enter and Space choose (Space on a\nchoice row changes it and leaves the menu open), Right Arrow\nopens a row's submenu and Left Arrow goes back, the two swapping on a\nright-to-left page. Left Arrow on the top page does nothing. Escape closes\nthe menu and returns focus to the trigger. Tab closes it and moves on.\n\nWhile it is open, the surface carries the trigger's width as\n`--floating-anchor-inline-size` and the room left below it as\n`--floating-available-block-size`, as Radix's dropdown menu publishes its\ntrigger's width, for a menu as wide as its trigger:\n`helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.\n\n**The choices in one place.** `checkedValues` holds the values of the rows\nthat are checked, anywhere in the menu, and setting it checks exactly\nthose rows, as React Aria's `selectedKeys` does. `change` is sent on the\nmenu when a reader's choice changes it.\n\nWith `context`, the trigger is an area and the menu is its context menu: a\nright-click, a long press, Shift+F10 or the menu key over the area opens it\nat the pointer, or at the area's corner from the keyboard, as Radix's context\nmenu does. A press on the area does not open it, and closing it returns focus\nto where it was. A touch or a pen held still on the area opens it too, on\nevery browser, since iOS sends no `contextmenu` for one.\n\n**A trigger with its own action.** With `open-on=\"long-press\"`, a press on\nthe trigger is the trigger's own, and a press held for half a second opens\nthe menu, as React Aria's `trigger=\"longPress\"` does. Alt+Down or Alt+Up\nopens it from the keyboard, and the trigger is described by\n`long-press-label`, which says so.\n\n**A filter field** is a separate import, `@fusion.dev/helix/menu/filter`, so\na menu that never filters carries none of its code:\n\n```js\nimport '@fusion.dev/helix/menu'\nimport '@fusion.dev/helix/menu/filter'\n```\n\nWith it imported and `filterable` set, the menu opens with focus in a field\nabove its rows, and typing narrows the rows of the page the keys move in,\nas React Aria's `Autocomplete` around a `Menu` does. A row is kept where its\nwords hold the filter, in any case, or where `filterMatch` says so. Each\npage starts unfiltered, and the filter is cleared as the menu closes. Where\ntyping keeps no row, the menu shows `no-results-text`. Focus stays in the\nfield: Up and Down Arrow move the highlight through the rows that are left,\nEnter chooses the highlighted row, Right Arrow opens its submenu, Left Arrow\non a submenu goes back, and Escape clears the filter and then closes the\nmenu. A screen reader hears how many rows the filter keeps\n(`results-label`). Home, End and the other keys move the caret and type. The field names\nthe highlighted row with `aria-activedescendant`, and the rows are a `menu`\nafter the field. Cancel `helix-filter` to keep every row\nshowing and narrow the rows yourself, such as by replacing them with rows\nfrom a server.",
           "name": "HelixHeadlessMenu",
           "cssProperties": [
             {
@@ -112889,7 +113330,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the menu shows a field above its rows that narrows them as the\nreader types, with focus staying in the field.",
+              "description": "Whether the menu shows a field above its rows that narrows them as the\nreader types, with focus staying in the field, once\n`@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)\nis imported. Without that import it does nothing, so a menu that never\nfilters carries none of the filter's code, and a development build says\nwhich import is missing.",
               "attribute": "filterable"
             },
             {
@@ -113244,41 +113685,21 @@
             },
             {
               "kind": "field",
-              "name": "field",
-              "type": {
-                "text": "HTMLInputElement | null"
-              },
-              "privacy": "private",
-              "description": "The filter field, with `filterable`.",
-              "readonly": true
-            },
-            {
-              "kind": "field",
-              "name": "filterPage",
-              "type": {
-                "text": "HelixHeadlessMenuItem | null"
-              },
-              "privacy": "private",
-              "default": "null",
-              "description": "The submenu the filter narrows, or null for the top page."
-            },
-            {
-              "kind": "field",
-              "name": "refused",
+              "name": "filterer",
               "type": {
-                "text": "string | undefined"
+                "text": "MenuFilterController | undefined"
               },
               "privacy": "private",
-              "description": "The filter a listener refused, which narrows nothing."
+              "description": "The filter `menu/filter` gives this menu, which `filterable` turns on.\n\nDeclared and never initialized, because the entry sets it from the\nconstructor Lit runs initializers in, which is before this class's own\nfields: an initializer here would set it back to `undefined`."
             },
             {
               "kind": "field",
-              "name": "filtering",
+              "name": "filters",
               "type": {
-                "text": "boolean"
+                "text": "MenuFilterController | undefined"
               },
               "privacy": "private",
-              "description": "Whether the filter is narrowing the rows.",
+              "description": "The filter, while `filterable` is set and `menu/filter` is imported.",
               "readonly": true
             },
             {
@@ -113298,7 +113719,7 @@
                   }
                 }
               ],
-              "description": "Whether the filter keeps a row: one of another page, or one whose words it matches."
+              "description": "Whether the filter keeps a row, which every row is without one."
             },
             {
               "kind": "method",
@@ -113317,41 +113738,7 @@
                   }
                 }
               ],
-              "description": "Asks to filter by new text, which the field and `filter` then hold. A\nrefusal keeps every row showing, for a page that narrows them itself."
-            },
-            {
-              "kind": "field",
-              "name": "handleFilterInput",
-              "privacy": "private",
-              "readonly": true
-            },
-            {
-              "kind": "method",
-              "name": "filterBy",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "value",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Filters by what the reader typed, and highlights the first row kept."
-            },
-            {
-              "kind": "field",
-              "name": "highlighted",
-              "type": {
-                "text": "HelixHeadlessMenuItem | undefined"
-              },
-              "privacy": "private",
-              "description": "The row the keys reached while focus stays in the filter field."
+              "description": "Asks to filter by new text. See `MenuFilterController.request`."
             },
             {
               "kind": "method",
@@ -113370,7 +113757,7 @@
                   }
                 }
               ],
-              "description": "Moves the reader to a row: focus, or with `filterable` the highlight,\nwhich the field names with `aria-activedescendant`. An element reference,\nbecause the field is in this shadow root and the row in the tree around\nit, the one direction a reference crosses."
+              "description": "Moves the reader to a row: focus, or with a filter the highlight, focus\nstaying in the filter field."
             },
             {
               "kind": "field",
@@ -113616,13 +114003,6 @@
               "readonly": true,
               "description": "A press on the trigger starting: the start of a held one under\n`open-on=\"long-press\"`, or a touch or a pen held on a context menu's area."
             },
-            {
-              "kind": "field",
-              "name": "handleMouseDown",
-              "privacy": "private",
-              "readonly": true,
-              "description": "Keeps focus in the filter field through a press on a row or the way\nback, as React Aria's virtual focus does: the press still chooses."
-            },
             {
               "kind": "field",
               "name": "handlePointerMove",
@@ -114559,7 +114939,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the menu shows a field above its rows that narrows them as the\nreader types, with focus staying in the field.",
+              "description": "Whether the menu shows a field above its rows that narrows them as the\nreader types, with focus staying in the field, once\n`@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)\nis imported. Without that import it does nothing, so a menu that never\nfilters carries none of the filter's code, and a development build says\nwhich import is missing.",
               "fieldName": "filterable"
             },
             {
@@ -172604,6 +172984,19 @@
               "attribute": "mode",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "nowLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Now'",
+              "description": "The words on the list's button that chooses the current time, drawn with\n`show-now`.",
+              "attribute": "now-label",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "placeholder",
@@ -172679,6 +173072,16 @@
               "description": "Whether times carry their seconds: the value is `HH:mm:ss`, a typed time\nmay give them, the field writes them, and the list's `step` counts seconds.\nSee Time Picker's `seconds`.",
               "attribute": "seconds"
             },
+            {
+              "kind": "field",
+              "name": "showNow",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Draws a button under the times in the list that chooses the current time,\nmoved to the nearest time on offer. See Time Picker's `show-now`. Its words\nare `now-label`.",
+              "attribute": "show-now"
+            },
             {
               "kind": "field",
               "name": "step",
@@ -175896,6 +176299,15 @@
               "description": "How many times the field holds at once.\n\nAbsent is one. `range` holds a start and an end, `multiple` holds any\nnumber, and both are carried as one comma-separated value, which is what a\nform submits. `TimePicker` carries the longer note on the interaction and\non why a wheel cannot do either.",
               "fieldName": "mode"
             },
+            {
+              "name": "now-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Now'",
+              "description": "The words on the list's button that chooses the current time, drawn with\n`show-now`.",
+              "fieldName": "nowLabel"
+            },
             {
               "name": "placeholder",
               "type": {
@@ -175950,6 +176362,15 @@
               "description": "Whether times carry their seconds: the value is `HH:mm:ss`, a typed time\nmay give them, the field writes them, and the list's `step` counts seconds.\nSee Time Picker's `seconds`.",
               "fieldName": "seconds"
             },
+            {
+              "name": "show-now",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Draws a button under the times in the list that chooses the current time,\nmoved to the nearest time on offer. See Time Picker's `show-now`. Its words\nare `now-label`.",
+              "fieldName": "showNow"
+            },
             {
               "name": "step",
               "type": {
@@ -200068,7 +200489,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The items arrive as data, in one of two ways:\n\n- `items` takes an array. A framework sets it as a property, and React\n  hydration keeps it.\n- `for` names a `<script type=\"application/json\">` that holds an array, which\n  a server sends as markup.\n\nEach item is drawn into a row in one of two ways:\n\n- `renderItem` is a function from an item and its index to the row's\n  content: a Lit template, a string, or a DOM node.\n- A `<template>` child defines one row. `data-field=\"name\"` fills an element\n  with the item's `name` as text, and `data-field-href=\"url\"` writes the\n  item's `url` into `href`, the same for any attribute. A field may be a path\n  of keys, such as `author.name`.\n\nRows are your markup in the light DOM, so your stylesheet styles them.\n\n**A grid.** `columns` lays the items out that many to a line, as a grid of\nequal columns, and windows the set a line at a time, as React Aria's grid\nlayout does. Each item draws one element, a cell of the grid, and\n`estimate` is the height of a line. `min-column-width` lays out as many\ncolumns as fit the box instead, as React Aria's grid layout does with its\nsmallest item size, and follows the box as it resizes. `gap` spaces the rows, and the columns\nof a grid, by a number of pixels the list counts in each row's place.\n\n**Across.** `orientation=\"horizontal\"` lays the items out along a line and\nscrolls it sideways, as a strip of cards does, windowed the same way:\n`estimate` is then an item's width, and the box needs an inline size.\n\n**Sections.** `section-field` names the field of each item that says which\nsection it is in, and the list draws a header before each section's items,\nas React Aria's list box sections do. Each section is an element with the\n`group` role, named by its header, which is its first child and carries\n`data-header`, so your stylesheet styles it, such as with `position:\nsticky`. A section starts wherever the field changes, so give the items in\norder. The window counts the headers with the items, and a section the\nwindow starts inside is drawn with its header. `renderSection` draws a\nheader of your own.\n\n**Keyboard.** The list is one tab stop.\n\n| Key | What it does |\n|---|---|\n| Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line. |\n| Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |\n| Home, End | Moves to the first or the last item. |\n| Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |\n| A letter or a word | Moves to the next item whose text starts with what you typed. |\n| Escape | Lets go of every chosen item, in a list with `selection-mode`. |\n| Alt with Up or Down | In a `reorderable` list, moves the item a place. Alt with Home or End moves it to either end. |\n| Tab | Moves into the focused row's own links and buttons, then out of the list. |\n\nAn item that is not drawn is scrolled into view and focused, so a keyboard\nreaches the whole set. The row a reader last focused keeps the tab stop and\nstays drawn when it scrolls away, so Tab and Shift+Tab come back to it, as\nReact Aria's collections do. In a list nobody has focused yet, the stop\nmoves to the first row on screen. Typing matches each item's\n`text-field`, which is the first `data-field` of the row template by default,\nor the item itself when it is a string or a number.\n\nEach row says its place in the whole set with `aria-posinset` and\n`aria-setsize`, so a screen reader says \"4,000 of 10,000\". The row holding\nfocus stays drawn when it scrolls out.\n\n**Selecting.** `selection-mode` makes the list a list box a reader chooses\nfrom: `single` selects one item and `multiple` any number. Space or a press\nselects an item, Shift with Space, an arrow, Home, End or a press takes in\nthe items from the last one chosen, and Control or Command with A selects\nthem all, in `multiple`. Escape lets go of every chosen item, and keeps the\nkey from the dialog or menu around the list while there was something to\nlet go of. `value` holds the chosen items' keys, separated by commas, in\nthe order of the set: `key-field` names each item's key, and a string or a\nnumber item is its own key. A change asks with `helix-before-change` and\ntells with `change`. Each row is an `option` marked `aria-selected`, so a\nrow's own links and buttons are not reached there: keep those to a list\nwithout `selection-mode`.\n\n`selection-behavior=\"replace\"` selects the item pressed alone, as a file\nlist does, and the arrow keys carry the selection with them. Control or\nCommand with a press or with Space adds or takes out one item, and with an\narrow moves without selecting.\n\n**Disabled items.** `disabled-keys` names items by their keys, separated by\ncommas. Their rows carry `aria-disabled`, the keys and typing pass over\nthem, and a press, Space, or Control with A does not select them.\n\n**Rows a stylesheet can tell apart.** A chosen row carries `data-selected`,\na disabled one `data-disabled`, as React Aria's rows do, and the row the\nkeys are on, which holds the tab stop, `data-active`, whether or not the\nlist has focus.\n\n**Loading more.** `helix-range-change` fires as the items on screen change,\nand `range` holds them. `helix-load-more` fires once a reader is within one\nscreen of the end, once for each length of the set: add to `items` and it can\nfire again. While you fetch, set `loading`: the list is busy, and a row after\nthe last item says \"Loading more\" (`loading-label`, or your own content in\nthe `loading` slot). `scrollToIndex` takes a reader to an item.\n\n**Moving items** is a separate import, `@fusion.dev/helix/virtual-list/reorder`,\nas React Aria's drag and drop is. With it imported, `reorderable` lets a\nreader move items in a list of one column without sections:\n\n- Alt with Up or Down moves the item the keys are on a place, and Alt with\n  Home or End to either end, as the APG's rearrangeable listbox does.\n- A pointer drags a whole row. A press that does not travel is still a\n  press. The list scrolls near an edge, and an item far down a long set is\n  reached by dragging to the edge.\n- A drop sends `helix-before-reorder`, which you can refuse, and then\n  `helix-reorder`, whose `keys` hold every item's key in the new order.\n  **You move the items**: set `items` to them in that order. The keys stay\n  on the item that moved.\n- Each move is said in a region screen readers announce. The row being\n  dragged carries `data-dragging`, and the row a drop would land beside\n  `data-drop-before` or `data-drop-after`.\n\n**An empty list.** Set `empty-label`, or put your own content in the `empty`\nslot, for a row shown when there are no items and none are loading, such as\n\"No messages yet\" and a link to write one. Without either, an empty list\nshows nothing, since a list whose items have not arrived yet has not said\nit has none.\n\nThe list takes the `empty` state while it has read its items and holds none,\nand the `loading` state while `loading` is set, so your stylesheet can\nchange the box around it for either. A list with no name is reported once\nin a development build. Name it with `label` or `aria-label`.\n\n**Row height.** Rows are placed by `estimate` until they are drawn. Then the\nlist reads the drawn rows' height once and places every row by it, so a\nwrong estimate still reaches the last item. Set `measured` for rows of\ndifferent heights. Once the list draws rows of different heights, such as\nrows that wrap on a narrow screen, it places each row by its own height\nwhether `measured` is set or not.\n\nThe list follows its source. A new `items` array, an edit to the script's\ntext, or a script replaced under the same id draws the new rows. A row that\nstays in view keeps its element as the list scrolls.\n\nThe viewport scrolls on this tier. It carries `data-scroller`, and `core`\nships `[data-scroller] { overflow: auto }` into every shadow root, so\n`scrollTop` works with no stylesheet. You still need to set a block size.",
+          "description": "The items arrive as data, in one of two ways:\n\n- `items` takes an array. A framework sets it as a property, and React\n  hydration keeps it.\n- `for` names a `<script type=\"application/json\">` that holds an array, which\n  a server sends as markup.\n\nEach item is drawn into a row in one of two ways:\n\n- `renderItem` is a function from an item and its index to the row's\n  content: a Lit template, a string, or a DOM node.\n- A `<template>` child defines one row. `data-field=\"name\"` fills an element\n  with the item's `name` as text, and `data-field-href=\"url\"` writes the\n  item's `url` into `href`, the same for any attribute. A field may be a path\n  of keys, such as `author.name`.\n\nRows are your markup in the light DOM, so your stylesheet styles them.\n\n**A grid.** `columns` lays the items out that many to a line, as a grid of\nequal columns, and windows the set a line at a time, as React Aria's grid\nlayout does. Each item draws one element, a cell of the grid, and\n`estimate` is the height of a line. `min-column-width` lays out as many\ncolumns as fit the box instead, as React Aria's grid layout does with its\nsmallest item size, and follows the box as it resizes. `gap` spaces the rows, and the columns\nof a grid, by a number of pixels the list counts in each row's place.\n\nA grid without `selection-mode` is a grid to a reader, as the APG's grid\nand React Aria's grid list are: the box is a `grid` with `aria-rowcount`\nand `aria-colcount`, each line drawn is a `row` with `aria-rowindex`, and\neach item a `gridcell` with `aria-colindex`. Each line is a slot of the\nlist's own, so your rows stay its children: give an item one element. With\n`selection-mode` it stays a list box of options, as React Aria's list box\nin a grid layout does.\n\n**A waterfall.** `layout=\"waterfall\"` puts each item, in the order of the\nset, under the column that ends highest so far, the leftmost of a tie, as a\nwall of photos of different heights is, and as React Aria's waterfall\nlayout and TanStack Virtual's lanes do. `columns`, or `min-column-width`,\nsays how many columns. Every item is measured, at the width of its column,\nand placed at its column and its height, so items of any height leave no\nholes. The list draws the items that reach into the box, and the item\nholding focus. A reader hears a list, or a list box, in the order of the\nset, which is also the order Tab and a screen reader's own keys take.\n\nIn a waterfall, Down and Up move along the column to the next or the\nprevious item in it, Right and Left move to the next or the previous\ncolumn, to the item there that sits beside this one the most, or the\nnearest above where none does, and Page Down and Page Up move a box down\nor up the column. Home and End go to the first and the last item of the\nset, and Shift with a key takes in the items between in the order of the\nset.\n\n**Across.** `orientation=\"horizontal\"` lays the items out along a line and\nscrolls it sideways, as a strip of cards does, windowed the same way:\n`estimate` is then an item's width, and the box needs an inline size.\n\n**Sections.** `section-field` names the field of each item that says which\nsection it is in, and the list draws a header before each section's items,\nas React Aria's list box sections do. Each section is an element with the\n`group` role, named by its header, which is its first child and carries\n`data-header`, so your stylesheet styles it, such as with `position:\nsticky`. A section starts wherever the field changes, so give the items in\norder. The window counts the headers with the items, and a section the\nwindow starts inside is drawn with its header. `renderSection` draws a\nheader of your own.\n\n**Keyboard.** The list is one tab stop.\n\n| Key | What it does |\n|---|---|\n| Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line, or in a waterfall to the next or the previous item down the same column. |\n| Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a waterfall, moves to the item beside in the next or the previous column. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |\n| Home, End | Moves to the first or the last item. In a grid without `selection-mode`, to the first or the last item of the line. |\n| Control or Command with Home or End | In a grid without `selection-mode`, moves to the first or the last item. |\n| Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen, or in a waterfall a box down or up the column. |\n| A letter or a word | Moves to the next item whose text starts with what you typed. |\n| Escape | Lets go of every chosen item, in a list with `selection-mode`. |\n| Alt with Up or Down | In a `reorderable` list, moves the item a place. Alt with Home or End moves it to either end. |\n| Tab | Moves into the focused row's own links and buttons, then out of the list. |\n\nAn item that is not drawn is scrolled into view and focused, so a keyboard\nreaches the whole set. The row a reader last focused keeps the tab stop and\nstays drawn when it scrolls away, so Tab and Shift+Tab come back to it, as\nReact Aria's collections do. In a list nobody has focused yet, the stop\nmoves to the first row on screen. Typing matches each item's\n`text-field`, which is the first `data-field` of the row template by default,\nor the item itself when it is a string or a number.\n\nEach row says its place in the whole set with `aria-posinset` and\n`aria-setsize`, so a screen reader says \"4,000 of 10,000\", and each cell of\na grid its line and its column. The row holding focus stays drawn when it\nscrolls out.\n\n**Selecting.** `selection-mode` makes the list a list box a reader chooses\nfrom: `single` selects one item and `multiple` any number. Space or a press\nselects an item, Shift with Space, an arrow, Home, End or a press takes in\nthe items from the last one chosen, and Control or Command with A selects\nthem all, in `multiple`. Escape lets go of every chosen item, and keeps the\nkey from the dialog or menu around the list while there was something to\nlet go of. `value` holds the chosen items' keys, separated by commas, in\nthe order of the set: `key-field` names each item's key, and a string or a\nnumber item is its own key. A change asks with `helix-before-change` and\ntells with `change`. Each row is an `option` marked `aria-selected`, so a\nrow's own links and buttons are not reached there: keep those to a list\nwithout `selection-mode`.\n\n`selection-behavior=\"replace\"` selects the item pressed alone, as a file\nlist does, and the arrow keys carry the selection with them. Control or\nCommand with a press or with Space adds or takes out one item, and with an\narrow moves without selecting.\n\n**Disabled items.** `disabled-keys` names items by their keys, separated by\ncommas. Their rows carry `aria-disabled`, the keys and typing pass over\nthem, and a press, Space, or Control with A does not select them.\n\n**Rows a stylesheet can tell apart.** A chosen row carries `data-selected`,\na disabled one `data-disabled`, as React Aria's rows do, and the row the\nkeys are on, which holds the tab stop, `data-active`, whether or not the\nlist has focus.\n\n**Loading more.** `helix-range-change` fires as the items on screen change,\nand `range` holds them. `helix-load-more` fires once a reader is within one\nscreen of the end, once for each length of the set: add to `items` and it can\nfire again. While you fetch, set `loading`: the list is busy, and a row after\nthe last item says \"Loading more\" (`loading-label`, or your own content in\nthe `loading` slot). `scrollToIndex` takes a reader to an item.\n\n**Moving items** is a separate import, `@fusion.dev/helix/virtual-list/reorder`,\nas React Aria's drag and drop is. With it imported, `reorderable` lets a\nreader move items in a list of one column without sections:\n\n- Alt with Up or Down moves the item the keys are on a place, and Alt with\n  Home or End to either end, as the APG's rearrangeable listbox does.\n- A pointer drags a whole row. A press that does not travel is still a\n  press. The list scrolls near an edge, and an item far down a long set is\n  reached by dragging to the edge.\n- A drop sends `helix-before-reorder`, which you can refuse, and then\n  `helix-reorder`, whose `keys` hold every item's key in the new order.\n  **You move the items**: set `items` to them in that order. The keys stay\n  on the item that moved.\n- Each move is said in a region screen readers announce. The row being\n  dragged carries `data-dragging`, and the row a drop would land beside\n  `data-drop-before` or `data-drop-after`.\n\n**An empty list.** Set `empty-label`, or put your own content in the `empty`\nslot, for a row shown when there are no items and none are loading, such as\n\"No messages yet\" and a link to write one. Without either, an empty list\nshows nothing, since a list whose items have not arrived yet has not said\nit has none.\n\nThe list takes the `empty` state while it has read its items and holds none,\nand the `loading` state while `loading` is set, so your stylesheet can\nchange the box around it for either. A list with no name is reported once\nin a development build. Name it with `label` or `aria-label`.\n\n**Row height.** Rows are placed by `estimate` until they are drawn. Then the\nlist reads the drawn rows' height once and places every row by it, so a\nwrong estimate still reaches the last item. Set `measured` for rows of\ndifferent heights. Once the list draws rows of different heights, such as\nrows that wrap on a narrow screen, it places each row by its own height\nwhether `measured` is set or not.\n\nThe list follows its source. A new `items` array, an edit to the script's\ntext, or a script replaced under the same id draws the new rows. A row that\nstays in view keeps its element as the list scrolls.\n\nThe viewport scrolls on this tier. It carries `data-scroller`, and `core`\nships `[data-scroller] { overflow: auto }` into every shadow root, so\n`scrollTop` works with no stylesheet. You still need to set a block size.",
           "name": "HelixHeadlessVirtualList",
           "cssParts": [
             {
@@ -200220,6 +200641,16 @@
               "description": "The list's name, read by screen readers, because only some of its rows\nare rendered at a time.\n\nAn `aria-label` or `aria-labelledby` on the host names the list too, and\nwins over this.",
               "attribute": "label"
             },
+            {
+              "kind": "field",
+              "name": "layout",
+              "type": {
+                "text": "'grid' | 'waterfall'"
+              },
+              "default": "'grid'",
+              "description": "How items of more than one column are laid out. `grid`, the default, puts\nthem in lines of equal columns. `waterfall` puts each item, in the order\nof the set, under the column that ends highest, as a wall of photos of\ndifferent heights is: `columns`, or `min-column-width`, says how many\ncolumns. Rows of a waterfall are measured, and Up and Down move along a\ncolumn.",
+              "attribute": "layout"
+            },
             {
               "kind": "field",
               "name": "loading",
@@ -200270,7 +200701,7 @@
                 "text": "'horizontal' | 'vertical'"
               },
               "default": "'vertical'",
-              "description": "Which way the list runs. `horizontal` lays the items out along a line\nand scrolls it sideways: Left and Right move between items, the other\nway round on a right-to-left page, and `estimate` is an item's width. A\ngrid always runs down.",
+              "description": "Which way the list runs. `horizontal` lays the items out along a line\nand scrolls it sideways: Left and Right move between items, the other\nway round on a right-to-left page, and `estimate` is an item's width. A\ngrid and a waterfall always run down.",
               "attribute": "orientation"
             },
             {
@@ -200296,7 +200727,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`\n(or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt\nwith an arrow moves the row the keys are on, and a pointer drags a row.\nThe list moves no item itself: you move your `items` on `helix-reorder`.\nWithout that import it does nothing, so a list that never moves items\ncarries none of the code. A list of one column, without sections.",
+              "description": "Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`\n(or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt\nwith an arrow moves the row the keys are on, and a pointer drags a row.\nThe list moves no item itself: you move your `items` on `helix-reorder`.\nWithout that import it does nothing, so a list that never moves items\ncarries none of the code. A list of one column, without sections or a\nwaterfall.",
               "attribute": "reorderable"
             },
             {
@@ -200481,7 +200912,7 @@
               "name": "virtualize",
               "privacy": "private",
               "readonly": true,
-              "default": "new VirtualizeController(this, { container: () => this.partNamed('viewport'), count: () => this.sections ? this.data.length + this.sections.starts.length : Math.ceil(this.data.length / this.across), estimate: () => this.estimate, gap: () => this.space, horizontal: () => this.horizontal, measured: () => this.measured, rows: () => this.lines(), })"
+              "default": "new VirtualizeController(this, { container: () => this.partNamed('viewport'), count: () => this.sections ? this.data.length + this.sections.starts.length : Math.ceil(this.data.length / this.across), estimate: () => this.estimate, gap: () => this.space, horizontal: () => this.horizontal, measured: () => this.measured, rows: () => this.lines(), waterfall: () => { this.lanes.lanes = this.columnCount return this.waterfall ? this.lanes : undefined }, })"
             },
             {
               "kind": "field",
@@ -200502,6 +200933,34 @@
               "description": "The gap in pixels, none where it is not a positive number.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "lanes",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Waterfall()",
+              "description": "Where each item of a waterfall stands, which the controller places."
+            },
+            {
+              "kind": "field",
+              "name": "waterfall",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the items are laid out as a waterfall, each down a column.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "lined",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the list is a grid a reader reads, and not a list box: lines of\ncolumns with no `selection-mode`, which are `grid`, `row` and `gridcell`\nto a reader, as the APG's grid and React Aria's grid list are.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "across",
@@ -200509,7 +200968,17 @@
                 "text": "number"
               },
               "privacy": "private",
-              "description": "How many items a line holds: as many as fit at `min-column-width` where\nit is set and the box has a width, and `columns` otherwise, at least one.",
+              "description": "How many items a line holds, which a waterfall draws one at a time: its\ncolumns are not lines.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "columnCount",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "description": "How many columns there are: as many as fit at `min-column-width` where\nit is set and the box has a width, and `columns` otherwise, at least one.",
               "readonly": true
             },
             {
@@ -200535,11 +201004,11 @@
               "kind": "field",
               "name": "measuredAcross",
               "type": {
-                "text": "number"
+                "text": "number | string"
               },
               "privacy": "private",
               "default": "1",
-              "description": "The items to a line the measurements were taken at."
+              "description": "The items to a line the measurements were taken at, or a waterfall's columns and width."
             },
             {
               "kind": "method",
@@ -200550,7 +201019,7 @@
                   "text": "void"
                 }
               },
-              "description": "Watches the box for its width while `min-column-width` asks for it."
+              "description": "Watches the box for its width while `min-column-width` asks for it, or a\nwaterfall, whose items are as tall as their width makes them."
             },
             {
               "kind": "method",
@@ -200597,7 +201066,7 @@
                 "text": "boolean"
               },
               "privacy": "private",
-              "description": "Whether the list runs across, which a grid never does.",
+              "description": "Whether the list runs across, which a grid and a waterfall never do.",
               "readonly": true
             },
             {
@@ -200861,6 +201330,43 @@
               "readonly": true,
               "description": "Moves between items with the keys `stepIndex` names.\n\nOnly from a row itself. A key pressed in a row's own link, button or field\nis that control's, so a field in a row keeps its arrows."
             },
+            {
+              "kind": "method",
+              "name": "inWaterfall",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "forward",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Where a key goes in a waterfall, through the columns `Waterfall.step`\nreads: along the column for Down, Up, Page Down and Page Up, and to the\nitem beside in the next column or the one before for the keys along the\nline, the other way round on a right-to-left page. Past a disabled item,\non the same way."
+            },
             {
               "kind": "method",
               "name": "keyAt",
@@ -201052,7 +201558,7 @@
                   }
                 }
               ],
-              "description": "Writes a row's role, and whether it is chosen in a list that selects:\n`option` with `aria-selected` there, and `listitem` otherwise, and\n`aria-disabled` on an item `disabled-keys` names. Every pass,\nsince a choice changes no row's content.\n\n`data-selected` and `data-disabled` say the same to a stylesheet, as\nReact Aria's rows do, so one rule reads the same in either kind of list."
+              "description": "Writes a row's role, and whether it is chosen in a list that selects:\n`option` with `aria-selected` there, `gridcell` in a grid, and `listitem`\notherwise, and `aria-disabled` on an item `disabled-keys` names. Every\npass, since a choice changes no row's content.\n\nIts place too: `aria-posinset` and `aria-setsize` in a list, and in a\ngrid its column, with the line's `row` given by the slot it is drawn in.\n\n`data-selected` and `data-disabled` say the same to a stylesheet, as\nReact Aria's rows do, so one rule reads the same in either kind of list."
             },
             {
               "kind": "method",
@@ -201077,7 +201583,7 @@
                   }
                 }
               ],
-              "description": "Writes a row's place in the set."
+              "description": "Writes which item a row drew, for the controller to measure it against:\nthe real index, the same one `aria-posinset` carries one higher.\n\n`mark` writes the place a reader hears from it, the real index and the\nreal total, not the position in the window. A reader arrowing through\nthis should hear where they are in the set."
             },
             {
               "kind": "method",
@@ -201149,6 +201655,26 @@
               "privacy": "private",
               "description": "The sections the rows were last placed in."
             },
+            {
+              "kind": "field",
+              "name": "placedWaterfall",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the rows were last placed in a waterfall."
+            },
+            {
+              "kind": "field",
+              "name": "drawnLines",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The lines of a grid drawn on the last pass, each a `row` the render draws a slot in."
+            },
             {
               "kind": "field",
               "name": "headedBy",
@@ -201676,6 +202202,15 @@
               "description": "The list's name, read by screen readers, because only some of its rows\nare rendered at a time.\n\nAn `aria-label` or `aria-labelledby` on the host names the list too, and\nwins over this.",
               "fieldName": "label"
             },
+            {
+              "name": "layout",
+              "type": {
+                "text": "'grid' | 'waterfall'"
+              },
+              "default": "'grid'",
+              "description": "How items of more than one column are laid out. `grid`, the default, puts\nthem in lines of equal columns. `waterfall` puts each item, in the order\nof the set, under the column that ends highest, as a wall of photos of\ndifferent heights is: `columns`, or `min-column-width`, says how many\ncolumns. Rows of a waterfall are measured, and Up and Down move along a\ncolumn.",
+              "fieldName": "layout"
+            },
             {
               "name": "loading",
               "type": {
@@ -201718,7 +202253,7 @@
                 "text": "'horizontal' | 'vertical'"
               },
               "default": "'vertical'",
-              "description": "Which way the list runs. `horizontal` lays the items out along a line\nand scrolls it sideways: Left and Right move between items, the other\nway round on a right-to-left page, and `estimate` is an item's width. A\ngrid always runs down.",
+              "description": "Which way the list runs. `horizontal` lays the items out along a line\nand scrolls it sideways: Left and Right move between items, the other\nway round on a right-to-left page, and `estimate` is an item's width. A\ngrid and a waterfall always run down.",
               "fieldName": "orientation"
             },
             {
@@ -201727,7 +202262,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`\n(or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt\nwith an arrow moves the row the keys are on, and a pointer drags a row.\nThe list moves no item itself: you move your `items` on `helix-reorder`.\nWithout that import it does nothing, so a list that never moves items\ncarries none of the code. A list of one column, without sections.",
+              "description": "Lets a reader move items, once `@fusion.dev/helix/virtual-list/reorder`\n(or `@fusion.dev/helix-headless/virtual-list/reorder`) is imported: Alt\nwith an arrow moves the row the keys are on, and a pointer drags a row.\nThe list moves no item itself: you move your `items` on `helix-reorder`.\nWithout that import it does nothing, so a list that never moves items\ncarries none of the code. A list of one column, without sections or a\nwaterfall.",
               "fieldName": "reorderable"
             },
             {
@@ -202020,6 +202555,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-headless",
-    "version": "0.182.2"
+    "version": "0.184.0"
   }
 }