@fusion.dev/helix-headless 0.177.2 → 0.179.0

package/types/vue.d.ts

@@ -7245,6 +7245,14 @@ an icon. */
   /** The name of the clear button, read by screen readers. The button shows only
 an icon. */
   clearLabel?: (HelixHeadlessFilterInput["clearLabel"]) | undefined;
+  /** How long typing rests before `source` is asked, in milliseconds. A delay
+sends one request for a word in place of one for each letter. The arrow
+keys and Enter ask at once. `0` asks on every keystroke. */
+  "filter-delay"?: (HelixHeadlessFilterInput["filterDelay"] | `${number}`) | undefined;
+  /** How long typing rests before `source` is asked, in milliseconds. A delay
+sends one request for a word in place of one for each letter. The arrow
+keys and Enter ask at once. `0` asks on every keystroke. */
+  filterDelay?: (HelixHeadlessFilterInput["filterDelay"]) | undefined;
   /** Whether the panel narrows itself to the suggestions that hold the term
 being typed, as React Aria's Autocomplete filters. Off, the panel shows
 what you slot and you narrow it. */
@@ -7438,6 +7446,13 @@ imperatively later, and nothing is hydrating by then.
 
 Here rather than on each control. */
   name?: (HelixHeadlessFilterInput["name"]) | undefined;
+  /** Where the suggestions come from: a function given the term at the caret,
+the field it is a value of, the whole text, and an `AbortSignal`, which
+returns the suggestions or a promise of them. Each is a string, or a
+`value` with a `label` and `disabled`. The field draws them as options in
+the panel, beside any you slot. A property only, there being no way to
+write a function in markup. See the class description. */
+  source?: (HelixHeadlessFilterInput["source"]) | undefined;
 };
 
 export type HelixHeadlessFilterInputVueEvents = {
@@ -7453,7 +7468,7 @@ export type HelixHeadlessFilterInputVueEvents = {
   "helix-dismiss": HelixHeadlessFilterInputHelixDismissElementEvent;
   /** Fired when a filter changes, whether it was typed, picked, or removed. Cancelable: call `preventDefault()` to leave the text and the chip as they were. */
   "helix-facet": HelixHeadlessFilterInputHelixFacetElementEvent;
-  /** 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. */
+  /** 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. */
   "helix-select": HelixHeadlessFilterInputHelixSelectElementEvent;
   /** Fired when the text changes. */
   input: HelixHeadlessFilterInputElementEvent;
@@ -7685,6 +7700,14 @@ or hides its notes. Drawn where the notes have two groups or more. */
   "legend-label"?: (HelixHeadlessGraph["legendLabel"]) | undefined;
   /** The legend's name, read by screen readers. */
   legendLabel?: (HelixHeadlessGraph["legendLabel"]) | undefined;
+  /** What screen readers hear when a walk along the links reaches a note that
+has no link to follow, or goes back to a note: `{note}` for its name and
+`{count}` for how many notes the list holds that it links to or from. */
+  "link-count-label"?: (HelixHeadlessGraph["linkCountLabel"]) | undefined;
+  /** What screen readers hear when a walk along the links reaches a note that
+has no link to follow, or goes back to a note: `{note}` for its name and
+`{count}` for how many notes the list holds that it links to or from. */
+  linkCountLabel?: (HelixHeadlessGraph["linkCountLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
   "linked-both-label"?: (HelixHeadlessGraph["linkedBothLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
@@ -7764,6 +7787,16 @@ the list then holds, written with `count-label`. */
   "using-label"?: (HelixHeadlessGraph["usingLabel"]) | undefined;
   /** The line shown while the graph, with `gestures="activate"`, has the gestures. */
   usingLabel?: (HelixHeadlessGraph["usingLabel"]) | undefined;
+  /** What screen readers hear when a walk along the links moves to a note:
+`{note}` for its name, `{relation}` for how it stands to the note the
+step came from, such as "Linked from Roadmap", and `{index}` and `{count}`
+for its place among that note's links. */
+  "walk-label"?: (HelixHeadlessGraph["walkLabel"]) | undefined;
+  /** What screen readers hear when a walk along the links moves to a note:
+`{note}` for its name, `{relation}` for how it stands to the note the
+step came from, such as "Linked from Roadmap", and `{index}` and `{count}`
+for its place among that note's links. */
+  walkLabel?: (HelixHeadlessGraph["walkLabel"]) | undefined;
   /** The hint shown when the wheel scrolls past the graph with
 `gestures="cooperative"`. `{key}` is ⌘ on a Mac and Ctrl elsewhere. */
   "wheel-hint-label"?: (HelixHeadlessGraph["wheelHintLabel"]) | undefined;
@@ -7956,7 +7989,7 @@ export type HelixHeadlessGraphVueEvents = {
   "helix-graph-layout": HelixHeadlessGraphHelixGraphLayoutElementEvent;
   /** A pan button or arrow key was pressed. `connectGraph` moves the drawing, then calls `moved()`. */
   "helix-graph-pan": HelixHeadlessGraphHelixGraphPanElementEvent;
-  /** The notes, the links, the selection, the depth or the gestures changed. Used by `connectGraph`; pages do not need to listen for it. */
+  /** 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. */
   "helix-graph-part-change": HelixHeadlessGraphHelixGraphPartChangeElementEvent;
   /** The graph has been drawn whole, laid out and settled. Sent each time `drawn()` says it is drawn after it was not. */
   "helix-graph-ready": HelixHeadlessGraphHelixGraphReadyElementEvent;
@@ -7974,6 +8007,12 @@ export type HelixHeadlessHeatmapElementEvent<E = Event> = TypedEvent<
 /** `helix-before-change` event type */
 export type HelixHeadlessHeatmapHelixBeforeChangeElementEvent =
   HelixHeadlessHeatmapElementEvent<HelixBeforeChangeEvent>;
+/** `helix-reading-change` event type */
+export type HelixHeadlessHeatmapHelixReadingChangeElementEvent =
+  HelixHeadlessHeatmapElementEvent<HelixReadingChangeEvent>;
+/** `helix-reading-press` event type */
+export type HelixHeadlessHeatmapHelixReadingPressElementEvent =
+  HelixHeadlessHeatmapElementEvent<HelixReadingPressEvent>;
 /** `helix-resize` event type */
 export type HelixHeadlessHeatmapHelixResizeElementEvent =
   HelixHeadlessHeatmapElementEvent<HelixResizeEvent>;
@@ -7985,16 +8024,6 @@ export type HelixHeadlessHeatmapVueProps = {
   /** The name the `overview` gives the busiest reading, `{busiestLabel}` in
 `overview-label`. */
   busiestLabel?: (HelixHeadlessHeatmap["busiestLabel"]) | undefined;
-  /** Shown when the table has no readings in it.
-
-Never shown while the table cannot be read at all, which is a server render
-and the hydrating one after it: see `sourceKnown`. */
-  "empty-text"?: (HelixHeadlessHeatmap["emptyText"]) | undefined;
-  /** Shown when the table has no readings in it.
-
-Never shown while the table cannot be read at all, which is a server render
-and the hydrating one after it: see `sourceKnown`. */
-  emptyText?: (HelixHeadlessHeatmap["emptyText"]) | undefined;
   /** Space between cells, in CSS pixels. It is a number for the same reason
 `min-cell` is. */
   gap?: (HelixHeadlessHeatmap["gap"]) | undefined;
@@ -8052,13 +8081,9 @@ calendar heatmap does: a week is a column, so the strip reads along the
 line in weeks, from the right on a right-to-left page, and top to bottom in
 days. */
   rows?: (HelixHeadlessHeatmap["rows"]) | undefined;
-  /** What the readout adds for a selected cell, under `selection-mode`, after
-where the cell stands: "Day 1: 0 (1 of 14, selected)". Empty adds
-nothing. */
+  /** What the readout added for a selected cell, under `selection-mode`. */
   "selected-label"?: (HelixHeadlessHeatmap["selectedLabel"]) | undefined;
-  /** What the readout adds for a selected cell, under `selection-mode`, after
-where the cell stands: "Day 1: 0 (1 of 14, selected)". Empty adds
-nothing. */
+  /** What the readout added for a selected cell, under `selection-mode`. */
   selectedLabel?: (HelixHeadlessHeatmap["selectedLabel"]) | undefined;
   /** What the `selection` part says after the selection changes. `{count}` is
 how many cells are selected, written in the locale, and a language that
@@ -8115,6 +8140,25 @@ header's words where it carries none.
 Set it to start with cells selected. Written by a press or a key under
 `selection-mode`. */
   value?: (HelixHeadlessHeatmap["value"]) | undefined;
+  /** The words shown in place of the drawing when the table has no readings,
+and the fallback of the `empty` slot. */
+  "empty-text"?: (HelixHeadlessHeatmap["emptyText"]) | undefined;
+  /** The words shown in place of the drawing when the table has no readings,
+and the fallback of the `empty` slot. */
+  emptyText?: (HelixHeadlessHeatmap["emptyText"]) | undefined;
+  /** Whether the readings are still on their way. The chart shows
+`loading-text` in place of an empty drawing until it has readings.
+
+Reflected, so a stylesheet can treat the chart while it waits. A chart
+that already has readings keeps drawing them, so a refresh does not
+blank it. */
+  loading?: (HelixHeadlessHeatmap["loading"]) | undefined;
+  /** The words shown in place of the drawing while `loading` is set and
+there are no readings yet, and the fallback of the `loading` slot. */
+  "loading-text"?: (HelixHeadlessHeatmap["loadingText"]) | undefined;
+  /** The words shown in place of the drawing while `loading` is set and
+there are no readings yet, and the fallback of the `loading` slot. */
+  loadingText?: (HelixHeadlessHeatmap["loadingText"]) | undefined;
   /** The id of the table to read.
 
 Names a table in the same tree, so a chart inside another component's
@@ -8181,6 +8225,10 @@ export type HelixHeadlessHeatmapVueEvents = {
   change: HelixHeadlessHeatmapElementEvent;
   /** Fired before a press or a key changes which cells are selected, with the `value` it would leave. Cancelable. */
   "helix-before-change": HelixHeadlessHeatmapHelixBeforeChangeElementEvent;
+  /** The reading shown moved, or was put away: `index` is the row, or `-1` for none, with its `label`, the `series` the keys rest on, and the `pointerType` that moved it. */
+  "helix-reading-change": HelixHeadlessHeatmapHelixReadingChangeElementEvent;
+  /** A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`. */
+  "helix-reading-press": HelixHeadlessHeatmapHelixReadingPressElementEvent;
   /** Fired when the number of cells drawn changes, with the new number. */
   "helix-resize": HelixHeadlessHeatmapHelixResizeElementEvent;
 };
@@ -11388,6 +11436,20 @@ empty string would give. */
   "default-read"?: (HelixHeadlessNotification["defaultRead"]) | undefined;
   /** Whether the notification starts as read, used until `read` is set. */
   defaultRead?: (HelixHeadlessNotification["defaultRead"]) | undefined;
+  /** The dismiss control's name, read by screen readers, with `{label}` for the
+row's own words.
+
+One sentence with the words in it, so a translation puts them where its
+language does: `registerWords('de', { 'helix-notification': { dismissLabel:
+'{label} schließen' } })`. */
+  "dismiss-label"?: (HelixHeadlessNotification["dismissLabel"]) | undefined;
+  /** The dismiss control's name, read by screen readers, with `{label}` for the
+row's own words.
+
+One sentence with the words in it, so a translation puts them where its
+language does: `registerWords('de', { 'helix-notification': { dismissLabel:
+'{label} schließen' } })`. */
+  dismissLabel?: (HelixHeadlessNotification["dismissLabel"]) | undefined;
   /** Locale for the timestamp.
 
 Empty is the runtime's own. */
@@ -11418,28 +11480,6 @@ its place. Translate it with the rest of your interface. */
   unreadLabel?: (HelixHeadlessNotification["unreadLabel"]) | undefined;
   /** Whether the element shows a control that dismisses it. */
   dismissible?: (HelixHeadlessNotification["dismissible"]) | undefined;
-  /** The dismiss control's label, read by screen readers.
-
-`attribute` is spelled out because Lit lowercases a property name to
-derive one rather than dash-casing it, so this would otherwise be
-reachable only as `dismisslabel`, which nobody would guess and no linter
-would catch.
-
-A word property: register it for a locale under the host's key. A family
-that names the control otherwise, such as Tag's `Remove {label}`,
-declares its own English with `@words` above the override. */
-  "dismiss-label"?: (HelixHeadlessNotification["dismissLabel"]) | undefined;
-  /** The dismiss control's label, read by screen readers.
-
-`attribute` is spelled out because Lit lowercases a property name to
-derive one rather than dash-casing it, so this would otherwise be
-reachable only as `dismisslabel`, which nobody would guess and no linter
-would catch.
-
-A word property: register it for a locale under the host's key. A family
-that names the control otherwise, such as Tag's `Remove {label}`,
-declares its own English with `@words` above the override. */
-  dismissLabel?: (HelixHeadlessNotification["dismissLabel"]) | undefined;
 };
 
 export type HelixHeadlessNotificationVueEvents = {
@@ -19504,7 +19544,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessFilterOperatorVueProps,
     HelixHeadlessFilterOperatorVueEvents
   >;
-  /** Tokens are your own elements, slotted in. A filter can be a facet with a prefix, a saved query, or a range, and these belong to your model, so the element does not render tokens from a list of strings. Removing a token is a request the element fires, and you apply it. Combobox works the other way: its tokens show a selection it owns, drawn from the options it was given.  'value' is the typed text. Every keystroke fires 'input' with the text on the element, so a table can narrow as the user types. Backspace in an empty field fires 'helix-dismiss' on the last token, the same event its remove control fires, so one handler covers the pointer and the keyboard.  **What a form receives.** The text under 'name', and then one more entry under 'name' for each token, in the order the tokens stand:  | Token | Entry | |---|---| | Any element with a 'value' attribute | The value as written: 'saved:mine' | | 'FilterChip' with 'name' and values | 'status:open,pending' | | The same, with 'operator="none"' (what a typed '-status:' makes) | '-status:open,pending' | | The same, with any other 'operator' except 'any' | 'created[after]:2024' | | A token with neither | Nothing |  The values are the chip's text outside its 'field' and 'operator' slots, with the spaces around each comma removed. A server splits an entry at its first colon, reads a leading '-' as the negation, and reads a word in brackets before the colon as the comparison.  **Keyboard.** Focus stays in the text, which is the field's one tab stop. The text names the highlighted suggestion as its 'aria-activedescendant', and the arrow keys reach the tokens.  | Key | What it does | |---|---| | Enter | Presses the highlighted suggestion. With none highlighted, reads the typed filters into chips, or submits the form when there are none. | | Down, Up | Moves the highlight through the suggestions, wrapping, and opens the panel. | | Home, End | Highlights the first or the last suggestion while the panel is open. | | 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. | | Backspace | In an empty field, asks the last token to go. | | 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. | | Left, Right on a token | Move between the tokens, and past the last back to the text. | | Delete, Backspace on a token | Asks the token to go. |  **Typed filters.** The field parses only the fields you declare. Write 'FilterField' elements, usually inside the 'FilterMenu' slotted into 'start', so the picker and the text share one set. On Enter, the field reads the text against them, and a paste is read the same way as soon as it lands. 'disposition:refunded,settled' and '-disposition:refunded' fire 'helix-facet' exactly as ticking those values in the picker would, and the parsed text is removed. Everything else stays, so 'refund tuesday disposition:settled' is a filter and a search at once. Helix defines the punctuation and you define every word. 'grammar.ts' has the full rule, so read it before you rely on it. A field with no 'FilterField' in it parses nothing.  A field whose values cannot be listed, such as 'assignee:ada', goes directly inside this element, outside the menu. It is not assigned to a slot, so nothing draws it and the menu has no page for it, and the grammar still reads it.  **The picker has an entry of its own.** 'FilterMenu' draws its pages with 'Menu', which a field without a picker does not need, so this family's entry leaves it out. A page that writes one imports '@fusion.dev/helix/filter-input/menu' as well, and a picker written without it is reported once the page has loaded, with the entry to add.  **Suggestions.** Slot options into 'suggestions' and the field shows them, moves through them with the arrow keys, and presses one on Enter. The option fires its own 'helix-select', and you decide what choosing it means. Keys before a colon and values after it use the same panel with different contents. 'filter-suggestions' narrows the panel to the options whose words hold the term at the caret, after its colon, ignoring case and accents, and hides the rest. 'readFilterText' is exported so you can narrow it yourself against partly typed text. While the panel is open, a reader hears how many suggestions it offers. The panel opens when it has options and closes when it has none, and a choice does not close it, so after picking a key you see its values next. Use 'selectionStart' and 'setSelectionRange' to write a completion back and put the caret after it, or the next parse reads the wrong term.  **State.** Three things have three different owners:  - 'value' is the text. The user types, the element applies it, and 'input'   reports it. Setting 'value' seeds or corrects the text, and the next   keystroke overwrites it, even in React. To control the value, cancel   'helix-before-change' and write the value you want, as with every field in   this library. 'default-value' seeds the field. - 'open' is the suggestions panel. Cancel 'helix-before-open' or   'helix-before-close' to control it, and use 'default-open' to seed it. - Tokens are your elements in a slot and hold no state. A token goes when you   remove it from your markup after 'helix-dismiss'. A 'FilterChip' naming a   declared field works differently, because the picker holds what is ticked   and removing the chip alone would leave its value ticked in the hidden   menu. Its dismissal is treated as the field being filtered by nothing, so   it fires 'helix-facet' like every other change, and the chip goes when the   filter goes. Set 'chips' and the field adds, updates, and removes those   chips itself, from every 'helix-facet' you do not cancel. */
+  /** Tokens are your own elements, slotted in. A filter can be a facet with a prefix, a saved query, or a range, and these belong to your model, so the element does not render tokens from a list of strings. Removing a token is a request the element fires, and you apply it. Combobox works the other way: its tokens show a selection it owns, drawn from the options it was given.  'value' is the typed text. Every keystroke fires 'input' with the text on the element, so a table can narrow as the user types. Backspace in an empty field fires 'helix-dismiss' on the last token, the same event its remove control fires, so one handler covers the pointer and the keyboard.  **What a form receives.** The text under 'name', and then one more entry under 'name' for each token, in the order the tokens stand:  | Token | Entry | |---|---| | Any element with a 'value' attribute | The value as written: 'saved:mine' | | 'FilterChip' with 'name' and values | 'status:open,pending' | | The same, with 'operator="none"' (what a typed '-status:' makes) | '-status:open,pending' | | The same, with any other 'operator' except 'any' | 'created[after]:2024' | | A token with neither | Nothing |  The values are the chip's text outside its 'field' and 'operator' slots, with the spaces around each comma removed. A server splits an entry at its first colon, reads a leading '-' as the negation, and reads a word in brackets before the colon as the comparison.  **Keyboard.** Focus stays in the text, which is the field's one tab stop. The text names the highlighted suggestion as its 'aria-activedescendant', and the arrow keys reach the tokens.  | Key | What it does | |---|---| | Enter | Presses the highlighted suggestion. With none highlighted, reads the typed filters into chips, or submits the form when there are none. | | Down, Up | Moves the highlight through the suggestions, wrapping, and opens the panel. | | Home, End | Highlights the first or the last suggestion while the panel is open. | | 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. | | Backspace | In an empty field, asks the last token to go. | | 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. | | Left, Right on a token | Move between the tokens, and past the last back to the text. | | Delete, Backspace on a token | Asks the token to go. |  **Typed filters.** The field parses only the fields you declare. Write 'FilterField' elements, usually inside the 'FilterMenu' slotted into 'start', so the picker and the text share one set. On Enter, the field reads the text against them, and a paste is read the same way as soon as it lands. 'disposition:refunded,settled' and '-disposition:refunded' fire 'helix-facet' exactly as ticking those values in the picker would, and the parsed text is removed. Everything else stays, so 'refund tuesday disposition:settled' is a filter and a search at once. Helix defines the punctuation and you define every word. 'grammar.ts' has the full rule, so read it before you rely on it. A field with no 'FilterField' in it parses nothing.  A field whose values cannot be listed, such as 'assignee:ada', goes directly inside this element, outside the menu. It is not assigned to a slot, so nothing draws it and the menu has no page for it, and the grammar still reads it.  **The picker has an entry of its own.** 'FilterMenu' draws its pages with 'Menu', which a field without a picker does not need, so this family's entry leaves it out. A page that writes a 'FilterMenu' imports both entries:  '''js import '@fusion.dev/helix/filter-input' import '@fusion.dev/helix/filter-input/menu' '''  A picker written without the second is reported once the page has loaded, with the entry to add.  **Suggestions.** Slot options into 'suggestions' and the field shows them, moves through them with the arrow keys, and presses one on Enter. The option fires its own 'helix-select', and you decide what choosing it means. Keys before a colon and values after it use the same panel with different contents. 'filter-suggestions' narrows the panel to the options whose words hold the term at the caret, after its colon, ignoring case and accents, and hides the rest. 'readFilterText' is exported so you can narrow it yourself against partly typed text. While the panel is open, a reader hears how many suggestions it offers. The panel opens when it has options and closes when it has none, and a choice does not close it, so after picking a key you see its values next. Use 'selectionStart' and 'setSelectionRange' to write a completion back and put the caret after it, or the next parse reads the wrong term.  **Suggestions from a source.** Set 'source' to a function, and the field asks it for suggestions as the text changes and draws them as options in the panel. It is given the term at the caret, the field the term is a value of, the whole text, and an 'AbortSignal', and returns the suggestions or a promise of them. 'filter-delay' waits for typing to rest before asking, and a later keystroke aborts a request still out. While a promise is pending, the panel shows 'loading-text' and a screen reader hears it, then the count. Choosing a suggestion writes its value over the term at the caret, and a finished 'field:value' is read into a chip as Enter would. Cancel its 'helix-select' to write it yourself.  '''js filter.source = async ({ field, term, signal }) => {   const response = await fetch('/values?field=${field}&q=${term}', { signal })   return response.json() } '''  **State.** Three things have three different owners:  - 'value' is the text. The user types, the element applies it, and 'input'   reports it. Setting 'value' seeds or corrects the text, and the next   keystroke overwrites it, even in React. To control the value, cancel   'helix-before-change' and write the value you want, as with every field in   this library. 'default-value' seeds the field. - 'open' is the suggestions panel. Cancel 'helix-before-open' or   'helix-before-close' to control it, and use 'default-open' to seed it. - Tokens are your elements in a slot and hold no state. A token goes when you   remove it from your markup after 'helix-dismiss'. A 'FilterChip' naming a   declared field works differently, because the picker holds what is ticked   and removing the chip alone would leave its value ticked in the hidden   menu. Its dismissal is treated as the field being filtered by nothing, so   it fires 'helix-facet' like every other change, and the chip goes when the   filter goes. Set 'chips' and the field adds, updates, and removes those   chips itself, from every 'helix-facet' you do not cancel. */
   "helix-headless-filter-input": DefineCustomElement<
     HelixHeadlessFilterInput,
     HelixHeadlessFilterInputVueProps,
@@ -19516,13 +19556,13 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessFormatDateVueProps,
     HelixHeadlessFormatDateVueEvents
   >;
-  /** Helix draws no graph. A force layout of thousands of notes is physics and WebGL, which a renderer such as Sigma.js does. Put the renderer's box in the frame, and 'connectGraph' from '@fusion.dev/helix-graph' draws 'nodes' and 'links' in it and keeps it in step with the frame.  What the frame adds is what a drawing of a graph cannot do: a list of every note beside it, which is the graph for a screen reader and a quick way to find a note for anyone. The selected note comes first, then the notes it links to and from, then every other note, and the search field narrows it. Selecting a note in the list or in the drawing is the same selection.  Set 'depth' to show the local graph: only the notes within that many links of the selected one.  Set 'legend' to name the groups over the drawing, each a button that shows or hides its notes. 'hiddenGroups' holds the groups turned off, and the list holds only what the drawing shows. The legend is a toolbar and one tab stop: the arrow keys, Home, End and a group's first letters move between its buttons, and Space or Enter presses one.  'nodes' and 'links' are properties, never markup: a graph of ten thousand notes as ten thousand elements would cost what the renderer exists to save. The list draws only the rows in view.  The list scrolls on this tier. It carries 'data-scroller', and 'core' ships '[data-scroller] { overflow: auto }' into every shadow root. You still need to set a block size on the list, or it grows to hold every row. */
+  /** Helix draws no graph. A force layout of thousands of notes is physics and WebGL, which a renderer such as Sigma.js does. Put the renderer's box in the frame, and 'connectGraph' from '@fusion.dev/helix-graph' draws 'nodes' and 'links' in it and keeps it in step with the frame.  What the frame adds is what a drawing of a graph cannot do: a list of every note beside it, which is the graph for a screen reader and a quick way to find a note for anyone. The selected note comes first, then the notes it links to and from, then every other note, and the search field narrows it. Selecting a note in the list or in the drawing is the same selection.  Set 'depth' to show the local graph: only the notes within that many links of the selected one.  The search field is a combobox over the list. Down and Up move through the notes while the focus stays in the field, and Enter selects one.  **Walk the links with Alt and the arrow keys**, in the list or in the search field once its keys are on a note. The note the keys are on is marked in the drawing.  | Key | What it does | |---|---| | Alt+Right | Follows a link, to the first note the one the keys are on links to or from. | | Alt+Down, Alt+Up | Moves to the next or the previous note linked to the one the step came from, wrapping. | | Alt+Left | Goes back along the links walked. |  Right and Left swap on a right-to-left page. Each step says the note, how it stands to the note it came from, and its place among that note's links, such as "Hiring plan. Linked from Roadmap. 2 of 3". Enter selects the note.  Set 'legend' to name the groups over the drawing, each a button that shows or hides its notes. 'hiddenGroups' holds the groups turned off, and the list holds only what the drawing shows. The legend is a toolbar and one tab stop: the arrow keys, Home, End and a group's first letters move between its buttons, and Space or Enter presses one.  'nodes' and 'links' are properties, never markup: a graph of ten thousand notes as ten thousand elements would cost what the renderer exists to save. The list draws only the rows in view.  The list scrolls on this tier. It carries 'data-scroller', and 'core' ships '[data-scroller] { overflow: auto }' into every shadow root. You still need to set a block size on the list, or it grows to hold every row. */
   "helix-headless-graph": DefineCustomElement<
     HelixHeadlessGraph,
     HelixHeadlessGraphVueProps,
     HelixHeadlessGraphVueEvents
   >;
-  /** A grid of cells, each colored by a tone. 'rows="1"' makes a status strip, and 'rows="7"' makes a contribution graph. GitHub's contribution graph uses five discrete levels, which a set of tones covers.  Color in a heatmap is per cell. In every other Helix chart, color is per series, so ninety differently colored cells would need ninety series.  **The data is a real '<table>' named by 'for'**, as in every Helix chart, and the table is the accessible representation. Hide it with 'data-hidden-visually', and screen readers still read it.  A cell takes its tone from its own 'data-tone', or from 'thresholds' and 'tones' applied to its value. 'data-tone' wins, so when you already know a day was degraded, you can set the tone directly.  **The headless tier does not resolve tone names.** A tone named 'success' writes '--heatmap-tone: var(--heatmap-tone-success)', and the styled tier or your own stylesheet defines that property. The headless tier does not use 'var(--helix-color-*)'.  **The strip is read by key.** It takes focus once it has cells. The up and down arrows move a cell, the left and right arrows move a column, which is a week with 'rows="7"', and Home and End go to the first and the last. The tooltip follows, the 'live' part says the cell's row in words, and Escape puts the tooltip away. PageUp and PageDown move a month, to the same day, where each row's header carries its date as a '<time datetime>', and four columns otherwise, which is four weeks with 'rows="7"'.  **The strip describes itself.** The 'overview' part says the busiest reading and the total of the readings drawn, "Busiest: 11 Jun, 12; Total 84", and the strip is described by it, as every chart is by its summary. Hide it visually. The 'summary' slot is still yours, for words of your own.  **'selection-mode' lets a reader select cells**: 'single' one at a time and 'multiple' any number. Space, Enter or a press selects the cell the keys or the pointer rest on, or lets it go, and under 'multiple' Shift with an arrow, Home, End, PageUp or PageDown takes in every cell from the last one pressed to where the key went. 'value' holds the selected days, separated by commas: each by its row's '<time datetime>', such as '2026-06-11', or by its row's name where the row carries no date. A change asks with 'helix-before-change' and tells with 'change', and the 'selection' part says how many are selected, in 'selection-label'.  **Keyboard.** The strip is one tab stop once it has cells.  | Key | What it does | |---|---| | Tab | Moves focus to the strip and shows the first cell. | | Down, Up | Moves to the next or the previous cell. | | Right, Left | Moves a column on or back, a week with 'rows="7"'. On a right-to-left page, Left moves on. | | Home, End | Moves to the first or the last cell. | | Page Down, Page Up | Moves a month on or back where the rows carry dates, and four columns otherwise. | | Enter, Space | Selects the cell, or lets it go, under 'selection-mode'. | | Shift with an arrow, Home, End, Page Up or Page Down | Selects every cell from the last one pressed to where the key went, under 'selection-mode="multiple"'. | | Escape | Puts the cell's tooltip away. | */
+  /** A grid of cells, each colored by a tone. 'rows="1"' makes a status strip, and 'rows="7"' makes a contribution graph. GitHub's contribution graph uses five discrete levels, which a set of tones covers.  Color in a heatmap is per cell. In every other Helix chart, color is per series, so ninety differently colored cells would need ninety series.  **The data is a real '<table>' named by 'for'**, as in every Helix chart, and the table is the accessible representation. Hide it with 'data-hidden-visually', and screen readers still read it.  A cell takes its tone from its own 'data-tone', or from 'thresholds' and 'tones' applied to its value. 'data-tone' wins, so when you already know a day was degraded, you can set the tone directly.  **The headless tier does not resolve tone names.** A tone named 'success' writes '--heatmap-tone: var(--heatmap-tone-success)', and the styled tier or your own stylesheet defines that property. The headless tier does not use 'var(--helix-color-*)'.  **The strip is read by key.** It takes focus once it has cells. The up and down arrows move a cell, the left and right arrows move a column, which is a week with 'rows="7"', and Home and End go to the first and the last. The tooltip follows, the 'live' part says the cell's row in words, and Escape puts the tooltip away. PageUp and PageDown move a month, to the same day, where each row's header carries its date as a '<time datetime>', and four columns otherwise, which is four weeks with 'rows="7"'.  **The strip describes itself.** The 'overview' part says the busiest reading and the total of the readings drawn, "Busiest: 11 Jun, 12; Total 84", and the strip is described by it, as every chart is by its summary. Hide it visually. The 'summary' slot is still yours, for words of your own.  **'selection-mode' lets a reader select cells**: 'single' one at a time and 'multiple' any number. Space, Enter or a press selects the cell the keys or the pointer rest on, or lets it go, and under 'multiple' Shift with an arrow, Home, End, PageUp or PageDown takes in every cell from the last one pressed to where the key went. 'value' holds the selected days, separated by commas: each by its row's '<time datetime>', such as '2026-06-11', or by its row's name where the row carries no date. A change asks with 'helix-before-change' and tells with 'change', and the 'selection' part says how many are selected, in 'selection-label'.  **Under 'selection-mode' the strip is a grid**, so the selection is state a reader is told rather than words alone: each column of the strip is a 'row', a week with 'rows="7"', and each cell a 'gridcell' named by its row in the table and carrying 'aria-selected'. The strip says 'aria-multiselectable' under 'multiple' and points at the cell the keys rest on with 'aria-activedescendant', so a screen reader reads that cell, and the 'live' part stays quiet. Without 'selection-mode' nothing is selectable, and the strip is an application with the readout, as every chart's plot is.  **Readings are sent as every chart sends them.** 'helix-reading-change' says each move of the reading, by pointer, tap or key, and 'helix-reading-press' a reading clicked, tapped, or pressed with Enter or Space, each with the row of the table in 'index'.  **Nothing to draw.** A table with no readings shows 'empty-text', "No readings", under the strip, and 'loading' shows 'loading-text' there until readings arrive. The 'empty' and 'loading' slots take markup in place of either, as on every chart.  **Keyboard.** The strip is one tab stop once it has cells.  | Key | What it does | |---|---| | Tab | Moves focus to the strip and shows the first cell. | | Down, Up | Moves to the next or the previous cell. | | Right, Left | Moves a column on or back, a week with 'rows="7"'. On a right-to-left page, Left moves on. | | Home, End | Moves to the first or the last cell. | | Page Down, Page Up | Moves a month on or back where the rows carry dates, and four columns otherwise. | | Enter, Space | Presses the cell, which sends 'helix-reading-press', and selects it or lets it go under 'selection-mode'. | | Shift with an arrow, Home, End, Page Up or Page Down | Selects every cell from the last one pressed to where the key went, under 'selection-mode="multiple"'. | | Escape | Puts the cell's tooltip away. | */
   "helix-headless-heatmap": DefineCustomElement<
     HelixHeadlessHeatmap,
     HelixHeadlessHeatmapVueProps,

package/types/words.d.ts

@@ -1639,6 +1639,14 @@ declare module '@fusion.dev/helix-core' {
        * English: `Groups`
        */
       legendLabel: Message
+      /**
+       * What screen readers hear when a walk along the links reaches a note that
+       * has no link to follow, or goes back to a note: `{note}` for its name and
+       * `{count}` for how many notes the list holds that it links to or from.
+       *
+       * English: `{note}. {count, plural, =0 {No links} one {# link} other {# links}}`
+       */
+      linkCountLabel: Message
       /**
        * How a note linked both to and from the selected one is described, with `{note}`.
        *
@@ -1757,6 +1765,15 @@ declare module '@fusion.dev/helix-core' {
        * English: `Using the graph. Press Escape to scroll the page again.`
        */
       usingLabel: Message
+      /**
+       * What screen readers hear when a walk along the links moves to a note:
+       * `{note}` for its name, `{relation}` for how it stands to the note the
+       * step came from, such as "Linked from Roadmap", and `{index}` and `{count}`
+       * for its place among that note's links.
+       *
+       * English: `{note}. {relation}. {index} of {count}`
+       */
+      walkLabel: Message
       /**
        * The hint shown when the wheel scrolls past the graph with
        * `gestures="cooperative"`. `{key}` is ⌘ on a Mac and Ctrl elsewhere.
@@ -1798,11 +1815,19 @@ declare module '@fusion.dev/helix-core' {
        */
       busiestLabel: Message
       /**
-       * Shown when the table has no readings in it.
+       * The words shown in place of the drawing when the table has no readings,
+       * and the fallback of the `empty` slot.
        *
        * English: `No readings`
        */
       emptyText: Message
+      /**
+       * The words shown in place of the drawing while `loading` is set and
+       * there are no readings yet, and the fallback of the `loading` slot.
+       *
+       * English: `Loading readings`
+       */
+      loadingText: Message
       /**
        * The `overview`'s sentence. `{busiestLabel}` and `{totalLabel}` are
        * `busiest-label` and `total-label`, `{busiest}` the busiest reading's name
@@ -1821,9 +1846,7 @@ declare module '@fusion.dev/helix-core' {
        */
       positionLabel: Message
       /**
-       * What the readout adds for a selected cell, under `selection-mode`, after
-       * where the cell stands: "Day 1: 0 (1 of 14, selected)". Empty adds
-       * nothing.
+       * What the readout added for a selected cell, under `selection-mode`.
        *
        * English: `selected`
        */
@@ -2441,9 +2464,10 @@ declare module '@fusion.dev/helix-core' {
     }
     'helix-notification': {
       /**
-       * The dismiss control's label, read by screen readers.
+       * The dismiss control's name, read by screen readers, with `{label}` for the
+       * row's own words.
        *
-       * English: `Dismiss`
+       * English: `Dismiss {label}`
        */
       dismissLabel: Message
       /**