@fusion.dev/helix-core 0.2.0 → 0.4.0

package/custom-elements.json

@@ -2924,7 +2924,7 @@
                   }
                 }
               ],
-              "description": "Records a boolean fact about this element as a custom state.\n\n**The host belongs to whoever rendered it, and a component's own\nbookkeeping may not be kept there.** An attribute written on the first\nupdate is markup a consumer's server never sent, so a React consumer\nhydrates a DOM that has gained attributes since and reports a mismatch it\nwill not patch up. A custom state is not in the DOM at all: it carries the\nfact to a stylesheet through `:state()` and leaves the markup alone, so the\nserver's output and the client's agree by construction.\n\n`SETTLED` carries the long version of that argument; `checked`, `open`,\n`invalid` and `has-label` are recorded the same way, each of them a state a\n`default-*` attribute resolves before React reaches the node.\n\n**Deferring the definitions is not a fix and could not be.** Importing them\nfrom an effect so the upgrades fall the other side of hydration works only\nwhile hydration is one pass: anything that splits it, a streamed segment or\na suspended boundary, puts an upgrade back inside the window. Timing cannot\nbe the guarantee when the fact is kept somewhere React reconciles.\n\nFeature-tested rather than assumed, the way `hostAria` tests element\nreferences. An engine without `CustomStateSet` records nothing and keeps\nwhatever the resting rule draws, which is the safe direction to fail.\n\n**Lit's server shim is no longer one of them**, and this said it was.\n`@lit-labs/ssr-dom-shim@1.6.0` sets `this.states = new Set()` in its\n`ElementInternals` constructor, so the guard passes on the server and a\ncustom state is recorded where nothing reads it, which is harmless. The\nengines the test is for are browsers: Safari below 17.4 and Firefox below\n126. There the write is a `TypeError`, so a component that bypasses this\nfails to render rather than rendering without whatever the state draws."
+              "description": "Records a boolean fact about this element as a custom state.\n\n**The host belongs to whoever rendered it, and a component's own\nbookkeeping may not be kept there.** An attribute written on the first\nupdate is markup a consumer's server never sent, so a React consumer\nhydrates a DOM that has gained attributes since and reports a mismatch it\nwill not patch up. A custom state is not in the DOM at all: it carries the\nfact to a stylesheet through `:state()` and leaves the markup alone, so the\nserver's output and the client's agree by construction.\n\n`SETTLED` carries the long version of that argument; `checked`, `open`,\n`invalid` and `has-label` are recorded the same way, each of them a state a\n`default-*` attribute resolves before React reaches the node.\n\n**Deferring the definitions is not a fix and could not be.** Importing them\nfrom an effect so the upgrades fall the other side of hydration works only\nwhile hydration is one pass: anything that splits it, a streamed segment or\na suspended boundary, puts an upgrade back inside the window. Timing cannot\nbe the guarantee when the fact is kept somewhere React reconciles.\n\nFeature-tested rather than assumed, the way `hostAria` tests element\nreferences. An engine without `CustomStateSet` records nothing and keeps\nwhatever the resting rule draws, which is the safe direction to fail.\n\n**The engines the test is for are browsers**: Safari below 17.4 and Firefox\nbelow 126, where the write is a `TypeError`, so a component bypassing this\nfails to render rather than rendering without whatever the state draws.\nLit's server shim sets `states`, so the guard passes there and records a\nstate nothing reads, which is harmless."
             },
             {
               "kind": "field",
@@ -2933,7 +2933,7 @@
                 "text": "Promise<void>"
               },
               "readonly": true,
-              "description": "Resolves a frame after the first update, when transitions are switched on.\n\n**Named `whenSettled` because `settled` was taken four times over.** Image\nand Splitter each have a private `settle`, and both color controls carry a\n`settled` of their own, all of them older than this and none of them about\ntransitions. A base class takes the name every subclass then cannot use, so\nit takes the one nobody wanted.\n\n**The state it reports cannot be watched, which is why this exists.** A\n`MutationObserver` could see `[data-settled]` arrive and there is no\nequivalent for `ElementInternals.states`: a custom state is deliberately not\nin the DOM, which is the whole reason it replaced the attribute. Anything\nthat used to wait on the attribute waits on this instead, and gets a better\nsignal for it, an awaited promise being what the callers wanted rather than\na mutation they had to interpret.\n\nSeparate from `updateComplete`, which resolves in the microtask checkpoint\nthe suppression is still active in. That is the distinction `readyToMove`\nin `@fusion.dev/helix-testing` is written around.\n\nIt never resolves where `requestAnimationFrame` never fires, which is a\nserver, a hidden tab, and happy-dom. Callers that must not hang race it\nagainst a timeout; `readyToMove` does exactly that.",
+              "description": "Resolves a frame after the first update, when transitions are switched on.\n\n**Named `whenSettled` because `settled` is taken four times over**, by\nImage, Splitter and both color controls, none of them about transitions. A\nbase class takes the name every subclass then cannot use.\n\n**The state it reports cannot be watched, which is why this exists.** A\ncustom state is deliberately not in the DOM, so there is no\n`MutationObserver` equivalent for `ElementInternals.states`. Await this\ninstead.\n\nSeparate from `updateComplete`, which resolves in the microtask checkpoint\nthe suppression is still active in. That is the distinction `readyToMove`\nin `@fusion.dev/helix-testing` is written around.\n\nIt never resolves where `requestAnimationFrame` never fires, which is a\nserver, a hidden tab, and happy-dom. Callers that must not hang race it\nagainst a timeout; `readyToMove` does exactly that.",
               "default": "new Promise<void>((resolve) => { this.resolveSettled = resolve })"
             },
             {
@@ -3204,7 +3204,7 @@
                   }
                 }
               ],
-              "description": "Records a boolean fact about this element as a custom state.\n\n**The host belongs to whoever rendered it, and a component's own\nbookkeeping may not be kept there.** An attribute written on the first\nupdate is markup a consumer's server never sent, so a React consumer\nhydrates a DOM that has gained attributes since and reports a mismatch it\nwill not patch up. A custom state is not in the DOM at all: it carries the\nfact to a stylesheet through `:state()` and leaves the markup alone, so the\nserver's output and the client's agree by construction.\n\n`SETTLED` carries the long version of that argument; `checked`, `open`,\n`invalid` and `has-label` are recorded the same way, each of them a state a\n`default-*` attribute resolves before React reaches the node.\n\n**Deferring the definitions is not a fix and could not be.** Importing them\nfrom an effect so the upgrades fall the other side of hydration works only\nwhile hydration is one pass: anything that splits it, a streamed segment or\na suspended boundary, puts an upgrade back inside the window. Timing cannot\nbe the guarantee when the fact is kept somewhere React reconciles.\n\nFeature-tested rather than assumed, the way `hostAria` tests element\nreferences. An engine without `CustomStateSet` records nothing and keeps\nwhatever the resting rule draws, which is the safe direction to fail.\n\n**Lit's server shim is no longer one of them**, and this said it was.\n`@lit-labs/ssr-dom-shim@1.6.0` sets `this.states = new Set()` in its\n`ElementInternals` constructor, so the guard passes on the server and a\ncustom state is recorded where nothing reads it, which is harmless. The\nengines the test is for are browsers: Safari below 17.4 and Firefox below\n126. There the write is a `TypeError`, so a component that bypasses this\nfails to render rather than rendering without whatever the state draws.",
+              "description": "Records a boolean fact about this element as a custom state.\n\n**The host belongs to whoever rendered it, and a component's own\nbookkeeping may not be kept there.** An attribute written on the first\nupdate is markup a consumer's server never sent, so a React consumer\nhydrates a DOM that has gained attributes since and reports a mismatch it\nwill not patch up. A custom state is not in the DOM at all: it carries the\nfact to a stylesheet through `:state()` and leaves the markup alone, so the\nserver's output and the client's agree by construction.\n\n`SETTLED` carries the long version of that argument; `checked`, `open`,\n`invalid` and `has-label` are recorded the same way, each of them a state a\n`default-*` attribute resolves before React reaches the node.\n\n**Deferring the definitions is not a fix and could not be.** Importing them\nfrom an effect so the upgrades fall the other side of hydration works only\nwhile hydration is one pass: anything that splits it, a streamed segment or\na suspended boundary, puts an upgrade back inside the window. Timing cannot\nbe the guarantee when the fact is kept somewhere React reconciles.\n\nFeature-tested rather than assumed, the way `hostAria` tests element\nreferences. An engine without `CustomStateSet` records nothing and keeps\nwhatever the resting rule draws, which is the safe direction to fail.\n\n**The engines the test is for are browsers**: Safari below 17.4 and Firefox\nbelow 126, where the write is a `TypeError`, so a component bypassing this\nfails to render rather than rendering without whatever the state draws.\nLit's server shim sets `states`, so the guard passes there and records a\nstate nothing reads, which is harmless.",
               "inheritedFrom": {
                 "name": "HelixElement",
                 "module": "src/helix-element/helix-element.ts"
@@ -3217,7 +3217,7 @@
                 "text": "Promise<void>"
               },
               "readonly": true,
-              "description": "Resolves a frame after the first update, when transitions are switched on.\n\n**Named `whenSettled` because `settled` was taken four times over.** Image\nand Splitter each have a private `settle`, and both color controls carry a\n`settled` of their own, all of them older than this and none of them about\ntransitions. A base class takes the name every subclass then cannot use, so\nit takes the one nobody wanted.\n\n**The state it reports cannot be watched, which is why this exists.** A\n`MutationObserver` could see `[data-settled]` arrive and there is no\nequivalent for `ElementInternals.states`: a custom state is deliberately not\nin the DOM, which is the whole reason it replaced the attribute. Anything\nthat used to wait on the attribute waits on this instead, and gets a better\nsignal for it, an awaited promise being what the callers wanted rather than\na mutation they had to interpret.\n\nSeparate from `updateComplete`, which resolves in the microtask checkpoint\nthe suppression is still active in. That is the distinction `readyToMove`\nin `@fusion.dev/helix-testing` is written around.\n\nIt never resolves where `requestAnimationFrame` never fires, which is a\nserver, a hidden tab, and happy-dom. Callers that must not hang race it\nagainst a timeout; `readyToMove` does exactly that.",
+              "description": "Resolves a frame after the first update, when transitions are switched on.\n\n**Named `whenSettled` because `settled` is taken four times over**, by\nImage, Splitter and both color controls, none of them about transitions. A\nbase class takes the name every subclass then cannot use.\n\n**The state it reports cannot be watched, which is why this exists.** A\ncustom state is deliberately not in the DOM, so there is no\n`MutationObserver` equivalent for `ElementInternals.states`. Await this\ninstead.\n\nSeparate from `updateComplete`, which resolves in the microtask checkpoint\nthe suppression is still active in. That is the distinction `readyToMove`\nin `@fusion.dev/helix-testing` is written around.\n\nIt never resolves where `requestAnimationFrame` never fires, which is a\nserver, a hidden tab, and happy-dom. Callers that must not hang race it\nagainst a timeout; `readyToMove` does exactly that.",
               "default": "new Promise<void>((resolve) => { this.resolveSettled = resolve })",
               "inheritedFrom": {
                 "name": "HelixElement",

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

@@ -1,110 +1,20 @@
-/** 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.
- *
- * **A state written on a host reaches nobody.** `Megamenu` and `SpeedDial` write
- * `aria-expanded` onto whatever a consumer slots, and where that is a
- * `<helix-button>` it lands on a host the tree reports as `generic`: measured
- * through Chrome's own tree, a button named "Mega" with no expanded state at
- * all. 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.** Removing any of
- * these from the control whenever the host lacks it 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 a controller
- * carrying nothing would wipe both on every update.
- *
- * 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;
         }
-        /* **The record belongs to the element it was written about.** `forwarded`
-           says what this controller put on the control. Kept across a replacement,
-           it claims a value the new element never had, and the clearing branches
-           below then take off what the component wrote itself: the fault the record
-           exists to prevent, one element later.
-    
-           **No component in this library replaces its control**, which is worth
-           saying because the comment here used to name one. All fifteen consumers
-           resolve to a single fixed part rendered once. `target` is a callback and
-           its contract permits a swap, so a controller in `core` is held to the
-           contract rather than to the fifteen callers it happens to have today. */
         if (target !== this.recorded) {
             this.forwarded.clear();
             this.recorded = target;
@@ -112,9 +22,6 @@ export class AriaForwardController {
         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);
@@ -127,14 +34,6 @@ export class AriaForwardController {
                 this.forwarded.add(attribute);
                 continue;
             }
-            /* Only if this controller is what put it there, which is the same rule
-               the states below keep and for a worse reason. `MixinField` writes
-               `aria-describedby` on the control for its own hint, and assigning null
-               here removes the content attribute, so forwarding nothing wiped the
-               component's own description on all eighteen form controls. Invisible to
-               every DOM spec: happy-dom implements no ARIA element reflection, so the
-               `property in target` guard above skips this whole branch and the suite
-               is green against code that clears a description in every browser. */
             if (this.forwarded.has(attribute)) {
                 reflect[property] = null;
                 this.forwarded.delete(attribute);
@@ -143,7 +42,6 @@ export class AriaForwardController {
         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);
@@ -164,9 +62,6 @@ export class AriaForwardController {
         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 produces a new element with none of this. */
     hostUpdated() {
         this.forward();
     }

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

@@ -1,51 +1,10 @@
-/**
- * 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.**
-         * A horizontal bar chart runs its categories *down* the box, so resolving
-         * every reading from the pointer's x leaves a move from the first row to the
-         * last never changing the answer: measured on four rows, all four reported
-         * the third, which is the slot the middle of the box falls in. It looks like
-         * a tooltip that will not follow and is 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')) {
@@ -57,11 +16,6 @@ export class ChartPointerController {
             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);
@@ -89,20 +43,6 @@ export class ChartPointerController {
         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;
@@ -112,21 +52,10 @@ export class ChartPointerController {
             .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;

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

@@ -1,73 +1,11 @@
-/**
- * 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.
- *
- * A `data-` recipe of our own would mean a delegated document listener a
- * consumer cannot see, an id lookup and activation semantics we would write
- * ourselves, 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) => {

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

@@ -1,29 +1,10 @@
 import { HelixCopyEvent } from '../../events/events.js';
-/**
- * Writes to the clipboard, by whichever of the two routes this context allows.
- *
- * The async API first, because it is the one with a future and the only one that
- * reports failure. It is gated in more places than it looks: an insecure origin,
- * a document that is not focused, and a Permissions Policy that defaults to
- * `self`, which a sandboxed iframe without `allow-same-origin` is not.
- *
- * `execCommand` second, deprecated and still the more widely permitted of the
- * two: it is synchronous and rides the user gesture that called it rather than
- * asking for a permission, so it works in a sandboxed frame where the modern one
- * is refused. A textarea rather than the selection, because the text being
- * copied is not on the page: it is a value.
- *
- * `fixed` and `opacity: 0` rather than off-screen, because scrolling to a
- * focused element is what a negative offset causes, and a copy that jumps the
- * page is worse than one that does not happen.
- */
 const write = async (text) => {
     try {
         await navigator.clipboard.writeText(text);
         return true;
     }
     catch {
-        /* Fall through. There is nothing to report yet. */
     }
     const carrier = document.createElement('textarea');
     carrier.value = text;
@@ -31,9 +12,6 @@ const write = async (text) => {
     carrier.setAttribute('aria-hidden', 'true');
     carrier.style.cssText = 'position:fixed;top:0;left:0;opacity:0;pointer-events:none';
     document.body.append(carrier);
-    /* Focused as well as selected. `select()` focuses in a browser and does not
-       everywhere, and `execCommand('copy')` copies the *document's* selection, so
-       an unfocused textarea copies whatever was selected on the page instead. */
     carrier.focus();
     carrier.select();
     let wrote = false;
@@ -46,47 +24,13 @@ const write = async (text) => {
     carrier.remove();
     return wrote;
 };
-/**
- * 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 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 class CopyController {
     constructor(host, options = {}) {
         this.host = host;
         this.options = options;
-        /** Whether the last write succeeded and is still being confirmed. */
         this.copied = false;
         host.addController(this);
     }
-    /**
-     * 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.
-     */
     async copy(text) {
         if (text === '') {
             return;
@@ -94,13 +38,6 @@ export class CopyController {
         if (!(await write(text))) {
             return;
         }
-        /* **The host may have gone while the clipboard was being written.** Writing
-           is asynchronous, `hostDisconnected` runs the moment the element leaves,
-           and it clears a timer that does not exist yet, so without this the
-           confirmation starts a fresh timer on a detached host and calls
-           `requestUpdate` on it a second later. Checked here rather than in
-           `reset`, because the thing to skip is the whole confirmation and not only
-           its clock. */
         if (this.host instanceof HTMLElement && !this.host.isConnected) {
             return;
         }

package/dist/controllers/disabled-cascade-controller/disabled-cascade-controller.js

@@ -1,44 +1,4 @@
 import { inheritDisabled, } from '../../utils/inherit-disabled/inherit-disabled.js';
-/**
- * Pushes a group's `disabled` onto its members, on every update, unasked.
- *
- * **The cascade itself is `inheritDisabled`, and this is what makes it
- * automatic.** Called by hand it runs only when whichever method holds the call
- * runs, so a group whose items changed by some other path leaves them holding
- * the last answer, and a group that forgets the call gets no cascade at all
- * with nothing to say so: the property exists, the attribute reflects, and the
- * members simply ignore it. That is invisible in review and shows up only when
- * someone disables a set.
- *
- * It adds no API. A group already has `disabled`, from `HelixFormElement` or
- * from the consumer; nothing here introduces a property or a method for anyone
- * to call. By this repo's own rule that makes it a controller and not a mixin:
- * it reacts to a lifecycle and nothing else.
- *
- * So a group states its members once, at construction, and never thinks about
- * it again:
- *
- *     new DisabledCascadeController(this, { items: () => this.items })
- *
- * **Runs after every render, and on every `slotchange`.** The second half is
- * not an extra: a member arriving in the light DOM changes no property, so Lit
- * schedules nothing, and a render-only cascade leaves a member slotted into an
- * already-disabled group enabled. Measured before it was added, on a radio
- * group holding two disabled members with a third inserted: `110`, and the
- * third was live in a set nobody could use.
- *
- * The listener is on the render root rather than on the host, because
- * `slotchange` bubbles but is not composed: it reaches the shadow root that
- * owns the slot and stops there. On the host it would never fire at all.
- *
- * After render rather than before, because the items are read from the DOM and
- * a newly slotted member is not there until the render that assigns it.
- *
- * Idempotent, so running on every update costs a comparison per member and
- * nothing else: `inheritDisabled` writes only where the answer changed and
- * remembers what each member said for itself, which is what lets a group be
- * re-enabled without freeing a member that was disabled on its own.
- */
 export class DisabledCascadeController {
     constructor(host, { items }) {
         this.cascade = () => {