@fusion.dev/helix 0.177.2 → 0.179.0

package/types/vue.d.ts

@@ -930,6 +930,14 @@ hit-testable at rest, or it would swallow clicks meant for what is over it,
 and an element that is not hit-testable never receives the `pointermove`
 this listens for. Asking for the pointer is asking for the hit test. */
   interactive?: (HelixAura["interactive"]) | undefined;
+  /** Whether the aura draws its own control that pauses the field and starts it
+again, in its trailing corner. Absent draws none, for a page with a pause
+control of its own. */
+  "pause-control"?: (HelixAura["pauseControl"]) | undefined;
+  /** Whether the aura draws its own control that pauses the field and starts it
+again, in its trailing corner. Absent draws none, for a page with a pause
+control of its own. */
+  pauseControl?: (HelixAura["pauseControl"]) | undefined;
   /** Whether the field holds still on the frame it shows.
 
 Set it from a pause control on your page, so a reader can stop the motion,
@@ -937,6 +945,14 @@ as WCAG 2.2.2 asks of anything that moves for more than five seconds. A
 change to another property still repaints the frame. Clearing it starts
 the field from where it stopped. */
   paused?: (HelixAura["paused"]) | undefined;
+  /** The pause control's name, read by screen readers. The control is a toggle
+and says it is pressed while the field is paused, so the name stays the
+same. */
+  "pause-label"?: (HelixAura["pauseLabel"]) | undefined;
+  /** The pause control's name, read by screen readers. The control is a toggle
+and says it is pressed while the field is paused, so the name stays the
+same. */
+  pauseLabel?: (HelixAura["pauseLabel"]) | undefined;
   /** How far the pointer reaches into the field, `0` upward.
 
 Multiplied into the presence the pointer already fades in and out with, so
@@ -1009,6 +1025,8 @@ states. */
 };
 
 export type HelixAuraVueEvents = {
+  /** Fired when the aura's own pause control pauses the field or starts it again. */
+  change: HelixAuraElementEvent;
   /** Fired each time the aura stops drawing its shader and shows its gradient, with the reason. */
   "helix-aura-fallback": HelixAuraHelixAuraFallbackElementEvent;
 };
@@ -8361,6 +8379,14 @@ an icon. */
   /** The name of the clear button, read by screen readers. The button shows only
 an icon. */
   clearLabel?: (HelixFilterInput["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"?: (HelixFilterInput["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?: (HelixFilterInput["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. */
@@ -8438,6 +8464,13 @@ imperatively later, and nothing is hydrating by then.
 
 Here rather than on each control. */
   name?: (HelixFilterInput["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?: (HelixFilterInput["source"]) | undefined;
 };
 
 export type HelixFilterInputVueEvents = {
@@ -8455,7 +8488,7 @@ export type HelixFilterInputVueEvents = {
   "helix-dismiss": HelixFilterInputHelixDismissElementEvent;
   /** 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": HelixFilterInputHelixFacetElementEvent;
-  /** 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": HelixFilterInputHelixSelectElementEvent;
   /** Fired when the text changes. */
   input: HelixFilterInputElementEvent;
@@ -8929,6 +8962,14 @@ or hides its notes. Drawn where the notes have two groups or more. */
   "legend-label"?: (HelixGraph["legendLabel"]) | undefined;
   /** The legend's name, read by screen readers. */
   legendLabel?: (HelixGraph["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"?: (HelixGraph["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?: (HelixGraph["linkCountLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
   "linked-both-label"?: (HelixGraph["linkedBothLabel"]) | undefined;
   /** How a note linked both to and from the selected one is described, with `{note}`. */
@@ -9008,6 +9049,16 @@ the list then holds, written with `count-label`. */
   "using-label"?: (HelixGraph["usingLabel"]) | undefined;
   /** The line shown while the graph, with `gestures="activate"`, has the gestures. */
   usingLabel?: (HelixGraph["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"?: (HelixGraph["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?: (HelixGraph["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"?: (HelixGraph["wheelHintLabel"]) | undefined;
@@ -9051,7 +9102,7 @@ export type HelixGraphVueEvents = {
   "helix-graph-layout": HelixGraphHelixGraphLayoutElementEvent;
   /** A pan button or arrow key was pressed. `connectGraph` moves the drawing, then calls `moved()`. */
   "helix-graph-pan": HelixGraphHelixGraphPanElementEvent;
-  /** 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": HelixGraphHelixGraphPartChangeElementEvent;
   /** 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": HelixGraphHelixGraphReadyElementEvent;
@@ -9153,11 +9204,36 @@ export type HelixHeatmapElementEvent<E = Event> = TypedEvent<HelixHeatmap, E>;
 /** `helix-before-change` event type */
 export type HelixHeatmapHelixBeforeChangeElementEvent =
   HelixHeatmapElementEvent<HelixBeforeChangeEvent>;
+/** `helix-reading-change` event type */
+export type HelixHeatmapHelixReadingChangeElementEvent =
+  HelixHeatmapElementEvent<HelixReadingChangeEvent>;
+/** `helix-reading-press` event type */
+export type HelixHeatmapHelixReadingPressElementEvent =
+  HelixHeatmapElementEvent<HelixReadingPressEvent>;
 /** `helix-resize` event type */
 export type HelixHeatmapHelixResizeElementEvent =
   HelixHeatmapElementEvent<HelixResizeEvent>;
 
 export type HelixHeatmapVueProps = {
+  /** The words shown in place of the drawing when the table has no readings,
+and the fallback of the `empty` slot. */
+  "empty-text"?: (HelixHeatmap["emptyText"]) | undefined;
+  /** The words shown in place of the drawing when the table has no readings,
+and the fallback of the `empty` slot. */
+  emptyText?: (HelixHeatmap["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?: (HelixHeatmap["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"?: (HelixHeatmap["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?: (HelixHeatmap["loadingText"]) | undefined;
   /** The id of the table to read.
 
 Names a table in the same tree, so a chart inside another component's
@@ -9200,16 +9276,6 @@ legend hid is not counted. */
   /** The name the `overview` gives the busiest reading, `{busiestLabel}` in
 `overview-label`. */
   busiestLabel?: (HelixHeatmap["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"?: (HelixHeatmap["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?: (HelixHeatmap["emptyText"]) | undefined;
   /** Space between cells, in CSS pixels. It is a number for the same reason
 `min-cell` is. */
   gap?: (HelixHeatmap["gap"]) | undefined;
@@ -9267,13 +9333,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?: (HelixHeatmap["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"?: (HelixHeatmap["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?: (HelixHeatmap["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
@@ -9360,6 +9422,10 @@ export type HelixHeatmapVueEvents = {
   change: HelixHeatmapElementEvent;
   /** Fired before a press or a key changes which cells are selected, with the `value` it would leave. Cancelable. */
   "helix-before-change": HelixHeatmapHelixBeforeChangeElementEvent;
+  /** 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": HelixHeatmapHelixReadingChangeElementEvent;
+  /** A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`. */
+  "helix-reading-press": HelixHeatmapHelixReadingPressElementEvent;
   /** Fired when the number of cells drawn changes, with the new number. */
   "helix-resize": HelixHeatmapHelixResizeElementEvent;
 };
@@ -21668,6 +21734,8 @@ export type CustomCssProperties = {
   "--aura-ground"?: (string) | undefined;
   /** The faint stop between the ground and the glow. Defaults to `--helix-color-primary-subtle`. */
   "--aura-haze"?: (string) | undefined;
+  /** The pause control's ground. Defaults to `--helix-color-surface-overlay`. */
+  "--aura-pause-background-color"?: (string) | undefined;
   /** The hottest stop, at the center of a shape. Defaults to `--helix-color-primary-active` on a light page and `--helix-color-foreground` on a dark one. */
   "--aura-peak"?: (string) | undefined;
   /** The fill of the count of avatars past `max`. */
@@ -24148,7 +24216,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixAreaChartVueProps,
     HelixAreaChartVueEvents
   >;
-  /** One fragment shader draws over a full-screen triangle, and its palette comes from the tokens. A background built on '--helix-color-primary' changes when your brand color changes.  Every shape ramps through four token stops, and the token layer inverts each one: the page background, 'primary-subtle', 'primary', and a peak. The peak is the foreground on a dark page and 'primary-active' on a light one, because mixing a saturated hue toward near-black removes its chroma. The component reads which way the page runs from the background's luminance, because the mode is a private token.  The geometry is three vertices derived from 'gl_VertexID'. There is no dependency, scene graph, attribute, buffer, or upload.  The shader stops drawing in these cases: - The element is off screen or in a background tab. - 'prefers-reduced-motion' is set. The element shows one still frame. - 'paused' is set, from a pause control on your page. The element holds the   frame it shows. - The browser takes back the drawing context, on a GPU reset or past its   limit of about sixteen contexts. The gradient shows until the context   returns.  On a renderer that draws on the CPU, such as a headless browser or a machine with no usable GPU, the element shows the gradient. There the shader costs about 450ms for the first frame of each element, against 2ms on a GPU.  Aura is styled only and has behavior, which the tier split does not otherwise allow. Its behavior is drawing to a canvas, so there is no structure for you to restyle and nothing for a headless version to hold.  **Content placed inside sits over the field**, in a 'content' part that covers the aura, so an interactive aura answers the pointer over the content too. Clicks still reach the content. Style '::part(content)' to place it, such as centering a hero's heading.  **The colors are the theme's, and each has a hook**: '--aura-ground', '--aura-haze', '--aura-glow' and '--aura-peak', read by the shader and by the fallback gradient alike, from wherever on the page you set them. A hook changed while the aura draws, by a class, a style or the color mode, reaches the shader on the next frame.  Where the gradient shows in place of the shader, the aura matches ':state(fallback)' and sends 'helix-aura-fallback' with the reason. */
+  /** One fragment shader draws over a full-screen triangle, and its palette comes from the tokens. A background built on '--helix-color-primary' changes when your brand color changes.  Every shape ramps through four token stops, and the token layer inverts each one: the page background, 'primary-subtle', 'primary', and a peak. The peak is the foreground on a dark page and 'primary-active' on a light one, because mixing a saturated hue toward near-black removes its chroma. The component reads which way the page runs from the background's luminance, because the mode is a private token.  The geometry is three vertices derived from 'gl_VertexID'. There is no dependency, scene graph, attribute, buffer, or upload.  The shader stops drawing in these cases: - The element is off screen or in a background tab. - 'prefers-reduced-motion' is set. The element shows one still frame. - 'paused' is set, from a pause control on your page or from the aura's own   under 'pause-control'. The element holds the frame it shows. - The browser takes back the drawing context, on a GPU reset or past its   limit of about sixteen contexts. The gradient shows until the context   returns.  On a renderer that draws on the CPU, such as a headless browser or a machine with no usable GPU, the element shows the gradient. There the shader costs about 450ms for the first frame of each element, against 2ms on a GPU.  Aura is styled only and has behavior, which the tier split does not otherwise allow. Its behavior is drawing to a canvas, so there is no structure for you to restyle and nothing for a headless version to hold.  **Content placed inside sits over the field**, in a 'content' part that covers the aura, so an interactive aura answers the pointer over the content too. Clicks still reach the content. Style '::part(content)' to place it, such as centering a hero's heading.  **The colors are the theme's, and each has a hook**: '--aura-ground', '--aura-haze', '--aura-glow' and '--aura-peak', read by the shader and by the fallback gradient alike, from wherever on the page you set them. A hook changed while the aura draws, by a class, a style or the color mode, reaches the shader on the next frame.  **'pause-control' draws a control that stops the motion and starts it again**, in the trailing corner of the field, as WCAG 2.2.2 asks of anything that moves for more than five seconds. It is a toggle button named by 'pause-label', which says it is pressed while the field is paused, and a press sends 'change'. A reader who asked for reduced motion sees no motion and no control.  Where the gradient shows in place of the shader, the aura matches ':state(fallback)' and sends 'helix-aura-fallback' with the reason. */
   "helix-aura": DefineCustomElement<
     HelixAura,
     HelixAuraVueProps,

package/types/words.d.ts

@@ -320,6 +320,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}`.
        *
@@ -932,6 +940,15 @@ declare module '@fusion.dev/helix-core' {
        * English: `Choose one to continue.`
        */
       valueMissingMessage: 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 a surface with
        * `gestures="cooperative"`, with `{key}`. Each family declares it as a
@@ -987,6 +1004,16 @@ declare module '@fusion.dev/helix-core' {
        */
       menuLabel: Message
     }
+    'helix-aura': {
+      /**
+       * The pause control's name, read by screen readers. The control is a toggle
+       * and says it is pressed while the field is paused, so the name stays the
+       * same.
+       *
+       * English: `Pause the motion`
+       */
+      pauseLabel: Message
+    }
     'helix-avatar-group': {
       /**
        * What a screen reader is told the count is, with `{count}` for the number,