@fusion.dev/helix-headless 0.23.0 → 0.24.0

package/dist/announcement/root/announcement-root.d.ts

@@ -46,12 +46,26 @@ export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement
      * Which color the band wears.
      *
      * Paint only: unlike `Callout`, no value here draws a mark, changes the label,
-     * or moves the live region off polite. The set matches `Tag`'s. `neutral` is
-     * the resting value, said out loud so a consumer can put a band back to it
-     * from markup, and `surface` is the one value that is not a color: it lifts
-     * the band onto the surface step instead of the sunken one.
+     * or moves the live region off polite. `neutral` is the resting value, said
+     * out loud so a consumer can put a band back to it from markup.
+     *
+     * **The set is `Tag`'s and `Badge`'s, and now actually is.** This doc claimed
+     * to match `Tag` while differing from it in both directions: it carried
+     * `surface`, which `Tag` does not, and lacked `accent`, which `Tag` has. Three
+     * components saying what a thing means, in three vocabularies, one of which
+     * described itself as a fourth.
+     *
+     * `accent` is the second emphasis, a rotation off the brand seed rather than a
+     * color of its own, so it stays in relation when somebody rethemes. `primary`
+     * is the seed itself.
+     *
+     * **`surface` was never a color and has moved to `separation`**, which is the
+     * axis that owns where a box sits relative to the page. It said the band rode
+     * the surface step instead of the sunken one, which is an elevation, and a
+     * band can be `info` and elevated at once: two values true together are two
+     * axes, which is the test the registry answers to.
      */
-    tone?: 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'surface' | 'warning';
+    tone?: 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     /**

package/dist/area-chart/index.d.ts

@@ -0,0 +1 @@
+export * from './root/area-chart-root.js';

package/dist/area-chart/index.js

@@ -0,0 +1 @@
+export * from './root/area-chart-root.js';

package/dist/area-chart/root/area-chart-root.d.ts

@@ -0,0 +1,182 @@
+import { type Curve, HelixElement, type Row } from '@fusion.dev/helix-core';
+import { nothing, type TemplateResult } from 'lit';
+import '../../tooltip/index.js';
+/** The table as parts of a total: which columns, what each holds, and the running sums. */
+export interface AreaStack {
+    /** The table's columns that hold numbers, by their place among its cells. */
+    columns: number[];
+    /** Each column's running sum at each reading, the top edge of its band. */
+    layers: number[][];
+    /** Each column's heading. */
+    names: string[];
+    /** Every reading's total. */
+    totals: number[];
+    /** Each column's own reading, not yet summed. */
+    values: number[][];
+}
+declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
+/**
+ * @summary How a total is made up over time, as bands stacked on one another.
+ *
+ * @description
+ * The chart for a composition: every column of the table is a part, the parts
+ * sum to the whole at each reading, and the top edge is that whole. What a line
+ * chart of the same table cannot show is the share, which here is the
+ * thickness of a band.
+ *
+ * **Not `Line Chart` with `area`.** That washes each series from the floor on
+ * its own, so the series overlap; this adds them. Reach for `Line Chart` when
+ * the question is how each series moved, and for this when it is how the whole
+ * is made up.
+ *
+ * **It measures from zero, always**, which is `BarChart`'s rule and for the same
+ * reason: a band's thickness *is* its value, so a range that starts anywhere
+ * else draws every part in proportion to nothing. `LineChart` measures from its
+ * own range because a line claims a position; a band claims an amount.
+ *
+ * **Straight between readings unless asked otherwise.** A band's top edge is a
+ * sum, and a curve fitted through one sum can pass under the curve fitted
+ * through the sum beneath it, so a smoothed stack can draw a part as less than
+ * nothing between two readings. Straight segments between ordered points stay
+ * ordered. `curve="smooth"` is there for a stack that is read as a shape.
+ *
+ * **`share` draws each reading as a hundred percent**, so the bands are the
+ * parts' shares and the top edge is flat. It answers "which part grew" where
+ * the default answers "did the whole grow".
+ *
+ * **What a reader without the picture is told is the total and the share**, not
+ * every band in turn. The table beside the chart already reads out every
+ * number; what the drawing adds is the composition, so the summary says the
+ * latest reading's total and each part's share of it. The drawing itself is
+ * `aria-hidden`.
+ *
+ * Every numeric column is a part. A table that carries its own total column
+ * would count it twice, so leave it out of the table the chart reads.
+ * A negative reading is drawn as none: a part of a whole cannot be less than
+ * nothing, and a band that folded under its neighbor would say it was.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category charts
+ * @aliases Stacked Area Chart, Composition Chart, Stream Chart
+ * @documentation https://helix.fusion.dev/components/area-chart
+ *
+ * @csspart area - One part's band.
+ * @csspart baseline - The rule at zero, which is the floor of the drawing.
+ * @csspart gridline - One rule across the plot, under `gridlines`.
+ * @csspart guide - A rule down the reading a pointer is resting on.
+ * @csspart label - One reading's name.
+ * @csspart labels - The row of reading names.
+ * @csspart line - The top edge of one part's band.
+ * @csspart mark - The invisible point the tooltip is anchored to.
+ * @csspart plot - The drawing.
+ * @csspart summary - The total and the shares at the latest reading, for a reader who cannot see the bands.
+ * @csspart svg - The drawing surface the bands sit on.
+ * @csspart tooltip - The bubble, forwarded from `Tooltip`.
+ * @csspart tooltip-anchor - The `Tooltip` element itself.
+ * @csspart tooltip-cell - One column's name and value inside the tooltip.
+ * @csspart tooltip-label - The reading's own name inside the tooltip.
+ * @csspart tooltip-name - A column's name inside the tooltip.
+ * @csspart tooltip-value - A column's value inside the tooltip.
+ */
+export declare class HelixHeadlessAreaChart extends HelixHeadlessAreaChart_base {
+    /**
+     * How a band's edge gets from one reading to the next.
+     *
+     * Absent is `straight`, for the reason the class doc gives, and absent rather
+     * than defaulted because a reflecting property with a default writes its
+     * attribute onto every host, including the ones nobody configured.
+     */
+    curve?: Curve;
+    /**
+     * Which rules are drawn across the plot, if any.
+     *
+     * The same three values `LineChart` takes, with the same fallback: a bare
+     * `gridlines`, or anything unrecognized, rules the levels. Drawn over the bands
+     * rather than under them, because the bands are opaque and a rule under one is
+     * a rule nobody sees.
+     */
+    gridlines?: 'both' | 'category' | 'value';
+    /**
+     * Whether each reading is drawn as a hundred percent.
+     *
+     * Absent stacks the amounts, so the top edge is the total. Set, every reading
+     * fills the height and the bands are shares of it.
+     */
+    share: boolean;
+    /**
+     * What to call the sum of the parts, in the tooltip and the summary.
+     */
+    totalLabel: string;
+    private warnedAboutNegatives;
+    /** Whether the levels are ruled, which is every value but `category`. */
+    protected get rulesValue(): boolean;
+    /** Whether each reading is ruled, which only two values ask for. */
+    protected get rulesCategory(): boolean;
+    /**
+     * The table as parts of a total.
+     *
+     * Read from the rows rather than from `series`, because `series` drops a
+     * column's empty cells and so numbers each column's readings on its own: a
+     * blank in one column would slide every reading after it one place left, and
+     * a sum across columns would then add different months together. A blank is
+     * none of that part, which is what a blank in a breakdown means.
+     */
+    protected get stack(): AreaStack;
+    /**
+     * Says once that a reading was below zero, and what was drawn instead.
+     *
+     * Once per element, and in a browser only: a server render warning per
+     * request is one nobody can act on.
+     */
+    private warnNegative;
+    protected render(): TemplateResult;
+    /**
+     * The bands, behind a seam the styled tier can move.
+     *
+     * **Each band is drawn as everything beneath its top edge, the widest first.**
+     * The next one down then covers the lower part of it, so what shows of each is
+     * the strip between its edge and the edge below. Drawing each band as its own
+     * closed strip would need the edge below traced backwards, and a curve traced
+     * backwards is not guaranteed to be the same curve: the two would part by a
+     * hairline and the page would show through between every pair.
+     */
+    protected renderPlot(stack: AreaStack, count: number, x: (value: number) => number, y: (value: number) => number, domain: [number, number]): TemplateResult;
+    /** One band: everything under its top edge, and the edge itself. */
+    protected renderLayer(layer: number[], depth: number, x: (value: number) => number, y: (value: number) => number): TemplateResult | typeof nothing;
+    /** The grid, or nothing, at the levels `ticks` picks and through each reading. */
+    protected renderGridlines(x: (value: number) => number, y: (value: number) => number, domain: [number, number], count: number): TemplateResult | typeof nothing;
+    /**
+     * A rule down the reading the tooltip is about.
+     *
+     * Over the bands rather than under them, which is the one place this differs
+     * from `LineChart`: a line leaves the ground showing, and a stack does not.
+     */
+    protected renderGuide(x: (value: number) => number): TemplateResult | typeof nothing;
+    /** The reading names, as HTML beside the drawing so they do not scale with it. */
+    protected renderLabels(readings: string[]): TemplateResult;
+    /**
+     * What a reader who cannot see the bands is told.
+     *
+     * The latest reading, because that is the question a composition is asked
+     * first, and the table has every other one. Each part in the table's order,
+     * which is the legend's and the bands' order, so the words and the picture
+     * name the parts the same way round.
+     */
+    protected renderSummary(stack: AreaStack, rows: Row[]): TemplateResult;
+    /**
+     * The rows the tooltip reads, with each part's share and the total added.
+     *
+     * The total is a cell of its own with no number on it, so the tooltip gives it
+     * no series color: it is the sum of the bands, not a band.
+     */
+    private tallied;
+    /** What a pointer resting on a reading shows, above the top of the stack. */
+    protected renderTooltip(stack: AreaStack, y: (value: number) => number): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-area-chart': HelixHeadlessAreaChart;
+    }
+}
+export {};

package/dist/area-chart/root/area-chart-root.js

@@ -0,0 +1,205 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, drawTooltip, formatNumbers, HelixElement, linear, linePath, MixinChartSource, seriesIndex, ticks, } from '@fusion.dev/helix-core';
+import { html, nothing, svg } from 'lit';
+import { property } from 'lit/decorators.js';
+import '../../tooltip/index.js';
+const WIDTH = 100;
+const HEIGHT = 100;
+const percent = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0, style: 'percent' });
+let HelixHeadlessAreaChart = class HelixHeadlessAreaChart extends MixinChartSource(HelixElement) {
+    constructor() {
+        super(...arguments);
+        this.share = false;
+        this.totalLabel = 'Total';
+        this.warnedAboutNegatives = false;
+    }
+    get rulesValue() {
+        return this.gridlines !== undefined && this.gridlines !== 'category';
+    }
+    get rulesCategory() {
+        return this.gridlines === 'both' || this.gridlines === 'category';
+    }
+    get stack() {
+        const rows = this.sourceRows;
+        const width = Math.max(0, ...rows.map((row) => row.cells.length));
+        const columns = Array.from({ length: width }, (_, column) => column).filter((column) => rows.some((row) => row.cells[column]?.value !== undefined));
+        const values = columns.map((column) => rows.map((row) => {
+            const value = row.cells[column]?.value ?? 0;
+            if (value < 0) {
+                this.warnNegative();
+            }
+            return Math.max(0, value);
+        }));
+        const totals = rows.map((_, index) => values.reduce((sum, column) => sum + (column[index] ?? 0), 0));
+        const drawn = this.share
+            ? values.map((column) => column.map((value, index) => {
+                const total = totals[index] ?? 0;
+                return total > 0 ? value / total : 0;
+            }))
+            : values;
+        const layers = [];
+        let running = rows.map(() => 0);
+        for (const column of drawn) {
+            running = running.map((sum, index) => sum + (column[index] ?? 0));
+            layers.push(running);
+        }
+        return {
+            columns,
+            layers,
+            names: columns.map((column) => rows.find((row) => row.cells[column])?.cells[column]?.name ?? ''),
+            totals,
+            values,
+        };
+    }
+    warnNegative() {
+        if (this.warnedAboutNegatives || typeof window === 'undefined') {
+            return;
+        }
+        this.warnedAboutNegatives = true;
+        console.warn(`<${this.localName}> read a negative number and drew it as none. Its bands are parts of a ` +
+            'total, and a part cannot be less than nothing: a band drawn below its neighbor would say ' +
+            'the part took some of the one beneath it away. A series that crosses zero is a line, so ' +
+            'reach for `helix-line-chart`.');
+    }
+    render() {
+        const rows = this.sourceRows;
+        const stack = this.stack;
+        if (rows.length === 0 || stack.columns.length === 0) {
+            return html `<div id="helix-chart-plot" part="plot"></div>`;
+        }
+        const top = this.share ? 1 : Math.max(0, ...stack.totals);
+        const domain = [0, top > 0 ? top : 1];
+        const y = linear(domain, [HEIGHT, 0]);
+        const slot = WIDTH / rows.length;
+        const x = linear([0, Math.max(rows.length - 1, 1)], [slot / 2, WIDTH - slot / 2]);
+        return html `${this.renderPlot(stack, rows.length, x, y, domain)}
+      ${this.renderLabels(rows.map((row) => row.label))} ${this.renderSummary(stack, rows)}`;
+    }
+    renderPlot(stack, count, x, y, domain) {
+        const order = stack.layers.map((_, depth) => depth).reverse();
+        return html `<div aria-hidden="true" id="helix-chart-plot" part="plot">
+      <svg part="svg"
+        preserveAspectRatio="none"
+        viewBox="0 0 ${WIDTH} ${HEIGHT}"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        ${order.map((depth) => this.renderLayer(stack.layers[depth] ?? [], depth, x, y))}
+        ${this.renderGridlines(x, y, domain, count)}
+        <line part="baseline" x1="0" x2=${WIDTH} y1=${HEIGHT} y2=${HEIGHT} />
+        ${this.renderGuide(x)}
+      </svg>
+      ${this.renderTooltip(stack, y)}
+    </div>`;
+    }
+    renderLayer(layer, depth, x, y) {
+        const points = layer.map((value, index) => [x(index), y(value)]);
+        const path = linePath(points, this.curve ?? 'straight');
+        if (path === '') {
+            return nothing;
+        }
+        const index = seriesIndex(depth);
+        const first = points[0];
+        const last = points.at(-1);
+        const wash = `${path}L${last[0]},${HEIGHT}L${first[0]},${HEIGHT}Z`;
+        return svg `<path
+        d=${wash}
+        data-series=${index}
+        part="area"
+        style="--chart-series: var(--chart-series-${index})"
+      /><path
+        d=${path}
+        data-series=${index}
+        fill="none"
+        part="line"
+        style="--chart-series: var(--chart-series-${index})"
+      />`;
+    }
+    renderGridlines(x, y, domain, count) {
+        if (this.gridlines === undefined) {
+            return nothing;
+        }
+        const down = this.rulesCategory
+            ? Array.from({ length: count }, (_, index) => svg `<line part="gridline" x1=${x(index)} x2=${x(index)} y1="0" y2=${HEIGHT} />`)
+            : [];
+        const across = this.rulesValue
+            ? ticks(domain)
+                .filter((level) => level > domain[0])
+                .map((level) => svg `<line part="gridline" x1="0" x2=${WIDTH} y1=${y(level)} y2=${y(level)} />`)
+            : [];
+        return svg `${down}${across}`;
+    }
+    renderGuide(x) {
+        const at = this.pointer.at;
+        if (at < 0) {
+            return nothing;
+        }
+        return svg `<line part="guide" x1=${x(at)} x2=${x(at)} y1="0" y2=${HEIGHT} />`;
+    }
+    renderLabels(readings) {
+        return html `<div aria-hidden="true" part="labels">
+      ${readings.map((one) => html `<span part="label">${one}</span>`)}
+    </div>`;
+    }
+    renderSummary(stack, rows) {
+        const last = rows.length - 1;
+        const total = stack.totals[last] ?? 0;
+        const format = formatNumbers('');
+        const shares = stack.names.map((name, depth) => `${name} ${percent.format(total > 0 ? (stack.values[depth]?.[last] ?? 0) / total : 0)}`);
+        const named = this.named ? `${this.named}, ` : '';
+        return html `<p part="summary">
+      ${named}${rows[last]?.label ?? ''}: ${this.totalLabel} ${format(total)}; ${shares.join(', ')}.
+    </p>`;
+    }
+    tallied(rows, stack) {
+        const format = formatNumbers('');
+        return rows.map((row, index) => {
+            const total = stack.totals[index] ?? 0;
+            return {
+                ...row,
+                cells: [
+                    ...row.cells.map((cell, column) => this.share && cell.value !== undefined && stack.columns.includes(column) && total > 0
+                        ? {
+                            ...cell,
+                            text: `${cell.text} (${percent.format(Math.max(0, cell.value) / total)})`,
+                        }
+                        : cell),
+                    { name: this.totalLabel, text: format(total) },
+                ],
+            };
+        });
+    }
+    renderTooltip(stack, y) {
+        const at = this.pointer.at;
+        const rows = this.tallied(this.sourceRows, stack);
+        if (at < 0) {
+            return drawTooltip(rows, at, this.tag('tooltip'));
+        }
+        const slot = 100 / rows.length;
+        return drawTooltip(rows, at, this.tag('tooltip'), {
+            placement: 'top',
+            x: `${at * slot + slot / 2}%`,
+            y: `${y(stack.layers.at(-1)?.[at] ?? 0)}%`,
+        });
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessAreaChart.prototype, "curve", void 0);
+__decorate([
+    property()
+], HelixHeadlessAreaChart.prototype, "gridlines", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessAreaChart.prototype, "share", void 0);
+__decorate([
+    property({ attribute: 'total-label' })
+], HelixHeadlessAreaChart.prototype, "totalLabel", void 0);
+HelixHeadlessAreaChart = __decorate([
+    customElement('helix-headless-area-chart')
+], HelixHeadlessAreaChart);
+export { HelixHeadlessAreaChart };

package/dist/carousel/root/carousel-root.d.ts

@@ -350,6 +350,7 @@ export declare class HelixHeadlessCarousel extends HelixElement {
     /** Pauses without forgetting that the reader wanted it running. */
     private readonly pause;
     protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     /**
      * Puts each slide into the pane rendered for it.

package/dist/carousel/root/carousel-root.js

@@ -92,7 +92,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         return [...(this.renderRoot?.querySelectorAll?.('[part="slide"]') ?? [])];
     }
     get slides() {
-        return [...(this.children ?? [])].filter((child) => child instanceof HTMLElement);
+        return this.knownChildren.filter((child) => child instanceof HTMLElement);
     }
     goTo(index) {
         if (this.slides.length === 0) {
@@ -195,9 +195,16 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         if (!this.hasUpdated) {
             this.rotating = this.autoplay;
         }
+        if (changed.has('index')) {
+            this.showing = undefined;
+        }
         hostAria(this.internals, { label: this.label, role: 'group' });
         this.internals.ariaRoleDescription = 'carousel';
     }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
     updated(changed) {
         super.updated(changed);
         if (changed.has('index')) {
@@ -211,6 +218,12 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         this.assign();
     }
     assign() {
+        if (this.assignsByName) {
+            this.slides.forEach((slide, index) => {
+                this.route(slide, `slide-${index + 1}`);
+            });
+            return;
+        }
         const panes = this.renderRoot?.querySelectorAll?.('[part="slide"] slot');
         if (!panes) {
             return;
@@ -276,7 +289,10 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
             aria-roledescription="slide"
             aria-label=${`${index + 1} of ${this.slides.length}`}
           >
-            <slot @slotchange=${() => this.requestUpdate()}></slot>
+            <slot
+              name=${this.assignsByName ? `slide-${index + 1}` : nothing}
+              @slotchange=${() => this.requestUpdate()}
+            ></slot>
           </div>`)}
       </div>
       ${this.slides.length > 1

package/dist/chat/index.d.ts

@@ -1,3 +1,3 @@
 export { HelixHeadlessChatComposer } from './composer/chat-composer.js';
 export { HelixHeadlessChatMessage } from './message/chat-message.js';
-export { HelixHeadlessChat } from './root/chat-root.js';
+export { type ChatTurn, HelixHeadlessChat } from './root/chat-root.js';

package/dist/chat/message/chat-message.d.ts

@@ -1,5 +1,12 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * What a turn that did not send is called, where nobody said otherwise.
+ *
+ * Exported because the transcript says it too: a failure is announced in the
+ * words the turn shows, and two defaults for one phrase are two phrases.
+ */
+export declare const FAILED_LABEL = "Not sent";
 /**
  * @summary One turn in a conversation, and what has happened to it.
  *

package/dist/chat/message/chat-message.js

@@ -8,11 +8,12 @@ import { customElement, HelixElement, HelixSendEvent, hostAria, relativeTime, sl
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+export const FAILED_LABEL = 'Not sent';
 let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixElement {
     constructor() {
         super(...arguments);
         this.at = '';
-        this.failedLabel = 'Not sent';
+        this.failedLabel = FAILED_LABEL;
         this.locale = '';
         this.retryLabel = 'Try again';
         this.sendingLabel = 'Sending';