@fusion.dev/helix-headless 0.177.2 → 0.178.0

package/custom-elements.json

@@ -69668,6 +69668,30 @@
             "name": "*",
             "module": "src/filter-input/root/filter-input-root.js"
           }
+        },
+        {
+          "kind": "js",
+          "name": "FilterSource",
+          "declaration": {
+            "name": "FilterSource",
+            "module": "./suggest.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "FilterSourceRequest",
+          "declaration": {
+            "name": "FilterSourceRequest",
+            "module": "./suggest.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "FilterSuggestion",
+          "declaration": {
+            "name": "FilterSuggestion",
+            "module": "./suggest.js"
+          }
         }
       ]
     },
@@ -70860,7 +70884,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Tokens are your own elements, slotted in. A filter can be a facet with a\nprefix, a saved query, or a range, and these belong to your model, so the\nelement does not render tokens from a list of strings. Removing a token is a\nrequest the element fires, and you apply it. Combobox works the other way:\nits tokens show a selection it owns, drawn from the options it was given.\n\n`value` is the typed text. Every keystroke fires `input` with the text on the\nelement, so a table can narrow as the user types. Backspace in an empty field\nfires `helix-dismiss` on the last token, the same event its remove control\nfires, so one handler covers the pointer and the keyboard.\n\n**What a form receives.** The text under `name`, and then one more entry\nunder `name` for each token, in the order the tokens stand:\n\n| Token | Entry |\n|---|---|\n| Any element with a `value` attribute | The value as written: `saved:mine` |\n| `FilterChip` with `name` and values | `status:open,pending` |\n| The same, with `operator=\"none\"` (what a typed `-status:` makes) | `-status:open,pending` |\n| The same, with any other `operator` except `any` | `created[after]:2024` |\n| A token with neither | Nothing |\n\nThe values are the chip's text outside its `field` and `operator` slots,\nwith the spaces around each comma removed. A server splits an entry at its\nfirst colon, reads a leading `-` as the negation, and reads a word in\nbrackets before the colon as the comparison.\n\n**Keyboard.** Focus stays in the text, which is the field's one tab stop. The\ntext names the highlighted suggestion as its `aria-activedescendant`, and the\narrow keys reach the tokens.\n\n| Key | What it does |\n|---|---|\n| Enter | Presses the highlighted suggestion. With none highlighted, reads the typed filters into chips, or submits the form when there are none. |\n| Down, Up | Moves the highlight through the suggestions, wrapping, and opens the panel. |\n| Home, End | Highlights the first or the last suggestion while the panel is open. |\n| Escape | Closes the panel and stops there, so a dialog around the field stays open. With the panel closed, empties the text. In an empty field, does nothing, so the page hears it. |\n| Backspace | In an empty field, asks the last token to go. |\n| Left | With the caret at the start of the text, moves to the last token's remove button. Right on a right-to-left page. |\n| Left, Right on a token | Move between the tokens, and past the last back to the text. |\n| Delete, Backspace on a token | Asks the token to go. |\n\n**Typed filters.** The field parses only the fields you declare. Write\n`FilterField` elements, usually inside the `FilterMenu` slotted into `start`,\nso the picker and the text share one set. On Enter, the field reads the text\nagainst them, and a paste is read the same way as soon as it lands.\n`disposition:refunded,settled` and `-disposition:refunded` fire\n`helix-facet` exactly as ticking those values in the picker would, and the\nparsed text is removed. Everything else stays, so `refund tuesday\ndisposition:settled` is a filter and a search at once. Helix defines the\npunctuation and you define every word. `grammar.ts` has the full rule, so\nread it before you rely on it. A field with no `FilterField` in it parses\nnothing.\n\nA field whose values cannot be listed, such as `assignee:ada`, goes directly\ninside this element, outside the menu. It is not assigned to a slot, so\nnothing draws it and the menu has no page for it, and the grammar still reads\nit.\n\n**The picker has an entry of its own.** `FilterMenu` draws its pages with\n`Menu`, which a field without a picker does not need, so this family's entry\nleaves it out. A page that writes one imports\n`@fusion.dev/helix/filter-input/menu` as well, and a picker written without it\nis reported once the page has loaded, with the entry to add.\n\n**Suggestions.** Slot options into `suggestions` and the field shows them,\nmoves through them with the arrow keys, and presses one on Enter. The option\nfires its own `helix-select`, and you decide what choosing it means. Keys\nbefore a colon and values after it use the same panel with different\ncontents. `filter-suggestions` narrows the panel to the options whose words\nhold the term at the caret, after its colon, ignoring case and accents, and\nhides the rest. `readFilterText` is exported so you can narrow it yourself\nagainst partly typed text. While the panel is open, a reader hears how many\nsuggestions it offers. The panel opens when it has options and closes when it has\nnone, and a choice does not close it, so after picking a key you see its\nvalues next. Use `selectionStart` and `setSelectionRange` to write a\ncompletion back and put the caret after it, or the next parse reads the wrong\nterm.\n\n**State.** Three things have three different owners:\n\n- `value` is the text. The user types, the element applies it, and `input`\n  reports it. Setting `value` seeds or corrects the text, and the next\n  keystroke overwrites it, even in React. To control the value, cancel\n  `helix-before-change` and write the value you want, as with every field in\n  this library. `default-value` seeds the field.\n- `open` is the suggestions panel. Cancel `helix-before-open` or\n  `helix-before-close` to control it, and use `default-open` to seed it.\n- Tokens are your elements in a slot and hold no state. A token goes when you\n  remove it from your markup after `helix-dismiss`. A `FilterChip` naming a\n  declared field works differently, because the picker holds what is ticked\n  and removing the chip alone would leave its value ticked in the hidden\n  menu. Its dismissal is treated as the field being filtered by nothing, so\n  it fires `helix-facet` like every other change, and the chip goes when the\n  filter goes. Set `chips` and the field adds, updates, and removes those\n  chips itself, from every `helix-facet` you do not cancel.",
+          "description": "Tokens are your own elements, slotted in. A filter can be a facet with a\nprefix, a saved query, or a range, and these belong to your model, so the\nelement does not render tokens from a list of strings. Removing a token is a\nrequest the element fires, and you apply it. Combobox works the other way:\nits tokens show a selection it owns, drawn from the options it was given.\n\n`value` is the typed text. Every keystroke fires `input` with the text on the\nelement, so a table can narrow as the user types. Backspace in an empty field\nfires `helix-dismiss` on the last token, the same event its remove control\nfires, so one handler covers the pointer and the keyboard.\n\n**What a form receives.** The text under `name`, and then one more entry\nunder `name` for each token, in the order the tokens stand:\n\n| Token | Entry |\n|---|---|\n| Any element with a `value` attribute | The value as written: `saved:mine` |\n| `FilterChip` with `name` and values | `status:open,pending` |\n| The same, with `operator=\"none\"` (what a typed `-status:` makes) | `-status:open,pending` |\n| The same, with any other `operator` except `any` | `created[after]:2024` |\n| A token with neither | Nothing |\n\nThe values are the chip's text outside its `field` and `operator` slots,\nwith the spaces around each comma removed. A server splits an entry at its\nfirst colon, reads a leading `-` as the negation, and reads a word in\nbrackets before the colon as the comparison.\n\n**Keyboard.** Focus stays in the text, which is the field's one tab stop. The\ntext names the highlighted suggestion as its `aria-activedescendant`, and the\narrow keys reach the tokens.\n\n| Key | What it does |\n|---|---|\n| Enter | Presses the highlighted suggestion. With none highlighted, reads the typed filters into chips, or submits the form when there are none. |\n| Down, Up | Moves the highlight through the suggestions, wrapping, and opens the panel. |\n| Home, End | Highlights the first or the last suggestion while the panel is open. |\n| Escape | Closes the panel and stops there, so a dialog around the field stays open. With the panel closed, empties the text. In an empty field, does nothing, so the page hears it. |\n| Backspace | In an empty field, asks the last token to go. |\n| Left | With the caret at the start of the text, moves to the last token's remove button. Right on a right-to-left page. |\n| Left, Right on a token | Move between the tokens, and past the last back to the text. |\n| Delete, Backspace on a token | Asks the token to go. |\n\n**Typed filters.** The field parses only the fields you declare. Write\n`FilterField` elements, usually inside the `FilterMenu` slotted into `start`,\nso the picker and the text share one set. On Enter, the field reads the text\nagainst them, and a paste is read the same way as soon as it lands.\n`disposition:refunded,settled` and `-disposition:refunded` fire\n`helix-facet` exactly as ticking those values in the picker would, and the\nparsed text is removed. Everything else stays, so `refund tuesday\ndisposition:settled` is a filter and a search at once. Helix defines the\npunctuation and you define every word. `grammar.ts` has the full rule, so\nread it before you rely on it. A field with no `FilterField` in it parses\nnothing.\n\nA field whose values cannot be listed, such as `assignee:ada`, goes directly\ninside this element, outside the menu. It is not assigned to a slot, so\nnothing draws it and the menu has no page for it, and the grammar still reads\nit.\n\n**The picker has an entry of its own.** `FilterMenu` draws its pages with\n`Menu`, which a field without a picker does not need, so this family's entry\nleaves it out. A page that writes a `FilterMenu` imports both entries:\n\n```js\nimport '@fusion.dev/helix/filter-input'\nimport '@fusion.dev/helix/filter-input/menu'\n```\n\nA picker written without the second is reported once the page has loaded,\nwith the entry to add.\n\n**Suggestions.** Slot options into `suggestions` and the field shows them,\nmoves through them with the arrow keys, and presses one on Enter. The option\nfires its own `helix-select`, and you decide what choosing it means. Keys\nbefore a colon and values after it use the same panel with different\ncontents. `filter-suggestions` narrows the panel to the options whose words\nhold the term at the caret, after its colon, ignoring case and accents, and\nhides the rest. `readFilterText` is exported so you can narrow it yourself\nagainst partly typed text. While the panel is open, a reader hears how many\nsuggestions it offers. The panel opens when it has options and closes when it has\nnone, and a choice does not close it, so after picking a key you see its\nvalues next. Use `selectionStart` and `setSelectionRange` to write a\ncompletion back and put the caret after it, or the next parse reads the wrong\nterm.\n\n**Suggestions from a source.** Set `source` to a function, and the field asks\nit for suggestions as the text changes and draws them as options in the\npanel. It is given the term at the caret, the field the term is a value of,\nthe whole text, and an `AbortSignal`, and returns the suggestions or a\npromise of them. `filter-delay` waits for typing to rest before asking, and\na later keystroke aborts a request still out. While a promise is pending, the\npanel shows `loading-text` and a screen reader hears it, then the count.\nChoosing a suggestion writes its value over the term at the caret, and a\nfinished `field:value` is read into a chip as Enter would. Cancel its\n`helix-select` to write it yourself.\n\n```js\nfilter.source = async ({ field, term, signal }) => {\n  const response = await fetch(`/values?field=${field}&q=${term}`, { signal })\n  return response.json()\n}\n```\n\n**State.** Three things have three different owners:\n\n- `value` is the text. The user types, the element applies it, and `input`\n  reports it. Setting `value` seeds or corrects the text, and the next\n  keystroke overwrites it, even in React. To control the value, cancel\n  `helix-before-change` and write the value you want, as with every field in\n  this library. `default-value` seeds the field.\n- `open` is the suggestions panel. Cancel `helix-before-open` or\n  `helix-before-close` to control it, and use `default-open` to seed it.\n- Tokens are your elements in a slot and hold no state. A token goes when you\n  remove it from your markup after `helix-dismiss`. A `FilterChip` naming a\n  declared field works differently, because the picker holds what is ticked\n  and removing the chip alone would leave its value ticked in the hidden\n  menu. Its dismissal is treated as the field being filtered by nothing, so\n  it fires `helix-facet` like every other change, and the chip goes when the\n  filter goes. Set `chips` and the field adds, updates, and removes those\n  chips itself, from every `helix-facet` you do not cancel.",
           "name": "HelixHeadlessFilterInput",
           "cssParts": [
             {
@@ -70900,7 +70924,7 @@
               "name": "live"
             },
             {
-              "description": "Shown in the panel while the suggestions load.",
+              "description": "Shown in the panel while the suggestions load: while `loading` is set, or a request to `source` is out.",
               "name": "loading"
             },
             {
@@ -71028,6 +71052,16 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "filterDelay",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "How long typing rests before `source` is asked, in milliseconds. A delay\nsends one request for a word in place of one for each letter. The arrow\nkeys and Enter ask at once. `0` asks on every keystroke.",
+              "attribute": "filter-delay"
+            },
             {
               "kind": "field",
               "name": "filterSuggestions",
@@ -71082,6 +71116,14 @@
               "description": "The text shown while the field is empty.\n\nNot a label: it goes when typing starts.",
               "attribute": "placeholder"
             },
+            {
+              "kind": "field",
+              "name": "source",
+              "type": {
+                "text": "FilterSource | undefined | undefined"
+              },
+              "description": "Where the suggestions come from: a function given the term at the caret,\nthe field it is a value of, the whole text, and an `AbortSignal`, which\nreturns the suggestions or a promise of them. Each is a string, or a\n`value` with a `label` and `disabled`. The field draws them as options in\nthe panel, beside any you slot. A property only, there being no way to\nwrite a function in markup. See the class description."
+            },
             {
               "kind": "field",
               "name": "suggestionLabel",
@@ -71481,6 +71523,130 @@
               },
               "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": "field",
+              "name": "fetching",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether a request to `source` is out, which the panel shows as loading."
+            },
+            {
+              "kind": "field",
+              "name": "busy",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the suggestions are loading: `loading`, or a request to `source` out.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "request",
+              "type": {
+                "text": "AbortController | undefined"
+              },
+              "privacy": "private",
+              "description": "The request to `source` still out, which a later one aborts."
+            },
+            {
+              "kind": "field",
+              "name": "asked",
+              "type": {
+                "text": "string | undefined"
+              },
+              "privacy": "private",
+              "description": "The text `source` was last asked about, so focus alone does not ask again."
+            },
+            {
+              "kind": "field",
+              "name": "used",
+              "type": {
+                "text": "FilterSource | undefined"
+              },
+              "privacy": "private",
+              "description": "The source the suggestions drawn now came from."
+            },
+            {
+              "kind": "field",
+              "name": "sourced",
+              "type": {
+                "text": "SuggestionOption[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The options this element drew from what `source` gave, which the next answer replaces."
+            },
+            {
+              "kind": "field",
+              "name": "asking",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DelayController(this, { renders: false })",
+              "description": "The request waiting out `filterDelay`, if any."
+            },
+            {
+              "kind": "method",
+              "name": "resetSource",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "A new source, or none: what the old one gave goes, and the new one is\nasked where the reader is in the field."
+            },
+            {
+              "kind": "method",
+              "name": "askSoon",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Asks `source` once typing rests for `filterDelay`, or at once without one."
+            },
+            {
+              "kind": "method",
+              "name": "ask",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Asks `source` for suggestions for the term at the caret, and draws what\nit gives.\n\n**A later request aborts this one, and an answer that arrives late is\ndropped**, whether or not the source heeds the signal: the panel shows\nwhat the text says now."
+            },
+            {
+              "kind": "method",
+              "name": "drawSourced",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "suggestions",
+                  "type": {
+                    "text": "readonly FilterSuggestion[]"
+                  }
+                }
+              ],
+              "description": "Draws what `source` gave as options in the `suggestions` slot, in place of\nthe ones it gave before, and leaves the ones you slotted alone. The\noptions are this tier's `Option`, which a page on the headless tier\nimports; one not registered is reported."
+            },
+            {
+              "kind": "field",
+              "name": "handleSourcedSelect",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A suggestion `source` gave, chosen: its value written over the term at the\ncaret, and a finished `field:value` read into a chip, as Enter reads it.\n\n**After every listener has had its turn**, as a chip under `chips` is\ndrawn, so a `preventDefault()` on the `helix-select` is read and leaves the\ntext to you."
+            },
             {
               "kind": "method",
               "name": "move",
@@ -73410,7 +73576,7 @@
               "type": {
                 "text": "HelixSelectEvent"
               },
-              "description": "Fired by an option in `suggestions` when it is chosen, and bubbles out of the field. Cancelable: call `preventDefault()` to stop other listeners acting on it. The field takes no action on a choice; you decide what it does.",
+              "description": "Fired by an option in `suggestions` when it is chosen, and bubbles out of the field. Cancelable: call `preventDefault()` to stop other listeners acting on it. The field takes no action on an option you slotted, and you decide what it does. A suggestion from `source` is written over the term at the caret unless you cancel it.",
               "name": "helix-select",
               "reactProp": "onhelix-select"
             },
@@ -73463,6 +73629,15 @@
               "description": "The name of the clear button, read by screen readers. The button shows only\nan icon.",
               "fieldName": "clearLabel"
             },
+            {
+              "name": "filter-delay",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "How long typing rests before `source` is asked, in milliseconds. A delay\nsends one request for a word in place of one for each letter. The arrow\nkeys and Enter ask at once. `0` asks on every keystroke.",
+              "fieldName": "filterDelay"
+            },
             {
               "name": "filter-suggestions",
               "type": {
@@ -73750,7 +73925,7 @@
               "name": "invalid"
             },
             {
-              "description": "While `loading` is set.",
+              "description": "While `loading` is set, or a request to `source` is out.",
               "name": "loading"
             },
             {
@@ -73868,6 +74043,61 @@
           ],
           "description": "The term being typed at the caret: the run of text since the last space,\nand after its colon where it has one, so `status:ope` narrows by `ope`."
         },
+        {
+          "kind": "function",
+          "name": "currentField",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "text",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "caret",
+              "default": "text.length",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "The field the term at the caret is a value of: the word before its colon,\nwithout a leading `-`, so `-status:ope` is a value of `status`. Empty where\nthe term has no colon, which is a key being typed."
+        },
+        {
+          "kind": "function",
+          "name": "completeTerm",
+          "return": {
+            "type": {
+              "text": "{ caret: number; text: string }"
+            }
+          },
+          "parameters": [
+            {
+              "name": "text",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "caret",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "The text with a suggestion written over the term at the caret, and where\nthe caret goes after it.\n\nThe word's field and its colon stay, and a leading `-`, so a value chosen\nfor `-status:op` gives `-status:open`. A space follows, ready for the next\nterm, unless the suggestion ends with a colon, which is a key whose value\ncomes next."
+        },
         {
           "kind": "function",
           "name": "suggests",
@@ -73938,6 +74168,22 @@
             "module": "src/filter-input/suggest.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "currentField",
+          "declaration": {
+            "name": "currentField",
+            "module": "src/filter-input/suggest.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "completeTerm",
+          "declaration": {
+            "name": "completeTerm",
+            "module": "src/filter-input/suggest.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "suggests",
@@ -75477,7 +75723,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Helix draws no graph. A force layout of thousands of notes is physics and\nWebGL, which a renderer such as Sigma.js does. Put the renderer's box in the\nframe, and `connectGraph` from `@fusion.dev/helix-graph` draws `nodes` and\n`links` in it and keeps it in step with the frame.\n\nWhat the frame adds is what a drawing of a graph cannot do: a list of every\nnote beside it, which is the graph for a screen reader and a quick way to\nfind a note for anyone. The selected note comes first, then the notes it\nlinks to and from, then every other note, and the search field narrows it.\nSelecting a note in the list or in the drawing is the same selection.\n\nSet `depth` to show the local graph: only the notes within that many links\nof the selected one.\n\nSet `legend` to name the groups over the drawing, each a button that shows\nor hides its notes. `hiddenGroups` holds the groups turned off, and the\nlist holds only what the drawing shows. The legend is a toolbar and one tab\nstop: the arrow keys, Home, End and a group's first letters move between\nits buttons, and Space or Enter presses one.\n\n`nodes` and `links` are properties, never markup: a graph of ten thousand\nnotes as ten thousand elements would cost what the renderer exists to save.\nThe list draws only the rows in view.\n\nThe list scrolls on this tier. It carries `data-scroller`, and `core` ships\n`[data-scroller] { overflow: auto }` into every shadow root. You still need\nto set a block size on the list, or it grows to hold every row.",
+          "description": "Helix draws no graph. A force layout of thousands of notes is physics and\nWebGL, which a renderer such as Sigma.js does. Put the renderer's box in the\nframe, and `connectGraph` from `@fusion.dev/helix-graph` draws `nodes` and\n`links` in it and keeps it in step with the frame.\n\nWhat the frame adds is what a drawing of a graph cannot do: a list of every\nnote beside it, which is the graph for a screen reader and a quick way to\nfind a note for anyone. The selected note comes first, then the notes it\nlinks to and from, then every other note, and the search field narrows it.\nSelecting a note in the list or in the drawing is the same selection.\n\nSet `depth` to show the local graph: only the notes within that many links\nof the selected one.\n\nThe search field is a combobox over the list. Down and Up move through the\nnotes while the focus stays in the field, and Enter selects one.\n\n**Walk the links with Alt and the arrow keys**, in the list or in the\nsearch field once its keys are on a note. The note the keys are on is\nmarked in the drawing.\n\n| Key | What it does |\n|---|---|\n| Alt+Right | Follows a link, to the first note the one the keys are on links to or from. |\n| Alt+Down, Alt+Up | Moves to the next or the previous note linked to the one the step came from, wrapping. |\n| Alt+Left | Goes back along the links walked. |\n\nRight and Left swap on a right-to-left page. Each step says the note, how it\nstands to the note it came from, and its place among that note's links,\nsuch as \"Hiring plan. Linked from Roadmap. 2 of 3\". Enter selects the note.\n\nSet `legend` to name the groups over the drawing, each a button that shows\nor hides its notes. `hiddenGroups` holds the groups turned off, and the\nlist holds only what the drawing shows. The legend is a toolbar and one tab\nstop: the arrow keys, Home, End and a group's first letters move between\nits buttons, and Space or Enter presses one.\n\n`nodes` and `links` are properties, never markup: a graph of ten thousand\nnotes as ten thousand elements would cost what the renderer exists to save.\nThe list draws only the rows in view.\n\nThe list scrolls on this tier. It carries `data-scroller`, and `core` ships\n`[data-scroller] { overflow: auto }` into every shadow root. You still need\nto set a block size on the list, or it grows to hold every row.",
           "name": "HelixHeadlessGraph",
           "cssParts": [
             {
@@ -75830,6 +76076,19 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "linkCountLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'{note}. {count, plural, =0 {No links} one {# link} other {# links}}'",
+              "description": "What screen readers hear when a walk along the links reaches a note that\nhas no link to follow, or goes back to a note: `{note}` for its name and\n`{count}` for how many notes the list holds that it links to or from.",
+              "attribute": "link-count-label",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "linkedBothLabel",
@@ -76081,6 +76340,19 @@
                 "module": "src/mixins/mixin-viewport/mixin-viewport.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "walkLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'{note}. {relation}. {index} of {count}'",
+              "description": "What screen readers hear when a walk along the links moves to a note:\n`{note}` for its name, `{relation}` for how it stands to the note the\nstep came from, such as \"Linked from Roadmap\", and `{index}` and `{count}`\nfor its place among that note's links.",
+              "attribute": "walk-label",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "wheelHintLabel",
@@ -76154,6 +76426,45 @@
               "default": "false",
               "description": "Whether the search and the list are open over the drawing, with `no-panel`."
             },
+            {
+              "kind": "field",
+              "name": "fieldKeys",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the search field's arrow keys have moved onto a note, which the\nfield then names as its `aria-activedescendant` while the focus stays in\nit. Typing, Left, Right, Escape, and leaving the field let it go."
+            },
+            {
+              "kind": "field",
+              "name": "listKeys",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the list has the focus, so the drawing marks the note its keys are on."
+            },
+            {
+              "kind": "field",
+              "name": "trail",
+              "type": {
+                "text": "string[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The notes a walk along the links stepped from, by `id`, the last the one\nthe note the keys are on was reached from. Empty when the keys moved some\nother way."
+            },
+            {
+              "kind": "field",
+              "name": "keyedSent",
+              "type": {
+                "text": "string | undefined"
+              },
+              "privacy": "private",
+              "description": "The note the drawing last heard the keys are on, so it hears each move once."
+            },
             {
               "kind": "field",
               "name": "adjacency",
@@ -76276,6 +76587,17 @@
               "readonly": true,
               "default": "new VirtualizeController(this, { container: () => this.partNamed('list'), count: () => this.entries.length, estimate: () => 32, rows: () => [...(this.renderRoot.querySelectorAll?.('[data-index]') ?? [])].map((element) => ({ element: element as HTMLElement, index: Number((element as HTMLElement).dataset.index), })), })"
             },
+            {
+              "kind": "method",
+              "name": "keyedId",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string | undefined"
+                }
+              },
+              "description": "The `id` of the note the keys are on, or `undefined` where neither the list nor the field has them."
+            },
             {
               "kind": "field",
               "name": "ready",
@@ -76592,6 +76914,10 @@
                   "type": {
                     "text": "number"
                   }
+                },
+                {
+                  "name": "walking",
+                  "default": "false"
                 }
               ],
               "description": "Moves the keyboard to a row, and the list to show it.\n\n**The row the keys are on is always drawn**, beside the window where it is\noutside it, so `aria-activedescendant` names a row that exists. The list\nthen scrolls to it, see `revealCursor`."
@@ -76657,6 +76983,88 @@
               ],
               "description": "Moves to the next note whose name starts with what was typed, through\ncore's `Typeahead`, as a listbox does: letters within half a second run\ntogether, and a repeated letter steps through the names that start with it."
             },
+            {
+              "kind": "method",
+              "name": "linkedRows",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "id",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "The rows of the notes `id` links to or is linked from, in the list's\norder, which is the order of their names. Only the notes the list holds:\na search, the legend, or `depth` leaves the others out."
+            },
+            {
+              "kind": "method",
+              "name": "relationFrom",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "from",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "id",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "How the note `id` stands to the note `from`, in the words the list uses for the selection."
+            },
+            {
+              "kind": "method",
+              "name": "walk",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "A walk along the links from the note the keys are on, with Alt and the\narrow keys, so a reader follows the lines of the drawing and not only\nthe order of the list. **The same four keys a tree takes**, with Alt,\nsince the list's own arrows already move through it:\n\n- Alt+Right follows a link, to the first note the one the keys are on\n  links to or from.\n- Alt+Down and Alt+Up move to the next and the previous note linked to\n  the one the step came from, wrapping.\n- Alt+Left goes back along the links walked.\n\nRight and Left swap on a right-to-left page. Each step says the note, how\nit stands to the note it was reached from, and its place among that\nnote's links. Returns whether the key was one of the walk's."
+            },
+            {
+              "kind": "method",
+              "name": "sayLinks",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Says the note at row `at` and how many notes in the list it links to or from."
+            },
             {
               "kind": "method",
               "name": "pageRows",
@@ -76673,7 +77081,14 @@
               "name": "handleSearchKeydown",
               "privacy": "private",
               "readonly": true,
-              "description": "The search field's keys, which belong to the field and never pan the\ngraph. Escape empties a search that has words in it, and passes through\nan empty one to whatever the page does with it."
+              "description": "The search field's keys, which belong to the field and never pan the\ngraph.\n\n**The field is a combobox over the list**, as React Aria's Autocomplete\nand the APG combobox are: the focus stays in the field, and Down and Up\nmove the keys through the notes, which the field names as its\n`aria-activedescendant`. Down starts on the note the keys were last on,\nthe first after a search, and Up on the last. Page Down and Page Up move\na page, Enter selects, Alt and the arrows walk the links as in the list,\nand Left, Right, Home and End go back to the text.\n\nEscape lets the note go, then empties a search that has words in it, and\npasses through an empty one to whatever the page does with it."
+            },
+            {
+              "kind": "field",
+              "name": "handleSearchBlur",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Leaving the field lets go of the note its keys were on."
             },
             {
               "kind": "method",
@@ -76718,7 +77133,8 @@
               "kind": "field",
               "name": "handleSearch",
               "privacy": "private",
-              "readonly": true
+              "readonly": true,
+              "description": "Typing is a new search, read from its top, with no note under the keys until Down."
             },
             {
               "kind": "method",
@@ -77905,7 +78321,7 @@
               "type": {
                 "text": "HelixGraphPartChangeEvent"
               },
-              "description": "The notes, the links, the selection, the depth or the gestures changed. Used by `connectGraph`; pages do not need to listen for it.",
+              "description": "The notes, the links, the selection, the depth, the note the keys are on, or the gestures changed. Used by `connectGraph`; pages do not need to listen for it.",
               "name": "helix-graph-part-change",
               "reactProp": "onhelix-graph-part-change"
             },
@@ -78015,6 +78431,15 @@
               "description": "The legend's name, read by screen readers.",
               "fieldName": "legendLabel"
             },
+            {
+              "name": "link-count-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'{note}. {count, plural, =0 {No links} one {# link} other {# links}}'",
+              "description": "What screen readers hear when a walk along the links reaches a note that\nhas no link to follow, or goes back to a note: `{note}` for its name and\n`{count}` for how many notes the list holds that it links to or from.",
+              "fieldName": "linkCountLabel"
+            },
             {
               "name": "linked-both-label",
               "type": {
@@ -78168,6 +78593,15 @@
               "description": "The line shown while the graph, with `gestures=\"activate\"`, has the gestures.",
               "fieldName": "usingLabel"
             },
+            {
+              "name": "walk-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'{note}. {relation}. {index} of {count}'",
+              "description": "What screen readers hear when a walk along the links moves to a note:\n`{note}` for its name, `{relation}` for how it stands to the note the\nstep came from, such as \"Linked from Roadmap\", and `{index}` and `{count}`\nfor its place among that note's links.",
+              "fieldName": "walkLabel"
+            },
             {
               "name": "wheel-hint-label",
               "type": {
@@ -199002,6 +199436,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-headless",
-    "version": "0.177.2"
+    "version": "0.178.0"
   }
 }

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

@@ -3,3 +3,4 @@ export * from './field/filter-field.js';
 export * from './grammar.js';
 export * from './operator/filter-operator.js';
 export * from './root/filter-input-root.js';
+export type { FilterSource, FilterSourceRequest, FilterSuggestion } from './suggest.js';