@fusion.dev/helix 0.185.0 → 0.186.1

package/types/svelte.d.ts

@@ -89,6 +89,7 @@ declare module 'svelte/elements' {
     'helix-icon': Helix<'helix-icon'>
     'helix-image': Helix<'helix-image'>
     'helix-input': Helix<'helix-input'>
+    'helix-isometric-heatmap': Helix<'helix-isometric-heatmap'>
     'helix-kbd': Helix<'helix-kbd'>
     'helix-legend': Helix<'helix-legend'>
     'helix-lightbox-item': Helix<'helix-lightbox-item'>

package/types/vue.d.ts

@@ -59,6 +59,7 @@ import type {
   HelixIcon,
   HelixImage,
   HelixInput,
+  HelixIsometricHeatmap,
   HelixKbd,
   HelixLegend,
   HelixLightboxItem,
@@ -9743,10 +9744,12 @@ disagreeing with its own name for every reader who meant the left. */
   /** The name of the icon in the Helix set.
 
 **A lookup, and the reason both this and `icon` exist.** A name is a string,
-so it is what markup can carry, and resolving one means an index that no
-bundler can shake. The family's entry indexes a small set, `icon/all`
-indexes the whole set at 15 kB, and `icon/root` indexes nothing, for a
-page that registers the glyphs it names or hands over the value instead.
+so it is what markup can carry, and resolving one means an index of the
+whole set that no bundler can shake: 15 kB for a consumer who renders one
+mark. An attribute is the only thing an HTML author can write, and that is
+worth the index; a consumer who would rather not pay it imports the
+element from `icon/root` and registers the glyphs it names, or hands over
+the value instead.
 
 A name written `prefix:name` asks the library registered under that
 prefix. */
@@ -10145,6 +10148,253 @@ export type HelixInputVueEvents = {
   input: HelixInputElementEvent;
 };
 
+/** `HelixIsometricHeatmap` component event */
+export type HelixIsometricHeatmapElementEvent<E = Event> = TypedEvent<
+  HelixIsometricHeatmap,
+  E
+>;
+/** `helix-before-change` event type */
+export type HelixIsometricHeatmapHelixBeforeChangeElementEvent =
+  HelixIsometricHeatmapElementEvent<HelixBeforeChangeEvent>;
+/** `helix-reading-change` event type */
+export type HelixIsometricHeatmapHelixReadingChangeElementEvent =
+  HelixIsometricHeatmapElementEvent<HelixReadingChangeEvent>;
+/** `helix-reading-press` event type */
+export type HelixIsometricHeatmapHelixReadingPressElementEvent =
+  HelixIsometricHeatmapElementEvent<HelixReadingPressEvent>;
+/** `helix-resize` event type */
+export type HelixIsometricHeatmapHelixResizeElementEvent =
+  HelixIsometricHeatmapElementEvent<HelixResizeEvent>;
+
+export type HelixIsometricHeatmapVueProps = {
+  /** Draws every prism at no height, so the tones lie on a plane. */
+  flat?: (HelixIsometricHeatmap["flat"]) | undefined;
+  /** How tall the highest reading stands, in cells. Every other reading stands
+at its share of it. */
+  relief?: (HelixIsometricHeatmap["relief"]) | undefined;
+  /** The words shown in place of the drawing when the table has no readings,
+and the fallback of the `empty` slot. */
+  "empty-text"?: (HelixIsometricHeatmap["emptyText"]) | undefined;
+  /** The words shown in place of the drawing when the table has no readings,
+and the fallback of the `empty` slot. */
+  emptyText?: (HelixIsometricHeatmap["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?: (HelixIsometricHeatmap["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"?: (HelixIsometricHeatmap["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?: (HelixIsometricHeatmap["loadingText"]) | undefined;
+  /** The id of the table to read.
+
+Names a table in the same tree, so a chart inside another component's
+shadow root reads a table in that root rather than one in the document. A
+`<table>` or anything built from grid roles, including `helix-table`.
+
+**In React this arrives as a property and not as an attribute**, the way
+`Tooltip.for` does, so it does not reflect and nothing styles on it. */
+  for?: (HelixIsometricHeatmap["for"]) | undefined;
+  /** The chart's name, which starts the chart's text summary.
+
+Absent falls back to the table's own caption, which is usually the right
+words and is already written. */
+  label?: (HelixIsometricHeatmap["label"]) | undefined;
+  /** The locale the chart's own numbers are written in: its axis, its
+percentages and its totals, such as `de` for `1.240` and `32 %`.
+
+Absent reads the nearest `lang`, then the runtime's own. The table's
+cells are shown as the table writes them, whatever this says. */
+  locale?: (HelixIsometricHeatmap["locale"]) | undefined;
+  /** Where a reading the keys moved to stands among the readings, said after
+it. `{position}` and `{count}` are replaced with the numbers, written in
+`locale`.
+
+Set it to the words of the page's language, such as `{position} von
+{count}`, or to nothing to say no position. A slice or a series a
+legend hid is not counted. */
+  "position-label"?: (HelixIsometricHeatmap["positionLabel"]) | undefined;
+  /** Where a reading the keys moved to stands among the readings, said after
+it. `{position}` and `{count}` are replaced with the numbers, written in
+`locale`.
+
+Set it to the words of the page's language, such as `{position} von
+{count}`, or to nothing to say no position. A slice or a series a
+legend hid is not counted. */
+  positionLabel?: (HelixIsometricHeatmap["positionLabel"]) | undefined;
+  /** The name the `overview` gives the busiest reading, `{busiestLabel}` in
+`overview-label`. */
+  "busiest-label"?: (HelixIsometricHeatmap["busiestLabel"]) | undefined;
+  /** The name the `overview` gives the busiest reading, `{busiestLabel}` in
+`overview-label`. */
+  busiestLabel?: (HelixIsometricHeatmap["busiestLabel"]) | undefined;
+  /** Space between cells, in CSS pixels. It is a number for the same reason
+`min-cell` is. */
+  gap?: (HelixIsometricHeatmap["gap"]) | undefined;
+  /** The smallest a cell may get before the strip draws fewer of them, in CSS pixels.
+
+**Set this only to overrule what the strip actually draws.** The arithmetic
+needs a width in pixels and the width is a length the stylesheet resolves,
+so a number written here that disagrees with the sheet is a promise the
+consumer has to keep by hand, and the one number a summary is told to trust
+is the one it gets wrong.
+
+The strip measures itself, so sizing the cells in a sheet is enough on its
+own and these two are the estimate used until the first measurement lands.
+Writing the attribute pins the value and stops the measurement being
+consulted, which is what a container query or a transition on the cell size
+wants, where what is drawn this frame is not what the arithmetic should
+plan around.
+
+Zero turns the dropping off altogether, which is right for a strip in a
+container that cannot get narrow. */
+  "min-cell"?: (HelixIsometricHeatmap["minCell"] | `${number}`) | undefined;
+  /** The smallest a cell may get before the strip draws fewer of them, in CSS pixels.
+
+**Set this only to overrule what the strip actually draws.** The arithmetic
+needs a width in pixels and the width is a length the stylesheet resolves,
+so a number written here that disagrees with the sheet is a promise the
+consumer has to keep by hand, and the one number a summary is told to trust
+is the one it gets wrong.
+
+The strip measures itself, so sizing the cells in a sheet is enough on its
+own and these two are the estimate used until the first measurement lands.
+Writing the attribute pins the value and stops the measurement being
+consulted, which is what a container query or a transition on the cell size
+wants, where what is drawn this frame is not what the arithmetic should
+plan around.
+
+Zero turns the dropping off altogether, which is right for a strip in a
+container that cannot get narrow. */
+  minCell?: (HelixIsometricHeatmap["minCell"]) | undefined;
+  /** The `overview`'s sentence. `{busiestLabel}` and `{totalLabel}` are
+`busiest-label` and `total-label`, `{busiest}` the busiest reading's name
+and its reading as the table writes it, and `{total}` the total of the
+readings drawn, written in the locale. */
+  "overview-label"?: (HelixIsometricHeatmap["overviewLabel"]) | undefined;
+  /** The `overview`'s sentence. `{busiestLabel}` and `{totalLabel}` are
+`busiest-label` and `total-label`, `{busiest}` the busiest reading's name
+and its reading as the table writes it, and `{total}` the total of the
+readings drawn, written in the locale. */
+  overviewLabel?: (HelixIsometricHeatmap["overviewLabel"]) | undefined;
+  /** How many rows the strip has.
+
+`1` is a status strip and `7` is a calendar week, which are the two readings
+this covers. Cells fill down the column and then across, which is what a
+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?: (HelixIsometricHeatmap["rows"]) | undefined;
+  /** What the readout added for a selected cell, under `selection-mode`. */
+  "selected-label"?: (HelixIsometricHeatmap["selectedLabel"]) | undefined;
+  /** What the readout added for a selected cell, under `selection-mode`. */
+  selectedLabel?: (HelixIsometricHeatmap["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
+needs plural forms writes them: `{count, plural, one {# wybrany} few
+{# wybrane} many {# wybranych} other {# wybranego}}`. */
+  "selection-label"?: (HelixIsometricHeatmap["selectionLabel"]) | 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
+needs plural forms writes them: `{count, plural, one {# wybrany} few
+{# wybrane} many {# wybranych} other {# wybranego}}`. */
+  selectionLabel?: (HelixIsometricHeatmap["selectionLabel"]) | undefined;
+  /** How many cells a reader can select: `single` or `multiple`.
+
+Absent selects nothing, and a press or Space does what it did. */
+  "selection-mode"?: (HelixIsometricHeatmap["selectionMode"]) | undefined;
+  /** How many cells a reader can select: `single` or `multiple`.
+
+Absent selects nothing, and a press or Space does what it did. */
+  selectionMode?: (HelixIsometricHeatmap["selectionMode"]) | undefined;
+  /** What Shift takes in under `selection-mode="multiple"`: `linear`, every
+cell between two in the table's order, or `rectangle`, the cells between
+two corners by row and by column, as a spreadsheet selects a range. */
+  "selection-shape"?: (HelixIsometricHeatmap["selectionShape"]) | undefined;
+  /** What Shift takes in under `selection-mode="multiple"`: `linear`, every
+cell between two in the table's order, or `rectangle`, the cells between
+two corners by row and by column, as a spreadsheet selects a range. */
+  selectionShape?: (HelixIsometricHeatmap["selectionShape"]) | undefined;
+  /** The strip's name where the chart has none: no `aria-label`, `label`, or
+table caption. */
+  "strip-label"?: (HelixIsometricHeatmap["stripLabel"]) | undefined;
+  /** The strip's name where the chart has none: no `aria-label`, `label`, or
+table caption. */
+  stripLabel?: (HelixIsometricHeatmap["stripLabel"]) | undefined;
+  /** Lower bounds for the tone buckets, in the order the tones are given.
+
+`thresholds="1 3 6 9"` with `tones="1 2 3 4"` puts 1 and 2 in the ramp's
+first step, 3 to 5 in the second, 6 to 8 in the third, and 9 upward in the
+fourth. A value below the first bound gets no tone at all: an empty day in a
+contribution graph is a day with nothing in it, and painting it as the
+lowest bucket claims a reading that does not exist. */
+  thresholds?: (HelixIsometricHeatmap["thresholds"]) | undefined;
+  /** The tone for each bucket, in the same order as `thresholds`.
+
+A name, resolved as `--heatmap-tone-<name>` by whichever tier answers.
+**`"1"` through `"5"` are a ramp and everything else is a category**, which
+is the distinction a heatmap lives or dies on: magnitude has to be one hue
+getting louder, because a reader compares two cells by weight and cannot
+compare two hues at all. `tones="surface info accent success primary"` for a
+commit count is five unrelated hues for five amounts, which is confetti with
+no order in it. */
+  tones?: (HelixIsometricHeatmap["tones"]) | undefined;
+  /** The name the `overview` gives the total of the readings drawn,
+`{totalLabel}` in `overview-label`. */
+  "total-label"?: (HelixIsometricHeatmap["totalLabel"]) | undefined;
+  /** The name the `overview` gives the total of the readings drawn,
+`{totalLabel}` in `overview-label`. */
+  totalLabel?: (HelixIsometricHeatmap["totalLabel"]) | undefined;
+  /** The selected cells, separated by commas: each by the date its row's
+header carries in a `<time datetime>`, such as `2026-06-11`, or by the
+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?: (HelixIsometricHeatmap["value"]) | undefined;
+  /** The readings as data, in the shape of a table, where the page has no
+table to point `for` at. `for` wins where both are set.
+
+```js
+chart.data = {
+  caption: 'Sessions by channel',
+  columns: ['Month', 'Direct', 'Referral'],
+  rows: [['Jan', 10, 4], ['Feb', 20, 8]],
+}
+```
+
+The first column holds each row's label and every column after it a
+series, as in a table. A cell is a number, words, `null` for a blank,
+or `{ value, text }` for a number shown as words, such as `$128k`. A
+number is shown in `locale`.
+
+**A table is still the better source where the page can show one**:
+it reads with no script and before hydration, and a reader can sort and
+copy it. Data is drawn on the client only, so a server serves the
+frame, and the summary, the keys and the readout are then the whole of
+what a screen reader is given. Set a new object to redraw: the chart
+does not look inside the one it has. */
+  data?: (HelixIsometricHeatmap["data"]) | undefined;
+};
+
+export type HelixIsometricHeatmapVueEvents = {
+  /** Fired once a press or a key has changed which cells are selected. */
+  change: HelixIsometricHeatmapElementEvent;
+  /** Fired before a press or a key changes which cells are selected, with the `value` it would leave. Cancelable. */
+  "helix-before-change": HelixIsometricHeatmapHelixBeforeChangeElementEvent;
+  /** 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": HelixIsometricHeatmapHelixReadingChangeElementEvent;
+  /** A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`. */
+  "helix-reading-press": HelixIsometricHeatmapHelixReadingPressElementEvent;
+  /** Fired when the number of cells drawn changes, with the new number. */
+  "helix-resize": HelixIsometricHeatmapHelixResizeElementEvent;
+};
+
 /** `HelixKbd` component event */
 export type HelixKbdElementEvent<E = Event> = TypedEvent<HelixKbd, E>;
 /** `helix-shortcut` event type */
@@ -22761,6 +23011,16 @@ export type CustomCssProperties = {
   "--input-radius"?: (string) | undefined;
   /** Height of the field. */
   "--input-size"?: (string) | undefined;
+  /** The largest a cell grows, along its edge. The strip is never wider than its box, and draws smaller cells to fit. */
+  "--isometric-heatmap-cell-size"?: (string) | undefined;
+  /** How much darker the left face is than the top, as a percentage mixed toward black. */
+  "--isometric-heatmap-left-shade"?: (string) | undefined;
+  /** How much darker the right face is than the top, as a percentage mixed toward black. */
+  "--isometric-heatmap-right-shade"?: (string) | undefined;
+  /** The color of the dashed edges of a selected prism, under `selection-mode`. By default, white on a dark face and black on a light one. */
+  "--isometric-heatmap-selected-color"?: (string) | undefined;
+  /** How many cells the drawing spans across: its columns and its rows together. The component writes it on the strip, and a stylesheet that caps the cell size reads it. */
+  "--isometric-heatmap-span"?: (string) | undefined;
   /** The fill of the key. */
   "--kbd-background-color"?: (string) | undefined;
   /** The height of a key, and the least width of one, in `em` of the text around it. */
@@ -24607,7 +24867,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixIconButtonVueProps,
     HelixIconButtonVueEvents
   >;
-  /** Draws in 'currentColor' and sizes from '--icon-size', so an icon takes the color of the text around it and a container can resize it without a property. Inside a button, '--icon-size' is set in 'em', so the icon scales with the button.  **The glyph turns, flips and moves inside its own box**, so the line around it keeps its place: 'rotate' turns it by a quarter, a half or three quarters, '--icon-rotate' by any angle, 'flip' mirrors it across either axis, and 'animation' spins, pulses or beats it, as Web Awesome's icon does. Reduced motion stills every animation. 'auto-width' gives the box the glyph's own proportions, for a mark wider than it is tall.  **'@fusion.dev/helix/icon' registers thirteen glyphs by name**, the ones a control most often needs, and '@fusion.dev/helix/icon/all' registers the whole set. The headless element lists the thirteen and says how a name is resolved. */
+  /** Draws in 'currentColor' and sizes from '--icon-size', so an icon takes the color of the text around it and a container can resize it without a property. Inside a button, '--icon-size' is set in 'em', so the icon scales with the button.  **The glyph turns, flips and moves inside its own box**, so the line around it keeps its place: 'rotate' turns it by a quarter, a half or three quarters, '--icon-rotate' by any angle, 'flip' mirrors it across either axis, and 'animation' spins, pulses or beats it, as Web Awesome's icon does. Reduced motion stills every animation. 'auto-width' gives the box the glyph's own proportions, for a mark wider than it is tall. */
   "helix-icon": DefineCustomElement<
     HelixIcon,
     HelixIconVueProps,
@@ -24625,6 +24885,12 @@ export interface WcToolkitVueGlobalComponents {
     HelixInputVueProps,
     HelixInputVueEvents
   >;
+  /** Each reading is a prism. The top face takes the cell's tone, and the two sides are the same tone, shaded darker, so the whole relief follows your theme's colors.  'tones="1 2 3 4 5"' uses the same five-step ramp as 'Heatmap', so the tone and the height both show the value. Set '--isometric-heatmap-cell-size' to change how large a cell may grow. */
+  "helix-isometric-heatmap": DefineCustomElement<
+    HelixIsometricHeatmap,
+    HelixIsometricHeatmapVueProps,
+    HelixIsometricHeatmapVueEvents
+  >;
   /** Drawn as a physical key, with a hairline border, a sunken fill, and one inset shadow along the bottom edge.  Sized in 'em', so it stays in proportion with the text around it, including in a heading. */
   "helix-kbd": DefineCustomElement<
     HelixKbd,