@fusion.dev/helix-headless 0.188.0 → 0.189.0

package/dist/spatial-scatter-chart/root/spatial-scatter-chart-root.js

@@ -0,0 +1,222 @@
+import { __decorate } from "tslib";
+import { AriaForwardController, CHART_PLOT, customElement, drawTooltip, formatWords, HelixElement, HelixPlotChangeEvent, HelixPlotTurnEvent, HelixReadingChangeEvent, HelixReadingPressEvent, isRtl, MixinChartSource, MixinChartStatus, spokenReading, words, } from '@fusion.dev/helix-core';
+import { html, nothing, svg } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import '../../tooltip/index.js';
+import { fieldOf } from '../field.js';
+import { boxView, drawBox, inBox, nearestTo, SPATIAL_VIEW, turned, } from '../view.js';
+const SERIES = 24;
+const TURNS = {
+    ArrowDown: { across: 0, up: -1 },
+    ArrowLeft: { across: -1, up: 0 },
+    ArrowRight: { across: 1, up: 0 },
+    ArrowUp: { across: 0, up: 1 },
+};
+let HelixHeadlessSpatialScatterChart = class HelixHeadlessSpatialScatterChart extends MixinChartStatus(MixinChartSource(HelixElement)) {
+    constructor() {
+        super(...arguments);
+        this.groupBy = '';
+        this.plotLabel = '3D scatter chart';
+        this.summaryLabel = '{count, plural, one {# point} other {# points}}: {x} across, {y} up, and {z} in depth.';
+        this.rendered = false;
+        this.camera = SPATIAL_VIEW;
+        this.placed = [];
+        this.last = undefined;
+        this.told = -1;
+        this.aria = new AriaForwardController(this, {
+            target: () => this.partNamed('plot'),
+        });
+        this.onPlotKeydown = (event) => {
+            const turn = TURNS[event.key];
+            if (!event.shiftKey || !turn || event.altKey || event.ctrlKey || event.metaKey) {
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            this.camera = turned(this.camera, turn.across, turn.up);
+            this.dispatchEvent(new HelixPlotTurnEvent(turn));
+        };
+        this.onDrawingMove = (event) => {
+            if (event.pointerType === 'touch') {
+                return;
+            }
+            const drawing = event.currentTarget;
+            this.requestActive(nearestTo(drawing, event, this.placed), event.pointerType === 'pen' ? 'pen' : 'mouse');
+        };
+        this.onDrawingLeave = (event) => {
+            if (event.pointerType !== 'touch') {
+                this.requestActive(-1, 'mouse');
+            }
+        };
+        this.onDrawingTap = (event) => {
+            if (event.pointerType === 'touch') {
+                this.requestActive(nearestTo(event.currentTarget, event, this.placed, 24), 'touch');
+            }
+        };
+    }
+    static { this.words = 'helix-spatial-scatter-chart'; }
+    get field() {
+        return fieldOf(this.sourceRows, this.plottedColumns, this.groupBy);
+    }
+    get active() {
+        return this.pointer.at;
+    }
+    get readings() {
+        return this.field.points.length;
+    }
+    rendererDrawn(on = true) {
+        this.rendered = on;
+        this.toggleState('drawn', on);
+    }
+    requestActive(index, kind = 'mouse') {
+        if (kind === 'touch') {
+            this.pointer.tapTo(index);
+        }
+        else if (index >= 0 || !this.pointer.keyed) {
+            this.pointer.set(index);
+        }
+    }
+    placeReading(at) {
+        this.place = at;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.pointer.axis = 'none';
+        this.pointer.onReading = (heard, detail) => {
+            const point = this.field.points[detail.index];
+            const told = {
+                ...detail,
+                index: point ? point.row : -1,
+                label: point?.label ?? '',
+            };
+            this.dispatchEvent(heard === 'press' ? new HelixReadingPressEvent(told) : new HelixReadingChangeEvent(told));
+        };
+    }
+    updated(changed) {
+        super.updated(changed);
+        const field = this.field;
+        if (!this.last || JSON.stringify(field) !== JSON.stringify(this.last)) {
+            this.last = field;
+            this.dispatchEvent(new HelixPlotChangeEvent({ kind: 'data' }));
+        }
+        if (this.pointer.at !== this.told) {
+            this.told = this.pointer.at;
+            this.dispatchEvent(new HelixPlotChangeEvent({ kind: 'focus' }));
+        }
+        if (changed.has('place')) {
+            ;
+            this.renderRoot.querySelector('[for="helix-chart-mark"]')?.reposition?.();
+        }
+    }
+    render() {
+        const field = this.field;
+        const { points } = field;
+        const readable = points.length > 0;
+        const at = this.pointer.at;
+        return html `<div
+        aria-describedby=${readable ? 'helix-chart-summary' : nothing}
+        aria-label=${this.named || this.plotLabel}
+        id=${CHART_PLOT}
+        part="plot"
+        role=${readable ? 'application' : 'img'}
+        tabindex=${readable ? '0' : nothing}
+        @keydown=${this.onPlotKeydown}
+      >
+        <slot></slot>
+        ${readable ? this.renderFallback(field, at) : nothing}
+        ${this.renderLive(points, at)}
+        ${this.renderTooltip(points[at]?.row)}
+      </div>
+      ${readable ? this.renderSummary(field) : this.renderStatus()}${this.renderTable()}`;
+    }
+    renderFallback(field, at) {
+        const view = boxView(field.axes, this.camera);
+        const places = field.points.map((point, index) => {
+            const box = [
+                inBox(field.axes.x, point.x),
+                inBox(field.axes.y, point.y),
+                inBox(field.axes.z, point.z),
+            ];
+            return { depth: view.depth(box), index, point, ...view.on(box) };
+        });
+        this.placed = places;
+        const painted = [...places].sort((one, other) => one.depth - other.depth);
+        const active = places[at];
+        const { bounds } = view;
+        return html `<div aria-hidden="true" dir="ltr" ?hidden=${this.rendered} part="fallback">
+      <svg
+        part="drawing"
+        preserveAspectRatio="xMidYMid meet"
+        viewBox="${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}"
+        xmlns="http://www.w3.org/2000/svg"
+        @pointerleave=${this.onDrawingLeave}
+        @pointermove=${this.onDrawingMove}
+        @pointerup=${this.onDrawingTap}
+      >${drawBox(view)}${painted.map((place) => svg `<circle cx=${place.x} cy=${place.y} part="point${place.index === at ? ' point-active' : ''}" r="0.045" style="--chart-series: var(--chart-series-${(place.point.groupIndex % SERIES) + 1})"></circle>`)}${active
+            ? svg `<circle cx=${active.x} cy=${active.y} part="ring" r="0.085"></circle><foreignObject height="0.001" overflow="visible" width="0.001" x=${active.x} y=${active.y}>${this.renderOwnTooltip(active.point.row)}</foreignObject>`
+            : nothing}</svg>
+    </div>`;
+    }
+    renderLive(points, at) {
+        if (points.length === 0) {
+            return nothing;
+        }
+        const row = this.sourceRows[points[at]?.row ?? -1];
+        const said = this.pointer.keyed && row
+            ? spokenReading(row, this.pointer.column, (cell) => this.pointer.shows(cell), this.pointer.position)
+            : '';
+        return html `<span aria-live="polite" part="live" role="status">${said}</span>`;
+    }
+    renderOwnTooltip(row) {
+        if (this.rendered || !this.sourceRows[row]) {
+            return nothing;
+        }
+        return drawTooltip(this.sourceRows, row, this.tag('tooltip'), { dir: isRtl(this) ? 'rtl' : 'ltr', fixed: true, placement: 'top', x: '0%', y: '0%' }, () => undefined);
+    }
+    renderTooltip(row) {
+        const place = this.place;
+        if (!this.rendered || !place || row === undefined || !this.sourceRows[row]) {
+            return nothing;
+        }
+        return drawTooltip(this.sourceRows, row, this.tag('tooltip'), {
+            dir: isRtl(this) ? 'rtl' : 'ltr',
+            fixed: true,
+            placement: 'top',
+            x: `${place.x * 100}%`,
+            y: `${place.y * 100}%`,
+        }, () => undefined);
+    }
+    renderSummary(field) {
+        const said = formatWords(this, 'summaryLabel', {
+            count: field.points.length,
+            x: field.axes.x.name,
+            y: field.axes.y.name,
+            z: field.axes.z.name,
+        });
+        return html `<p id="helix-chart-summary" part="summary">${said}</p>`;
+    }
+};
+__decorate([
+    property({ attribute: 'group-by' })
+], HelixHeadlessSpatialScatterChart.prototype, "groupBy", void 0);
+__decorate([
+    words,
+    property({ attribute: 'plot-label' })
+], HelixHeadlessSpatialScatterChart.prototype, "plotLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'summary-label' })
+], HelixHeadlessSpatialScatterChart.prototype, "summaryLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessSpatialScatterChart.prototype, "rendered", void 0);
+__decorate([
+    state()
+], HelixHeadlessSpatialScatterChart.prototype, "camera", void 0);
+__decorate([
+    state()
+], HelixHeadlessSpatialScatterChart.prototype, "place", void 0);
+HelixHeadlessSpatialScatterChart = __decorate([
+    customElement('helix-headless-spatial-scatter-chart')
+], HelixHeadlessSpatialScatterChart);
+export { HelixHeadlessSpatialScatterChart };

package/dist/spatial-scatter-chart/view.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A spatial chart's box as SVG, seen from a camera that turns and tilts: its
+ * edges, a grid at the ticks on its floor and two walls, and where its
+ * numbers and its measures' names stand. Shared by the spatial scatter and
+ * the spatial surface, which draw their own readings inside it.
+ *
+ * Kept apart from the elements because it is arithmetic a picture hides: a
+ * tick drawn at the wrong place reads as a number the data never had.
+ *
+ * **The box is two units on every side**, from -1 to 1, as the three.js
+ * driver's is, so the same reading stands at the same place in either
+ * drawing. Across is the floor's across, up is the height, and in depth runs
+ * toward the viewer, which is the way back from the floor's back.
+ */
+import { type Camera, type PagePoint, type Projection } from '@fusion.dev/helix-core';
+import { type SVGTemplateResult } from 'lit';
+import type { PlotAxis } from './field.js';
+/**
+ * Where a spatial chart's SVG drawing is seen from until it is turned: from
+ * the front right and a little above, about where the three.js driver's
+ * camera starts, so a renderer that takes over does not swing the view.
+ */
+export declare const SPATIAL_VIEW: Camera;
+/** How far one step of Shift with an arrow turns or tilts the view, in degrees, as the renderer's. */
+export declare const VIEW_STEP = 15;
+/** A place in the box: across, up, and in depth, each from -1 to 1. */
+export type BoxPoint = readonly [number, number, number];
+/** A number or a name written in the drawing, where it stands on the page. */
+export interface ViewLabel {
+    /** Whether it is a measure's name, drawn stronger, rather than a tick's number. */
+    name: boolean;
+    text: string;
+    x: number;
+    y: number;
+}
+/** The box as the camera sees it. */
+export interface BoxView {
+    /** The box every line, label, and reading fits in, on the page: its left, top, width, and height. */
+    bounds: {
+        height: number;
+        width: number;
+        x: number;
+        y: number;
+    };
+    /** The box's edges and its grid, as one path. */
+    grid: string;
+    labels: ViewLabel[];
+    /** A place in the box, on the page. */
+    on(point: BoxPoint): PagePoint;
+    /** How near the camera a place in the box stands: the larger, the nearer. */
+    depth(point: BoxPoint): number;
+    projection: Projection;
+}
+/** Where a number stands in the box, from -1 at its axis' low end to 1 at its high end. */
+export declare const inBox: (axis: PlotAxis, value: number) => number;
+/** A number on an axis, written short enough for a tick. */
+export declare const tickText: (value: number) => string;
+/** How large a tick's number and a measure's name are, on the page, in the box's units. */
+export declare const TICK_SIZE = 0.13;
+export declare const NAME_SIZE = 0.15;
+/**
+ * The box for `axes`, seen from `camera`, and the readings' own places on
+ * the page, which `extra` adds to the bounds.
+ */
+export declare const boxView: (axes: {
+    x: PlotAxis;
+    y: PlotAxis;
+    z: PlotAxis;
+}, camera: Camera, extra?: readonly PagePoint[]) => BoxView;
+/** A place on the page as a share of the bounds, from their top left, for a mark the tooltip points at. */
+export declare const shareOf: (view: BoxView, point: PagePoint) => {
+    x: number;
+    y: number;
+};
+/** Path data for a closed shape through `points`. */
+export declare const shape: (points: readonly PagePoint[]) => string;
+/** The next view after a step of Shift with an arrow, held between the lowest tilt and straight above. */
+export declare const turned: (camera: Camera, across: number, up: number) => Camera;
+/** The box's grid, its numbers, and its measures' names, drawn first so every reading stands in front of them. */
+export declare const drawBox: (view: BoxView) => SVGTemplateResult;
+/** A reading drawn on the page, which the pointer finds. */
+export interface Placed {
+    index: number;
+    x: number;
+    y: number;
+}
+/**
+ * The reading drawn nearest the pointer, within `reach` pixels of it, or
+ * `-1`. **Measured on the screen**, through the drawing's own transform, so
+ * a small point is found from as far as a large one, at any size the
+ * drawing is shown.
+ */
+export declare const nearestTo: (drawing: SVGSVGElement | null | undefined, event: PointerEvent, places: readonly Placed[], reach?: number) => number;

package/dist/spatial-scatter-chart/view.js

@@ -0,0 +1,115 @@
+import { pathData, projectionOf, shortNumber, } from '@fusion.dev/helix-core';
+import { svg } from 'lit';
+export const SPATIAL_VIEW = { tilt: 25, turn: 42 };
+export const VIEW_STEP = 15;
+export const inBox = (axis, value) => {
+    const [low, high] = axis.range;
+    return high === low ? 0 : ((value - low) / (high - low)) * 2 - 1;
+};
+export const tickText = (value) => String(Number(value.toPrecision(6)));
+const WIDE = 0.58;
+export const TICK_SIZE = 0.13;
+export const NAME_SIZE = 0.15;
+export const boxView = (axes, camera, extra = []) => {
+    const projection = projectionOf(camera);
+    const on = ([x, y, z]) => projection.at(x, -z, y);
+    const depth = ([x, , z]) => projection.depth(x, -z);
+    const lines = [];
+    const line = (from, to) => {
+        const [a, b] = [on(from), on(to)];
+        lines.push(`M${shortNumber(a.x)} ${shortNumber(a.y)}L${shortNumber(b.x)} ${shortNumber(b.y)}`);
+    };
+    for (const a of [-1, 1]) {
+        for (const b of [-1, 1]) {
+            line([-1, a, b], [1, a, b]);
+            line([a, -1, b], [a, 1, b]);
+            line([a, b, -1], [a, b, 1]);
+        }
+    }
+    for (const tick of axes.x.ticks) {
+        const x = inBox(axes.x, tick);
+        line([x, -1, -1], [x, -1, 1]);
+        line([x, -1, -1], [x, 1, -1]);
+    }
+    for (const tick of axes.z.ticks) {
+        const z = inBox(axes.z, tick);
+        line([-1, -1, z], [1, -1, z]);
+        line([-1, -1, z], [-1, 1, z]);
+    }
+    for (const tick of axes.y.ticks) {
+        const y = inBox(axes.y, tick);
+        line([-1, y, -1], [1, y, -1]);
+        line([-1, y, -1], [-1, y, 1]);
+    }
+    const labels = [];
+    const label = (at, text, name = false) => {
+        labels.push({ name, text, ...on(at) });
+    };
+    for (const tick of axes.x.ticks) {
+        label([inBox(axes.x, tick), -1, 1.14], tickText(tick));
+    }
+    for (const tick of axes.z.ticks) {
+        label([1.14, -1, inBox(axes.z, tick)], tickText(tick));
+    }
+    for (const tick of axes.y.ticks.slice(1)) {
+        label([-1.14, inBox(axes.y, tick), 1], tickText(tick));
+    }
+    label([0, -1, 1.38], axes.x.name, true);
+    label([1.6, -1, 0], axes.z.name, true);
+    label([-1, 1.28, 1], axes.y.name, true);
+    const corners = [];
+    for (const x of [-1, 1]) {
+        for (const y of [-1, 1]) {
+            for (const z of [-1, 1]) {
+                corners.push(on([x, y, z]));
+            }
+        }
+    }
+    for (const one of labels) {
+        const size = one.name ? NAME_SIZE : TICK_SIZE;
+        const half = (one.text.length * size * WIDE) / 2;
+        corners.push({ x: one.x - half, y: one.y - size }, { x: one.x + half, y: one.y + size });
+    }
+    corners.push(...extra);
+    const xs = corners.map((point) => point.x);
+    const ys = corners.map((point) => point.y);
+    const [left, top] = [Math.min(...xs), Math.min(...ys)];
+    return {
+        bounds: { height: Math.max(...ys) - top, width: Math.max(...xs) - left, x: left, y: top },
+        depth,
+        grid: lines.join(''),
+        labels,
+        on,
+        projection,
+    };
+};
+export const shareOf = (view, point) => ({
+    x: (point.x - view.bounds.x) / view.bounds.width,
+    y: (point.y - view.bounds.y) / view.bounds.height,
+});
+export const shape = (points) => pathData(points);
+export const turned = (camera, across, up) => ({
+    tilt: Math.min(Math.max(camera.tilt + up * VIEW_STEP, 15), 90),
+    turn: camera.turn + across * VIEW_STEP,
+});
+export const drawBox = (view) => svg `<path d=${view.grid} part="grid"></path>${view.labels.map((label) => label.name
+    ? svg `<text dominant-baseline="central" font-size=${NAME_SIZE} part="axis-name" text-anchor="middle" x=${shortNumber(label.x)} y=${shortNumber(label.y)}>${label.text}</text>`
+    : svg `<text dominant-baseline="central" font-size=${TICK_SIZE} part="tick" text-anchor="middle" x=${shortNumber(label.x)} y=${shortNumber(label.y)}>${label.text}</text>`)}`;
+export const nearestTo = (drawing, event, places, reach = 14) => {
+    const matrix = drawing?.getScreenCTM?.();
+    if (!matrix) {
+        return -1;
+    }
+    let found = -1;
+    let distance = reach;
+    for (const place of places) {
+        const x = matrix.a * place.x + matrix.c * place.y + matrix.e;
+        const y = matrix.b * place.x + matrix.d * place.y + matrix.f;
+        const away = Math.hypot(x - event.clientX, y - event.clientY);
+        if (away < distance) {
+            distance = away;
+            found = place.index;
+        }
+    }
+    return found;
+};

package/dist/spatial-surface-chart/grid.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A 3D surface's table read as a grid of heights.
+ *
+ * Kept apart from the element because it is arithmetic a picture hides: a
+ * reading put in the wrong cell bends the surface in a place the data never
+ * did, and a missing reading drawn as zero digs a pit that is not there.
+ */
+import { type FieldRow, type PlotAxis } from '../spatial-scatter-chart/field.js';
+/** One place on the grid: where it stands across and in depth, and its reading, where the table has one. */
+export interface SurfaceCell {
+    /** The row's own label, where the table has a reading here. */
+    label?: string | undefined;
+    /** The row it was read from, counting from zero. */
+    row?: number | undefined;
+    /** The height, where the table has a reading here. */
+    value?: number | undefined;
+    /** Across and in depth, in the table's own numbers. */
+    x: number;
+    z: number;
+}
+/** The table as a 3D surface reads it. */
+export interface SurfaceField {
+    /** Across, up (the height), and in depth. */
+    axes: {
+        x: PlotAxis;
+        y: PlotAxis;
+        z: PlotAxis;
+    };
+    /**
+     * Every place on the grid, across first: the cell `across` places along
+     * and `depth` places back is at `across * depths.length + depth`.
+     */
+    cells: SurfaceCell[];
+    /** The distinct places across, lowest first. */
+    acrosses: number[];
+    /** The distinct places in depth, lowest first. */
+    depths: number[];
+    /** How many cells hold a reading. */
+    readings: number;
+}
+/**
+ * Reads the table: **the first numeric column is across, the second is in
+ * depth, and the third is the height**, one reading per row. The grid takes
+ * every distinct place across and in depth, so a place the table has no
+ * reading for is a cell with no value, which the surface leaves open. A
+ * later row for a place already read replaces it.
+ */
+export declare const surfaceOf: (rows: readonly FieldRow[], columns: readonly number[]) => SurfaceField;
+/** How high a cell stands between the lowest and the highest reading, from 0 to 1, or undefined where it has none. */
+export declare const levelOf: (field: SurfaceField, cell: SurfaceCell) => number | undefined;

package/dist/spatial-surface-chart/grid.js

@@ -0,0 +1,46 @@
+import { ticks } from '@fusion.dev/helix-core';
+import { niceRange } from '../spatial-scatter-chart/field.js';
+export const surfaceOf = (rows, columns) => {
+    const [xAt, zAt, yAt] = columns;
+    const nameOf = (column) => column === undefined ? '' : (rows.find((row) => row.cells[column])?.cells[column]?.name ?? '');
+    const read = [];
+    rows.forEach((row, at) => {
+        const value = (column) => column === undefined ? undefined : row.cells[column]?.value;
+        const [x, z, y] = [value(xAt), value(zAt), value(yAt)];
+        if (Number.isFinite(x) && Number.isFinite(z) && Number.isFinite(y)) {
+            read.push({ label: row.label, row: at, value: y, x: x, z: z });
+        }
+    });
+    const distinct = (values) => [...new Set(values)].sort((a, b) => a - b);
+    const acrosses = distinct(read.map((one) => one.x));
+    const depths = distinct(read.map((one) => one.z));
+    const cells = acrosses.flatMap((x) => depths.map((z) => ({ x, z })));
+    for (const one of read) {
+        const at = acrosses.indexOf(one.x) * depths.length + depths.indexOf(one.z);
+        cells[at] = { label: one.label, row: one.row, value: one.value, x: one.x, z: one.z };
+    }
+    const axis = (column, values, exact) => {
+        const [low, high] = [Math.min(...values), Math.max(...values)];
+        const range = exact && low < high ? [low, high] : niceRange(low, high);
+        return { name: nameOf(column), range, ticks: ticks(range) };
+    };
+    return {
+        acrosses,
+        axes: {
+            x: axis(xAt, acrosses, true),
+            y: axis(yAt, read.map((one) => one.value), false),
+            z: axis(zAt, depths, true),
+        },
+        cells,
+        depths,
+        readings: read.length,
+    };
+};
+export const levelOf = (field, cell) => {
+    if (cell.value === undefined) {
+        return undefined;
+    }
+    const values = field.cells.flatMap((one) => (one.value === undefined ? [] : [one.value]));
+    const [low, high] = [Math.min(...values), Math.max(...values)];
+    return high === low ? 0.5 : (cell.value - low) / (high - low);
+};

package/dist/spatial-surface-chart/index.d.ts

@@ -0,0 +1,2 @@
+export { levelOf, type SurfaceCell, type SurfaceField, surfaceOf } from './grid.js';
+export { HelixHeadlessSpatialSurfaceChart } from './root/spatial-surface-chart-root.js';

package/dist/spatial-surface-chart/index.js

@@ -0,0 +1,2 @@
+export { levelOf, surfaceOf } from './grid.js';
+export { HelixHeadlessSpatialSurfaceChart } from './root/spatial-surface-chart-root.js';