@fusion.dev/helix-headless 0.0.0-dev

package/dist/kbd/root/kbd-root.js

@@ -0,0 +1,230 @@
+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, HelixElement, HelixShortcutEvent } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * How each name in a chord is drawn, per platform.
+ *
+ * Apple keyboards label their modifiers with glyphs and print no separator
+ * between them, so `⌘K` is the whole of it. Everywhere else the words are the
+ * label and the plus is part of the convention rather than prose. That is the
+ * one separator this component is willing to supply: the class docstring says
+ * a separator between keys is prose because it is "then" in a sequence and
+ * "plus" in a simultaneous press, and `keys` is only ever the second of those.
+ */
+const APPLE = {
+    alt: '⌥',
+    backspace: '⌫',
+    cmd: '⌘',
+    ctrl: '⌃',
+    del: '⌦',
+    down: '↓',
+    enter: '↵',
+    esc: 'Esc',
+    left: '←',
+    meta: '⌘',
+    mod: '⌘',
+    opt: '⌥',
+    right: '→',
+    shift: '⇧',
+    space: 'Space',
+    tab: '⇥',
+    up: '↑',
+};
+const ELSEWHERE = {
+    alt: 'Alt',
+    backspace: 'Backspace',
+    cmd: 'Win',
+    ctrl: 'Ctrl',
+    del: 'Del',
+    down: '↓',
+    enter: 'Enter',
+    esc: 'Esc',
+    left: '←',
+    meta: 'Win',
+    mod: 'Ctrl',
+    opt: 'Alt',
+    right: '→',
+    shift: 'Shift',
+    space: 'Space',
+    tab: 'Tab',
+    up: '↑',
+};
+/** Whether the keyboard in front of the reader labels its modifiers with glyphs. */
+const onApple = () => typeof navigator !== 'undefined' && /mac|iphone|ipad|ipod/i.test(navigator.userAgent);
+/**
+ * @summary A keyboard key or chord, set inline with text.
+ *
+ * @description
+ * Renders a real `<kbd>`, so the passage still means "press this" to anything
+ * reading the markup rather than only to a reader looking at it.
+ *
+ * **One key per element, with `keys` as the stated exception.** A *sequence* is
+ * several of these with the separator written between them as ordinary text,
+ * because that separator is prose: it is "then" in a sequence and "plus" in a
+ * simultaneous press, and a component that inserted one would have to guess
+ * which. `keys` cannot be guessing, since a chord written `mod+k` has said
+ * which it is.
+ *
+ * **`keys` exists because the glyphs were being typed by hand and were wrong.**
+ * A literal `⌘K` in a template tells a reader on Windows to press a key their
+ * keyboard does not have, and nothing catches it, a string being a string.
+ * Given `mod` this renders `⌘K` on Apple and `Ctrl+K` everywhere else.
+ *
+ * **`within` is what binds it, and it is absent by default.** Without it this
+ * draws a key and listens for nothing, which is what every existing use of this
+ * component wants. The two values are the two honest lifetimes:
+ *
+ * - `control` listens within the element's own parent, which is the case this
+ *   is mostly for: a hint sitting inside the control it belongs to, where the
+ *   shortcut should work while that control has focus and stop existing when
+ *   the control does.
+ * - `document` listens on the document, for a chord that works from anywhere.
+ *
+ * *Corrected 25 Aug 2026: this said `scope`, `self` and `global` until then,
+ * naming a property that has never existed under that name. The rename is
+ * explained on the property itself, twenty lines below, and this paragraph
+ * above it went on teaching the old one. A reader who trusted the class doc
+ * wrote an attribute that binds nothing, which is also what an unset `within`
+ * does, so nothing about the mistake looked like one.*
+ *
+ * **A hidden `kbd` is a dead shortcut, and that is the point rather than a
+ * trap.** Binding here ties the key to its own advertisement, so a hint that is
+ * not rendered is a shortcut that is not offered. A chord that must outlive its
+ * label is a chord whose owner is not a label: give it to whatever owns the
+ * action and let this element only describe it.
+ *
+ * Nothing binds until this upgrades, so a shortcut is not available in the
+ * moments before hydration.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category typography
+ * @aliases Key, Shortcut, Hotkey
+ * @documentation https://helix.fusion.dev/components/kbd
+ *
+ * @slot - The key's label, where `keys` is not set.
+ *
+ * @event {HelixShortcutEvent} helix-shortcut - Fired when the chord is pressed, and cancelable.
+ *
+ * @csspart kbd - The key.
+ */
+let HelixHeadlessKbd = class HelixHeadlessKbd extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * The chord, written plainly: `mod+k`, `shift+?`, `/`.
+         *
+         * `mod` is the platform's own command modifier, which is the reason to write
+         * a chord here rather than a glyph: it is the one token whose right answer
+         * differs per reader.
+         */
+        this.keys = '';
+        this.handleKeydown = (event) => {
+            const press = event;
+            /* Mid-composition is not a chord. An IME sends keystrokes that belong to
+               the text being composed, and taking one is how a shortcut eats a
+               character the reader was trying to type. */
+            if (press.isComposing) {
+                return;
+            }
+            if (!this.matches_(press)) {
+                return;
+            }
+            /* Announced before it is consumed, so a consumer can refuse it: the key
+               goes on to whatever would have had it wherever this is prevented. */
+            const shortcut = new HelixShortcutEvent({ keys: this.keys });
+            this.dispatchEvent(shortcut);
+            if (!shortcut.defaultPrevented) {
+                press.preventDefault();
+            }
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.listen();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.deafen();
+    }
+    updated(changed) {
+        super.updated(changed);
+        /* The target changes with `within` and the chord changes with `keys`, and
+           the second matters as much as the first: a listener holding the old chord
+           answers to a key the element no longer advertises. */
+        if (changed.has('within') || changed.has('keys')) {
+            this.deafen();
+            this.listen();
+        }
+    }
+    /** The chord as this reader's keyboard labels it. */
+    get label() {
+        const names = onApple() ? APPLE : ELSEWHERE;
+        const parts = this.keys
+            .split('+')
+            .map((part) => part.trim())
+            .filter((part) => part !== '')
+            .map((part) => names[part.toLowerCase()] ?? (part.length === 1 ? part.toUpperCase() : part));
+        return parts.join(onApple() ? '' : '+');
+    }
+    listen() {
+        if (!this.within || this.keys === '') {
+            return;
+        }
+        const target = this.within === 'document' ? this.ownerDocument : this.parentElement;
+        if (!target) {
+            return;
+        }
+        this.listening = target;
+        target.addEventListener('keydown', this.handleKeydown);
+    }
+    deafen() {
+        this.listening?.removeEventListener('keydown', this.handleKeydown);
+        this.listening = undefined;
+    }
+    /** Whether a press is this chord, modifiers and all. */
+    matches_(press) {
+        const parts = this.keys
+            .split('+')
+            .map((part) => part.trim().toLowerCase())
+            .filter((part) => part !== '');
+        if (parts.length === 0) {
+            return false;
+        }
+        const wanted = parts[parts.length - 1] ?? '';
+        const modifiers = new Set(parts.slice(0, -1));
+        const mod = onApple() ? press.metaKey : press.ctrlKey;
+        /* Every modifier is checked in both directions, so `mod+k` is not answered
+           by `shift+mod+k`: a chord a reader did not press is a chord that should
+           go to whatever did want it. */
+        return (press.key.toLowerCase() === wanted &&
+            (modifiers.has('mod') ? mod : true) &&
+            (modifiers.has('shift') ? press.shiftKey : !press.shiftKey) &&
+            (modifiers.has('alt') || modifiers.has('opt') ? press.altKey : !press.altKey) &&
+            (modifiers.has('ctrl') ? press.ctrlKey : modifiers.has('mod') ? true : !press.ctrlKey) &&
+            (modifiers.has('cmd') || modifiers.has('meta')
+                ? press.metaKey
+                : modifiers.has('mod')
+                    ? true
+                    : !press.metaKey));
+    }
+    render() {
+        return html `<kbd part="kbd">${this.keys === '' ? html `<slot></slot>` : this.label}</kbd>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessKbd.prototype, "keys", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessKbd.prototype, "within", void 0);
+HelixHeadlessKbd = __decorate([
+    customElement('helix-headless-kbd')
+], HelixHeadlessKbd);
+export { HelixHeadlessKbd };

package/dist/legend/index.d.ts

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

package/dist/legend/index.js

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

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

@@ -0,0 +1,83 @@
+import { HelixElement, SourceController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary The names a chart draws, each beside the color it is drawn in.
+ *
+ * @description
+ * A legend is a list, so it is a list: not part of a chart, and shared by
+ * whichever of them needs one. It takes its entries from the same table the
+ * chart reads, through `for`, so the two cannot disagree about how many series
+ * there are or what they are called.
+ *
+ * `entries` picks which way to read that table, and the two ways are the two
+ * shapes a chart comes in. `series` is one entry per data column, named by the
+ * header row, which is a line or a bar chart. `categories` is one entry per
+ * body row, named by its row header, which is a donut: its slices are the rows,
+ * and it has no axis to write their names along.
+ *
+ * **The table is resolved on the client and there is no server pass.** `for` is
+ * an id and resolving it wants a document, which the server render does not
+ * have, so a legend ships empty and fills in on hydration. The table itself is
+ * ordinary markup and is served whole, so nothing is missing from the page
+ * before then, only from this list.
+ *
+ * The table is watched, because a legend that goes stale when its data changes
+ * is a legend that has to be told, and nothing else in the page would know to
+ * tell it.
+ *
+ * **Not hidden from a screen reader, though the mapping it draws is a color
+ * one.** The argument for hiding it is real: the colours mean nothing to a
+ * reader who cannot see them, and the names are already in the table. It stays
+ * because the cost of being wrong runs one way. A duplicated list of three
+ * words is noise; a consumer who took the table out of the accessibility tree
+ * and then found the legend hidden too has a chart nobody can read, and neither
+ * decision announces itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category charts
+ * @aliases Key, Series Key
+ * @documentation https://helix.fusion.dev/components/legend
+ *
+ * @csspart entry - One name and its swatch.
+ * @csspart list - The list itself.
+ * @csspart name - One series name.
+ * @csspart swatch - The color a series is drawn in.
+ */
+export declare class HelixHeadlessLegend extends HelixElement {
+    /**
+     * Which way to read the table.
+     *
+     * Absent is `series`, one entry per data column. `categories` reads one entry
+     * per body row instead, for a donut, whose slices are the rows.
+     */
+    entries?: 'categories' | 'series';
+    /**
+     * The id of the table to take the names from.
+     *
+     * Resolved through `getRootNode()`, so a legend inside another component's
+     * shadow root names a table in that root rather than in the document.
+     *
+     * **In React this arrives as a property and not as an attribute**, the way
+     * `Tooltip.for` does, so it does not reflect and nothing styles on it.
+     */
+    for: string;
+    protected readonly source: SourceController;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /**
+     * The names, in the order the chart will draw them.
+     *
+     * `protected` rather than private because the styled tier has to match a
+     * per-series treatment against them, the way `BarChart` matches `outlined` and
+     * `subtle` against the headings its table gives. A legend keys a chart, so the
+     * two answer the same question about the same series, and the tier that paints
+     * cannot do that without knowing which entry is which.
+     */
+    protected names(): string[];
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-legend': HelixHeadlessLegend;
+    }
+}

package/dist/legend/root/legend-root.js

@@ -0,0 +1,125 @@
+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, HelixElement, SourceController } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+/** How many colours the series palette has, and so where it starts over. */
+const PALETTE = 24;
+/**
+ * @summary The names a chart draws, each beside the color it is drawn in.
+ *
+ * @description
+ * A legend is a list, so it is a list: not part of a chart, and shared by
+ * whichever of them needs one. It takes its entries from the same table the
+ * chart reads, through `for`, so the two cannot disagree about how many series
+ * there are or what they are called.
+ *
+ * `entries` picks which way to read that table, and the two ways are the two
+ * shapes a chart comes in. `series` is one entry per data column, named by the
+ * header row, which is a line or a bar chart. `categories` is one entry per
+ * body row, named by its row header, which is a donut: its slices are the rows,
+ * and it has no axis to write their names along.
+ *
+ * **The table is resolved on the client and there is no server pass.** `for` is
+ * an id and resolving it wants a document, which the server render does not
+ * have, so a legend ships empty and fills in on hydration. The table itself is
+ * ordinary markup and is served whole, so nothing is missing from the page
+ * before then, only from this list.
+ *
+ * The table is watched, because a legend that goes stale when its data changes
+ * is a legend that has to be told, and nothing else in the page would know to
+ * tell it.
+ *
+ * **Not hidden from a screen reader, though the mapping it draws is a color
+ * one.** The argument for hiding it is real: the colours mean nothing to a
+ * reader who cannot see them, and the names are already in the table. It stays
+ * because the cost of being wrong runs one way. A duplicated list of three
+ * words is noise; a consumer who took the table out of the accessibility tree
+ * and then found the legend hidden too has a chart nobody can read, and neither
+ * decision announces itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category charts
+ * @aliases Key, Series Key
+ * @documentation https://helix.fusion.dev/components/legend
+ *
+ * @csspart entry - One name and its swatch.
+ * @csspart list - The list itself.
+ * @csspart name - One series name.
+ * @csspart swatch - The color a series is drawn in.
+ */
+let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * The id of the table to take the names from.
+         *
+         * Resolved through `getRootNode()`, so a legend inside another component's
+         * shadow root names a table in that root rather than in the document.
+         *
+         * **In React this arrives as a property and not as an attribute**, the way
+         * `Tooltip.for` does, so it does not reflect and nothing styles on it.
+         */
+        this.for = '';
+        /* One controller rather than the resolve-and-watch each chart had written
+           out for itself. Three copies had already drifted into two names for the
+           same lookup. */
+        this.source = new SourceController(this);
+    }
+    willUpdate(changed) {
+        if (changed.has('for')) {
+            this.source.watch();
+        }
+    }
+    /**
+     * The names, in the order the chart will draw them.
+     *
+     * `protected` rather than private because the styled tier has to match a
+     * per-series treatment against them, the way `BarChart` matches `outlined` and
+     * `subtle` against the headings its table gives. A legend keys a chart, so the
+     * two answer the same question about the same series, and the tier that paints
+     * cannot do that without knowing which entry is which.
+     */
+    names() {
+        const series = this.source.series;
+        return this.entries === 'categories'
+            ? (series[0]?.points.map((point) => point.label) ?? [])
+            : series.map((one) => one.name);
+    }
+    render() {
+        /* The index rather than the color, because a color is a token and the
+           headless tier holds none. The styled tier maps one to the other, and it
+           starts over after twenty-four.
+         *
+         * The palette is eight hues in three tones, so a legend of nine repeats the
+         * first hue in a brighter tone rather than repeating a color outright. It
+         * is still a hue collision and a chart with nine series has a worse problem
+         * than the palette does; twenty-four is where it stops being able to help. */
+        return html `<ul part="list" role="list">
+      ${this.names().map((name, index) => html `<li
+          data-series=${(index % PALETTE) + 1}
+          part="entry"
+          style="--chart-series: var(--chart-series-${(index % PALETTE) + 1})"
+          role="listitem"
+        >
+          <span aria-hidden="true" part="swatch"></span>
+          <span part="name">${name}</span>
+        </li>`)}
+    </ul>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessLegend.prototype, "entries", void 0);
+__decorate([
+    property()
+], HelixHeadlessLegend.prototype, "for", void 0);
+HelixHeadlessLegend = __decorate([
+    customElement('helix-headless-legend')
+], HelixHeadlessLegend);
+export { HelixHeadlessLegend };

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

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

package/dist/line-chart/index.js

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