@fusion.dev/helix-headless 0.22.0 → 0.24.0

package/dist/object-inspector/root/object-inspector-root.js

@@ -0,0 +1,348 @@
+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 { CopyController, customElement, HelixElement, VirtualizeController, } from '@fusion.dev/helix-core';
+import { caretDown, caretRight } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import { html as staticHtml } from 'lit/static-html.js';
+import '../../copy-button/index.js';
+const branchy = (value) => value !== null && typeof value === 'object';
+const entries = (value) => Array.isArray(value) ? value.map((item, at) => [String(at), item]) : Object.entries(value);
+const child = (path, key) => `${path}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.defaultDepth = 1;
+        this.for = '';
+        this.label = '';
+        this.noCopy = false;
+        this.value = undefined;
+        this.windowed = false;
+        this.read = undefined;
+        this.opened = new Set();
+        this.active = 0;
+        this.revealing = false;
+        this.virtualize = new VirtualizeController(this, {
+            container: () => this.windowed ? this.renderRoot?.querySelector('[part="tree"]') : null,
+            count: () => this.rows.length,
+            estimate: () => 24,
+            measured: () => this.windowed,
+            rows: () => [...(this.renderRoot?.querySelectorAll('[part="row"]') ?? [])].map((element) => ({ element, index: Number(element.dataset.index) })),
+        });
+        this.rows = [];
+        this.copier = new CopyController(this);
+        this.handleKeydown = (event) => {
+            const rows = this.rows;
+            const row = rows[this.active];
+            if (!row) {
+                return;
+            }
+            if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'c') {
+                if (globalThis.getSelection?.()?.toString()) {
+                    return;
+                }
+                void this.copier.copy(this.copyable(row));
+                event.preventDefault();
+                return;
+            }
+            switch (event.key) {
+                case 'ArrowDown':
+                    this.move(this.active + 1);
+                    break;
+                case 'ArrowUp':
+                    this.move(this.active - 1);
+                    break;
+                case 'Home':
+                    this.move(0);
+                    break;
+                case 'End':
+                    this.move(rows.length - 1);
+                    break;
+                case 'ArrowRight':
+                    if (row.branch && !row.open) {
+                        this.toggle(row, true);
+                    }
+                    else if (row.open) {
+                        this.move(this.active + 1);
+                    }
+                    break;
+                case 'ArrowLeft':
+                    if (row.open) {
+                        this.toggle(row, false);
+                    }
+                    else {
+                        const parent = rows.findLastIndex((candidate, at) => at < this.active && candidate.depth === row.depth - 1);
+                        if (parent >= 0) {
+                            this.move(parent);
+                        }
+                    }
+                    break;
+                case 'Enter':
+                case ' ':
+                    if (row.branch) {
+                        this.toggle(row);
+                    }
+                    break;
+                default:
+                    return;
+            }
+            event.preventDefault();
+        };
+    }
+    get root() {
+        return this.value === undefined ? this.read : this.value;
+    }
+    flatten() {
+        const rows = [];
+        if (this.root === undefined) {
+            return rows;
+        }
+        const visit = (value, path, depth, position, siblings, key) => {
+            const branch = branchy(value);
+            const open = branch && this.opened.has(path);
+            rows.push({
+                branch,
+                depth,
+                open,
+                path,
+                position,
+                siblings,
+                value,
+                ...(key === undefined ? {} : { key }),
+            });
+            if (open) {
+                const children = entries(value);
+                children.forEach(([name, item], at) => {
+                    visit(item, child(path, name), depth + 1, at + 1, children.length, name);
+                });
+            }
+        };
+        visit(this.root, '', 0, 1, 1);
+        return rows;
+    }
+    seed() {
+        const opened = new Set();
+        const visit = (value, path, depth) => {
+            if (!branchy(value) || depth >= this.defaultDepth) {
+                return;
+            }
+            opened.add(path);
+            for (const [name, item] of entries(value)) {
+                visit(item, child(path, name), depth + 1);
+            }
+        };
+        visit(this.root, '', 0);
+        this.opened = opened;
+        this.active = 0;
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (this.loadedFor !== this.for &&
+            typeof this.ownerDocument?.getElementById === 'function' &&
+            !this.hydrating) {
+            this.loadedFor = this.for;
+            this.load();
+        }
+        if (changed.has('value') || changed.has('read') || changed.has('defaultDepth')) {
+            this.seed();
+        }
+        if (changed.has('value') ||
+            changed.has('read') ||
+            changed.has('opened') ||
+            changed.has('defaultDepth')) {
+            this.rows = this.flatten();
+            this.active = Math.min(this.active, Math.max(0, this.rows.length - 1));
+        }
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
+    updated(changed) {
+        super.updated?.(changed);
+        if (this.windowed) {
+            this.virtualize.measure();
+        }
+        if (this.revealing) {
+            this.revealing = false;
+            this.reveal();
+        }
+    }
+    load() {
+        const text = this.for === '' ? '' : (this.ownerDocument.getElementById(this.for)?.textContent ?? '');
+        try {
+            this.read = text.trim() === '' ? undefined : JSON.parse(text);
+        }
+        catch {
+            this.read = undefined;
+        }
+    }
+    reveal(attempts = 8) {
+        const tree = this.renderRoot?.querySelector('[part="tree"]');
+        const row = tree?.querySelector(`[data-index="${this.active}"]`);
+        if (row) {
+            row.scrollIntoView({ block: 'nearest' });
+            return;
+        }
+        const drawn = [...(tree?.querySelectorAll('[part="row"]') ?? [])];
+        const first = drawn[0];
+        const last = drawn.at(-1);
+        if (!tree || !this.windowed || !first || !last || attempts === 0) {
+            return;
+        }
+        const height = first.offsetHeight || 24;
+        const from = Number(this.active > Number(last.dataset.index) ? last.dataset.index : first.dataset.index);
+        tree.scrollTop += (this.active - from) * height;
+        this.virtualize.measure();
+        void this.updateComplete.then(() => this.reveal(attempts - 1));
+    }
+    copyable(row) {
+        if (!row) {
+            return '';
+        }
+        if (typeof row.value === 'string') {
+            return row.value;
+        }
+        return JSON.stringify(row.value, null, 2) ?? String(row.value);
+    }
+    toggle(row, open = !row.open) {
+        const opened = new Set(this.opened);
+        if (open) {
+            opened.add(row.path);
+        }
+        else {
+            opened.delete(row.path);
+        }
+        this.opened = opened;
+    }
+    move(to) {
+        const last = this.rows.length - 1;
+        this.active = Math.max(0, Math.min(to, last));
+        this.revealing = true;
+    }
+    handleRowClick(index, row) {
+        this.active = index;
+        if (row.branch) {
+            this.toggle(row);
+        }
+    }
+    renderValue(row) {
+        const { value } = row;
+        if (row.branch) {
+            const count = entries(value).length;
+            const array = Array.isArray(value);
+            const noun = array ? (count === 1 ? 'item' : 'items') : count === 1 ? 'key' : 'keys';
+            return html `<span part="summary">${array ? '[…]' : '{…}'}</span>
+        <span part="count">${`${count} ${noun}`}</span>`;
+        }
+        if (typeof value === 'string') {
+            return html `<span part="string">${JSON.stringify(value)}</span>`;
+        }
+        if (typeof value === 'number') {
+            return html `<span part="number">${String(value)}</span>`;
+        }
+        if (typeof value === 'boolean') {
+            return html `<span part="boolean">${String(value)}</span>`;
+        }
+        if (value === null) {
+            return html `<span part="null">null</span>`;
+        }
+        return html `<span part="string">${String(value)}</span>`;
+    }
+    renderRow(row, index) {
+        return html `<div
+      part="row"
+      role="treeitem"
+      id=${`row-${index}`}
+      data-index=${index}
+      ?data-active=${index === this.active}
+      aria-level=${row.depth + 1}
+      aria-posinset=${row.position}
+      aria-setsize=${row.siblings}
+      aria-expanded=${row.branch ? String(row.open) : nothing}
+      style=${`--object-inspector-level: ${row.depth}`}
+      @click=${() => this.handleRowClick(index, row)}
+    >
+      ${row.branch
+            ? html `<svg
+              part="toggle"
+              fill="currentColor"
+              viewBox=${(row.open ? caretDown : caretRight).viewBox}
+              aria-hidden="true"
+            >
+              ${unsafeSVG((row.open ? caretDown : caretRight).content)}
+            </svg>`
+            : nothing}${row.key === undefined ? nothing : html `<span part="key">${row.key}</span>: `}${this.renderValue(row)}
+    </div>`;
+    }
+    renderCopyButton(row) {
+        return staticHtml `<${this.tag('copy-button')}
+      part="copy"
+      exportparts="button: copy-button, mark: copy-mark, tooltip: copy-tooltip,
+        tooltip-arrow: copy-tooltip-arrow"
+      label=${row?.key === undefined ? 'Copy value' : `Copy ${row.key}`}
+      .value=${this.copyable(row)}
+    ></${this.tag('copy-button')}>`;
+    }
+    render() {
+        const rows = this.rows;
+        const { after, before, first, last } = this.windowed
+            ? this.virtualize.window
+            : { after: 0, before: 0, first: 0, last: rows.length };
+        const shown = rows.slice(first, last);
+        return html `${this.label ? html `<div part="header"><span part="label">${this.label}</span></div>` : nothing}
+      <div part="frame">
+        <div
+          part="tree"
+          role="tree"
+          tabindex="0"
+          ?data-scroller=${this.windowed}
+          aria-label=${this.label || 'Value'}
+          aria-activedescendant=${rows.length > 0 ? `row-${this.active}` : nothing}
+          @keydown=${this.handleKeydown}
+          @scroll=${() => this.virtualize.measure()}
+        >
+          ${this.windowed ? html `<div part="before" role="presentation" style="block-size: ${before}px"></div>` : nothing}
+          ${shown.map((row, at) => this.renderRow(row, first + at))}
+          ${this.windowed ? html `<div part="after" role="presentation" style="block-size: ${after}px"></div>` : nothing}
+        </div>
+        ${this.noCopy ? nothing : this.renderCopyButton(rows[this.active])}
+      </div>`;
+    }
+};
+__decorate([
+    property({ attribute: 'default-depth', type: Number })
+], HelixHeadlessObjectInspector.prototype, "defaultDepth", void 0);
+__decorate([
+    property()
+], HelixHeadlessObjectInspector.prototype, "for", void 0);
+__decorate([
+    property()
+], HelixHeadlessObjectInspector.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'no-copy', reflect: true, type: Boolean })
+], HelixHeadlessObjectInspector.prototype, "noCopy", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessObjectInspector.prototype, "value", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessObjectInspector.prototype, "windowed", void 0);
+__decorate([
+    state()
+], HelixHeadlessObjectInspector.prototype, "read", void 0);
+__decorate([
+    state()
+], HelixHeadlessObjectInspector.prototype, "opened", void 0);
+__decorate([
+    state()
+], HelixHeadlessObjectInspector.prototype, "active", void 0);
+HelixHeadlessObjectInspector = __decorate([
+    customElement('helix-headless-object-inspector')
+], HelixHeadlessObjectInspector);
+export { HelixHeadlessObjectInspector };

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

@@ -58,7 +58,8 @@ export declare class HelixHeadlessOutline extends HelixElement {
      */
     label: string;
     /**
-     * How far below the top of the window a heading counts as reached, in pixels.
+     * How far below the top of what scrolls a heading counts as reached, in
+     * pixels: the window, or the panel the sections scroll in.
      *
      * The reading line. A page with a sticky masthead sets this to its height, or
      * a little more: without it the current section changes as a heading slides
@@ -119,6 +120,20 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * measured against.
      */
     private get atEnd();
+    /** The element the page itself scrolls with, which `atEnd` explains. */
+    private get page();
+    /**
+     * What the sections scroll in: the nearest ancestor of the first one that
+     * scrolls, or the page when none does.
+     *
+     * **The window is not always what moves.** A contents rail beside a panel
+     * with its own scrollbar, which is a docs layout and every sandbox preview,
+     * measured the window. The window never scrolled, so it was always at its end
+     * and the last section was always current: the events example named `api`
+     * at rest with `install` on screen, a wheel over the panel changed nothing,
+     * and a press on `install` marked it for a moment and snapped back.
+     */
+    private get scroller();
     /** The frame a mark is already scheduled for, so a scroll asks for one. */
     private frame;
     /** Where a click said to go, while the page is still on its way there. */

package/dist/outline/root/outline-root.js

@@ -47,10 +47,10 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             const arrive = () => {
                 clearTimeout(this.landed);
                 this.landing = undefined;
-                globalThis.removeEventListener?.('scrollend', arrive);
+                globalThis.document?.removeEventListener('scrollend', arrive, true);
                 this.mark();
             };
-            globalThis.addEventListener?.('scrollend', arrive, { once: true });
+            globalThis.document?.addEventListener('scrollend', arrive, { capture: true, once: true });
             this.landed = setTimeout(arrive, 1200);
             if (this.behavior === 'auto') {
                 return;
@@ -97,7 +97,10 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         if (sections.length === 0) {
             return;
         }
-        const passed = sections.filter(({ target }) => target.getBoundingClientRect().top - this.offset <= 1);
+        const scroller = this.scroller;
+        const page = scroller === this.page;
+        const origin = page ? 0 : scroller.getBoundingClientRect().top;
+        const passed = sections.filter(({ target }) => target.getBoundingClientRect().top - origin - this.offset <= 1);
         const active = this.atEnd ? sections.at(-1) : (passed.at(-1) ?? sections[0]);
         this.markTo(active);
     }
@@ -117,12 +120,24 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         }
     }
     get atEnd() {
-        const doc = globalThis.document?.scrollingElement ?? globalThis.document?.documentElement;
-        if (!doc) {
-            return false;
-        }
+        const doc = this.scroller;
         return Math.ceil(doc.scrollTop + doc.clientHeight) >= doc.scrollHeight - 1;
     }
+    get page() {
+        const doc = globalThis.document;
+        return (doc.scrollingElement ?? doc.documentElement);
+    }
+    get scroller() {
+        const doc = globalThis.document;
+        const first = this.sections[0]?.target;
+        for (let node = first?.parentElement; node && node !== doc.body && node !== doc.documentElement; node = node.parentElement) {
+            const { overflowY } = getComputedStyle(node);
+            if (/auto|scroll|overlay/.test(overflowY) && node.scrollHeight > node.clientHeight) {
+                return node;
+            }
+        }
+        return this.page;
+    }
     reach() {
         for (const { target } of this.sections) {
             const element = target;
@@ -147,7 +162,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('click', this.handleClick);
-        globalThis.removeEventListener?.('scroll', this.handleScroll);
+        globalThis.document?.removeEventListener('scroll', this.handleScroll, true);
         if (this.frame !== 0) {
             globalThis.cancelAnimationFrame(this.frame);
             this.frame = 0;
@@ -162,7 +177,10 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('click', this.handleClick);
-        globalThis.addEventListener?.('scroll', this.handleScroll, { passive: true });
+        globalThis.document?.addEventListener('scroll', this.handleScroll, {
+            capture: true,
+            passive: true,
+        });
         if (this.hasUpdated) {
             this.watch();
             this.resize = new ResizeObserver(() => this.indicator.place());

package/dist/radio/group/radio-group.d.ts

@@ -36,6 +36,7 @@ declare const HelixHeadlessRadioGroup_base: (new (...args: any[]) => import("@fu
  *
  * @event {Event} change - Announced once the value has moved.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the answer changes, and cancelable.
+ * @event {HelixSelectEvent} helix-select - Fired when an answer is chosen. Dispatched by the radio and listened for here, because the group is what a consumer holds. Cancelable: refusing it takes the decision and nothing moves.
  * @event {Event} input - Announced once the value has moved.
  *
  * @csspart feedback - What is wrong with it.

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

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

package/dist/scatter-chart/index.js

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

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

@@ -0,0 +1,144 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type TemplateResult } from 'lit';
+import '../../tooltip/index.js';
+/** One row drawn as a point: which row, which series, and where, in percent of the plot. */
+export interface ScatterPoint {
+    depth: number;
+    row: number;
+    x: number;
+    y: number;
+}
+/** The table as the chart reads it: points, both ranges and what each axis is called. */
+export interface ScatterField {
+    points: ScatterPoint[];
+    /** Each series' readings as pairs, for the summary. */
+    pairs: Array<Array<[number, number]>>;
+    x: [number, number];
+    xName: string;
+    y: [number, number];
+    yNames: string[];
+}
+declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
+/**
+ * @summary Whether two measures move together, one point per row.
+ *
+ * @description
+ * The chart for a relation rather than a series. The table's first numeric
+ * column is measured across and every other numeric column is measured up, one
+ * point per row, so a table of countries with a column of income and a column
+ * of life expectancy draws one dot for each country. More numeric columns are
+ * more series against the same across, each in its own color.
+ *
+ * **Both axes are measured, so both are labeled.** A line chart's readings are
+ * named along the bottom and its values are read from the tooltip; here the
+ * horizontal position is itself a value, and a point with no scale under it says
+ * nothing about how far along it is. The ticks sit at round numbers and the
+ * range is widened to them, so the plot's edges are numbers a reader can name.
+ *
+ * **What a reader without the picture is told is how strongly the two relate**,
+ * because that is the question a scatter is drawn to answer and the one a table
+ * of the same numbers makes hardest to see. The summary gives each series'
+ * correlation coefficient and how many points it rests on; the table has every
+ * number, and the drawing is `aria-hidden`.
+ *
+ * **The points are elements, not shapes in the drawing.** The drawing stretches
+ * to its box, and a circle in a stretched space is an ellipse, so each point is
+ * a `<span>` placed by percentage over it, which is how `LineChart` draws its
+ * termini and for the same reason.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category charts
+ * @aliases Scatter Plot, XY Chart, Correlation Chart, Dot Plot
+ * @documentation https://helix.fusion.dev/components/scatter-chart
+ *
+ * @csspart gridline - One rule across the plot, under `gridlines`.
+ * @csspart mark - The invisible point the tooltip is anchored to.
+ * @csspart plot - The drawing.
+ * @csspart point - One row, as a point.
+ * @csspart summary - How strongly the measures relate, for a reader who cannot see the points.
+ * @csspart svg - The drawing surface the rules 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 row'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.
+ * @csspart x-axis - The levels measured across, under the plot.
+ * @csspart x-name - What is measured across.
+ * @csspart x-tick - One labeled level across. A part of its own rather than a shared `tick`, because `::part()` cannot tell which axis a tick is on.
+ * @csspart y-axis - The levels measured up, beside the plot.
+ * @csspart y-name - What is measured up.
+ * @csspart y-tick - One labeled level up.
+ *
+ * @cssproperty --chart-point-x - Where a point sits across, as a percentage. Written by the component.
+ * @cssproperty --chart-point-y - Where a point sits up, as a percentage from the top. Written by the component.
+ * @cssproperty --chart-tick - Where a tick sits along its axis, as a percentage. Written by the component.
+ */
+export declare class HelixHeadlessScatterChart extends HelixHeadlessScatterChart_base {
+    /**
+     * What to call the strength of the relation in the summary.
+     */
+    correlationLabel: string;
+    /**
+     * Which rules are drawn across the plot, if any.
+     *
+     * Both axes are measured, so the values name an axis rather than a role:
+     * `x` rules the levels across, `y` the levels up. A bare `gridlines`, or
+     * anything unrecognized, means `both`, since neither axis is the one a scatter
+     * is read along.
+     */
+    gridlines?: 'both' | 'x' | 'y';
+    /**
+     * What to call a row in the summary, which counts them.
+     */
+    pointsLabel: string;
+    /** The points as last drawn, which the pointer searches. */
+    private drawn;
+    /** The point a pointer is resting nearest, which the tooltip sits on. */
+    private nearest;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Whether the levels across are ruled. */
+    protected get rulesX(): boolean;
+    /** Whether the levels up are ruled. */
+    protected get rulesY(): boolean;
+    /**
+     * The table as points.
+     *
+     * Read from the rows rather than from `series`, because a point needs both of
+     * its numbers from the same row, and `series` numbers each column's readings
+     * on its own once a cell is blank. A row missing either number is not drawn:
+     * a point with one coordinate has nowhere to be.
+     */
+    protected get field(): ScatterField;
+    protected render(): TemplateResult;
+    /** The rules and the points, behind a seam the styled tier can move. */
+    protected renderPlot(field: ScatterField, along: (value: number) => number, up: (value: number) => number): TemplateResult;
+    /**
+     * What a reader who cannot see the points is told.
+     *
+     * One clause per series, each naming what is measured up against what is
+     * measured across, how many rows it rests on and its correlation, which is
+     * absent where there are fewer than three points or no spread to measure.
+     */
+    protected renderSummary(field: ScatterField): TemplateResult;
+    /** The row a pointer is resting on, over the point it is nearest. */
+    protected renderTooltip(): TemplateResult | typeof nothing;
+    /**
+     * The point a pointer is nearest, within reach.
+     *
+     * Measured in the plot's pixels rather than in percent, because the plot is
+     * rarely square and a percent across is a different distance from a percent
+     * up. A mouse or a pen only, as every chart here: a finger has no hover to
+     * rest on a point with.
+     */
+    private readonly handleMove;
+    private readonly handleLeave;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-scatter-chart': HelixHeadlessScatterChart;
+    }
+}
+export {};