@fusion.dev/helix-headless 0.14.0 → 0.15.0

package/custom-elements.json

@@ -26638,7 +26638,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "**The tokens are the consumer's own elements, slotted.** What a filter narrows\nby belongs to the consumer's model rather than to this element: a facet with a\nprefix, a saved query, a range. So they are slotted rather than rendered from\na list of strings, and removing one is a request this element makes rather\nthan a change it applies. Combobox is the other way round, and that is the\ndifference between the two: its tokens are a view of a selection it owns,\ndrawn from options it was handed.\n\n**`value` is the text being typed, not the tokens**, which is what makes this\na field a consumer can listen to. Every keystroke announces `input` with the\ntext on the element, so a table narrows as the reader types. The tokens need\nno reporting back, being markup the consumer already holds.\n\nBackspace on an empty field asks the last token to go, through the same\n`helix-dismiss` its own remove control fires, so a consumer who handled the\npointer has already handled the keyboard.",
+          "description": "**The tokens are the consumer's own elements, slotted.** What a filter narrows\nby belongs to the consumer's model rather than to this element: a facet with a\nprefix, a saved query, a range. So they are slotted rather than rendered from\na list of strings, and removing one is a request this element makes rather\nthan a change it applies. Combobox is the other way round, and that is the\ndifference between the two: its tokens are a view of a selection it owns,\ndrawn from options it was handed.\n\n**`value` is the text being typed, not the tokens**, which is what makes this\na field a consumer can listen to. Every keystroke announces `input` with the\ntext on the element, so a table narrows as the reader types. The tokens need\nno reporting back, being markup the consumer already holds.\n\nBackspace on an empty field asks the last token to go, through the same\n`helix-dismiss` its own remove control fires, so a consumer who handled the\npointer has already handled the keyboard.\n\n**It can suggest what to type next, and it never learns the grammar.** Slot\n`helix-option` elements into `suggestions` and the field shows them, moves\nthrough them with the arrows, and lets Enter press one; the option fires its\nown `helix-select` and the consumer decides what choosing meant. Deciding\n*what* to suggest is theirs too: keys before a colon and values after it are\nthe same panel with different contents, which is all a two-level filter is,\nand the parse that tells them apart belongs where the domain does.\n\n**The panel opens when there is something in it and closes when there is\nnot**, rather than on a choice. A reader who picks a key wants its values\nnext, and closing on the choice would shut the panel between two renders. Use\n`selectionStart` and `setSelectionRange` to write a completion back and put\nthe caret after it, or the next parse reads the wrong term.",
           "name": "HelixHeadlessFilterInput",
           "cssParts": [
             {
@@ -26669,6 +26669,10 @@
               "description": "How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.",
               "name": "rest"
             },
+            {
+              "description": "The floating panel the suggestions sit in.",
+              "name": "surface"
+            },
             {
               "description": "The row the tokens sit in.",
               "name": "tags"
@@ -26683,6 +26687,10 @@
               "description": "Before the text, for a search icon.",
               "name": "start"
             },
+            {
+              "description": "What could be typed next, as `Option`s, and `Option.Group`s of them.",
+              "name": "suggestions"
+            },
             {
               "description": "What is already narrowing the results, as `Tag`s.",
               "name": "tags"
@@ -26751,6 +26759,43 @@
               "default": "0",
               "description": "How many tokens did not fit, which is what the row's count renders."
             },
+            {
+              "kind": "field",
+              "name": "activeAt",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "-1",
+              "description": "Which suggestion the keyboard is on, or `-1` for none.\n\nAn index rather than a value, unlike Listbox's: these are the consumer's\nown list and two of them may legitimately carry the same value, a `label`\nand an `assignee` both called `ada`. Position is what a reader is moving\nthrough and it is what stays right when they do."
+            },
+            {
+              "kind": "field",
+              "name": "suggesting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether anything is offering itself to be suggested.\n\n**The ARIA follows this rather than being declared once.** A text field\ncarrying `role=\"combobox\"` promises a popup; a filter field that no consumer\never gives options to has none, and saying otherwise sends a screen reader\nlooking for a list that does not exist. So the role, `aria-expanded` and\n`aria-controls` all arrive with the first option and leave with the last."
+            },
+            {
+              "kind": "field",
+              "name": "dismissed",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether Escape has closed the panel over text that still has suggestions.\n\nWithout it the panel is open whenever there is something to show, so Escape\nwould close it and the next render would put it straight back. Cleared by\nthe next keystroke, because that is the reader saying something new."
+            },
+            {
+              "kind": "field",
+              "name": "panel",
+              "privacy": "protected",
+              "readonly": true,
+              "default": "new PopoverController(this, { anchor: () => this.renderRoot?.querySelector<HTMLElement>('[part=\"field\"]'), boundary: (): readonly (Element | null | undefined)[] => [ this.renderRoot?.querySelector<HTMLElement>('[part=\"surface\"]'), this.renderRoot?.querySelector<HTMLElement>('[part=\"field\"]'), ], offset: () => 4, onDismiss: () => this.requestOpen(false), placement: 'bottom-start', surface: () => this.renderRoot?.querySelector<HTMLElement>('[part=\"surface\"]'), })"
+            },
             {
               "kind": "field",
               "name": "releaseCaret",
@@ -26798,6 +26843,77 @@
               "description": "Whether there is a clear button on screen right now.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "suggestions",
+              "type": {
+                "text": "SuggestionOption[]"
+              },
+              "privacy": "private",
+              "description": "The suggestions, in the order a reader moves through them.\n\n**Groups are opened out rather than walked into.** A slot assigns the group\nelement, not the options inside it, so a panel that read only what was\nassigned would offer nothing at all the moment a consumer reached for\n`option-group` to say what a run of values belongs to.\n\nA disabled option keeps its place on screen and is skipped here, which is\nthe difference between a list that explains why something cannot be chosen\nand one that pretends it was never there.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "selectionDirection",
+              "type": {
+                "text": "'backward' | 'forward' | 'none'"
+              },
+              "description": "The caret and the selection, under the platform's own names.\n\n**Published for the reason `Input` publishes them, and this element needs\nthem more.** The `<input>` is inside this shadow root, so a consumer has no\nway to ask where the caret is: `querySelector` does not cross the boundary.\nA grammar that completes what is being typed cannot work without it, because\n\"what is being typed\" is the term the caret is in, and after writing a\ncompletion back the caret has to be put after it or the next parse reads the\nwrong term.\n\nZero before there is a control, which is where an empty field's caret would\nbe anyway.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "selectionEnd",
+              "type": {
+                "text": "number"
+              },
+              "description": "Where the selection ends, which is the caret when nothing is selected.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "selectionStart",
+              "type": {
+                "text": "number"
+              },
+              "description": "Where the selection starts, which is the caret when nothing is selected.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "setSelectionRange",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "start",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "end",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "direction",
+                  "optional": true,
+                  "type": {
+                    "text": "'backward' | 'forward' | 'none'"
+                  }
+                }
+              ],
+              "description": "Moves the caret, or selects a run of the text.",
+              "type": {
+                "text": "setSelectionRange(start: number, end: number, direction?: 'backward' | 'forward' | 'none') => void"
+              }
+            },
             {
               "kind": "field",
               "name": "handleInput",
@@ -26819,12 +26935,74 @@
               "readonly": true,
               "description": "Empties the text and gives the caret back.\n\nFocus returns to the input rather than staying on a button that is about to\ndisappear, which would otherwise land on the body."
             },
+            {
+              "kind": "method",
+              "name": "settleOpen",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Opens the panel when there is something in it, and closes it when there is\nnot.\n\n**Derived rather than commanded, which is the whole of how two levels\nwork.** A reader who picks `disposition` wants its values next, and the\nconsumer answers by rendering those values; if picking closed the panel it\nwould shut and reopen between two renders, which a reader sees as a flicker\nand a screen reader hears as a list going away. Nothing here closes on a\nchoice: the panel goes when the consumer stops offering, which is exactly\nwhen a value has been completed and there is nothing left to say.\n\nThrough `requestOpen` for both directions, so `helix-before-open` and\n`helix-before-close` still gate it and a consumer who refuses is obeyed.\n**No guard of its own**, because that method already returns early when the\nanswer has not moved: this runs after every render, and a second guard here\nwould only be a copy of that one going stale."
+            },
+            {
+              "kind": "method",
+              "name": "move",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "by",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Moves the highlight, wrapping, and opens the panel if it was closed."
+            },
             {
               "kind": "field",
               "name": "handleKeydown",
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "refreshSuggesting",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "What is on offer, settled before the render that draws it.\n\n**Not left to `slotchange`, for the reason the token row is not.** That\nevent reports the assignment moving and nothing else, and it does not fire\nat all under the harness these are tested in, so a panel that learned only\nfrom it would be a panel that never opened. Reading the slot every update is\nwhat makes the answer true whenever anyone asks.\n\nState only. Opening is an announcement and belongs after the render, which\nis why `settleOpen` is not called from here."
+            },
+            {
+              "kind": "field",
+              "name": "handleSuggestions",
+              "privacy": "private",
+              "readonly": true,
+              "description": "The panel again, whenever what is in it changes."
+            },
+            {
+              "kind": "field",
+              "name": "handleFocusIn",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Focus arriving in the field is a reader asking what they can type."
+            },
+            {
+              "kind": "field",
+              "name": "handleFocusOut",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Focus leaving the element closes it.\n\n`relatedTarget` and not a timer: a press inside the panel moves focus within\nthis element and must not close what is being pressed."
+            },
             {
               "kind": "field",
               "name": "handleTokens",
@@ -26847,6 +27025,17 @@
                 "module": "src/mixins/mixin-tokens/mixin-tokens.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "markActive",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Marks the highlighted suggestion, and tells the control which one it is.\n\n**Two halves, and neither does the other's job.** `active` is the option's\nown published flag and is what a stylesheet draws from. The control carries\n`aria-activedescendant`, because focus never leaves the text: a screen\nreader is told what is highlighted by the field the caret is in, not by the\nlist.\n\nThrough `ariaActiveDescendantElement` rather than an id, which is what\n`Listbox` reaches for and for the same two reasons: it crosses a shadow\nboundary, where an `aria-activedescendant` naming an id cannot, and it needs\nno ids invented for the consumer's own elements. Feature-tested, because\nwhere it is missing the assignment is a silent no-op rather than an error,\nand the highlight is still drawn."
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -26869,6 +27058,112 @@
                 "text": "focus(options?: FocusOptions) => void"
               }
             },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the element is open.\n\nOne property, not two, so `dialog.open` answers the question anyone\nasking it meant. Writing always applies; `<helix-dialog open>` is the\nsame statement in markup.\n\n**Not reflected, and that is required rather than tidy.** Reflection\nwrites the resolved state back as an attribute, so an element that opened\nitself would put `open` on its own host: cloned, serialized for\nhydration, or diffed by a framework, it comes back holding whatever the\nlast reader did rather than what the author wrote. `:state(open)` carries\nthe resolved state for stylesheets, which is what the mirror is for.",
+              "attribute": "open",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "defaultOpen",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Initial open state for uncontrolled use, where nothing declared one.",
+              "attribute": "default-open",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "openState",
+              "type": {
+                "text": "boolean | undefined"
+              },
+              "privacy": "private",
+              "default": "undefined",
+              "description": "The state, whoever set it, and `undefined` until somebody has.\n\nPrefixed, and it has to be. These mixins compose onto one prototype\nchain, `Select` takes this one and `MixinControllerValue` together, and\nTypeScript's `private` is a compile-time fiction: two mixins with a field\ncalled `state` share one property on the instance, and the second one\nsilently overwrites the first. Measured, as a select whose `value` came\nback holding its `open` boolean.\n\nOne field and not two. Writing always applies, the way a native control\ndoes when a script assigns to it.",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "requestOpen",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "next",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Requests an open-state change, and reports whether it was applied.\n\nAnnounces before it acts, so `preventDefault()` on the `helix-before-open` or\n`helix-before-close` is a refusal and nothing moves. Nobody refusing means the\nelement opens or closes itself, whether or not a consumer declared\n`open`: a declared property is a seed and a correction, and a consumer\nwho wants the decision for themselves refuses it and assigns their own.",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              },
+              "type": {
+                "text": "requestOpen(next: boolean) => boolean"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "announceToggle",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "open",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Says the state moved, under the platform's own name and in its shape.\n\n**A native `toggle` from inside a shadow root reaches nobody**, because\nit neither bubbles nor composes, so the ten families showing a\n`popover=\"manual\"` panel and the two rendering a real `<dialog>` announce\nnothing to a consumer. The disclosures have no native element to fire\nanything at all: `AccordionItem` and `TreeItem` are `aria-expanded` and\n`hidden` written by hand, which is `<details>`'s job done manually.\n\n**From here rather than from `PopoverController`.** The controller covers\neleven families and the mixin covers sixteen, so announcing from both\nwould announce twice on the ten they share. What `toggle` reports is the\n*state*, and the state is this mixin's; the controller is a way of\nputting a panel on the screen.\n\n**`newState` and `oldState`, because that is the platform's shape**, so a\nconsumer arriving from `<details>` reads the same two words. Not\ncancelable: the before events are the request, and a second cancelable\nevent for one transition is two answers to one question.",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "toggleOpen",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Requests the opposite of the current state.",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              },
+              "type": {
+                "text": "toggleOpen() => boolean"
+              }
+            },
             {
               "kind": "field",
               "name": "collapseLabel",
@@ -27732,6 +28027,22 @@
               "name": "helix-before-change",
               "reactProp": "onhelix-before-change"
             },
+            {
+              "type": {
+                "text": "HelixBeforeCloseEvent"
+              },
+              "description": "Fired before the suggestions go, and cancelable.",
+              "name": "helix-before-close",
+              "reactProp": "onhelix-before-close"
+            },
+            {
+              "type": {
+                "text": "HelixBeforeOpenEvent"
+              },
+              "description": "Fired before the suggestions show, and cancelable.",
+              "name": "helix-before-open",
+              "reactProp": "onhelix-before-open"
+            },
             {
               "name": "input",
               "type": {
@@ -27743,6 +28054,14 @@
                 "module": "src/mixins/mixin-controller-value/mixin-controller-value.ts"
               },
               "reactProp": "oninput"
+            },
+            {
+              "type": {
+                "text": "Event"
+              },
+              "description": "Says the panel moved, carrying `newState` and `oldState`.",
+              "name": "toggle",
+              "reactProp": "ontoggle"
             }
           ],
           "attributes": [
@@ -27773,6 +28092,31 @@
               "description": "Shown while the field is empty.\n\nNot a label: it goes when typing starts.",
               "fieldName": "placeholder"
             },
+            {
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the element is open.\n\nOne property, not two, so `dialog.open` answers the question anyone\nasking it meant. Writing always applies; `<helix-dialog open>` is the\nsame statement in markup.\n\n**Not reflected, and that is required rather than tidy.** Reflection\nwrites the resolved state back as an attribute, so an element that opened\nitself would put `open` on its own host: cloned, serialized for\nhydration, or diffed by a framework, it comes back holding whatever the\nlast reader did rather than what the author wrote. `:state(open)` carries\nthe resolved state for stylesheets, which is what the mirror is for.",
+              "fieldName": "open",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              }
+            },
+            {
+              "name": "default-open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Initial open state for uncontrolled use, where nothing declared one.",
+              "fieldName": "defaultOpen",
+              "inheritedFrom": {
+                "name": "MixinControllerOpen",
+                "module": "src/mixins/mixin-controller-open/mixin-controller-open.ts"
+              }
+            },
             {
               "name": "collapse-label",
               "type": {
@@ -27930,6 +28274,10 @@
             }
           ],
           "mixins": [
+            {
+              "name": "MixinControllerOpen",
+              "package": "@fusion.dev/helix-core"
+            },
             {
               "name": "MixinTokens",
               "package": "@fusion.dev/helix-core"

package/dist/element-events.generated.js

@@ -53,7 +53,14 @@ registerElementEvents({
     'helix-headless-drilldown': ['helix-select'],
     'helix-headless-drilldown-item': ['helix-select'],
     'helix-headless-file-input': ['change', 'helix-before-change', 'input'],
-    'helix-headless-filter-input': ['change', 'helix-before-change', 'input'],
+    'helix-headless-filter-input': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'input',
+        'toggle',
+    ],
     'helix-headless-heatmap': ['helix-resize'],
     'helix-headless-image': ['error', 'load'],
     'helix-headless-input': ['change', 'helix-before-change', 'input'],

package/dist/filter-input/root/filter-input-root.d.ts

@@ -1,6 +1,6 @@
-import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinTokensInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinTokensInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A field that narrows something else, beside what is already narrowing it.
  *
@@ -22,6 +22,20 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * `helix-dismiss` its own remove control fires, so a consumer who handled the
  * pointer has already handled the keyboard.
  *
+ * **It can suggest what to type next, and it never learns the grammar.** Slot
+ * `helix-option` elements into `suggestions` and the field shows them, moves
+ * through them with the arrows, and lets Enter press one; the option fires its
+ * own `helix-select` and the consumer decides what choosing meant. Deciding
+ * *what* to suggest is theirs too: keys before a colon and values after it are
+ * the same panel with different contents, which is all a two-level filter is,
+ * and the parse that tells them apart belongs where the domain does.
+ *
+ * **The panel opens when there is something in it and closes when there is
+ * not**, rather than on a choice. A reader who picks a key wants its values
+ * next, and closing on the choice would shut the panel between two renders. Use
+ * `selectionStart` and `setSelectionRange` to write a completion back and put
+ * the caret after it, or the next parse reads the wrong term.
+ *
  * @since 0.1.0
  * @status experimental
  * @category forms
@@ -30,11 +44,15 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  *
  * @slot end - After the text, for a count or a control.
  * @slot start - Before the text, for a search icon.
+ * @slot suggestions - What could be typed next, as `Option`s, and `Option.Group`s of them.
  * @slot tags - What is already narrowing the results, as `Tag`s.
  *
  * @event {Event} change - Relayed from the input once the reader has finished.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the suggestions go, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the suggestions show, and cancelable.
  * @event {Event} input - Announced once the text has moved.
+ * @event {Event} toggle - Says the panel moved, carrying `newState` and `oldState`.
  *
  * @csspart clear - The button that empties the field.
  * @csspart control - The input itself.
@@ -43,6 +61,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @csspart hint - Help under the field, while nothing is wrong.
  * @csspart label - The question, over the field.
  * @csspart rest - How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.
+ * @csspart surface - The floating panel the suggestions sit in.
  * @csspart tags - The row the tokens sit in.
  */
 export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_base {
@@ -70,6 +89,34 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     placeholder: string;
     /** How many tokens did not fit, which is what the row's count renders. */
     private over;
+    /**
+     * Which suggestion the keyboard is on, or `-1` for none.
+     *
+     * An index rather than a value, unlike Listbox's: these are the consumer's
+     * own list and two of them may legitimately carry the same value, a `label`
+     * and an `assignee` both called `ada`. Position is what a reader is moving
+     * through and it is what stays right when they do.
+     */
+    private activeAt;
+    /**
+     * Whether anything is offering itself to be suggested.
+     *
+     * **The ARIA follows this rather than being declared once.** A text field
+     * carrying `role="combobox"` promises a popup; a filter field that no consumer
+     * ever gives options to has none, and saying otherwise sends a screen reader
+     * looking for a list that does not exist. So the role, `aria-expanded` and
+     * `aria-controls` all arrive with the first option and leave with the last.
+     */
+    private suggesting;
+    /**
+     * Whether Escape has closed the panel over text that still has suggestions.
+     *
+     * Without it the panel is open whenever there is something to show, so Escape
+     * would close it and the next render would put it straight back. Cleared by
+     * the next keystroke, because that is the reader saying something new.
+     */
+    private dismissed;
+    protected readonly panel: PopoverController;
     /**
      * The caret, held across a value the consumer wrote rather than the reader.
      *
@@ -83,6 +130,40 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     private get tokens();
     /** Whether there is a clear button on screen right now. */
     private get showsClear();
+    /**
+     * The suggestions, in the order a reader moves through them.
+     *
+     * **Groups are opened out rather than walked into.** A slot assigns the group
+     * element, not the options inside it, so a panel that read only what was
+     * assigned would offer nothing at all the moment a consumer reached for
+     * `option-group` to say what a run of values belongs to.
+     *
+     * A disabled option keeps its place on screen and is skipped here, which is
+     * the difference between a list that explains why something cannot be chosen
+     * and one that pretends it was never there.
+     */
+    private get suggestions();
+    /**
+     * The caret and the selection, under the platform's own names.
+     *
+     * **Published for the reason `Input` publishes them, and this element needs
+     * them more.** The `<input>` is inside this shadow root, so a consumer has no
+     * way to ask where the caret is: `querySelector` does not cross the boundary.
+     * A grammar that completes what is being typed cannot work without it, because
+     * "what is being typed" is the term the caret is in, and after writing a
+     * completion back the caret has to be put after it or the next parse reads the
+     * wrong term.
+     *
+     * Zero before there is a control, which is where an empty field's caret would
+     * be anyway.
+     */
+    get selectionDirection(): 'backward' | 'forward' | 'none';
+    /** Where the selection ends, which is the caret when nothing is selected. */
+    get selectionEnd(): number;
+    /** Where the selection starts, which is the caret when nothing is selected. */
+    get selectionStart(): number;
+    /** Moves the caret, or selects a run of the text. */
+    setSelectionRange(start: number, end: number, direction?: 'backward' | 'forward' | 'none'): void;
     /**
      * Every keystroke, cancelable, and put back where it is refused.
      *
@@ -100,7 +181,52 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * disappear, which would otherwise land on the body.
      */
     private readonly handleClear;
+    /**
+     * Opens the panel when there is something in it, and closes it when there is
+     * not.
+     *
+     * **Derived rather than commanded, which is the whole of how two levels
+     * work.** A reader who picks `disposition` wants its values next, and the
+     * consumer answers by rendering those values; if picking closed the panel it
+     * would shut and reopen between two renders, which a reader sees as a flicker
+     * and a screen reader hears as a list going away. Nothing here closes on a
+     * choice: the panel goes when the consumer stops offering, which is exactly
+     * when a value has been completed and there is nothing left to say.
+     *
+     * Through `requestOpen` for both directions, so `helix-before-open` and
+     * `helix-before-close` still gate it and a consumer who refuses is obeyed.
+     * **No guard of its own**, because that method already returns early when the
+     * answer has not moved: this runs after every render, and a second guard here
+     * would only be a copy of that one going stale.
+     */
+    private settleOpen;
+    /** Moves the highlight, wrapping, and opens the panel if it was closed. */
+    private move;
     private readonly handleKeydown;
+    /**
+     * What is on offer, settled before the render that draws it.
+     *
+     * **Not left to `slotchange`, for the reason the token row is not.** That
+     * event reports the assignment moving and nothing else, and it does not fire
+     * at all under the harness these are tested in, so a panel that learned only
+     * from it would be a panel that never opened. Reading the slot every update is
+     * what makes the answer true whenever anyone asks.
+     *
+     * State only. Opening is an announcement and belongs after the render, which
+     * is why `settleOpen` is not called from here.
+     */
+    private refreshSuggesting;
+    /** The panel again, whenever what is in it changes. */
+    private readonly handleSuggestions;
+    /** Focus arriving in the field is a reader asking what they can type. */
+    private readonly handleFocusIn;
+    /**
+     * Focus leaving the element closes it.
+     *
+     * `relatedTarget` and not a timer: a press inside the panel moves focus within
+     * this element and must not close what is being pressed.
+     */
+    private readonly handleFocusOut;
     /** The row again, whenever what is in it changes. */
     private readonly handleTokens;
     /**
@@ -117,6 +243,23 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Marks the highlighted suggestion, and tells the control which one it is.
+     *
+     * **Two halves, and neither does the other's job.** `active` is the option's
+     * own published flag and is what a stylesheet draws from. The control carries
+     * `aria-activedescendant`, because focus never leaves the text: a screen
+     * reader is told what is highlighted by the field the caret is in, not by the
+     * list.
+     *
+     * Through `ariaActiveDescendantElement` rather than an id, which is what
+     * `Listbox` reaches for and for the same two reasons: it crosses a shadow
+     * boundary, where an `aria-activedescendant` naming an id cannot, and it needs
+     * no ids invented for the consumer's own elements. Feature-tested, because
+     * where it is missing the assignment is a silent no-op rather than an error,
+     * and the highlight is still drawn.
+     */
+    private markActive;
     /** Puts the caret in the field, the way a label pointing at one would. */
     focus(options?: FocusOptions): void;
     protected render(): TemplateResult;

package/dist/filter-input/root/filter-input-root.js

@@ -4,12 +4,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, customElement, drawIcon, HelixFormElement, holdCaret, MixinControllerValue, MixinField, MixinTokens, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, drawIcon, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 const asksToGo = (node) => typeof node?.dismiss === 'function';
-let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinTokens(MixinControllerValue(MixinField(HelixFormElement))) {
+const isOption = (node) => 'active' in node && 'value' in node;
+let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
     constructor() {
         super(...arguments);
         this.aria = new AriaForwardController(this, {
@@ -20,11 +21,27 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
         this.clearLabel = 'Clear';
         this.placeholder = '';
         this.over = 0;
+        this.activeAt = -1;
+        this.suggesting = false;
+        this.dismissed = false;
+        this.panel = new PopoverController(this, {
+            anchor: () => this.renderRoot?.querySelector('[part="field"]'),
+            boundary: () => [
+                this.renderRoot?.querySelector('[part="surface"]'),
+                this.renderRoot?.querySelector('[part="field"]'),
+            ],
+            offset: () => 4,
+            onDismiss: () => this.requestOpen(false),
+            placement: 'bottom-start',
+            surface: () => this.renderRoot?.querySelector('[part="surface"]'),
+        });
         this.handleInput = (event) => {
             event.stopPropagation();
             const control = event.target;
             this.requestValue(control.value);
             restoreValue(control, this.value);
+            this.dismissed = false;
+            this.settleOpen();
         };
         this.handleChange = (event) => {
             event.stopPropagation();
@@ -39,7 +56,68 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
             }
         };
         this.handleKeydown = (event) => {
-            this.tokenKeydown(event, this.value);
+            if (this.tokenKeydown(event, this.value)) {
+                return;
+            }
+            if (!this.suggesting) {
+                return;
+            }
+            switch (event.key) {
+                case 'ArrowDown':
+                    event.preventDefault();
+                    this.move(1);
+                    return;
+                case 'ArrowUp':
+                    event.preventDefault();
+                    this.move(-1);
+                    return;
+                case 'Home':
+                    if (this.open) {
+                        event.preventDefault();
+                        this.activeAt = 0;
+                    }
+                    return;
+                case 'End':
+                    if (this.open) {
+                        event.preventDefault();
+                        this.activeAt = this.suggestions.length - 1;
+                    }
+                    return;
+                case 'Escape':
+                    if (this.open) {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        this.dismissed = true;
+                        this.activeAt = -1;
+                        this.requestOpen(false);
+                    }
+                    return;
+                case 'Enter': {
+                    const active = this.suggestions[this.activeAt];
+                    if (!this.open || !active) {
+                        return;
+                    }
+                    event.preventDefault();
+                    active.select();
+                    return;
+                }
+                default:
+            }
+        };
+        this.handleSuggestions = () => {
+            this.refreshSuggesting();
+            this.settleOpen();
+        };
+        this.handleFocusIn = () => {
+            this.settleOpen();
+        };
+        this.handleFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && this.contains(next)) {
+                return;
+            }
+            this.activeAt = -1;
+            this.requestOpen(false);
         };
         this.handleTokens = () => {
             this.over = this.hideOverflow(this.tokens);
@@ -58,6 +136,56 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
     get showsClear() {
         return this.clearable && this.value !== '' && !this.isDisabled;
     }
+    get suggestions() {
+        const slot = this.renderRoot?.querySelector('slot[name="suggestions"]');
+        const found = [];
+        for (const node of slot?.assignedElements({ flatten: true }) ?? []) {
+            if (isOption(node)) {
+                found.push(node);
+                continue;
+            }
+            for (const child of node.children) {
+                if (isOption(child)) {
+                    found.push(child);
+                }
+            }
+        }
+        return found.filter((option) => !option.disabled);
+    }
+    get selectionDirection() {
+        return this.control?.selectionDirection ?? 'none';
+    }
+    get selectionEnd() {
+        return this.control?.selectionEnd ?? 0;
+    }
+    get selectionStart() {
+        return this.control?.selectionStart ?? 0;
+    }
+    setSelectionRange(start, end, direction) {
+        this.control?.setSelectionRange(start, end, direction);
+    }
+    settleOpen() {
+        const focused = this.matches(':focus-within') || this.contains(document.activeElement);
+        this.requestOpen(this.suggesting && !this.dismissed && !this.isDisabled && focused);
+    }
+    move(by) {
+        const options = this.suggestions;
+        if (options.length === 0) {
+            return;
+        }
+        if (!this.open) {
+            this.dismissed = false;
+            this.settleOpen();
+        }
+        const from = this.activeAt;
+        this.activeAt =
+            from < 0 ? (by > 0 ? 0 : options.length - 1) : (from + by + options.length) % options.length;
+    }
+    refreshSuggesting() {
+        const options = this.suggestions;
+        this.suggesting = options.length > 0;
+        this.activeAt = this.activeAt < options.length ? this.activeAt : -1;
+    }
     removeLastToken() {
         const last = this.tokens?.assignedElements({ flatten: true }).at(-1);
         if (asksToGo(last)) {
@@ -74,23 +202,46 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
             this.releaseCaret = holdCaret(control);
         }
         this.handleTokens();
+        this.refreshSuggesting();
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.handleTokens();
+        this.refreshSuggesting();
     }
     updated(changed) {
         super.updated(changed);
         this.releaseCaret?.();
         this.releaseCaret = undefined;
         this.internals.setFormValue(this.value);
+        this.markActive();
+        if (this.open) {
+            this.panel.show();
+        }
+        else {
+            this.panel.hide();
+        }
+        this.settleOpen();
+    }
+    markActive() {
+        const options = this.suggestions;
+        const active = this.open ? options[this.activeAt] : undefined;
+        for (const [at, option] of options.entries()) {
+            option.active = this.open && at === this.activeAt;
+        }
+        const control = this.control;
+        if (control && 'ariaActiveDescendantElement' in control) {
+            ;
+            control.ariaActiveDescendantElement = active ?? null;
+        }
+        active?.scrollIntoView({ block: 'nearest' });
     }
     focus(options) {
         this.control?.focus(options);
     }
     render() {
         return html `${this.renderLabel()}
-    <div part="field">
+    <div part="field" @focusin=${this.handleFocusIn} @focusout=${this.handleFocusOut}>
       <slot name="start"></slot>
       ${this.renderTokenRow(html `<slot name="tags" @slotchange=${this.handleTokens}></slot>`, this.over)}
       <input
@@ -101,6 +252,10 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
         name=${this.name || nothing}
         placeholder=${this.placeholder || nothing}
         aria-describedby=${this.describedBy ?? nothing}
+        role=${this.suggesting ? 'combobox' : nothing}
+        aria-autocomplete=${this.suggesting ? 'list' : nothing}
+        aria-controls=${this.suggesting ? 'suggestions' : nothing}
+        aria-expanded=${this.suggesting ? (this.open ? 'true' : 'false') : nothing}
         ?disabled=${this.isDisabled}
         ?required=${this.required}
         @input=${this.handleInput}
@@ -119,6 +274,14 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinToken
             </button>`
             : nothing}
     </div>
+    <!-- **Always rendered, and hidden rather than absent**, for the reason the
+         token row is: a slot that is not in the tree assigns nothing, so a panel
+         built only once there were options could never learn that there are
+         any. A manual popover puts it in the top layer, so it is not clipped by
+         a scrolling table or an overflow on an ancestor. -->
+    <div part="surface" id="suggestions" role="listbox" popover="manual" ?hidden=${!this.open}>
+      <slot name="suggestions" @slotchange=${this.handleSuggestions}></slot>
+    </div>
     ${this.renderHint()}${this.renderFeedback()}`;
     }
 };
@@ -134,6 +297,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessFilterInput.prototype, "over", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "activeAt", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "suggesting", void 0);
 HelixHeadlessFilterInput = __decorate([
     customElement('helix-headless-filter-input')
 ], HelixHeadlessFilterInput);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -45,14 +45,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.14.0",
-    "@fusion.dev/helix-icons": "0.14.0",
+    "@fusion.dev/helix-core": "0.15.0",
+    "@fusion.dev/helix-icons": "0.15.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.14.0",
-    "@fusion.dev/helix-testing": "0.14.0",
+    "@fusion.dev/helix-cem": "0.15.0",
+    "@fusion.dev/helix-testing": "0.15.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^3.3.0",

package/types/jsx.d.ts

@@ -5800,6 +5800,12 @@ export type HelixHeadlessFilterInputElementEvent<E = Event> = TypedEvent<
 /** `helix-before-change` event type */
 export type HelixHeadlessFilterInputHelixBeforeChangeElementEvent =
   HelixHeadlessFilterInputElementEvent<HelixBeforeChangeEvent>;
+/** `helix-before-close` event type */
+export type HelixHeadlessFilterInputHelixBeforeCloseElementEvent =
+  HelixHeadlessFilterInputElementEvent<HelixBeforeCloseEvent>;
+/** `helix-before-open` event type */
+export type HelixHeadlessFilterInputHelixBeforeOpenElementEvent =
+  HelixHeadlessFilterInputElementEvent<HelixBeforeOpenEvent>;
 
 export type HelixHeadlessFilterInputProps = {
   /** Whether the field offers a button that empties it.
@@ -5817,6 +5823,23 @@ them. */
 
 Not a label: it goes when typing starts. */
   placeholder?: (HelixHeadlessFilterInput["placeholder"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  open?: (HelixHeadlessFilterInput["open"]) | undefined;
+  /** Initial open state for uncontrolled use, where nothing declared one. */
+  "default-open"?: (HelixHeadlessFilterInput["defaultOpen"]) | undefined;
+  /** Initial open state for uncontrolled use, where nothing declared one. */
+  defaultOpen?: (HelixHeadlessFilterInput["defaultOpen"]) | undefined;
   /** What the control says once everything is showing. */
   "collapse-label"?: (HelixHeadlessFilterInput["collapseLabel"]) | undefined;
   /** What the control says once everything is showing. */
@@ -5883,8 +5906,18 @@ Here rather than on each control. */
   "onhelix-before-change"?: ((
     e: HelixHeadlessFilterInputHelixBeforeChangeElementEvent,
   ) => void) | undefined;
+  /** Fired before the suggestions go, and cancelable. */
+  "onhelix-before-close"?: ((
+    e: HelixHeadlessFilterInputHelixBeforeCloseElementEvent,
+  ) => void) | undefined;
+  /** Fired before the suggestions show, and cancelable. */
+  "onhelix-before-open"?: ((
+    e: HelixHeadlessFilterInputHelixBeforeOpenElementEvent,
+  ) => void) | undefined;
   /** Announced once the text has moved. */
   oninput?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
+  /** Says the panel moved, carrying `newState` and `oldState`. */
+  ontoggle?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
 };
 
 export type HelixHeadlessFilterInputSolidJsProps = {
@@ -5903,6 +5936,23 @@ them. */
 
 Not a label: it goes when typing starts. */
   "prop:placeholder"?: (HelixHeadlessFilterInput["placeholder"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  "prop:open"?: (HelixHeadlessFilterInput["open"]) | undefined;
+  /** Initial open state for uncontrolled use, where nothing declared one. */
+  "bool:default-open"?: (HelixHeadlessFilterInput["defaultOpen"]) | undefined;
+  /** Initial open state for uncontrolled use, where nothing declared one. */
+  "prop:defaultOpen"?: (HelixHeadlessFilterInput["defaultOpen"]) | undefined;
   /** What the control says once everything is showing. */
   "attr:collapse-label"?: (HelixHeadlessFilterInput["collapseLabel"]) | undefined;
   /** What the control says once everything is showing. */
@@ -5968,8 +6018,18 @@ Here rather than on each control. */
   "on:helix-before-change"?: ((
     e: HelixHeadlessFilterInputHelixBeforeChangeElementEvent,
   ) => void) | undefined;
+  /** Fired before the suggestions go, and cancelable. */
+  "on:helix-before-close"?: ((
+    e: HelixHeadlessFilterInputHelixBeforeCloseElementEvent,
+  ) => void) | undefined;
+  /** Fired before the suggestions show, and cancelable. */
+  "on:helix-before-open"?: ((
+    e: HelixHeadlessFilterInputHelixBeforeOpenElementEvent,
+  ) => void) | undefined;
   /** Announced once the text has moved. */
   "on:input"?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
+  /** Says the panel moved, carrying `newState` and `oldState`. */
+  "on:toggle"?: ((e: HelixHeadlessFilterInputElementEvent) => void) | undefined;
 
   /** Set the innerHTML of the element */
   innerHTML?: (string) | undefined;
@@ -20567,6 +20627,20 @@ export type CustomElements = {
    * `helix-dismiss` its own remove control fires, so a consumer who handled the
    * pointer has already handled the keyboard.
    *
+   * **It can suggest what to type next, and it never learns the grammar.** Slot
+   * `helix-option` elements into `suggestions` and the field shows them, moves
+   * through them with the arrows, and lets Enter press one; the option fires its
+   * own `helix-select` and the consumer decides what choosing meant. Deciding
+   * *what* to suggest is theirs too: keys before a colon and values after it are
+   * the same panel with different contents, which is all a two-level filter is,
+   * and the parse that tells them apart belongs where the domain does.
+   *
+   * **The panel opens when there is something in it and closes when there is
+   * not**, rather than on a choice. A reader who picks a key wants its values
+   * next, and closing on the choice would shut the panel between two renders. Use
+   * `selectionStart` and `setSelectionRange` to write a completion back and put
+   * the caret after it, or the next parse reads the wrong term.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
@@ -20581,6 +20655,19 @@ export type CustomElements = {
    * - `placeholder`: Shown while the field is empty.
    *
    * Not a label: it goes when typing starts.
+   * - `open`: Whether the element is open.
+   *
+   * One property, not two, so `dialog.open` answers the question anyone
+   * asking it meant. Writing always applies; `<helix-dialog open>` is the
+   * same statement in markup.
+   *
+   * **Not reflected, and that is required rather than tidy.** Reflection
+   * writes the resolved state back as an attribute, so an element that opened
+   * itself would put `open` on its own host: cloned, serialized for
+   * hydration, or diffed by a framework, it comes back holding whatever the
+   * last reader did rather than what the author wrote. `:state(open)` carries
+   * the resolved state for stylesheets, which is what the mirror is for.
+   * - `default-open`/`defaultOpen`: Initial open state for uncontrolled use, where nothing declared one.
    * - `collapse-label`/`collapseLabel`: What the control says once everything is showing.
    * - `expandable`: Whether the count is a control that shows the rest.
    * - `expand-label`/`expandLabel`: What the collapsed count is called, since `+3` names nothing.
@@ -20620,6 +20707,20 @@ export type CustomElements = {
    * imperatively later, and nothing is hydrating by then.
    *
    * Here rather than on each control.
+   * - `selectionDirection`: The caret and the selection, under the platform's own names.
+   *
+   * **Published for the reason `Input` publishes them, and this element needs
+   * them more.** The `<input>` is inside this shadow root, so a consumer has no
+   * way to ask where the caret is: `querySelector` does not cross the boundary.
+   * A grammar that completes what is being typed cannot work without it, because
+   * "what is being typed" is the term the caret is in, and after writing a
+   * completion back the caret has to be put after it or the next parse reads the
+   * wrong term.
+   *
+   * Zero before there is a control, which is where an empty field's caret would
+   * be anyway. (property only) (readonly)
+   * - `selectionEnd`: Where the selection ends, which is the caret when nothing is selected. (property only) (readonly)
+   * - `selectionStart`: Where the selection starts, which is the caret when nothing is selected. (property only) (readonly)
    * - `form`: The form this control belongs to, if any. (property only) (readonly)
    * - `labels`: Labels associated with this control. (property only) (readonly)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
@@ -20647,7 +20748,10 @@ export type CustomElements = {
    *
    * - `change`: Relayed from the input once the reader has finished.
    * - `helix-before-change`: Fired as the text changes, and cancelable.
+   * - `helix-before-close`: Fired before the suggestions go, and cancelable.
+   * - `helix-before-open`: Fired before the suggestions show, and cancelable.
    * - `input`: Announced once the text has moved.
+   * - `toggle`: Says the panel moved, carrying `newState` and `oldState`.
    *
    * ## Slots
    *
@@ -20655,13 +20759,23 @@ export type CustomElements = {
    *
    * - `end`: After the text, for a count or a control.
    * - `start`: Before the text, for a search icon.
+   * - `suggestions`: What could be typed next, as `Option`s, and `Option.Group`s of them.
    * - `tags`: What is already narrowing the results, as `Tag`s.
    *
    * ## Methods
    *
    * Methods that can be called to access component functionality.
    *
+   * - `setSelectionRange(start: number, end: number, direction?: 'backward' | 'forward' | 'none') => void`: Moves the caret, or selects a run of the text.
    * - `focus(options?: FocusOptions) => void`: Puts the caret in the field, the way a label pointing at one would.
+   * - `requestOpen(next: boolean) => boolean`: Requests an open-state change, and reports whether it was applied.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-open` or
+   * `helix-before-close` is a refusal and nothing moves. Nobody refusing means the
+   * element opens or closes itself, whether or not a consumer declared
+   * `open`: a declared property is a seed and a correction, and a consumer
+   * who wants the decision for themselves refuses it and assigns their own.
+   * - `toggleOpen() => boolean`: Requests the opposite of the current state.
    * - `requestValue(next: string) => boolean`: Requests a new value, and reports whether the request stood.
    *
    * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
@@ -20724,6 +20838,7 @@ export type CustomElements = {
    * - `hint`: Help under the field, while nothing is wrong.
    * - `label`: The question, over the field.
    * - `rest`: How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.
+   * - `surface`: The floating panel the suggestions sit in.
    * - `tags`: The row the tokens sit in.
    */
   "helix-headless-filter-input": Partial<
@@ -35007,6 +35122,20 @@ export type CustomElementsSolidJs = {
    * `helix-dismiss` its own remove control fires, so a consumer who handled the
    * pointer has already handled the keyboard.
    *
+   * **It can suggest what to type next, and it never learns the grammar.** Slot
+   * `helix-option` elements into `suggestions` and the field shows them, moves
+   * through them with the arrows, and lets Enter press one; the option fires its
+   * own `helix-select` and the consumer decides what choosing meant. Deciding
+   * *what* to suggest is theirs too: keys before a colon and values after it are
+   * the same panel with different contents, which is all a two-level filter is,
+   * and the parse that tells them apart belongs where the domain does.
+   *
+   * **The panel opens when there is something in it and closes when there is
+   * not**, rather than on a choice. A reader who picks a key wants its values
+   * next, and closing on the choice would shut the panel between two renders. Use
+   * `selectionStart` and `setSelectionRange` to write a completion back and put
+   * the caret after it, or the next parse reads the wrong term.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
@@ -35021,6 +35150,19 @@ export type CustomElementsSolidJs = {
    * - `placeholder`: Shown while the field is empty.
    *
    * Not a label: it goes when typing starts.
+   * - `open`: Whether the element is open.
+   *
+   * One property, not two, so `dialog.open` answers the question anyone
+   * asking it meant. Writing always applies; `<helix-dialog open>` is the
+   * same statement in markup.
+   *
+   * **Not reflected, and that is required rather than tidy.** Reflection
+   * writes the resolved state back as an attribute, so an element that opened
+   * itself would put `open` on its own host: cloned, serialized for
+   * hydration, or diffed by a framework, it comes back holding whatever the
+   * last reader did rather than what the author wrote. `:state(open)` carries
+   * the resolved state for stylesheets, which is what the mirror is for.
+   * - `default-open`/`defaultOpen`: Initial open state for uncontrolled use, where nothing declared one.
    * - `collapse-label`/`collapseLabel`: What the control says once everything is showing.
    * - `expandable`: Whether the count is a control that shows the rest.
    * - `expand-label`/`expandLabel`: What the collapsed count is called, since `+3` names nothing.
@@ -35060,6 +35202,20 @@ export type CustomElementsSolidJs = {
    * imperatively later, and nothing is hydrating by then.
    *
    * Here rather than on each control.
+   * - `selectionDirection`: The caret and the selection, under the platform's own names.
+   *
+   * **Published for the reason `Input` publishes them, and this element needs
+   * them more.** The `<input>` is inside this shadow root, so a consumer has no
+   * way to ask where the caret is: `querySelector` does not cross the boundary.
+   * A grammar that completes what is being typed cannot work without it, because
+   * "what is being typed" is the term the caret is in, and after writing a
+   * completion back the caret has to be put after it or the next parse reads the
+   * wrong term.
+   *
+   * Zero before there is a control, which is where an empty field's caret would
+   * be anyway. (property only) (readonly)
+   * - `selectionEnd`: Where the selection ends, which is the caret when nothing is selected. (property only) (readonly)
+   * - `selectionStart`: Where the selection starts, which is the caret when nothing is selected. (property only) (readonly)
    * - `form`: The form this control belongs to, if any. (property only) (readonly)
    * - `labels`: Labels associated with this control. (property only) (readonly)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
@@ -35087,7 +35243,10 @@ export type CustomElementsSolidJs = {
    *
    * - `change`: Relayed from the input once the reader has finished.
    * - `helix-before-change`: Fired as the text changes, and cancelable.
+   * - `helix-before-close`: Fired before the suggestions go, and cancelable.
+   * - `helix-before-open`: Fired before the suggestions show, and cancelable.
    * - `input`: Announced once the text has moved.
+   * - `toggle`: Says the panel moved, carrying `newState` and `oldState`.
    *
    * ## Slots
    *
@@ -35095,13 +35254,23 @@ export type CustomElementsSolidJs = {
    *
    * - `end`: After the text, for a count or a control.
    * - `start`: Before the text, for a search icon.
+   * - `suggestions`: What could be typed next, as `Option`s, and `Option.Group`s of them.
    * - `tags`: What is already narrowing the results, as `Tag`s.
    *
    * ## Methods
    *
    * Methods that can be called to access component functionality.
    *
+   * - `setSelectionRange(start: number, end: number, direction?: 'backward' | 'forward' | 'none') => void`: Moves the caret, or selects a run of the text.
    * - `focus(options?: FocusOptions) => void`: Puts the caret in the field, the way a label pointing at one would.
+   * - `requestOpen(next: boolean) => boolean`: Requests an open-state change, and reports whether it was applied.
+   *
+   * Announces before it acts, so `preventDefault()` on the `helix-before-open` or
+   * `helix-before-close` is a refusal and nothing moves. Nobody refusing means the
+   * element opens or closes itself, whether or not a consumer declared
+   * `open`: a declared property is a seed and a correction, and a consumer
+   * who wants the decision for themselves refuses it and assigns their own.
+   * - `toggleOpen() => boolean`: Requests the opposite of the current state.
    * - `requestValue(next: string) => boolean`: Requests a new value, and reports whether the request stood.
    *
    * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
@@ -35164,6 +35333,7 @@ export type CustomElementsSolidJs = {
    * - `hint`: Help under the field, while nothing is wrong.
    * - `label`: The question, over the field.
    * - `rest`: How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.
+   * - `surface`: The floating panel the suggestions sit in.
    * - `tags`: The row the tokens sit in.
    */
   "helix-headless-filter-input": Partial<

package/types/vue.d.ts

@@ -2975,6 +2975,12 @@ export type HelixHeadlessFilterInputElementEvent<E = Event> = TypedEvent<
 /** `helix-before-change` event type */
 export type HelixHeadlessFilterInputHelixBeforeChangeElementEvent =
   HelixHeadlessFilterInputElementEvent<HelixBeforeChangeEvent>;
+/** `helix-before-close` event type */
+export type HelixHeadlessFilterInputHelixBeforeCloseElementEvent =
+  HelixHeadlessFilterInputElementEvent<HelixBeforeCloseEvent>;
+/** `helix-before-open` event type */
+export type HelixHeadlessFilterInputHelixBeforeOpenElementEvent =
+  HelixHeadlessFilterInputElementEvent<HelixBeforeOpenEvent>;
 
 export type HelixHeadlessFilterInputVueProps = {
   /** Whether the field offers a button that empties it.
@@ -2992,6 +2998,23 @@ them. */
 
 Not a label: it goes when typing starts. */
   placeholder?: (HelixHeadlessFilterInput["placeholder"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  open?: (HelixHeadlessFilterInput["open"]) | undefined;
+  /** Initial open state for uncontrolled use, where nothing declared one. */
+  "default-open"?: (HelixHeadlessFilterInput["defaultOpen"]) | undefined;
+  /** Initial open state for uncontrolled use, where nothing declared one. */
+  defaultOpen?: (HelixHeadlessFilterInput["defaultOpen"]) | undefined;
   /** What the control says once everything is showing. */
   "collapse-label"?: (HelixHeadlessFilterInput["collapseLabel"]) | undefined;
   /** What the control says once everything is showing. */
@@ -3058,8 +3081,14 @@ export type HelixHeadlessFilterInputVueEvents = {
   change: HelixHeadlessFilterInputElementEvent;
   /** Fired as the text changes, and cancelable. */
   "helix-before-change": HelixHeadlessFilterInputHelixBeforeChangeElementEvent;
+  /** Fired before the suggestions go, and cancelable. */
+  "helix-before-close": HelixHeadlessFilterInputHelixBeforeCloseElementEvent;
+  /** Fired before the suggestions show, and cancelable. */
+  "helix-before-open": HelixHeadlessFilterInputHelixBeforeOpenElementEvent;
   /** Announced once the text has moved. */
   input: HelixHeadlessFilterInputElementEvent;
+  /** Says the panel moved, carrying `newState` and `oldState`. */
+  toggle: HelixHeadlessFilterInputElementEvent;
 };
 
 export type HelixHeadlessFormatDateVueProps = {
@@ -8333,7 +8362,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessFileInputVueProps,
     HelixHeadlessFileInputVueEvents
   >;
-  /** **The tokens are the consumer's own elements, slotted.** What a filter narrows by belongs to the consumer's model rather than to this element: a facet with a prefix, a saved query, a range. So they are slotted rather than rendered from a list of strings, and removing one is a request this element makes rather than a change it applies. Combobox is the other way round, and that is the difference between the two: its tokens are a view of a selection it owns, drawn from options it was handed.  **'value' is the text being typed, not the tokens**, which is what makes this a field a consumer can listen to. Every keystroke announces 'input' with the text on the element, so a table narrows as the reader types. The tokens need no reporting back, being markup the consumer already holds.  Backspace on an empty field asks the last token to go, through the same 'helix-dismiss' its own remove control fires, so a consumer who handled the pointer has already handled the keyboard. */
+  /** **The tokens are the consumer's own elements, slotted.** What a filter narrows by belongs to the consumer's model rather than to this element: a facet with a prefix, a saved query, a range. So they are slotted rather than rendered from a list of strings, and removing one is a request this element makes rather than a change it applies. Combobox is the other way round, and that is the difference between the two: its tokens are a view of a selection it owns, drawn from options it was handed.  **'value' is the text being typed, not the tokens**, which is what makes this a field a consumer can listen to. Every keystroke announces 'input' with the text on the element, so a table narrows as the reader types. The tokens need no reporting back, being markup the consumer already holds.  Backspace on an empty field asks the last token to go, through the same 'helix-dismiss' its own remove control fires, so a consumer who handled the pointer has already handled the keyboard.  **It can suggest what to type next, and it never learns the grammar.** Slot 'helix-option' elements into 'suggestions' and the field shows them, moves through them with the arrows, and lets Enter press one; the option fires its own 'helix-select' and the consumer decides what choosing meant. Deciding *what* to suggest is theirs too: keys before a colon and values after it are the same panel with different contents, which is all a two-level filter is, and the parse that tells them apart belongs where the domain does.  **The panel opens when there is something in it and closes when there is not**, rather than on a choice. A reader who picks a key wants its values next, and closing on the choice would shut the panel between two renders. Use 'selectionStart' and 'setSelectionRange' to write a completion back and put the caret after it, or the next parse reads the wrong term. */
   "helix-headless-filter-input": DefineCustomElement<
     HelixHeadlessFilterInput,
     HelixHeadlessFilterInputVueProps,