@fusion.dev/helix-headless 0.178.0 → 0.179.0

package/types/vue.d.ts

@@ -8007,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>;
@@ -8018,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;
@@ -8085,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
@@ -8148,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
@@ -8214,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;
 };
@@ -11421,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. */
@@ -11451,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 = {
@@ -19555,7 +19562,7 @@ export interface WcToolkitVueGlobalComponents {
     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

@@ -1815,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
@@ -1838,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`
        */
@@ -2458,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
       /**