@fusion.dev/helix-core 0.0.0-dev

package/dist/controllers/aria-forward-controller/aria-forward-controller.d.ts

@@ -0,0 +1,67 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What the controller needs to know: which element inside is the control. */
+export interface AriaForwardOptions {
+    /** The focusable thing in the shadow root, or null before it renders. */
+    target: () => HTMLElement | null;
+}
+/**
+ * Carries a host's ARIA references down to the control inside it.
+ *
+ * **The gap this closes, measured.** `<helix-button aria-describedby="tip">` puts
+ * the description on the host, and the host is not what a reader is on: the
+ * accessibility tree exposes the `<button>` in the shadow root, and the host
+ * beside it is a generic with a description nobody hears. Read from Chrome's own
+ * tree:
+ *
+ * ```
+ * host           role=generic  name=""       desc="Helix description"
+ * inner button   role=button   name="Helix"  desc=""
+ * ```
+ *
+ * A plain `<button>` with the identical attribute reads `desc="Helix
+ * description"`, so the reference itself is fine and only its destination is
+ * wrong. This moves it.
+ *
+ * **An IDREF cannot make that trip and an element reference can.** The ids are
+ * written in the consumer's tree and the control is in a shadow root, so
+ * `aria-describedby` copied onto the inner element resolves to nothing.
+ * `ariaDescribedByElements` takes the elements themselves, and a reference is
+ * valid into the same tree *or a shadow-including ancestor* of it: from inside
+ * the shadow root looking out, the document is exactly that. Measured, the
+ * assignment reads back with the node intact, where the inward direction, from a
+ * light-DOM trigger to a node in a shadow root, reads back empty. This is the
+ * one direction that works, which is why `Tooltip` needs `for` and this does
+ * not.
+ *
+ * **The attributes stay on the host.** Nothing is removed and nothing is added:
+ * the consumer's markup is exactly what they wrote, which is the same reason
+ * `hostAria` exists. What changes is only that the control now also holds the
+ * reference, so a screen reader on the focused element hears it.
+ *
+ * Watched with a `MutationObserver`, because a reference can arrive at any time:
+ * a framework rendering a tooltip after this element upgrades, or a consumer
+ * pointing `aria-describedby` at a different id, changes an attribute and
+ * nothing schedules a Lit update.
+ */
+export declare class AriaForwardController implements ReactiveController {
+    private readonly host;
+    private readonly target;
+    private observer;
+    /** Which state attributes this controller wrote, so only those are removed. */
+    private readonly forwarded;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: AriaForwardOptions);
+    /**
+     * Resolves the host's references and hands them to the control.
+     *
+     * Resolved through the host's own root rather than `document`, so a button
+     * inside another component's shadow root finds the ids written beside it
+     * there. Ids that resolve to nothing are dropped rather than passed on: an
+     * `aria-describedby` naming a heading that has been removed is a stale
+     * reference, and an empty array clears the property rather than leaving the
+     * last good one in place.
+     */
+    forward(): void;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+}

package/dist/controllers/aria-forward-controller/aria-forward-controller.js

@@ -0,0 +1,146 @@
+/** The two relationships a consumer writes on a host and means for the control. */
+const RELATIONSHIPS = [
+    ['aria-describedby', 'ariaDescribedByElements'],
+    ['aria-labelledby', 'ariaLabelledByElements'],
+];
+/**
+ * The state attributes a host may carry and mean for the control inside it.
+ *
+ * **Copied rather than resolved, which is what makes them a separate list.** A
+ * relationship above names ids in the consumer's tree and can only travel as an
+ * element reference; these are plain strings and the value means the same thing
+ * wherever it is written, so the whole of the work is putting it on the node the
+ * accessibility tree actually exposes.
+ *
+ * **The case that asked for it was a disclosure with a slotted trigger.**
+ * `Megamenu` and `SpeedDial` write `aria-expanded` onto whatever a consumer
+ * slots, and where that is a `<helix-button>` the attribute landed on a host the
+ * tree reports as `generic`: measured through Chrome's own tree, a button named
+ * "Mega" with no expanded state at all, on a component whose comment says the
+ * write exists so a screen reader is not "told the control was a plain button
+ * forever". A plain `<button slot="trigger">` never had the problem, because
+ * there the host *is* the focusable node.
+ *
+ * **Only what this controller put there is ever taken away, and getting that
+ * wrong broke three components.** The first version removed any of these from
+ * the control whenever the host lacked it, which reads as the obvious way to
+ * keep the two in step and quietly deletes what the component renders for
+ * itself: `Combobox` writes `aria-controls="listbox"` onto its own input and
+ * `Select` writes `aria-expanded` onto its own trigger, and both were wiped on
+ * every update by a controller carrying nothing. Their own specs caught it.
+ *
+ * So the record below holds what was forwarded last time, and a host that stops
+ * carrying one removes exactly that and nothing else. A control's own attribute
+ * is untouched either way, which is the only rule that can be right: this
+ * controller knows what the host said and cannot know what the template meant.
+ */
+const STATES = ['aria-expanded', 'aria-haspopup', 'aria-controls'];
+/**
+ * Carries a host's ARIA references down to the control inside it.
+ *
+ * **The gap this closes, measured.** `<helix-button aria-describedby="tip">` puts
+ * the description on the host, and the host is not what a reader is on: the
+ * accessibility tree exposes the `<button>` in the shadow root, and the host
+ * beside it is a generic with a description nobody hears. Read from Chrome's own
+ * tree:
+ *
+ * ```
+ * host           role=generic  name=""       desc="Helix description"
+ * inner button   role=button   name="Helix"  desc=""
+ * ```
+ *
+ * A plain `<button>` with the identical attribute reads `desc="Helix
+ * description"`, so the reference itself is fine and only its destination is
+ * wrong. This moves it.
+ *
+ * **An IDREF cannot make that trip and an element reference can.** The ids are
+ * written in the consumer's tree and the control is in a shadow root, so
+ * `aria-describedby` copied onto the inner element resolves to nothing.
+ * `ariaDescribedByElements` takes the elements themselves, and a reference is
+ * valid into the same tree *or a shadow-including ancestor* of it: from inside
+ * the shadow root looking out, the document is exactly that. Measured, the
+ * assignment reads back with the node intact, where the inward direction, from a
+ * light-DOM trigger to a node in a shadow root, reads back empty. This is the
+ * one direction that works, which is why `Tooltip` needs `for` and this does
+ * not.
+ *
+ * **The attributes stay on the host.** Nothing is removed and nothing is added:
+ * the consumer's markup is exactly what they wrote, which is the same reason
+ * `hostAria` exists. What changes is only that the control now also holds the
+ * reference, so a screen reader on the focused element hears it.
+ *
+ * Watched with a `MutationObserver`, because a reference can arrive at any time:
+ * a framework rendering a tooltip after this element upgrades, or a consumer
+ * pointing `aria-describedby` at a different id, changes an attribute and
+ * nothing schedules a Lit update.
+ */
+export class AriaForwardController {
+    constructor(host, options) {
+        /** Which state attributes this controller wrote, so only those are removed. */
+        this.forwarded = new Set();
+        this.host = host;
+        this.target = options.target;
+        host.addController(this);
+    }
+    /**
+     * Resolves the host's references and hands them to the control.
+     *
+     * Resolved through the host's own root rather than `document`, so a button
+     * inside another component's shadow root finds the ids written beside it
+     * there. Ids that resolve to nothing are dropped rather than passed on: an
+     * `aria-describedby` naming a heading that has been removed is a stale
+     * reference, and an empty array clears the property rather than leaving the
+     * last good one in place.
+     */
+    forward() {
+        const target = this.target();
+        if (!target) {
+            return;
+        }
+        const root = this.host.getRootNode();
+        for (const [attribute, property] of RELATIONSHIPS) {
+            if (!(property in target)) {
+                // An engine without element reflection. Nothing to do, and nothing that
+                // silently half works: assigning to a property it does not implement is
+                // a no-op rather than an error, which is what the guard makes visible.
+                continue;
+            }
+            const ids = (this.host.getAttribute(attribute) ?? '').split(/\s+/).filter(Boolean);
+            const elements = ids
+                .map((id) => root.getElementById?.(id) ?? null)
+                .filter((element) => element !== null);
+            target[property] =
+                elements.length > 0 ? elements : null;
+        }
+        for (const attribute of STATES) {
+            const value = this.host.getAttribute(attribute);
+            if (value === null) {
+                // Only if this controller is what put it there. See the note above.
+                if (this.forwarded.has(attribute)) {
+                    target.removeAttribute(attribute);
+                    this.forwarded.delete(attribute);
+                }
+                continue;
+            }
+            target.setAttribute(attribute, value);
+            this.forwarded.add(attribute);
+        }
+    }
+    hostConnected() {
+        this.observer = new MutationObserver(() => this.forward());
+        this.observer.observe(this.host, {
+            attributeFilter: [...RELATIONSHIPS.map(([attribute]) => attribute), ...STATES],
+        });
+    }
+    hostDisconnected() {
+        this.observer?.disconnect();
+        this.observer = undefined;
+    }
+    /* After the render that created the control, because there is nothing to
+       forward to before it exists. Every update, not only the first: a component
+       that re-renders its control, which `Button` does whenever `href` changes it
+       between an anchor and a button, produces a new element with none of this. */
+    hostUpdated() {
+        this.forward();
+    }
+}

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.d.ts

@@ -0,0 +1,79 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What the controller needs of its host, which is a Lit element and a count. */
+export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
+    /**
+     * How many readings there are, so the pointer has something to land on.
+     */
+    readonly readings: number;
+    /**
+     * Where the chart drew itself, which is where the plot is looked for.
+     */
+    readonly renderRoot: DocumentFragment | HTMLElement;
+}
+/**
+ * Which reading a pointer is nearest, for a chart that draws no markers.
+ *
+ * **The anchor is a position and not an element, and that is the whole reason
+ * this exists.** A bar and a donut slice are elements a tooltip could be hung
+ * on; a line is one `<path>` for a whole series, because
+ * `preserveAspectRatio="none"` turns a circle into an ellipse and there is no
+ * vector-effect that answers for a shape, so `LineChart` deliberately draws no
+ * per-reading marker. Anchoring per datum works for two charts of four and
+ * cannot be extended to the third, so the resolution is arithmetic instead.
+ *
+ * **It maps along one axis only.** The nearest reading to a pointer is decided
+ * by x alone in a vertical chart, whatever y is doing, because a reader moving
+ * across a chart is asking about a column of it rather than about a point. A
+ * true nearest-point search would make a two-series chart answer differently
+ * depending on which line the pointer drifted toward, which is a tooltip that
+ * changes its mind while the reader holds still.
+ *
+ * **Coarse pointers get nothing.** A touch has no hover, so a tooltip driven by
+ * one appears where a finger already covers it and stays after the finger
+ * lifts. The table underneath is the readable version and is what a phone
+ * should be given, so this listens for `pointermove` and ignores anything whose
+ * `pointerType` is not fine.
+ */
+export declare class ChartPointerController implements ReactiveController {
+    #private;
+    /** The reading under the pointer, or -1 when the pointer is elsewhere. */
+    at: number;
+    /**
+     * Which axis the readings are laid out along.
+     *
+     * **An axis and not a boolean, because two of the four charts do not use x.**
+     * This was `tracks = true`, and every reading was resolved from the pointer's
+     * x whatever the chart was doing. A horizontal bar chart runs its categories
+     * *down* the box, so moving the pointer from the first row to the last never
+     * changed the answer: measured on four rows, all four reported the third,
+     * which is the slot the middle of the box falls in. It looked like a tooltip
+     * that would not follow and was a tooltip reading the wrong axis.
+     *
+     * `none` is the ring. Its slices are real elements at every angle, so the
+     * reading under the pointer is the one the pointer is over, and arithmetic on
+     * either axis would answer with whichever slice shared a coordinate: at three
+     * o'clock and at nine o'clock, x alone gives the same slice for opposite
+     * sides. The slices call `set` and this only holds the answer.
+     */
+    axis: 'block' | 'inline' | 'none';
+    constructor(host: ChartPointerHost);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Tells the tooltip its anchor moved, which nothing else would.
+     *
+     * The mark the tooltip is hung on is one element the chart walks from reading
+     * to reading with an inline style, and Floating UI's `autoUpdate` watches
+     * scrolling, resizing and layout shift. Moving an absolutely positioned
+     * element by writing `inset` is none of the three, so the bubble is placed
+     * once on open and then stays where the first reading was while the mark
+     * travels out from under it.
+     *
+     * Here rather than in the chart because the reading is this controller's, and
+     * after the update rather than in `set` because the mark is still at the old
+     * position until the render that follows.
+     */
+    hostUpdated(): void;
+    /** Puts the pointer on a reading, for a chart that resolves it some other way. */
+    set(at: number): void;
+}

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.js

@@ -0,0 +1,140 @@
+/**
+ * Which reading a pointer is nearest, for a chart that draws no markers.
+ *
+ * **The anchor is a position and not an element, and that is the whole reason
+ * this exists.** A bar and a donut slice are elements a tooltip could be hung
+ * on; a line is one `<path>` for a whole series, because
+ * `preserveAspectRatio="none"` turns a circle into an ellipse and there is no
+ * vector-effect that answers for a shape, so `LineChart` deliberately draws no
+ * per-reading marker. Anchoring per datum works for two charts of four and
+ * cannot be extended to the third, so the resolution is arithmetic instead.
+ *
+ * **It maps along one axis only.** The nearest reading to a pointer is decided
+ * by x alone in a vertical chart, whatever y is doing, because a reader moving
+ * across a chart is asking about a column of it rather than about a point. A
+ * true nearest-point search would make a two-series chart answer differently
+ * depending on which line the pointer drifted toward, which is a tooltip that
+ * changes its mind while the reader holds still.
+ *
+ * **Coarse pointers get nothing.** A touch has no hover, so a tooltip driven by
+ * one appears where a finger already covers it and stays after the finger
+ * lifts. The table underneath is the readable version and is what a phone
+ * should be given, so this listens for `pointermove` and ignores anything whose
+ * `pointerType` is not fine.
+ */
+export class ChartPointerController {
+    #host;
+    #moved;
+    #plot;
+    constructor(host) {
+        this.#moved = false;
+        /** The reading under the pointer, or -1 when the pointer is elsewhere. */
+        this.at = -1;
+        /**
+         * Which axis the readings are laid out along.
+         *
+         * **An axis and not a boolean, because two of the four charts do not use x.**
+         * This was `tracks = true`, and every reading was resolved from the pointer's
+         * x whatever the chart was doing. A horizontal bar chart runs its categories
+         * *down* the box, so moving the pointer from the first row to the last never
+         * changed the answer: measured on four rows, all four reported the third,
+         * which is the slot the middle of the box falls in. It looked like a tooltip
+         * that would not follow and was a tooltip reading the wrong axis.
+         *
+         * `none` is the ring. Its slices are real elements at every angle, so the
+         * reading under the pointer is the one the pointer is over, and arithmetic on
+         * either axis would answer with whichever slice shared a coordinate: at three
+         * o'clock and at nine o'clock, x alone gives the same slice for opposite
+         * sides. The slices call `set` and this only holds the answer.
+         */
+        this.axis = 'inline';
+        this.#move = (event) => {
+            if (this.axis === 'none' || (event.pointerType !== 'mouse' && event.pointerType !== 'pen')) {
+                return;
+            }
+            const box = this.#box();
+            const count = this.#host.readings;
+            const along = this.axis === 'block' ? box?.height : box?.width;
+            if (!box || !along || count === 0) {
+                return;
+            }
+            /* The same slot arithmetic the charts draw with: reading `i` sits in the
+               middle of the `i`th of `count` equal slots, so the nearest is the slot
+               the pointer is in. Rounding a proportion of `count - 1` instead puts the
+               boundaries half a slot off and the first and last reading get half the
+               catchment of the others. */
+            const from = this.axis === 'block' ? event.clientY - box.top : event.clientX - box.left;
+            const slot = Math.floor((from / along) * count);
+            const next = Math.min(Math.max(slot, 0), count - 1);
+            if (next !== this.at) {
+                this.at = next;
+                this.#moved = true;
+                this.#host.requestUpdate();
+            }
+        };
+        this.#leave = () => {
+            if (this.at !== -1) {
+                this.at = -1;
+                this.#host.requestUpdate();
+            }
+        };
+        this.#host = host;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.#host.addEventListener('pointermove', this.#move);
+        this.#host.addEventListener('pointerleave', this.#leave);
+    }
+    hostDisconnected() {
+        this.#host.removeEventListener('pointermove', this.#move);
+        this.#host.removeEventListener('pointerleave', this.#leave);
+        this.at = -1;
+    }
+    /**
+     * Tells the tooltip its anchor moved, which nothing else would.
+     *
+     * The mark the tooltip is hung on is one element the chart walks from reading
+     * to reading with an inline style, and Floating UI's `autoUpdate` watches
+     * scrolling, resizing and layout shift. Moving an absolutely positioned
+     * element by writing `inset` is none of the three, so the bubble is placed
+     * once on open and then stays where the first reading was while the mark
+     * travels out from under it.
+     *
+     * Here rather than in the chart because the reading is this controller's, and
+     * after the update rather than in `set` because the mark is still at the old
+     * position until the render that follows.
+     */
+    hostUpdated() {
+        if (!this.#moved) {
+            return;
+        }
+        this.#moved = false;
+        this.#host.renderRoot
+            .querySelector('[part="tooltip-anchor"]')
+            ?.reposition?.();
+    }
+    /**
+     * The box the readings are laid out in, which is the plot and not the host.
+     *
+     * The host also holds the row of labels, so measuring against it would map
+     * the pointer over a box taller than the drawing. That mattered the moment a
+     * chart started measuring down the box rather than across it, which is what
+     * `axis` is for: on a horizontal bar chart the labels are beside the plot
+     * rather than under it, and the host is wider than the drawing by exactly
+     * their column.
+     */
+    #box() {
+        this.#plot ??= this.#host.renderRoot.querySelector('[part="plot"]') ?? undefined;
+        return this.#plot?.getBoundingClientRect();
+    }
+    /** Puts the pointer on a reading, for a chart that resolves it some other way. */
+    set(at) {
+        if (at !== this.at) {
+            this.at = at;
+            this.#moved = true;
+            this.#host.requestUpdate();
+        }
+    }
+    #move;
+    #leave;
+}

package/dist/controllers/command-controller/command-controller.d.ts

@@ -0,0 +1,83 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * Whether the browser implements invoker commands.
+ *
+ * Feature-detected on the prototype rather than on an instance, so it can be
+ * answered before anything has rendered, and guarded for a server, which has no
+ * `HTMLButtonElement` at all.
+ */
+export declare const supportsInvokers: () => boolean;
+/**
+ * The `command` event, for a browser that does not send one.
+ *
+ * Invoker commands are recent: Chrome 135, Firefox 137, Safari 18.4. Before
+ * this, a button in an older browser set `commandForElement` on nothing, the
+ * wiring silently did not happen, and the control did nothing at all when
+ * clicked. No error, no warning, and every `command` in the library dead at
+ * once, which is the worst way for a feature to be missing: the markup is
+ * right, the component is right, and the button is simply inert.
+ *
+ * So the button sends this instead where the platform will not. It carries the
+ * two members `CommandController` reads and dispatches at the target, which is
+ * where the platform dispatches too, so nothing downstream can tell the
+ * difference.
+ *
+ * **The built-in commands are not reproduced.** `show-modal`, `close` and
+ * `toggle-popover` are defined against native elements and applied by the
+ * browser itself, and writing our own would mean reimplementing part of the
+ * platform against elements we do not own. Nothing in this library uses them:
+ * a custom element only ever answers a `--` command, which is the platform's
+ * marker for "the target decides", and the target is ours.
+ */
+export declare class HelixFallbackCommandEvent extends Event {
+    /** The command asked for, verbatim. */
+    readonly command: string;
+    /** The element that asked. */
+    readonly source: Element | null;
+    constructor(command: string, source: Element | null);
+}
+/** What the host answers to, by command name. */
+export interface CommandOptions {
+    /** Each command the host implements, keyed by the name a trigger writes. */
+    commands: Record<string, (source: Element | null) => void>;
+}
+/**
+ * Lets a control elsewhere on the page operate this one, declaratively.
+ *
+ * ```html
+ * <helix-button commandfor="confirm" command="--show">Delete…</helix-button>
+ * <helix-dialog id="confirm">…</helix-dialog>
+ * ```
+ *
+ * **The platform's own invoker, not a convention of ours.** `commandfor` and
+ * `command` are attributes the browser understands: it resolves the id, wires
+ * the two together, and dispatches a `command` event at the target when the
+ * trigger is activated. That is a real event with a real source, so it works
+ * for a click, for Enter, for Space, and for anything else the platform decides
+ * counts as activation later.
+ *
+ * The alternative was a `data-` recipe of our own with a delegated listener on
+ * the document, and it is worse in every direction: a global listener a
+ * consumer cannot see, an id lookup we would write ourselves, activation
+ * semantics we would have to guess at, and a convention that is ours to
+ * document and theirs to learn.
+ *
+ * **Only custom commands reach a custom element.** The built-in ones —
+ * `show-modal`, `close`, `toggle-popover` — are defined against native elements
+ * and the browser applies them itself; pointed at a custom element they do
+ * nothing. So the names here start with `--`, which is the platform's marker
+ * for "the target decides what this means", and the target deciding is exactly
+ * what this is.
+ *
+ * Unrecognized commands are left alone rather than swallowed, so a host that
+ * answers `--show` does not quietly absorb a `--print` meant for something
+ * else.
+ */
+export declare class CommandController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: CommandOptions);
+    private readonly handle;
+    hostConnected(): void;
+    hostDisconnected(): void;
+}

package/dist/controllers/command-controller/command-controller.js

@@ -0,0 +1,93 @@
+/**
+ * Whether the browser implements invoker commands.
+ *
+ * Feature-detected on the prototype rather than on an instance, so it can be
+ * answered before anything has rendered, and guarded for a server, which has no
+ * `HTMLButtonElement` at all.
+ */
+export const supportsInvokers = () => typeof HTMLButtonElement !== 'undefined' && 'commandForElement' in HTMLButtonElement.prototype;
+/**
+ * The `command` event, for a browser that does not send one.
+ *
+ * Invoker commands are recent: Chrome 135, Firefox 137, Safari 18.4. Before
+ * this, a button in an older browser set `commandForElement` on nothing, the
+ * wiring silently did not happen, and the control did nothing at all when
+ * clicked. No error, no warning, and every `command` in the library dead at
+ * once, which is the worst way for a feature to be missing: the markup is
+ * right, the component is right, and the button is simply inert.
+ *
+ * So the button sends this instead where the platform will not. It carries the
+ * two members `CommandController` reads and dispatches at the target, which is
+ * where the platform dispatches too, so nothing downstream can tell the
+ * difference.
+ *
+ * **The built-in commands are not reproduced.** `show-modal`, `close` and
+ * `toggle-popover` are defined against native elements and applied by the
+ * browser itself, and writing our own would mean reimplementing part of the
+ * platform against elements we do not own. Nothing in this library uses them:
+ * a custom element only ever answers a `--` command, which is the platform's
+ * marker for "the target decides", and the target is ours.
+ */
+export class HelixFallbackCommandEvent extends Event {
+    constructor(command, source) {
+        // Matching the platform: fired at the invokee, cancelable, and not
+        // bubbling. `CommandController` listens on the target itself, so there is
+        // nothing above it that a bubble would reach anyway.
+        super('command', { cancelable: true });
+        this.command = command;
+        this.source = source;
+    }
+}
+/**
+ * Lets a control elsewhere on the page operate this one, declaratively.
+ *
+ * ```html
+ * <helix-button commandfor="confirm" command="--show">Delete…</helix-button>
+ * <helix-dialog id="confirm">…</helix-dialog>
+ * ```
+ *
+ * **The platform's own invoker, not a convention of ours.** `commandfor` and
+ * `command` are attributes the browser understands: it resolves the id, wires
+ * the two together, and dispatches a `command` event at the target when the
+ * trigger is activated. That is a real event with a real source, so it works
+ * for a click, for Enter, for Space, and for anything else the platform decides
+ * counts as activation later.
+ *
+ * The alternative was a `data-` recipe of our own with a delegated listener on
+ * the document, and it is worse in every direction: a global listener a
+ * consumer cannot see, an id lookup we would write ourselves, activation
+ * semantics we would have to guess at, and a convention that is ours to
+ * document and theirs to learn.
+ *
+ * **Only custom commands reach a custom element.** The built-in ones —
+ * `show-modal`, `close`, `toggle-popover` — are defined against native elements
+ * and the browser applies them itself; pointed at a custom element they do
+ * nothing. So the names here start with `--`, which is the platform's marker
+ * for "the target decides what this means", and the target deciding is exactly
+ * what this is.
+ *
+ * Unrecognized commands are left alone rather than swallowed, so a host that
+ * answers `--show` does not quietly absorb a `--print` meant for something
+ * else.
+ */
+export class CommandController {
+    constructor(host, options) {
+        this.handle = (event) => {
+            const command = event.command;
+            const run = this.options.commands[command];
+            if (!run) {
+                return;
+            }
+            run(event.source);
+        };
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('command', this.handle);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('command', this.handle);
+    }
+}

package/dist/controllers/copy-controller/copy-controller.d.ts

@@ -0,0 +1,58 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What a copy needs to know, asked for rather than assumed. */
+export interface CopyOptions {
+    /**
+     * How long the confirmation stands, in milliseconds.
+     *
+     * On a timer rather than on the pointer leaving, so it survives a hand that
+     * has already moved on: the press and the reading of it are two moments, and
+     * a mark that vanishes with the cursor is one a fast reader never sees.
+     */
+    after?: number;
+}
+/**
+ * Puts text on the clipboard and holds a confirmation for a moment.
+ *
+ * A controller rather than a component, because copying is a behavior and not a
+ * shape. Color's chip is a swatch that copies, and a copy button is a button
+ * that copies, and those two have nothing in common to look at: what they share
+ * is the write, the confirmation that follows it, the timer that ends it and the
+ * event that announces it. Written twice, the second one would get the failure
+ * case wrong.
+ *
+ * **There are two routes and both are tried**, because the modern one is gated
+ * in more places than it looks: an insecure origin, an unfocused document, and a
+ * Permissions Policy defaulting to `self`, which a sandboxed iframe is not. The
+ * component using this reported as not working, and a control that does nothing
+ * is indistinguishable from a broken one. See `write` above.
+ *
+ * **Where neither route is allowed, the failure is silence.** The confirmation
+ * does not appear, which is the honest report: a message about a clipboard is
+ * worse than a chip that did not flash, and there is nothing a reader could do
+ * about a permission policy anyway.
+ *
+ * **The event is announced after the write, not before it.** It is not
+ * cancelable for the same reason: by the time anything could be said, the text
+ * is already on the clipboard, and an event that cannot prevent what it
+ * describes should not pretend otherwise.
+ *
+ * The timer is cleared when the host leaves the document, or a component removed
+ * mid-confirmation asks a detached element to re-render.
+ */
+export declare class CopyController implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    /** Whether the last write succeeded and is still being confirmed. */
+    copied: boolean;
+    private timer;
+    constructor(host: ReactiveControllerHost & EventTarget, options?: CopyOptions);
+    /**
+     * Writes to the clipboard, and confirms it if the platform allowed it.
+     *
+     * Empty text is not copied. An empty clipboard is not a thing a reader ever
+     * asks for, and confirming one is worse than doing nothing.
+     */
+    copy(text: string): Promise<void>;
+    hostDisconnected(): void;
+    private reset;
+}