@fusion.dev/helix 0.177.2 → 0.178.0

package/custom-elements.json

@@ -87900,6 +87900,20 @@
                 "module": "src/filter-input/root/filter-input-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "filterSuggestions",
@@ -87974,6 +87988,18 @@
                 "module": "src/filter-input/root/filter-input-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "suggestionLabel",
@@ -88521,6 +88547,178 @@
                 "module": "src/filter-input/root/filter-input-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "busy",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "description": "Whether the suggestions are loading: `loading`, or a request to `source` out.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "request",
+              "type": {
+                "text": "AbortController | undefined"
+              },
+              "privacy": "private",
+              "description": "The request to `source` still out, which a later one aborts.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "used",
+              "type": {
+                "text": "FilterSource | undefined"
+              },
+              "privacy": "private",
+              "description": "The source the suggestions drawn now came from.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "asking",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new DelayController(this, { renders: false })",
+              "description": "The request waiting out `filterDelay`, if any.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "askSoon",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Asks `source` once typing rests for `filterDelay`, or at once without one.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "move",
@@ -89829,6 +90027,19 @@
                 "module": "src/filter-input/root/filter-input-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFilterInput",
+                "module": "src/filter-input/root/filter-input-root.ts"
+              }
+            },
             {
               "name": "filter-suggestions",
               "type": {
@@ -90035,7 +90246,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",
               "inheritedFrom": {
@@ -90212,7 +90423,7 @@
               }
             },
             {
-              "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",
               "inheritedFrom": {
                 "name": "HelixHeadlessFilterInput",
@@ -90254,7 +90465,7 @@
               }
             },
             {
-              "description": "While `loading` is set.",
+              "description": "While `loading` is set, or a request to `source` is out.",
               "name": "loading",
               "inheritedFrom": {
                 "name": "HelixHeadlessFilterInput",
@@ -93504,6 +93715,23 @@
                 "module": "src/graph/root/graph-root.ts"
               }
             },
+            {
+              "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
+              },
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "linkedBothLabel",
@@ -93793,6 +94021,23 @@
                 "module": "src/graph/root/graph-root.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
+              },
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "zoomedInLabel",
@@ -93869,6 +94114,61 @@
                 "module": "src/graph/root/graph-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "adjacency",
@@ -94043,6 +94343,21 @@
                 "module": "src/graph/root/graph-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "ready",
@@ -94296,6 +94611,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`.",
@@ -94385,6 +94704,104 @@
                 "module": "src/graph/root/graph-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "pageRows",
@@ -94405,7 +94822,18 @@
               "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "handleSearchBlur",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Leaving the field lets go of the note its keys were on.",
               "inheritedFrom": {
                 "name": "HelixHeadlessGraph",
                 "module": "src/graph/root/graph-root.ts"
@@ -94448,6 +94876,7 @@
               "name": "handleSearch",
               "privacy": "private",
               "readonly": true,
+              "description": "Typing is a new search, read from its top, with no note under the keys until Down.",
               "inheritedFrom": {
                 "name": "HelixHeadlessGraph",
                 "module": "src/graph/root/graph-root.ts"
@@ -95166,6 +95595,19 @@
                 "module": "src/graph/root/graph-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "name": "linked-both-label",
               "type": {
@@ -95387,6 +95829,19 @@
                 "module": "src/graph/root/graph-root.ts"
               }
             },
+            {
+              "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",
+              "inheritedFrom": {
+                "name": "HelixHeadlessGraph",
+                "module": "src/graph/root/graph-root.ts"
+              }
+            },
             {
               "name": "wheel-hint-label",
               "type": {
@@ -95492,7 +95947,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",
               "inheritedFrom": {
@@ -250249,6 +250704,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix",
-    "version": "0.177.2"
+    "version": "0.178.0"
   }
 }

package/dist/graph/root/graph-root.css.js

@@ -11,7 +11,8 @@ export const styles = createSheet(`:host {display: contents;}[part="region"] {ba
 slot[name="filter-icon"]::slotted(*) {--icon-size: var(--helix-size-icon-tight);block-size: var(--helix-size-icon-tight);inline-size: var(--helix-size-icon-tight);}[part="search-field"] {appearance: none;background-color: transparent;block-size: var(--helix-size-control-tight);border: none;box-sizing: border-box;color: var(--helix-color-foreground);flex: 1 1 auto;font-family: var(--helix-font-sans);font-size: max(var(--helix-text-field-min), var(--helix-text-sm));font-weight: var(--helix-weight-medium);min-inline-size: 0;padding-inline: var(--helix-space-2xs);}[part="search-field"]::placeholder {color: var(--helix-color-foreground-subtle);}[part="search-field"]:focus-visible {outline: none;}[part="search"]:has([part="search-field"]:focus-visible),
 [part="list"]:focus-visible {outline: var(--helix-size-focus-ring) solid var(--helix-color-focus-ring);outline-offset: calc(var(--helix-size-focus-offset) * -1);}[part="count"] {color: var(--helix-color-foreground-muted);flex: 0 0 auto;font-size: var(--helix-text-xs);font-variant-numeric: tabular-nums;padding-inline-end: calc(var(--helix-space-xs) - var(--helix-space-2xs));}[part="empty"],
 [part="loading"] {color: var(--helix-color-foreground-muted);font-size: var(--helix-text-sm);grid-area: 2 / 1;padding: var(--helix-space-sm);}[part="list"] {min-block-size: 0;overflow-y: auto;overscroll-behavior: contain;padding-block: var(--helix-space-2xs);}[part~="note"] {align-items: center;box-sizing: border-box;cursor: pointer;display: flex;font-size: var(--graph-note-text, var(--helix-text-sm));gap: var(--helix-space-sm);min-block-size: var(--helix-size-control-tight);padding-block: var(--helix-space-2xs);padding-inline: var(--graph-note-padding-inline, var(--helix-space-xs));user-select: none;}[part~="note"]:hover,
-[part="list"]:focus-visible [part~="note-cursor"] {--_graph-wash: var(
+[part="list"]:focus-visible [part~="note-cursor"],
+[part="search"]:has([aria-activedescendant]) ~ [part="list"] [part~="note-cursor"] {--_graph-wash: var(
 --graph-note-hover-color,
 light-dark(
 color-mix(in oklab, var(--helix-color-foreground) 8%, transparent),