@fusion.dev/helix-headless 0.218.0 → 0.220.0

package/dist/spatial-bar-chart/bars.js

@@ -1,4 +1,4 @@
-import { solid, ticks } from '@fusion.dev/helix-core';
+import { depthOrder, pathData, 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;
@@ -12,50 +12,125 @@ const named = (count, labels, nearest = false) => {
         ticks: labels.map((_, at) => at),
     };
 };
-export const barsOf = (rows, columns) => {
+export const barsOf = (rows, columns, stacked = false, toneOf = () => undefined) => {
     const series = columns.map((column) => rows.find((row) => row.cells[column])?.cells[column]?.name ?? '');
     const cells = [];
     const values = [];
+    const reached = [];
     rows.forEach((row, at) => {
+        let [above, below] = [0, 0];
         columns.forEach((column, depth) => {
             const value = row.cells[column]?.value;
             const read = Number.isFinite(value) ? value : undefined;
+            let from = stacked ? above : 0;
             if (read !== undefined) {
                 values.push(read);
+                if (stacked) {
+                    from = read < 0 ? below : above;
+                    if (read < 0) {
+                        below += read;
+                    }
+                    else {
+                        above += read;
+                    }
+                }
+                reached.push(from + read);
             }
-            cells.push({ across: at, column, depth, label: row.label, row: at, value: read });
+            const lane = stacked ? 0 : depth;
+            const tone = toneOf(at, depth);
+            cells.push({
+                across: at,
+                column,
+                depth,
+                from,
+                label: row.label,
+                lane,
+                row: at,
+                ...(tone ? { tone } : {}),
+                value: read,
+            });
         });
     });
-    const [low, high] = [Math.min(0, ...values), Math.max(0, ...values)];
+    const lanes = stacked ? 1 : series.length;
+    const [low, high] = [Math.min(0, ...reached), Math.max(0, ...reached)];
     const range = low === high ? [0, 1] : niceRange(low, high);
-    const longest = Math.max(rows.length, series.length, 1);
+    const longest = Math.max(rows.length, lanes, 1);
     return {
         axes: {
-            extent: [Math.max(rows.length, 1) / longest, HEIGHT, Math.max(series.length, 1) / longest],
+            extent: [Math.max(rows.length, 1) / longest, HEIGHT, Math.max(lanes, 1) / longest],
             x: named(rows.length, rows.map((row) => row.label)),
             y: { name: series.length === 1 ? (series[0] ?? '') : '', range, ticks: ticks(range) },
-            z: named(series.length, series.length === 1 ? [] : series, true),
+            z: named(lanes, lanes === 1 ? [] : series, true),
         },
         categories: rows.map((row) => row.label),
         cells,
+        lanes,
         readings: values.length,
         series,
+        stacked,
     };
 };
 const FOOTPRINT = 0.6;
-export const barsDrawn = (field, projection) => {
+const CLIMB = 15 / 72;
+const placesOf = (field, projection, layout) => {
+    const [ex, , ez] = field.axes.extent;
+    const [cos, sin] = projection.across;
+    const lined = layout !== 'grid';
+    const spread = lined ? Math.abs(cos) + Math.abs(sin) : 1;
+    const spacing = Math.min((2 * ex) / Math.max(field.categories.length, 1), (2 * ez) / Math.max(field.lanes, 1)) /
+        spread;
+    const origin = projection.at(0, 0, 0);
+    const rise = origin.y - projection.at(-sin, cos, 0).y;
+    const across = projection.at(cos, sin, 0).x - origin.x;
+    const climb = layout === 'diagonal' && rise > 0 ? ((field.climb ?? CLIMB) * across) / rise : 0;
+    return {
+        place: (cell) => {
+            const along = inBox(field.axes.x, cell.across) * ex;
+            const back = -inBox(field.axes.z, cell.lane) * ez + along * climb;
+            return lined
+                ? { x: along * cos - back * sin, y: along * sin + back * cos }
+                : { x: along, y: back };
+        },
+        spacing,
+    };
+};
+export const rowFits = (width, size) => size > 0 ? Math.max(1, Math.floor((width * FOOTPRINT) / size)) : 1;
+export const widthOf = (bar) => {
+    const xs = bar.corners.map((corner) => corner.x);
+    return Math.max(...xs) - Math.min(...xs);
+};
+export const climbing = (field, rise, length) => ({
+    ...field,
+    climb: length > 0 ? Math.min(CLIMB, rise / length) : CLIMB,
+});
+const ROW_TALL = 1.25;
+export const tallestTimes = (field, projection, bars) => {
+    const first = bars[0];
+    const fall = Math.abs(projection.at(0, 0, 1).y - projection.at(0, 0, 0).y);
+    const tallest = Math.max(0, ...bars.map((bar) => bar.height)) * fall;
+    if (!first || tallest <= 0) {
+        return Number.POSITIVE_INFINITY;
+    }
+    const length = (field.categories.length * widthOf(first)) / FOOTPRINT;
+    return (ROW_TALL * length) / tallest;
+};
+export const heightened = (field, times) => {
     const [ex, ey, ez] = field.axes.extent;
-    const spacing = Math.min((2 * ex) / Math.max(field.categories.length, 1), (2 * ez) / Math.max(field.series.length, 1));
-    const zero = inBox(field.axes.y, 0) * ey;
+    return { ...field, axes: { ...field.axes, extent: [ex, ey * times, ez] } };
+};
+export const barsDrawn = (field, projection, layout = 'grid', grown = () => 1) => {
+    const ey = field.axes.extent[1];
+    const { place, spacing } = placesOf(field, projection, layout);
     return field.cells.flatMap((cell, index) => {
-        if (cell.value === undefined) {
+        if (cell.value === undefined || (field.stacked && cell.value === 0)) {
             return [];
         }
-        const x = inBox(field.axes.x, cell.across) * ex;
-        const y = -inBox(field.axes.z, cell.depth) * ez;
-        const top = inBox(field.axes.y, cell.value) * ey;
-        const base = Math.min(zero, top);
-        const height = Math.abs(top - zero);
+        const { x, y } = place(cell);
+        const share = grown(cell);
+        const start = inBox(field.axes.y, cell.from * share) * ey;
+        const top = inBox(field.axes.y, (cell.from + cell.value) * share) * ey;
+        const base = Math.min(start, top);
+        const height = Math.abs(top - start);
         const lifted = {
             ...projection,
             at: (px, py, pz = 0) => projection.at(px, py, pz + base),
@@ -67,6 +142,108 @@ export const barsDrawn = (field, projection) => {
                 corners.push(lifted.at(cx, cy, 0), lifted.at(cx, cy, height));
             }
         }
-        return [{ corners, drawn: solid(lifted, 'block', x, y, width, height), height, index, x, y }];
+        return [
+            { base, corners, drawn: solid(lifted, 'block', x, y, width, height), height, index, x, y },
+        ];
+    });
+};
+export const paintOrder = (projection, bars) => {
+    const columns = new Map();
+    for (const bar of depthOrder(projection, bars)) {
+        const place = `${bar.x},${bar.y}`;
+        columns.set(place, [...(columns.get(place) ?? []), bar]);
+    }
+    return [...columns.values()].flatMap((column) => column.sort((one, two) => one.base - two.base));
+};
+const PLATE = 0.85;
+export const floorOf = (field, projection, layout = 'row') => {
+    const { place, spacing } = placesOf(field, projection, layout);
+    const floor = inBox(field.axes.y, 0) * field.axes.extent[1];
+    const half = (spacing * PLATE) / 2;
+    const seen = new Set();
+    return field.cells.flatMap((cell) => {
+        const key = `${cell.across} ${cell.lane}`;
+        if (seen.has(key)) {
+            return [];
+        }
+        seen.add(key);
+        const { x, y } = place(cell);
+        const corners = [
+            projection.at(x - half, y - half, floor),
+            projection.at(x + half, y - half, floor),
+            projection.at(x + half, y + half, floor),
+            projection.at(x - half, y + half, floor),
+        ];
+        const front = corners.reduce((low, one) => (one.y > low.y ? one : low));
+        return [{ across: cell.across, corners, d: pathData(corners), front }];
+    });
+};
+const NAME_WIDE = 0.58;
+export const namesOf = (field, plates, size) => {
+    const fronts = new Map();
+    for (const plate of plates) {
+        const kept = fronts.get(plate.across);
+        if (!kept || plate.front.y > kept.y) {
+            fronts.set(plate.across, plate.front);
+        }
+    }
+    const tones = new Map();
+    for (const cell of field.cells) {
+        if (cell.tone && cell.value !== undefined && !tones.has(cell.across)) {
+            tones.set(cell.across, cell.tone);
+        }
+    }
+    const all = field.categories.flatMap((text, across) => {
+        const front = fronts.get(across);
+        return front
+            ? [{ across, text, tone: tones.get(across), x: front.x, y: front.y + size * 1.1 }]
+            : [];
     });
+    const room = (name) => {
+        const half = (name.text.length * size * NAME_WIDE) / 2 + size * 0.4;
+        return [name.x - half, name.x + half];
+    };
+    const clear = (one, kept) => {
+        const [from, to] = room(one);
+        return kept.every((other) => {
+            const [left, right] = room(other);
+            return to <= left || from >= right;
+        });
+    };
+    const toned = all.filter((name) => name.tone);
+    const rest = all.filter((name) => !name.tone);
+    for (let step = 1; step <= Math.max(1, all.length); step++) {
+        const kept = toned.filter((name, at) => clear(name, toned.slice(0, at)));
+        let fits = true;
+        for (const name of rest) {
+            if (name.across % step !== 0) {
+                continue;
+            }
+            if (clear(name, kept)) {
+                kept.push(name);
+            }
+            else if (!clear(name, kept.filter((one) => one.tone))) {
+            }
+            else {
+                fits = false;
+                break;
+            }
+        }
+        if (fits) {
+            return kept.sort((one, other) => one.across - other.across);
+        }
+    }
+    return [];
+};
+const GROW = 1000;
+const STAGGER = 110;
+const SPREAD = 660;
+const stepOf = (categories) => categories > 1 ? Math.min(STAGGER, SPREAD / (categories - 1)) : 0;
+export const grownAt = (across, categories, elapsed) => {
+    const t = (elapsed - across * stepOf(categories)) / GROW;
+    if (t <= 0) {
+        return 0;
+    }
+    return t >= 1 ? 1 : 1 - (1 - t) ** 3;
 };
+export const growTime = (categories) => GROW + stepOf(categories) * Math.max(0, categories - 1);

package/dist/spatial-bar-chart/root/spatial-bar-chart-root.d.ts

@@ -13,6 +13,11 @@ declare const HelixHeadlessSpatialBarChart_base: typeof HelixElement & (new (...
  * depth, each as tall as its value from zero and colored by its series, so
  * one series is a single row of bars and several make a block of them.
  *
+ * **A cell's `data-tone` colors its own bar and writes its value above it**,
+ * such as `data-tone="primary"` on the one reading a chart is about, as on
+ * `Bar Chart`. The value is the cell's own text. Without a tone, a bar takes
+ * its series' color.
+ *
  * **The flat `Bar Chart` is read more exactly.** Measured, a reader judges
  * a 3D bar's value less closely than a flat one's, and a bar can stand
  * behind another. Use this one where the shape across two sets of names
@@ -79,6 +84,8 @@ declare const HelixHeadlessSpatialBarChart_base: typeof HelixElement & (new (...
  * @csspart empty - The words when the table has no readings: the `empty` slot, falling back to `empty-text`.
  * @csspart face - One face of a bar 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 floor - One place on the floor of a `row`, under a bar or where one would stand, drawn as its outline.
+ * @csspart glow - The outline of a bar whose cell names a tone, blurred by 8 CSS pixels and painted under the bar, with no fill until a stylesheet gives it one: a soft glow in the bar's tone.
  * @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 bar the keys moved to. Hide it visually.
  * @csspart loading - The words while `loading` is set and there are no readings.
@@ -90,7 +97,7 @@ declare const HelixHeadlessSpatialBarChart_base: typeof HelixElement & (new (...
  * @csspart summary - The number of bars, series, and categories, and the range of values, 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`, a page of them at a time past a few hundred. Hide it visually.
  * @csspart table-pages - Which readings a page of the `table` holds, and the buttons that show the previous and the next page, rendered only while it holds a page. Hide it visually.
- * @csspart tick - A category's or a series' name, or a value at a tick, along its edge of the box, in the chart's own drawing.
+ * @csspart tick - A category's or a series' name, or a value at a tick, along its edge of the box, or a category's name under its place in a `row`, in the chart's own drawing.
  * @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`.
@@ -107,8 +114,16 @@ declare const HelixHeadlessSpatialBarChart_base: typeof HelixElement & (new (...
  * @csspart tooltip-surface-right - The bubble while it is right of the reading. Set alongside `tooltip-surface`.
  * @csspart tooltip-surface-top - The bubble while it is above the reading. Set alongside `tooltip-surface`.
  * @csspart tooltip-value - A column's value inside the tooltip.
+ * @csspart value - The value of a bar whose cell names a tone, written above it in the chart's own drawing.
  *
- * @cssproperty --spatial-bar-chart-shade - How far a bar'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.
+ * @cssproperty --spatial-bar-chart-shade -How far a bar'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.
+ * @cssproperty --spatial-bar-chart-tone-accent - The color of a bar whose cell says `data-tone="accent"`.
+ * @cssproperty --spatial-bar-chart-tone-danger - The color of a bar whose cell says `data-tone="danger"`.
+ * @cssproperty --spatial-bar-chart-tone-info - The color of a bar whose cell says `data-tone="info"`.
+ * @cssproperty --spatial-bar-chart-tone-muted - The color of a bar whose cell says `data-tone="muted"`.
+ * @cssproperty --spatial-bar-chart-tone-primary - The color of a bar whose cell says `data-tone="primary"`. A tone with no property of its own falls back to the bar's series color, and the same holds for a name you define.
+ * @cssproperty --spatial-bar-chart-tone-success - The color of a bar whose cell says `data-tone="success"`.
+ * @cssproperty --spatial-bar-chart-tone-warning - The color of a bar whose cell says `data-tone="warning"`.
  *
  * @cssstate active - While a bar is shown, under the pointer or the keys.
  * @cssstate drawn - While a renderer has drawn the bars, and the chart's own drawing is hidden.
@@ -122,8 +137,32 @@ export declare class HelixHeadlessSpatialBarChart extends HelixHeadlessSpatialBa
      */
     static words: 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
+     * Grows the bars up from the floor the first time the chart comes into
+     * view with readings, each category a little after the one before it, so
+     * the drawing arrives the way a page's own picture does. The growth is
+     * fast at first, slows to rest, and never passes a bar's value.
+     *
+     * Under `prefers-reduced-motion`, or where the page has paused its motion
+     * through `pauseMotion` or `Motion Toggle`, the bars stand at their height
+     * from the start. A later table draws the bars it already had at their
+     * height, and grows the bars it adds, each from the floor, so a reading that
+     * arrives while the chart is in view arrives the same way.
+     */
+    grow: boolean;
+    /**
+     * Grows the bars again each time the chart comes back into view after it
+     * left it, as a pane does when it is opened again, where `grow` alone grows
+     * them the first time only. Only a chart that grows takes it.
+     *
+     * While it is out of view the bars stand at the floor, so the first frame
+     * after it returns is the start of the growth and never a flash at full
+     * height.
+     */
+    growAgain: boolean;
+    /**
+     * Draws no box: no edges, grid, numbers, or names, and in a `row` no
+     * floor, 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.
      */
@@ -135,12 +174,57 @@ export declare class HelixHeadlessSpatialBarChart extends HelixHeadlessSpatialBa
     openLabel: string;
     /** The plot's name where the chart has none: no `aria-label`, `label`, or table caption. */
     plotLabel: string;
+    /**
+     * Stacks a category's series into one column, each block standing on the
+     * ones before it, so the column is as tall as the category's total, as a
+     * flat `Bar Chart` stacks them.
+     *
+     * Absent stands the series one behind another in depth. Stacked, every
+     * series stands in the front row, so none hides another, and the parts of
+     * one total read together. A negative reading hangs below zero on the
+     * negatives before it. The scale fits the stacks.
+     */
+    stacked: boolean;
     /**
      * The `summary` part's sentence. `{count}`, `{series}`, and `{categories}`
      * are the number of bars, series, and categories, written in the locale,
      * and `{low}` and `{high}` the lowest and the highest value.
      */
     summaryLabel: string;
+    /**
+     * How the bars stand.
+     *
+     * Unset, they stand on a grid of categories across and series in depth,
+     * in a box the camera looks at from a corner, so the grid recedes at an
+     * angle. `row` lays the categories in a straight line across the page and
+     * turns each bar to the camera, showing its top and two sides, for one row
+     * of readings in a small space such as a pane: turning the view turns each
+     * bar where it stands, and the row stays level. It is the chart's own
+     * drawing that lays the row: a renderer connected through
+     * `@fusion.dev/helix-plot` stands the bars on the grid.
+     *
+     * `diagonal` is the same row climbing to the right as it recedes, each
+     * place a step further back than the one before, as a row of days on a
+     * product's page is drawn: the row rises one part in five across the page
+     * from any turn, and its floor and names climb with it. A row whose bars
+     * have a size climbs at most a quarter of the plot's height, so the bars
+     * of a long row keep theirs.
+     *
+     * **A row draws its floor in place of a box**: each place as an outline a
+     * little wider than its bar, and each category's name under it, as many
+     * names as fit without touching. A name whose bar names a tone is written
+     * first, in that tone. `no-box` leaves the floor and the names out.
+     *
+     * **A `column-gap` on the `fallback` part gives a row's bars one width**,
+     * which the styled tier sets from `--spatial-bar-chart-bar-size`: one bar
+     * stands as wide as each of twenty, the row is as long as its bars and
+     * centered, the tallest bar stands as high as the plot has room for and
+     * no taller than the row is long and a quarter again, so one bar stands
+     * as a block, and `fits` says how many bars the plot holds, so a page
+     * can give it the latest of a longer table. It is read when the plot's
+     * size changes.
+     */
+    variant?: 'diagonal' | 'row';
     /** Whether a renderer has drawn the bars, 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. */
@@ -153,6 +237,34 @@ export declare class HelixHeadlessSpatialBarChart extends HelixHeadlessSpatialBa
     private last;
     /** The bar the keys rested on last, so a change of it can be told. */
     private told;
+    /**
+     * The size of the box the chart's own drawing fills, its font size, and
+     * the bar size the stylesheet asks for, in CSS pixels, once measured: the
+     * names and values are written at that size whatever the drawing's scale.
+     */
+    private room;
+    /** Measures the box the chart's own drawing fills. */
+    private sizes;
+    /**
+     * How far the bars have grown in: waiting to be seen, growing since a
+     * moment, or `undefined` once they stand at their height. `grew` says the
+     * first table has been drawn, so a later one is not grown again.
+     */
+    private growth;
+    private grew;
+    /**
+     * The bars a later table added, by category label, each growing from the
+     * floor: when it started, and its place among the bars that came with it, so
+     * several arriving together follow one another as the first table's do. A
+     * bar leaves the map once it stands.
+     */
+    private readonly fresh;
+    /** The categories of the table drawn last, so a later table's new ones are known. */
+    private drawnLabels;
+    /** Watches for the chart to leave the view, after which `grow-again` has it grow in once more. */
+    private gone;
+    /** Watches for the chart to come into view, which starts the bars growing. */
+    private seen;
     /** Carries a host `aria-labelledby` and `aria-describedby` to the plot. */
     protected readonly aria: AriaForwardController;
     /**
@@ -160,7 +272,7 @@ export declare class HelixHeadlessSpatialBarChart extends HelixHeadlessSpatialBa
      * column a series.** A renderer reads it.
      */
     get field(): BarField;
-    /** The field last read, and the rows and columns it was read from. */
+    /** The field last read, and the rows, columns, and series it was read from. */
     private memo;
     /** The bar the keys or the pointer rest on, as its place in `field.cells`, or `-1`. */
     get active(): number;
@@ -194,6 +306,36 @@ export declare class HelixHeadlessSpatialBarChart extends HelixHeadlessSpatialBa
      * the server calls this one.
      */
     protected willUpdate(changed: PropertyValues<this>): void;
+    /** Draws each frame until the bars a later table added stand. */
+    private followFresh;
+    disconnectedCallback(): void;
+    /** The element the size observer watches, so a drawing drawn again is watched again. */
+    private measured;
+    /** Watches the box the chart's own drawing fills, and keeps its size and font size. */
+    private measure;
+    /**
+     * How many categories a `row` or a `diagonal` has room for across the
+     * plot at its bar size, measured as it is read, or
+     * `undefined` where there is no row, no bar size, or nothing drawn to
+     * measure. A page with a longer table gives the chart its latest that
+     * many rows, and says so.
+     */
+    get fits(): number | undefined;
+    /**
+     * A row with a bar size of its own: how many of the drawing's units make a
+     * pixel, so each bar is as wide as asked, and the field with its value axis
+     * as tall as fills the plot's height with the names and the value. Where
+     * the row is too long for the plot, its bars narrow until it fits.
+     */
+    private sized;
+    /** Starts the bars growing once the chart comes into view, and draws each frame until they stand. */
+    private watchGrowth;
+    /**
+     * Under `grow-again`, waits for the chart to leave the view, then puts the
+     * bars back at the floor and waits to be seen, so growing again starts from
+     * the same place the first time did.
+     */
+    private watchExit;
     connectedCallback(): void;
     protected updated(changed: PropertyValues): void;
     /**
@@ -222,7 +364,7 @@ export declare class HelixHeadlessSpatialBarChart extends HelixHeadlessSpatialBa
      * drawing, until a renderer has drawn and where none is connected.
      */
     private renderFallback;
-    /** One bar, its faces in its series' color, each shaded by which way it faces. */
+    /** One bar, its faces in its tone's color or its series', each shaded by which way it faces. */
     private renderBar;
     /** The readout: the bar's category, series, and value in words, once the keys have moved to one. */
     private renderLive;