@fusion.dev/helix-headless 0.198.0 → 0.199.1

package/dist/spatial-treemap/blocks.js

@@ -0,0 +1,215 @@
+import { solid, ticks } from '@fusion.dev/helix-core';
+import { niceRange } from '../spatial-scatter-chart/field.js';
+import { inBox } from '../spatial-scatter-chart/view.js';
+const HEIGHT = 0.6;
+const SLAB = 0.06;
+const GROUP_GAP = 0.05;
+const BLOCK_GAP = 0.018;
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+export const squarified = (sizes, within) => {
+    const total = sum(sizes);
+    const across = within.x1 - within.x0;
+    const deep = within.z1 - within.z0;
+    if (total <= 0 || across <= 0 || deep <= 0) {
+        return sizes.map(() => ({ ...within, x1: within.x0, z1: within.z0 }));
+    }
+    const areas = sizes.map((size) => (size / total) * across * deep);
+    const placed = [];
+    const free = { ...within };
+    const worst = (row, side) => {
+        const all = sum(row);
+        const [most, least] = [Math.max(...row), Math.min(...row)];
+        return Math.max((side * side * most) / (all * all), (all * all) / (side * side * least));
+    };
+    let at = 0;
+    while (at < areas.length) {
+        const wide = free.x1 - free.x0 >= free.z1 - free.z0;
+        const side = wide ? free.z1 - free.z0 : free.x1 - free.x0;
+        const row = [areas[at]];
+        let next = at + 1;
+        while (next < areas.length &&
+            worst([...row, areas[next]], side) <= worst(row, side)) {
+            row.push(areas[next]);
+            next++;
+        }
+        const thick = sum(row) / side;
+        let along = wide ? free.z0 : free.x0;
+        for (const area of row) {
+            const length = area / thick;
+            placed.push(wide
+                ? { x0: free.x0, x1: free.x0 + thick, z0: along, z1: along + length }
+                : { x0: along, x1: along + length, z0: free.z0, z1: free.z0 + thick });
+            along += length;
+        }
+        if (wide) {
+            free.x0 += thick;
+        }
+        else {
+            free.z0 += thick;
+        }
+        at = next;
+    }
+    return placed;
+};
+const inset = (area, gap) => {
+    const margin = Math.min(gap / 2, (area.x1 - area.x0) / 4, (area.z1 - area.z0) / 4);
+    return {
+        x0: area.x0 + margin,
+        x1: area.x1 - margin,
+        z0: area.z0 + margin,
+        z1: area.z1 - margin,
+    };
+};
+const FLOOR = { name: '', range: [-1, 1], rules: [], ticks: [] };
+export const treemapOf = (rows, columns, groupBy = '') => {
+    const nameOf = (column) => column === undefined ? '' : (rows.find((row) => row.cells[column])?.cells[column]?.name ?? '');
+    const [sizeAt, heightAt] = columns.filter((column) => nameOf(column) !== groupBy);
+    const groups = [];
+    const blocks = [];
+    rows.forEach((row, at) => {
+        const size = sizeAt === undefined ? undefined : row.cells[sizeAt]?.value;
+        if (size === undefined || !Number.isFinite(size) || size <= 0) {
+            return;
+        }
+        const height = heightAt === undefined ? undefined : row.cells[heightAt]?.value;
+        const group = groupBy ? (row.cells.find((cell) => cell.name === groupBy)?.text ?? '') : '';
+        let groupIndex = groups.indexOf(group);
+        if (groupIndex < 0) {
+            groupIndex = groups.push(group) - 1;
+        }
+        blocks.push({
+            area: { x0: 0, x1: 0, z0: 0, z1: 0 },
+            group,
+            groupIndex,
+            height: Number.isFinite(height) ? height : undefined,
+            label: row.label,
+            row: at,
+            size,
+        });
+    });
+    const totals = groups.map((_, index) => sum(blocks.filter((block) => block.groupIndex === index).map((block) => block.size)));
+    const byTotal = groups
+        .map((_, index) => index)
+        .sort((one, other) => (totals[other] ?? 0) - (totals[one] ?? 0));
+    const shares = squarified(byTotal.map((index) => totals[index] ?? 0), { x0: -1, x1: 1, z0: -1, z1: 1 });
+    byTotal.forEach((index, at) => {
+        const share = shares[at];
+        if (!share) {
+            return;
+        }
+        const members = blocks
+            .filter((block) => block.groupIndex === index)
+            .sort((one, other) => other.size - one.size);
+        const areas = squarified(members.map((block) => block.size), groups.length > 1 ? inset(share, GROUP_GAP) : share);
+        members.forEach((block, place) => {
+            block.area = inset(areas[place], BLOCK_GAP);
+        });
+    });
+    const heights = blocks.flatMap((block) => (block.height === undefined ? [] : [block.height]));
+    const tall = heightAt !== undefined;
+    const [low, high] = [Math.min(0, ...heights), Math.max(0, ...heights)];
+    const range = !tall || low === high ? [0, 1] : niceRange(low, high);
+    return {
+        axes: {
+            extent: [1, tall ? HEIGHT : SLAB, 1],
+            x: FLOOR,
+            y: tall ? { name: nameOf(heightAt), range, ticks: ticks(range) } : { ...FLOOR, range },
+            z: FLOOR,
+        },
+        blocks,
+        groups,
+        height: nameOf(heightAt),
+        size: nameOf(sizeAt),
+    };
+};
+export const blocksDrawn = (field, projection) => {
+    const [ex, ey, ez] = field.axes.extent;
+    const zero = inBox(field.axes.y, 0) * ey;
+    const tall = field.height !== '';
+    return field.blocks.map((block, index) => {
+        const top = inBox(field.axes.y, tall ? (block.height ?? 0) : 1) * ey;
+        const base = Math.min(zero, top);
+        const height = Math.abs(top - zero);
+        const floor = {
+            x0: block.area.x0 * ex,
+            x1: block.area.x1 * ex,
+            y0: -block.area.z1 * ez,
+            y1: -block.area.z0 * ez,
+        };
+        const lifted = {
+            ...projection,
+            at: (px, py, pz = 0) => projection.at(px, py, pz + base),
+        };
+        const corners = [];
+        for (const cx of [floor.x0, floor.x1]) {
+            for (const cy of [floor.y0, floor.y1]) {
+                corners.push(lifted.at(cx, cy, 0), lifted.at(cx, cy, height));
+            }
+        }
+        return {
+            corners,
+            drawn: solid(lifted, 'block', (floor.x0 + floor.x1) / 2, (floor.y0 + floor.y1) / 2, floor.x1 - floor.x0, height, floor.y1 - floor.y0),
+            floor,
+            index,
+        };
+    });
+};
+const LEVEL = 1e-9;
+export const paintOrder = (projection, blocks) => {
+    const [ax, ay] = projection.toward;
+    const along = (oneLow, oneHigh, otherLow, otherHigh, toward) => {
+        if (Math.abs(toward) < LEVEL) {
+            return 0;
+        }
+        if (oneHigh <= otherLow) {
+            return toward > 0 ? -1 : 1;
+        }
+        if (otherHigh <= oneLow) {
+            return toward > 0 ? 1 : -1;
+        }
+        return 0;
+    };
+    const count = blocks.length;
+    const after = Array.from({ length: count }, () => []);
+    const waiting = new Array(count).fill(0);
+    for (let one = 0; one < count; one++) {
+        for (let other = one + 1; other < count; other++) {
+            const [a, b] = [blocks[one].floor, blocks[other].floor];
+            const across = along(a.x0, a.x1, b.x0, b.x1, ax);
+            const back = along(a.y0, a.y1, b.y0, b.y1, ay);
+            const order = across !== 0 && back !== 0 && across !== back ? 0 : across || back;
+            if (order < 0) {
+                after[one]?.push(other);
+                waiting[other] = (waiting[other] ?? 0) + 1;
+            }
+            else if (order > 0) {
+                after[other]?.push(one);
+                waiting[one] = (waiting[one] ?? 0) + 1;
+            }
+        }
+    }
+    const depthOf = blocks.map((block) => projection.depth((block.floor.x0 + block.floor.x1) / 2, (block.floor.y0 + block.floor.y1) / 2));
+    const done = new Array(count).fill(false);
+    const order = [];
+    for (let step = 0; step < count; step++) {
+        let pick = -1;
+        for (let at = 0; at < count; at++) {
+            if (done[at]) {
+                continue;
+            }
+            const free = waiting[at] === 0;
+            const best = pick < 0 ? undefined : waiting[pick] === 0;
+            if (pick < 0 ||
+                (free && !best) ||
+                (free === best && (depthOf[at] ?? 0) < (depthOf[pick] ?? 0))) {
+                pick = at;
+            }
+        }
+        done[pick] = true;
+        order.push(blocks[pick]);
+        for (const next of after[pick] ?? []) {
+            waiting[next] = (waiting[next] ?? 0) - 1;
+        }
+    }
+    return order;
+};

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

@@ -0,0 +1,2 @@
+export { blocksDrawn, type DrawnBlock, type FloorArea, paintOrder, squarified, type TreemapBlock, type TreemapField, treemapOf, } from './blocks.js';
+export { HelixHeadlessSpatialTreemap } from './root/spatial-treemap-root.js';

package/dist/spatial-treemap/index.js

@@ -0,0 +1,2 @@
+export { blocksDrawn, paintOrder, squarified, treemapOf, } from './blocks.js';
+export { HelixHeadlessSpatialTreemap } from './root/spatial-treemap-root.js';

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

@@ -0,0 +1,236 @@
+import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../tooltip/index.js';
+import { type TreemapField } from '../blocks.js';
+declare const HelixHeadlessSpatialTreemap_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartStatusInterface);
+/**
+ * @summary A treemap drawn in three dimensions, each item a block whose area is its size and whose height is a second measure.
+ *
+ * @description
+ * A 3D treemap shares a floor out among the rows of its table: **the first
+ * numeric column is each block's size, and its share of the floor is in
+ * proportion to it**. The second numeric column, where there is one, is each
+ * block's height, from zero, so one block shows two measures: how large an
+ * item is, and how it stands on another count, such as each service's
+ * requests and its errors. `group-by` names a column of text, such as a team,
+ * that gathers its rows into one part of the floor, in one color, and the
+ * part is as large as their total.
+ *
+ * **Each part is laid out as near to square as its share allows**, so two
+ * items compare by area, and the largest stand at the back left, where they
+ * hide the least. With no height column the blocks stand as one thin slab, a
+ * treemap seen in 3D.
+ *
+ * **Helix draws the frame, and the chart draws the blocks in 3D itself, in
+ * SVG**: a picture a print and a page without WebGL show too, which a drag
+ * or Shift with an arrow turns. Put a box inside the chart, and
+ * `connectSpatialTreemap` from `@fusion.dev/helix-plot`, given
+ * `threeTreemapDriver` from `@fusion.dev/helix-plot/three`, draws the blocks
+ * in it with three.js, lit and in perspective.
+ *
+ * **The table is the reading.** Every number is in it, and screen readers
+ * read it. The `summary` part names the number of items and groups and the
+ * range of their sizes, and describes the plot.
+ *
+ * **The plot is read by key, in the table's order.** It takes focus, named
+ * by `label` or the caption. The left and right arrows move from item to
+ * item, the down and up arrows among the item's measures, which the readout
+ * says first, and Home and End go to the first and the last item. Shift
+ * with an arrow turns the view, and Escape lets the item go.
+ *
+ * **A reading shows its row in a tooltip**, as on every chart: the block a
+ * mouse or a pen rests on, the block tapped, or the one the keys move to.
+ *
+ * **Readings are sent as every chart sends them.** `helix-reading-change`
+ * says each move of the reading, and `helix-reading-press` a block clicked
+ * or pressed with Enter or Space, each with the row of the table in `index`.
+ *
+ * **Keyboard.** The plot is one tab stop once it has readings.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Tab | Moves focus to the plot. |
+ * | Right, Left | Moves to the next or the previous item, in the table's order. |
+ * | Down, Up | Moves among the item's measures, which the readout says first. |
+ * | Home, End | Moves to the first or the last item. |
+ * | Shift with an arrow | Turns the view across, or tilts it up and down. |
+ * | Enter, Space | Presses the item, which sends `helix-reading-press`. |
+ * | Escape | Lets the item go. |
+ *
+ * @since 0.199.0
+ * @status experimental
+ * @category charts
+ * @aliases 3D treemap, Isometric treemap, Treemap in 3D, City map chart
+ * @documentation https://fusion.dev/helix/components/spatial-treemap
+ *
+ * @slot - The renderer's box, which the 3D drawing is made in.
+ * @slot empty - Content shown when the table has no readings. Falls back to `empty-text`.
+ * @slot loading - Content shown while `loading` is set and there are no readings yet. Falls back to `loading-text`.
+ *
+ * @event {HelixPlotChangeEvent} helix-plot-change - The blocks or the block the keys rest on changed, which the renderer is told. It stays on the chart.
+ * @event {HelixPlotTurnEvent} helix-plot-turn - Shift with an arrow asked the view to turn, by a step across or up.
+ * @event {HelixReadingChangeEvent} helix-reading-change - The reading moved, or was put away: `index` is the row, or `-1` for none, with its `label` and the `pointerType` that moved it.
+ * @event {HelixReadingPressEvent} helix-reading-press - A block was clicked or pressed with Enter or Space, with the same detail as `helix-reading-change`.
+ *
+ * @csspart axis-name - The height's name, along its edge of the box, in the chart's own drawing.
+ * @csspart block - One block, its faces in its group's color.
+ * @csspart block-active - The block the pointer or the keys rest on. Set alongside `block`.
+ * @csspart drawing - The chart's own drawing in SVG: the box, its grid and numbers, and the blocks.
+ * @csspart empty - The words when the table has no readings: the `empty` slot, falling back to `empty-text`.
+ * @csspart face - One face of a block the view shows, shaded by which way it faces.
+ * @csspart fallback - The box the chart's own drawing fills, shown until a renderer has drawn and where none is connected. Hidden from screen readers.
+ * @csspart grid - The box's edges and its grid, in the chart's own drawing.
+ * @csspart live - The readout: a polite live region that says the item the keys moved to. Hide it visually.
+ * @csspart loading - The words while `loading` is set and there are no readings.
+ * @csspart mark - The invisible point the tooltip is anchored to, where the renderer draws the reading.
+ * @csspart plot - 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 ring - The outline around the block the pointer or the keys rest on, painted after it, so the blocks in front of it cover it.
+ * @csspart summary - The number of items and groups and the range of their sizes, written as a sentence for screen readers, which describes the plot. Hide it visually.
+ * @csspart table - The readings as a table, for a screen reader, rendered only where they were drawn from `data`. Hide it visually.
+ * @csspart tick - A height at a tick, along its edge of the box, in the chart's own drawing.
+ * @csspart tooltip - The bubble, forwarded from `Tooltip`.
+ * @csspart tooltip-anchor - The `Tooltip` element itself.
+ * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
+ * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, on its top edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, on its right edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, on its left edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The point while the bubble is above the reading, on its bottom edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the reading. Set alongside `tooltip`.
+ * @csspart tooltip-cell - One column's name and value inside the tooltip.
+ * @csspart tooltip-cell-current - The cell a chart's series keys rest on, which every chart's tooltip can mark. This chart marks none, since its readout says the measure. Set alongside `tooltip-cell`.
+ * @csspart tooltip-label - The row's own name inside the tooltip.
+ * @csspart tooltip-left - The bubble while it is left of the reading. Set alongside `tooltip`.
+ * @csspart tooltip-name - A column's name inside the tooltip.
+ * @csspart tooltip-right - The bubble while it is right of the reading. Set alongside `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the reading. Set alongside `tooltip`.
+ * @csspart tooltip-value - A column's value inside the tooltip.
+ *
+ * @cssproperty --spatial-treemap-shade - How far a block's face turns from the light, from 0 for its top. The component writes it on each face, and the stylesheet that shades the face reads it.
+ *
+ * @cssstate active - While a block is shown, under the pointer or the keys.
+ * @cssstate drawn - While a renderer has drawn the blocks, and the chart's own drawing is hidden.
+ * @cssstate empty - While the `empty` part stands in place of the readings.
+ * @cssstate loading - While the `loading` part stands in place of the readings.
+ */
+export declare class HelixHeadlessSpatialTreemap extends HelixHeadlessSpatialTreemap_base {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-spatial-treemap': { emptyText: 'Keine Werte' } })`.
+     */
+    static words: string;
+    /** The column of text that gathers the rows into groups, by its heading. None by default. */
+    groupBy: string;
+    /**
+     * Draws no box: no edges, grid, numbers, or names, so the readings stand
+     * alone and fill the plot, as a picture on a product's own page does. The
+     * table, the summary, the tooltip, and the keys still carry every value,
+     * and a renderer draws no box either.
+     */
+    noBox: boolean;
+    /** The plot's name where the chart has none: no `aria-label`, `label`, or table caption. */
+    plotLabel: string;
+    /**
+     * The `summary` part's sentence. `{count}` and `{groups}` are the number
+     * of items and groups, written in the locale, and `{low}` and `{high}` the
+     * smallest and the largest size.
+     */
+    summaryLabel: string;
+    /** Whether a renderer has drawn the blocks, which hides the chart's own drawing. */
+    private rendered;
+    /** Where the chart's own drawing is seen from, which a drag or Shift with an arrow turns. */
+    private camera;
+    /** A drag across the chart's own drawing, which turns its view. */
+    private readonly drag;
+    /** Where the renderer draws the reading, which the tooltip points at. */
+    private place;
+    /** The field last told, kept so a change of it can be told. */
+    private last;
+    /** The block the keys rested on last, so a change of it can be told. */
+    private told;
+    /** Carries a host `aria-labelledby` and `aria-describedby` to the plot. */
+    protected readonly aria: AriaForwardController;
+    /**
+     * The table read as blocks. **The first numeric column is each block's
+     * size, and the second its height.** A renderer reads it.
+     */
+    get field(): TreemapField;
+    /** The field last read, and the rows, columns, and group column it was read from. */
+    private memo;
+    /** The block the keys or the pointer rest on, as its place in `field.blocks`, or `-1`. */
+    get active(): number;
+    /** The number of blocks, which the keys walk. */
+    get readings(): number;
+    /**
+     * Says whether a renderer has drawn the blocks, which hides the chart's own
+     * drawing or shows it again. Called by the connector.
+     */
+    rendererDrawn(on?: boolean): void;
+    /**
+     * Puts the reading on the block 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 plot 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;
+    connectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Shift with an arrow turns the view, the chart's own drawing and the
+     * renderer's alike, and moves no reading.
+     */
+    private readonly onPlotKeydown;
+    /** The block a pointer event is over, or `-1`: the one in front, since the blocks are painted back to front. */
+    private blockAt;
+    /** A mouse or a pen over the chart's own drawing puts the reading on the block it rests on. */
+    private readonly onDrawingMove;
+    private readonly onDrawingDown;
+    /** A press the browser took back, such as for a scroll, which ends a drag as a release does. */
+    private readonly onDrawingCancel;
+    private readonly onDrawingLeave;
+    /**
+     * A tap is a touch reader's hover, unless it was a drag, which turned the
+     * view: it shows the block under it until a tap lands elsewhere.
+     */
+    private readonly onDrawingTap;
+    protected render(): TemplateResult;
+    /**
+     * The blocks in 3D, in SVG: the box with its height's grid and numbers, and
+     * each block on its part of the floor, standing from zero to its height,
+     * painted back to front, in its group's color and shaded by which way each
+     * face turns. The chart's own drawing, until a renderer has drawn and where
+     * none is connected.
+     */
+    private renderFallback;
+    /** One block, its faces in its group's color, each shaded by which way it faces. */
+    private renderBlock;
+    /** The readout: the item's row in words, once the keys have moved to one. */
+    private renderLive;
+    /**
+     * The reading's row in the tooltip, pointed at its block in the chart's own
+     * drawing, which holds it there.
+     */
+    private renderOwnTooltip;
+    /**
+     * The reading's row in the tooltip every chart shows, pointed at where the
+     * renderer draws it. Only once a renderer has drawn; until then the
+     * chart's own drawing holds the tooltip at the block.
+     */
+    private renderTooltip;
+    /** What the plot shows, in a sentence, which describes the plot. */
+    private renderSummary;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-spatial-treemap': HelixHeadlessSpatialTreemap;
+    }
+}
+export {};