@fusion.dev/helix-headless 0.165.0 → 0.166.0

package/custom-elements.json

@@ -12964,6 +12964,21 @@
               ],
               "description": "The dismiss button's name: `dismissLabel` with the heading's words, or the\ntone's name.\n\nThe heading is read from the children, so a server and a hydrating render\nname the button for the tone, and the update after names it for the\nheading."
             },
+            {
+              "kind": "method",
+              "name": "dismissEvent",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "HelixDismissEvent"
+                }
+              },
+              "description": "The event a dismissal sends, naming the note by its heading where it has\none, the words its dismiss button is named by, and otherwise by its text.",
+              "inheritedFrom": {
+                "name": "MixinDismissible",
+                "module": "src/mixins/mixin-dismissible/mixin-dismissible.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "journey",
@@ -12997,21 +13012,6 @@
                 "module": "src/mixins/mixin-dismissible/mixin-dismissible.ts"
               }
             },
-            {
-              "kind": "method",
-              "name": "dismissEvent",
-              "privacy": "protected",
-              "return": {
-                "type": {
-                  "text": "HelixDismissEvent"
-                }
-              },
-              "description": "The event, built and not dispatched.\n\nReading text is safe here: nothing calls this on a server, because the\nonly things that do are a press and a timer.",
-              "inheritedFrom": {
-                "name": "MixinDismissible",
-                "module": "src/mixins/mixin-dismissible/mixin-dismissible.ts"
-              }
-            },
             {
               "kind": "field",
               "name": "returnFocusTo",
@@ -30939,7 +30939,7 @@
       "declarations": [
         {
           "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. 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.",
+          "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. 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.",
           "name": "HelixHeadlessCodeBlock",
           "cssProperties": [
             {
@@ -31056,6 +31056,14 @@
               "description": "In a diff, one file's header and block.",
               "name": "file"
             },
+            {
+              "description": "One file tab, `aria-selected` while its file is shown.",
+              "name": "file-tab"
+            },
+            {
+              "description": "The file tabs over the blocks a block holds, where there are several.",
+              "name": "files"
+            },
             {
               "description": "In a split diff, the empty row opposite a line the other side does not have.",
               "name": "filler"
@@ -31271,6 +31279,28 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "file",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The name of the file shown, where the block holds several Code Blocks:\nthe `label` of one, or its `language` without one.\n\nUnset, or a name no file has, shows the first.",
+              "attribute": "file"
+            },
+            {
+              "kind": "field",
+              "name": "filesLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Files'",
+              "description": "The name of the file tabs, read by screen readers.",
+              "attribute": "files-label",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "hideUnchangedLabel",
@@ -31590,6 +31620,119 @@
               },
               "description": "Places each mark behind its run of lines, and makes each number in a\nwrapping gutter as tall as its line, from where the lines are laid out.\n\n**Written onto the elements as custom properties**, which are facts the\nblock computed and CSS cannot, and no render follows from them."
             },
+            {
+              "kind": "field",
+              "name": "blocks",
+              "type": {
+                "text": "HelixHeadlessCodeBlock[]"
+              },
+              "privacy": "private",
+              "description": "The Code Blocks this block holds as its code, once its children can be read.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "tabbed",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the block is one of several files under another block's tabs,\nwhich name it. Read from the parent, so a block needs no telling.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "shownFile",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HelixHeadlessCodeBlock | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "blocks",
+                  "type": {
+                    "text": "HelixHeadlessCodeBlock[]"
+                  }
+                }
+              ],
+              "description": "The file shown among several: the one `file` names, or the first."
+            },
+            {
+              "kind": "method",
+              "name": "chooseFile",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "block",
+                  "type": {
+                    "text": "HelixHeadlessCodeBlock"
+                  }
+                }
+              ],
+              "description": "Shows the file a tab names, once nobody refused."
+            },
+            {
+              "kind": "field",
+              "name": "handleFileKey",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Arrow keys, `Home` and `End` on the file tabs, which move to a tab and\nshow its file, as a tab list that follows focus does and as Sandbox's file\ntabs do. Left and Right swap on a right-to-left page."
+            },
+            {
+              "kind": "field",
+              "name": "hid",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Set<Element>()",
+              "description": "The blocks this element hid, to show them again."
+            },
+            {
+              "kind": "field",
+              "name": "fileCount",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "How many files the block last held, so each is told when that changes."
+            },
+            {
+              "kind": "method",
+              "name": "showFile",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Hides the files not shown, shows any this element hid that is now, and\ntells each file when how many there are changes, since a file draws its\nown name only while it is alone."
+            },
+            {
+              "kind": "method",
+              "name": "renderFiles",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "blocks",
+                  "type": {
+                    "text": "HelixHeadlessCodeBlock[]"
+                  }
+                }
+              ],
+              "description": "The tabs over several files, and the file shown under them. One file\ndraws no tabs, only itself."
+            },
             {
               "kind": "method",
               "name": "renderExpand",
@@ -31642,6 +31785,10 @@
                   "type": {
                     "text": "string"
                   }
+                },
+                {
+                  "name": "drawn",
+                  "default": "name"
                 }
               ],
               "description": "The name with the copy button beside it, or nothing when there is no name.\n\n**The button is in the header wherever there is one**, because beside the\ncode it stands over the block and the block has to make room for it. A\ndiff cannot: its washes run to the edge, so the button stood on the hunk\nline and the line under it. In the header it is over nothing.\n\n**No name draws no header**, unless the page put a control in `actions`\nor asked for the wrap button. A bar holding the copy button alone turned a\n`Usage` section of one-line imports into a run of empty strips. The button\nthen stands beside the code, in room the block keeps for it."
@@ -32208,6 +32355,22 @@
             }
           ],
           "events": [
+            {
+              "type": {
+                "text": "Event"
+              },
+              "description": "A file tab showed its file, whose name `file` now holds.",
+              "name": "change",
+              "reactProp": "onchange"
+            },
+            {
+              "type": {
+                "text": "HelixBeforeChangeEvent"
+              },
+              "description": "A file tab is about to show its file, with the file's name in `detail.value`. Cancelable: cancel it to keep the file shown.",
+              "name": "helix-before-change",
+              "reactProp": "onhelix-before-change"
+            },
             {
               "type": {
                 "text": "HelixBeforeToggleEvent"
@@ -32216,6 +32379,22 @@
               "name": "helix-before-toggle",
               "reactProp": "onhelix-before-toggle"
             },
+            {
+              "type": {
+                "text": "HelixCopyEvent"
+              },
+              "description": "The copy button put the code on the clipboard, with the text in `detail.value`.",
+              "name": "helix-copy",
+              "reactProp": "onhelix-copy"
+            },
+            {
+              "type": {
+                "text": "HelixCopyErrorEvent"
+              },
+              "description": "A press on the copy button put nothing on the clipboard: the browser did not allow the write, or there was no code.",
+              "name": "helix-copy-error",
+              "reactProp": "onhelix-copy-error"
+            },
             {
               "type": {
                 "text": "HelixToggleEvent"
@@ -32315,6 +32494,23 @@
               "description": "The expand button's words while the cap hides lines.",
               "fieldName": "expandLabel"
             },
+            {
+              "name": "file",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The name of the file shown, where the block holds several Code Blocks:\nthe `label` of one, or its `language` without one.\n\nUnset, or a name no file has, shows the first.",
+              "fieldName": "file"
+            },
+            {
+              "name": "files-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Files'",
+              "description": "The name of the file tabs, read by screen readers.",
+              "fieldName": "filesLabel"
+            },
             {
               "name": "hide-unchanged-label",
               "type": {
@@ -32419,6 +32615,10 @@
               "description": "The expand button has shown every line of a capped block.",
               "name": "expanded"
             },
+            {
+              "description": "The block is one of several files under another block's tabs, which name it, so it draws no name of its own.",
+              "name": "tabbed"
+            },
             {
               "description": "Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.",
               "name": "settled",
@@ -67827,6 +68027,10 @@
               "description": "Shown while the fields are loading.",
               "name": "menu-loading"
             },
+            {
+              "description": "The inner menu's filter field, drawn with `filterable`.",
+              "name": "menu-search-field"
+            },
             {
               "description": "The floating panel the menu is drawn on.",
               "name": "menu-surface"
@@ -107397,7 +107601,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "One element covers three kinds of row, and what you give it decides which:\n- Content in the `submenu` slot makes the row open a submenu page.\n- `checked` makes the row a choice.\n- With neither, the row is a command.\n\nThe role follows the kind. A row with `checkable` or `checked` is\n`menuitemcheckbox` with `aria-checked`, and an `exclusive` row is\n`menuitemradio`, for a set where only one can be on. A row that opens a page\nkeeps `menuitem` and sets `aria-haspopup`.\n\nChoosing a choice row checks or unchecks it before `helix-select` is sent,\nso a listener reads the new `checked`. An `exclusive` row turns on and turns\noff the `exclusive` rows next to it. Cancel `helix-before-toggle` to keep a\nrow as it is and set `checked` yourself.\n\nSpace on a choice row changes it and leaves the menu open, so a reader can\nset several in a row, as the APG's menu does. Enter and a press change it and\nclose the menu. `close-on-select=\"false\"` on the row keeps the menu open after\nany choice of it, and `close-on-select` on the row closes it after a Space as\nwell.\n\nThe menu sets whether the row's page is showing as a property, never as an\nattribute. An attribute written onto your element after it upgrades causes a\nhydration mismatch.\n\n`shortcut` shows a row's keyboard shortcut after its label, drawn by `Kbd`\nin the platform's glyphs, and gives the row `aria-keyshortcuts`. It binds\nnothing: the shortcut is the page's to bind. Other trailing words, such as a\ncount, go in the `end` slot.\n\nThe row is named by its label alone. Words in `description`, a line under the\nlabel, and in `end` describe it instead, through `aria-describedby`, as\nReact Aria's menu item does with its description: a reader hears \"Copy\",\nthen \"Copies the selection\".\n\nA development build warns when a row has no words to be named by, such as a\nrow holding only an icon with no label.\n\nThe check mark and the caret are the fallbacks of the `check` and `chevron`\nslots, so a mark of your own replaces either by being slotted. Neither is\nread as part of the row's name.",
+          "description": "One element covers three kinds of row, and what you give it decides which:\n- Content in the `submenu` slot makes the row open a submenu page.\n- `checked` makes the row a choice.\n- With neither, the row is a command.\n\nThe role follows the kind. A row with `checkable` or `checked` is\n`menuitemcheckbox` with `aria-checked`, and an `exclusive` row is\n`menuitemradio`, for a set where only one can be on. A row that opens a page\nkeeps `menuitem` and sets `aria-haspopup`.\n\nChoosing a choice row checks or unchecks it before `helix-select` is sent,\nso a listener reads the new `checked`. An `exclusive` row turns on and turns\noff the `exclusive` rows next to it. Cancel `helix-before-toggle` to keep a\nrow as it is and set `checked` yourself.\n\nSpace on a choice row changes it and leaves the menu open, so a reader can\nset several in a row, as the APG's menu does. Enter and a press change it and\nclose the menu. `close-on-select=\"false\"` on the row keeps the menu open after\nany choice of it, and `close-on-select` on the row closes it after a Space as\nwell.\n\nThe menu sets whether the row's page is showing as a property, never as an\nattribute. An attribute written onto your element after it upgrades causes a\nhydration mismatch.\n\n`shortcut` shows a row's keyboard shortcut after its label, drawn by `Kbd`\nin the platform's glyphs, and gives the row `aria-keyshortcuts`. It binds\nnothing: the shortcut is the page's to bind. Other trailing words, such as a\ncount, go in the `end` slot.\n\nThe row is named by its label alone. Words in `description`, a line under the\nlabel, and in `end` describe it instead, through `aria-describedby`, as\nReact Aria's menu item does with its description: a reader hears \"Copy\",\nthen \"Copies the selection\".\n\nA development build warns when a row has no words to be named by, such as a\nrow holding only an icon with no label.\n\nThe check mark and the caret are the fallbacks of the `check` and `chevron`\nslots, so a mark of your own replaces either by being slotted. Neither is\nread as part of the row's name.\n\nIn a menu with `filterable`, focus stays in the menu's filter field and the\nrow the arrow keys reach is highlighted: the field names it with\n`aria-activedescendant`, the row carries its role on its host so the field\ncan point at it, and `:state(highlighted)` says which row it is. A row with\nan `href` then follows its link without an anchor, as `Option` does.",
           "name": "HelixHeadlessMenuItem",
           "cssParts": [
             {
@@ -107665,7 +107869,7 @@
               "kind": "field",
               "name": "describedBy",
               "type": {
-                "text": "string | typeof nothing"
+                "text": "string | null"
               },
               "privacy": "private",
               "description": "What describes the row: the line under its label and the words after it.",
@@ -107835,6 +108039,16 @@
               ],
               "description": "The trailing mark: the caret of a row that opens a page, or the tick of a\nchecked one, each the fallback of a slot a mark of your own replaces.\n\nOne trailing column, and a row is never both: a way into a page has nothing\nto tick, and a choice opens nothing. The tick sits after the label rather\nthan before it, so the labels start at the edge of the row and the marks\nline up down the side they are read from.\n\n`data-mirror` is what tells the two apart. They share a part name because\nthey share a column, and only one of them is directional: a caret has to\nmirror in a right-to-left document and a tick must not, which Unicode's own\nmirroring list agrees on. The attribute is on an element in this shadow\nroot rather than on the host, so it is the divider's `data-empty` and not a\nhydration hazard.\n\nNothing to mark, so nothing is drawn. The column this would have sat in is\nreserved by the menu when some row on the page needs one, so the labels\nstill line up without every row carrying an empty box to line them up with."
             },
+            {
+              "kind": "field",
+              "name": "onHost",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the row says what it is from its host, for a field's `aria-activedescendant`.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -108298,6 +108512,10 @@
               "description": "The row is checked.",
               "name": "checked"
             },
+            {
+              "description": "In a menu with `filterable`, the arrow keys or the pointer reached the row while focus stays in the filter field.",
+              "name": "highlighted"
+            },
             {
               "description": "Under `submenus=\"flyout\"`, a row in this row's submenu can be ticked or opens a submenu, so the submenu keeps its trailing column.",
               "name": "submenu-mark"
@@ -108366,7 +108584,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.\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\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.",
+          "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.\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\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. 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": [
             {
@@ -108404,7 +108622,11 @@
               "name": "loading"
             },
             {
-              "description": "The floating panel the menu is drawn on.",
+              "description": "With `filterable`, the field that narrows the rows.",
+              "name": "search-field"
+            },
+            {
+              "description": "The floating panel the menu is drawn on. It is the `menu` itself, and with `filterable` it holds the filter field and then the `menu`.",
               "name": "surface"
             },
             {
@@ -108417,6 +108639,10 @@
               "description": "The items.",
               "name": ""
             },
+            {
+              "description": "What the menu shows when the filter keeps no rows, for content richer than `no-results-text`.",
+              "name": "no-results"
+            },
             {
               "description": "The control that opens the menu, or with `context` the area a context menu opens over.",
               "name": "trigger"
@@ -108471,6 +108697,47 @@
               "attribute": "context",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "filter",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The text the rows are filtered by, which the filter field holds.\n\nCleared as the menu closes and as a submenu opens or closes, so each page\nstarts with every row showing.",
+              "attribute": "filter"
+            },
+            {
+              "kind": "field",
+              "name": "filterable",
+              "type": {
+                "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.",
+              "attribute": "filterable"
+            },
+            {
+              "kind": "field",
+              "name": "filterLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Filter'",
+              "description": "The filter field's name and placeholder.",
+              "attribute": "filter-label",
+              "helix": {
+                "words": true
+              }
+            },
+            {
+              "kind": "field",
+              "name": "filterMatch",
+              "type": {
+                "text": "((text: string, filter: string) => boolean) | undefined | undefined"
+              },
+              "description": "Whether a row is kept by the filter: a function given the row's words and\nthe filter, trimmed, that returns `true` to keep it showing, as React\nAria's `Autocomplete` takes `filter`. See Listbox's `filterMatch`.\n\nAbsent, a row is kept where its words hold the filter, in any case. A\nproperty only, there being no way to write a function in markup."
+            },
             {
               "kind": "field",
               "name": "label",
@@ -108591,6 +108858,19 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "noResultsText",
+              "type": {
+                "text": "string"
+              },
+              "default": "'No matches'",
+              "description": "The text shown when the filter keeps no rows.",
+              "attribute": "no-results-text",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "offset",
@@ -108679,7 +108959,7 @@
               "name": "aria",
               "privacy": "protected",
               "readonly": true,
-              "default": "new AriaForwardController(this, { label: true, target: () => this.partNamed('surface'), })",
+              "default": "new AriaForwardController(this, { label: true, target: () => this.menuBox, })",
               "description": "Carries a host `aria-label` and `aria-labelledby` to the surface."
             },
             {
@@ -108757,6 +109037,146 @@
               "description": "The items on the page that is showing, which is what the keys move over.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "menuBox",
+              "type": {
+                "text": "HTMLElement | null"
+              },
+              "privacy": "private",
+              "description": "The element that is the `menu`: the surface, or with `filterable` the box after the field.",
+              "readonly": true
+            },
+            {
+              "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",
+              "type": {
+                "text": "string | undefined"
+              },
+              "privacy": "private",
+              "description": "The filter a listener refused, which narrows nothing."
+            },
+            {
+              "kind": "field",
+              "name": "filtering",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the filter is narrowing the rows.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "kept",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "row",
+                  "type": {
+                    "text": "HelixHeadlessMenuItem"
+                  }
+                }
+              ],
+              "description": "Whether the filter keeps a row: one of another page, or one whose words it matches."
+            },
+            {
+              "kind": "method",
+              "name": "requestFilter",
+              "privacy": "private",
+              "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": "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."
+            },
+            {
+              "kind": "method",
+              "name": "reach",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "row",
+                  "type": {
+                    "text": "HelixHeadlessMenuItem | undefined"
+                  }
+                }
+              ],
+              "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."
+            },
             {
               "kind": "method",
               "name": "show",
@@ -108871,6 +109291,25 @@
               "readonly": true,
               "description": "Keeps whatever has focus in sight, however it got there.\n\nOn `focusin` rather than in the branches that move focus: a row reached by\nTab, or focused by the drilldown on the way into a page, can otherwise sit\nbelow the fold of a scrolled panel."
             },
+            {
+              "kind": "method",
+              "name": "revealRow",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "item",
+                  "type": {
+                    "text": "HelixHeadlessMenuItem"
+                  }
+                }
+              ],
+              "description": "Scrolls the panel that holds a row to show it."
+            },
             {
               "kind": "field",
               "name": "handleKeydown",
@@ -108928,6 +109367,13 @@
               "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",
@@ -109788,6 +110234,14 @@
               "name": "helix-before-open",
               "reactProp": "onhelix-before-open"
             },
+            {
+              "type": {
+                "text": "HelixFilterEvent"
+              },
+              "description": "The text in the filter field changed, with the new text in `detail.value`. Cancelable: cancel it to keep every row showing and narrow the rows yourself.",
+              "name": "helix-filter",
+              "reactProp": "onhelix-filter"
+            },
             {
               "type": {
                 "text": "HelixSelectEvent"
@@ -109837,6 +110291,33 @@
               "description": "Whether the menu is the trigger's context menu: it opens where the reader\nasks for one, with a right-click, a long press, Shift+F10 or the menu key.",
               "fieldName": "context"
             },
+            {
+              "name": "filter",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The text the rows are filtered by, which the filter field holds.\n\nCleared as the menu closes and as a submenu opens or closes, so each page\nstarts with every row showing.",
+              "fieldName": "filter"
+            },
+            {
+              "name": "filterable",
+              "type": {
+                "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.",
+              "fieldName": "filterable"
+            },
+            {
+              "name": "filter-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Filter'",
+              "description": "The filter field's name and placeholder.",
+              "fieldName": "filterLabel"
+            },
             {
               "name": "label",
               "type": {
@@ -109855,6 +110336,15 @@
               "description": "The description a trigger gives under `open-on=\"long-press\"`, saying how\nto open the menu. Translate it with the rest of your interface.",
               "fieldName": "longPressLabel"
             },
+            {
+              "name": "no-results-text",
+              "type": {
+                "text": "string"
+              },
+              "default": "'No matches'",
+              "description": "The text shown when the filter keeps no rows.",
+              "fieldName": "noResultsText"
+            },
             {
               "name": "offset",
               "type": {
@@ -118445,6 +118935,28 @@
               },
               "description": "Says how many entries the filter matched, and nothing for an empty one."
             },
+            {
+              "kind": "method",
+              "name": "focus",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "description": "Moves focus to the row the keys move from, or to the tree while that row\nis scrolled out of the window, as Tab reaches them.",
+              "type": {
+                "text": "focus(options?: FocusOptions) => void"
+              }
+            },
             {
               "kind": "method",
               "name": "focusActive",
@@ -150810,6 +151322,38 @@
               "description": "The index of the stage the reader is on, or `-1`.\n\nRead from `active` once anything has set it, because a move writes\n`active` at once and each step's `current` only on the next update: two\ncalls to `next()` in one task then move two stages.",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "requestActive",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "next",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "cause",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Requests a new current stage, and returns whether it moved.\n\nWhere only a step's `current` says where the reader is, `active` is first\nwritten with that step, so `helix-activate` names it as `previous`.",
+              "inheritedFrom": {
+                "name": "MixinControllerActive",
+                "module": "src/mixins/mixin-controller-active/mixin-controller-active.ts"
+              },
+              "type": {
+                "text": "requestActive(next: string, cause?: string) => boolean"
+              }
+            },
             {
               "kind": "method",
               "name": "next",
@@ -151000,38 +151544,6 @@
                 "module": "src/mixins/mixin-controller-active/mixin-controller-active.ts"
               }
             },
-            {
-              "kind": "method",
-              "name": "requestActive",
-              "return": {
-                "type": {
-                  "text": "boolean"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "next",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "cause",
-                  "optional": true,
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Requests a new current item, and returns whether the change was applied.\n\nAnnounces before it acts, so `preventDefault()` on the `helix-before-activate` is\na refusal and nothing moves. Unlike a native control, nothing has moved\nby the time this runs, so refusing is simply not writing: there is\nnothing to put back. Nobody refusing means the set updates itself,\nwhether or not a consumer declared `active`, a declared property being a\nseed and a correction. `cause` says why, where the family names its\ncauses, and reaches the event as `detail.cause`.",
-              "inheritedFrom": {
-                "name": "MixinControllerActive",
-                "module": "src/mixins/mixin-controller-active/mixin-controller-active.ts"
-              },
-              "type": {
-                "text": "requestActive(next: string, cause?: string) => boolean"
-              }
-            },
             {
               "kind": "method",
               "name": "announceActivated",
@@ -186577,6 +187089,10 @@
               "description": "Shown while the items are loading.",
               "name": "menu-loading"
             },
+            {
+              "description": "The inner menu's filter field, drawn with `filterable`.",
+              "name": "menu-search-field"
+            },
             {
               "description": "The floating panel the menu is drawn on.",
               "name": "menu-surface"
@@ -188894,6 +189410,10 @@
               "description": "The text shown while the items are loading.",
               "name": "captions-menu-loading"
             },
+            {
+              "description": "The inner menu's filter field, drawn with `filterable`.",
+              "name": "captions-menu-search-field"
+            },
             {
               "description": "The floating panel the menu is drawn on.",
               "name": "captions-menu-surface"
@@ -189018,6 +189538,10 @@
               "description": "The text shown while the items are loading.",
               "name": "overflow-loading"
             },
+            {
+              "description": "The inner menu's filter field, drawn with `filterable`.",
+              "name": "overflow-search-field"
+            },
             {
               "description": "The floating panel the menu is drawn on.",
               "name": "overflow-surface"
@@ -193663,6 +194187,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-headless",
-    "version": "0.165.0"
+    "version": "0.166.0"
   }
 }