@fusion.dev/helix-headless 0.188.0 → 0.190.0

package/dist/element-events.generated.js

@@ -148,13 +148,6 @@ registerElementEvents({
     'helix-headless-icon-button': ['helix-press'],
     'helix-headless-image': ['error', 'load'],
     'helix-headless-input': ['change', 'helix-before-change', 'helix-clear', 'input'],
-    'helix-headless-isometric-heatmap': [
-        'change',
-        'helix-before-change',
-        'helix-reading-change',
-        'helix-reading-press',
-        'helix-resize',
-    ],
     'helix-headless-kbd': ['helix-shortcut'],
     'helix-headless-legend': ['change', 'helix-before-change'],
     'helix-headless-lightbox': [
@@ -264,6 +257,27 @@ registerElementEvents({
     ],
     'helix-headless-slider': ['change', 'helix-before-change', 'input'],
     'helix-headless-sparkline': ['helix-reading-change', 'helix-reading-press'],
+    'helix-headless-spatial-heatmap': [
+        'change',
+        'helix-before-change',
+        'helix-plot-change',
+        'helix-plot-turn',
+        'helix-reading-change',
+        'helix-reading-press',
+        'helix-resize',
+    ],
+    'helix-headless-spatial-scatter-chart': [
+        'helix-plot-change',
+        'helix-plot-turn',
+        'helix-reading-change',
+        'helix-reading-press',
+    ],
+    'helix-headless-spatial-surface-chart': [
+        'helix-plot-change',
+        'helix-plot-turn',
+        'helix-reading-change',
+        'helix-reading-press',
+    ],
     'helix-headless-speed-dial': [
         'helix-before-close',
         'helix-before-open',

package/dist/index.d.ts

@@ -54,7 +54,6 @@ export * from './icon/index.js';
 export * from './icon-button/index.js';
 export * from './image/index.js';
 export * from './input/index.js';
-export * from './isometric-heatmap/index.js';
 export * from './kbd/index.js';
 export * from './legend/index.js';
 export * from './lightbox/index.js';
@@ -88,6 +87,9 @@ export * from './skeleton/index.js';
 export * from './skip-link/index.js';
 export * from './slider/index.js';
 export * from './sparkline/index.js';
+export * from './spatial-heatmap/index.js';
+export * from './spatial-scatter-chart/index.js';
+export * from './spatial-surface-chart/index.js';
 export * from './speed-dial/index.js';
 export * from './splitter/index.js';
 export * from './stat/index.js';

package/dist/index.js

@@ -45,7 +45,6 @@ export * from './icon/index.js';
 export * from './icon-button/index.js';
 export * from './image/index.js';
 export * from './input/index.js';
-export * from './isometric-heatmap/index.js';
 export * from './kbd/index.js';
 export * from './legend/index.js';
 export * from './lightbox/index.js';
@@ -79,6 +78,9 @@ export * from './skeleton/index.js';
 export * from './skip-link/index.js';
 export * from './slider/index.js';
 export * from './sparkline/index.js';
+export * from './spatial-heatmap/index.js';
+export * from './spatial-scatter-chart/index.js';
+export * from './spatial-surface-chart/index.js';
 export * from './speed-dial/index.js';
 export * from './splitter/index.js';
 export * from './stat/index.js';

package/dist/spatial-heatmap/index.d.ts

@@ -0,0 +1 @@
+export { HelixHeadlessSpatialHeatmap } from './root/spatial-heatmap-root.js';

package/dist/spatial-heatmap/index.js

@@ -0,0 +1 @@
+export { HelixHeadlessSpatialHeatmap } from './root/spatial-heatmap-root.js';

package/dist/{isometric-heatmap → spatial-heatmap}/projection.d.ts

@@ -1,5 +1,5 @@
 /**
- * Where each reading of an isometric heatmap stands, as SVG path data.
+ * Where each reading of a spatial heatmap stands, in the isometric projection, as SVG path data.
  *
  * Kept apart from the element because it is arithmetic a picture hides: a face
  * drawn in the wrong order is covered by the prism it should cover, and a
@@ -8,14 +8,16 @@
  * **The units are cells.** A step along a column or a row is one cell, and a
  * prism's height is in the same unit, so the drawing scales as a whole through
  * the `viewBox` and a server can write it with no width to measure.
+ *
+ * **The projection is the one every spatial drawing shares**, `helix-core`'s,
+ * seen from the isometric camera. What is here is the heatmap's own: which way
+ * its columns and rows run, its prisms, and the slab under them.
  */
+import { type PagePoint } from '@fusion.dev/helix-core';
 /** How far across the page one step along either axis goes: the cosine of 30 degrees. */
 export declare const ACROSS: number;
 /** A point on the page, in cells. */
-export interface Point {
-    x: number;
-    y: number;
-}
+export type Point = PagePoint;
 /** One reading drawn as a prism: three visible faces, as path data. */
 export interface Prism {
     /** The reading's place among those drawn. */
@@ -29,8 +31,19 @@ export interface Prism {
     /** The face the reading's tone is painted on. */
     top: string;
 }
-/** Every prism, and the box they fit in. */
+/**
+ * The slab the prisms stand on: its top, which is the floor, and its two
+ * sides seen from the front, as path data.
+ */
+export interface Base {
+    left: string;
+    right: string;
+    top: string;
+}
+/** Every prism, the slab under them, and the box they fit in. */
 export interface Relief {
+    /** The slab under the grid, or none where there is nothing to stand on it. */
+    base: Base | undefined;
     /** The box every face fits in, in cells: its left, top, width, and height. */
     box: {
         height: number;
@@ -38,9 +51,22 @@ export interface Relief {
         x: number;
         y: number;
     };
+    /**
+     * The two ends of the front edge, at the foot of the slab: `start` at the
+     * left corner, under the first column, and `end` at the bottom corner,
+     * under the last. The strip's first and last labels stand there.
+     */
+    corners: {
+        end: Point;
+        start: Point;
+    } | undefined;
     /** In the order they are painted, which is the order of the readings. */
     prisms: Prism[];
 }
+/** How far the slab reaches past the grid on every side, in cells. */
+export declare const MARGIN = 0.3;
+/** How thick the slab is, in cells. */
+export declare const THICKNESS = 0.25;
 /**
  * Each reading's height, from zero, as a share of the highest reading times
  * `tallest`.

package/dist/{isometric-heatmap → spatial-heatmap}/projection.js

@@ -1,14 +1,14 @@
+import { ISOMETRIC, pathData, projectionOf } from '@fusion.dev/helix-core';
 export const ACROSS = Math.sqrt(3) / 2;
+export const MARGIN = 0.3;
+export const THICKNESS = 0.25;
 export const heightsOf = (values, highest, tallest) => values.map((value) => highest > 0 && value !== undefined && value > 0
     ? (Math.min(value, highest) / highest) * tallest
     : 0);
 export const highestOf = (values) => values.reduce((high, value) => (value !== undefined && value > high ? value : high), 0);
-const short = (value) => String(Math.round(value * 1000) / 1000 || 0);
-const at = (column, row, height) => ({
-    x: (column - row) * ACROSS,
-    y: (column + row) / 2 - height,
-});
-const path = (points) => `M${points.map((point) => `${short(point.x)} ${short(point.y)}`).join('L')}Z`;
+const isometric = projectionOf(ISOMETRIC);
+const at = (column, row, height) => isometric.at(column, -row, height);
+const path = pathData;
 export const reliefOf = (heights, rows, footprint) => {
     const count = Math.max(1, Math.floor(rows) || 1);
     const inset = (1 - Math.min(1, Math.max(0, footprint))) / 2;
@@ -43,7 +43,32 @@ export const reliefOf = (heights, rows, footprint) => {
         };
     });
     if (prisms.length === 0) {
-        return { box: { height: 0, width: 0, x: 0, y: 0 }, prisms };
+        return { base: undefined, box: { height: 0, width: 0, x: 0, y: 0 }, corners: undefined, prisms };
     }
-    return { box: { height: bottom - top, width: right - left, x: left, y: top }, prisms };
+    const columns = Math.ceil(heights.length / count);
+    const deep = Math.min(count, heights.length);
+    const [first, last] = [-MARGIN, columns + MARGIN];
+    const [near, far] = [-MARGIN, deep + MARGIN];
+    const back = at(first, near, 0);
+    const across = at(last, near, 0);
+    const front = at(last, far, 0);
+    const down = at(first, far, 0);
+    const acrossFoot = at(last, near, -THICKNESS);
+    const frontFoot = at(last, far, -THICKNESS);
+    const downFoot = at(first, far, -THICKNESS);
+    const base = {
+        left: path([down, front, frontFoot, downFoot]),
+        right: path([front, across, acrossFoot, frontFoot]),
+        top: path([back, across, front, down]),
+    };
+    left = Math.min(left, downFoot.x);
+    right = Math.max(right, acrossFoot.x);
+    top = Math.min(top, back.y);
+    bottom = Math.max(bottom, frontFoot.y);
+    return {
+        base,
+        box: { height: bottom - top, width: right - left, x: left, y: top },
+        corners: { end: frontFoot, start: downFoot },
+        prisms,
+    };
 };

package/dist/spatial-heatmap/root/spatial-heatmap-root.d.ts

@@ -0,0 +1,239 @@
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+import '../../tooltip/index.js';
+import { HelixHeadlessHeatmap } from '../../heatmap/root/heatmap-root.js';
+/**
+ * @summary A heatmap drawn as a relief, where each reading stands as tall as its value.
+ *
+ * @description
+ * The same strip as `Heatmap`, seen from above at an angle. Each reading is a
+ * prism: its top face takes the cell's tone, and its height repeats the value,
+ * measured from zero against the highest reading in the table. `rows="7"`
+ * makes a contribution graph, with each week a column running down to the
+ * right.
+ *
+ * **The height says what the tone says.** Read the exact value from the tooltip
+ * or the table, and compare readings by tone. A tall reading at the front can
+ * hide a short one behind it, so the newest column stands at the front, where
+ * nothing covers it.
+ *
+ * **Everything else is `Heatmap`.** The table named by `for`, the tones and
+ * thresholds, the keys, the tooltip, the overview, `selection-mode`, and the
+ * events all work as they do there. The class extends the headless heatmap,
+ * and its own entry point carries the drawing, so a page using only `Heatmap`
+ * loads none of it.
+ *
+ * **It was `helix-isometric-heatmap` until 0.189.0**, and
+ * `helix-headless-isometric-heatmap` in the headless tier. The old tags are
+ * gone, and so are the `--isometric-heatmap-*` hooks, which are
+ * `--spatial-heatmap-*`, and the words key, which is `helix-spatial-heatmap`.
+ * The two shade hooks now take a step of lightness, such as `0.07`, where they
+ * took a percentage mixed toward black. Every attribute, part, and event kept
+ * its name.
+ *
+ * **`flat` lays every prism down** at no height, which leaves the tones on a
+ * plane at the same angle.
+ *
+ * **The prisms stand on a slab**, the `base`, which reaches a little past the
+ * grid, so the relief reads as one object. The `start` and `end` slots name
+ * the two ends of the front edge, which is the strip's first and last column:
+ * the component writes where those corners are on the `footer`, and a
+ * stylesheet stands each label at its corner. A renderer tells the chart where
+ * it draws those corners, so the labels stand at them there too, and follow
+ * them as the view turns.
+ *
+ * **`gap` and `min-cell` set the smallest cell.** The drawing scales as a
+ * whole, so a wider box draws larger cells and the gap grows with them. A box
+ * too narrow for every column at `min-cell` draws the newest that fit.
+ *
+ * **The drawing is SVG and holds still.** It scales with its box through its
+ * `viewBox`, needs no WebGL, and has no motion to pause.
+ *
+ * **A renderer can draw it in 3D instead.** Put a box for it in the
+ * `renderer` slot, and `connectSpatialHeatmap` from `@fusion.dev/helix-plot`
+ * draws the prisms in it with three.js, lit, in the same tones, in a view
+ * that drags round and zooms. The chart publishes its readings in `field`,
+ * and its own drawing stays under the renderer's, unseen, where a screen
+ * reader and the keys still reach it. Shift with an arrow turns the view,
+ * except under `selection-mode="multiple"`, where it selects.
+ *
+ * **Keyboard.** The keys are `Heatmap`'s. Down moves to the next reading in a
+ * column, drawn down to the left, and Right to the same reading in the next
+ * column, drawn down to the right.
+ *
+ * | 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"`. |
+ * | Shift with an arrow | Turns a renderer's view, where one is connected and `selection-mode` is not `multiple`. |
+ * | Escape | Puts the cell's tooltip away. |
+ *
+ * @since 0.189.0
+ * @status experimental
+ * @category charts
+ * @aliases Isometric heatmap, Isometric chart, 3D heatmap, Relief chart, Isometric contribution graph
+ * @documentation https://fusion.dev/helix/components/spatial-heatmap
+ *
+ * @slot renderer - The renderer's box, which a 3D drawing is made in, over the chart's own.
+ *
+ * @event {HelixPlotChangeEvent} helix-plot-change - The readings drawn or the reading the keys rest on changed, which a renderer is told. It stays on the chart.
+ * @event {HelixPlotTurnEvent} helix-plot-turn - Shift with an arrow asked a renderer's view to turn, by a step across or up.
+ *
+ * @csspart base - The slab the prisms stand on: a group holding its top and its two sides. Hidden from screen readers.
+ * @csspart base-left - The slab's side toward the viewer at the lower left, under the strip's last row.
+ * @csspart base-right - The slab's side toward the viewer at the lower right, under the newest column.
+ * @csspart base-top - The slab's top, which is the floor the prisms stand on.
+ * @csspart cell - One reading: a group holding its three faces.
+ * @csspart drawing - The SVG every prism is drawn in. It is mirrored on a right-to-left page.
+ * @csspart left-face - The face of a prism toward the next row, drawn at its lower left.
+ * @csspart right-face - The face of a prism toward the next column, drawn at its lower right.
+ * @csspart row - A column of prisms, which a grid reads as a row, under `selection-mode`.
+ * @csspart strip - The box the drawing fills, which takes focus to be read by key. It is named by the host's `aria-labelledby` or `aria-label`, then by `label`, then by the caption of the table.
+ * @csspart top-face - The top of a prism, which carries the reading's tone.
+ *
+ * @cssproperty --spatial-heatmap-depth - How tall the drawing is for its width. The component writes it on the footer, and a stylesheet that stands the `start` and `end` labels at their corners reads it.
+ * @cssproperty --spatial-heatmap-end-x - Where the front edge ends, under the newest column, across the drawing, from 0 at its inline start to 1. The component writes it on the footer, and a stylesheet that stands the `end` label there reads it.
+ * @cssproperty --spatial-heatmap-end-y - How far down the drawing the front edge ends, under the newest column, as a share of the drawing's width: its whole depth in the chart's own drawing, and wherever a renderer draws it. The component writes it on the footer, and a stylesheet that stands the `end` label there reads it.
+ * @cssproperty --spatial-heatmap-span - 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.
+ * @cssproperty --spatial-heatmap-start-x - Where the front edge starts, under the first column, across the drawing, from 0 at its inline start to 1: 0 in the chart's own drawing, and wherever a renderer draws it. The component writes it on the footer, and a stylesheet that stands the `start` label there reads it.
+ * @cssproperty --spatial-heatmap-start-y - How far down the drawing the front edge starts, under the first column, as a share of the drawing's width. The component writes it on the footer, and a stylesheet that stands the `start` label there reads it.
+ *
+ * @cssstate drawn - While a renderer has drawn the relief, and the chart's own drawing stays unseen under it.
+ */
+export declare class HelixHeadlessSpatialHeatmap extends HelixHeadlessHeatmap {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-spatial-heatmap': { emptyText: 'Keine Werte' } })`.
+     */
+    static words: string;
+    protected static markRules: string[];
+    /**
+     * Draws every prism at no height, so the tones lie on a plane.
+     */
+    flat: boolean;
+    /**
+     * How tall the highest reading stands, in cells. Every other reading stands
+     * at its share of it.
+     */
+    relief: number;
+    /** The prisms drawn on the last render, which the tooltip is placed against. */
+    private shown;
+    /** Whether a renderer has drawn the relief, which its own drawing then stays under. */
+    private rendered;
+    /** Where the renderer draws the reading, which the tooltip points at. */
+    private place;
+    /** Where the renderer draws the two ends of the front edge, which the first and last labels stand at. */
+    private corners;
+    /** The field last told, and the reading, so a renderer is told of a change only. */
+    private told;
+    /**
+     * What a renderer draws: every reading drawn, down each column and then
+     * across, with its place on the grid, its height in cells, and its tone.
+     */
+    get field(): {
+        cells: Array<{
+            column: number;
+            height: number;
+            label: string;
+            row: number;
+            tone?: string | undefined;
+        }>;
+        columns: number;
+        rows: number;
+    };
+    /** The reading the pointer or the keys rest on, as its place in `field.cells`, or `-1`. */
+    get active(): number;
+    /**
+     * Says whether a renderer has drawn the relief, which its own drawing then
+     * stays under, or shows it again. Called by the connector.
+     */
+    rendererDrawn(on?: boolean): void;
+    /**
+     * Puts the reading on the prism at `index`, or lets it go with `-1`, as a
+     * pointer resting on it in the renderer's drawing or a press there does.
+     * A touch keeps it until a tap lands elsewhere, and a mouse leaving a
+     * reading the keys moved to leaves it. Called by the connector.
+     */
+    requestActive(index: number, kind?: 'mouse' | 'pen' | 'touch'): void;
+    /**
+     * Says where the renderer draws the reading, as fractions of the strip from
+     * its top left, or `undefined` while it draws none. The tooltip points
+     * there. Called by the connector.
+     */
+    placeReading(at: {
+        x: number;
+        y: number;
+    } | undefined): void;
+    /**
+     * Says where the renderer draws the two ends of the front edge, under the
+     * first column and the last, as fractions of the strip from its top left,
+     * or `undefined` while they are out of view, where the labels keep the
+     * last place they had. The `start` and `end` labels stand there. Called by
+     * the connector.
+     */
+    placeCorners(at: {
+        end: {
+            x: number;
+            y: number;
+        };
+        start: {
+            x: number;
+            y: number;
+        };
+    } | undefined): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Shift with an arrow turns a renderer's view, and moves no reading,
+     * except under `selection-mode="multiple"`, where it selects a range.
+     */
+    private readonly onTurnKeydown;
+    /**
+     * How many readings fit, as whole columns, newest kept.
+     *
+     * The drawing runs at 30 degrees, so a cell takes `ACROSS` of its width, and
+     * the rows run across too: a strip `rows` deep starts that many cells to the
+     * left of its first column.
+     */
+    protected get room(): number;
+    /** The drawn readings as prisms, standing against the highest reading in the table. */
+    private drawnRelief;
+    protected render(): TemplateResult;
+    /**
+     * One reading as a prism. The sides come first, so the top face is painted
+     * over the edge they share with it.
+     *
+     * Under `selection-mode` the prism is a `gridcell` named by its row in the
+     * table and saying whether it is selected, as the flat strip's cell is.
+     */
+    private renderPrism;
+    /**
+     * The slab under the prisms, painted first so every prism stands on it.
+     * Hidden from screen readers, and out of a grid's rows.
+     */
+    private renderBase;
+    /**
+     * Where the front edge's two ends stand, for the labels that name them.
+     * **As shares of the drawing's width**, the one length a percentage margin
+     * is measured against, so a sheet places a label with no height to read.
+     */
+    private cornersStyle;
+    /**
+     * The prisms as a grid's rows, one for each column of the strip, which is
+     * also the order they are painted in.
+     */
+    private renderPrismRows;
+    /**
+     * The bubble over the top face of the reading the pointer or the keys rest
+     * on, placed as a share of the drawing, which the strip's box matches.
+     */
+    protected renderTooltip(grid?: boolean): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-spatial-heatmap': HelixHeadlessSpatialHeatmap;
+    }
+}