@fusion.dev/helix-core 0.0.0-dev → 0.0.3

package/dist/utils/draw-icon/draw-icon.js

@@ -8,15 +8,15 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
  * every consumer of any component that renders one ships all of the generated
  * path data: measured at 50,814 bytes raw and 15,010 gzipped for 102 icons, and
  * growing about 147 gzipped bytes per icon added. A named import ships one path
- * and is checked when the package compiles rather than when `check:icons` runs.
+ * and is checked when the package compiles rather than by a name lookup later.
  *
  * That element still earns its place as *public* API, where a consumer writes a
  * name in markup and a lookup is the only thing that can work. What it should
  * not be is how this library draws its own marks.
  *
  * **There is no `part` option, and there cannot be.** A part name behind an
- * interpolation is a part the manifest cannot see, so `check:selectors` reports
- * the component's own stylesheet as matching nothing and the part stops being
+ * interpolation is a part the manifest cannot see, so the component's own
+ * stylesheet matches nothing and the part stops being
  * API. `Trend` needs one and therefore writes its `<svg>` out with a literal
  * `part="icon"`, which is the honest cost: a helper can carry everything except
  * the thing static analysis has to read.

package/dist/utils/elapsed-time/elapsed-time.js

@@ -82,9 +82,7 @@ export const elapsedTime = (locale) => {
         if (size < 60_000) {
             /* Floored like every other branch. At 59,999 milliseconds the remainder is
                one, and a caller handed a one is re-armed inside the callback that
-               fired it. `relativeTime` shipped without this floor on the same branch
-               and its own `Relative.next` claimed to have it; only the shared ticker's
-               own `Math.max(1000, ...)` was standing between that and a busy loop. */
+               fired it. */
             return { next: Math.max(1000, 60_000 - size), text: zero.format(0, 'second') };
         }
         /* A date, and it will not change again. `Infinity` is the whole point of

package/dist/utils/focusable-elements/focusable-elements.d.ts

@@ -26,11 +26,10 @@ export declare const deepActiveElement: () => Element | null;
  * `deepActiveElement`, which returns exactly such a node, that pairing is a trap
  * of its own: the two look like they belong together and one of them crosses.
  *
- * `FocusTrapController` had precisely that, `contains(deepActiveElement())`,
- * and it is why every dialog and drawer in the library leaked. Focus on a
+ * `contains(deepActiveElement())` is the shape to avoid: focus on a
  * `helix-button` reports as the `<button>` in its shadow root, which is in no
- * light-DOM container anywhere, so the trap read every reader as already
- * outside it.
+ * light-DOM container anywhere, so a trap written that way reads every reader
+ * as already outside it.
  *
  * `host` is reached without naming `ShadowRoot`, which the server has no global
  * for. This runs from a keydown handler and would never execute there, but a

package/dist/utils/focusable-elements/focusable-elements.js

@@ -30,13 +30,12 @@ const NATIVE_FOCUSABLE = [
 export const focusableElements = (root) => 
 /* One pass asking both questions, rather than two passes concatenated.
  *
- * Two lists joined end to end is not document order, and this said "in
- * document order" while returning every native element followed by every
- * delegating host: measured, `b d a c` for a tree holding `a b c d`. The
- * trap reads `items[0]` and `items.at(-1)` as its boundaries, so a surface
- * whose last control is a plain `<button>` and whose first is a Helix
- * component had a last that was not last, and forward Tab off the real end
- * did not wrap. Focus left the dialog.
+ * Two lists joined end to end is not document order: every native element
+ * followed by every delegating host comes out `b d a c` for a tree holding
+ * `a b c d`, measured. The trap reads `items[0]` and `items.at(-1)` as its
+ * boundaries, so a surface whose last control is a plain `<button>` and whose
+ * first is a Helix component has a last that is not last, forward Tab off the
+ * real end does not wrap, and focus leaves the dialog.
  *
  * It is invisible in a set that is all one kind, which is what every example
  * and every spec had. A single filtered walk cannot express the fault, and
@@ -65,11 +64,10 @@ export const deepActiveElement = () => {
  * `deepActiveElement`, which returns exactly such a node, that pairing is a trap
  * of its own: the two look like they belong together and one of them crosses.
  *
- * `FocusTrapController` had precisely that, `contains(deepActiveElement())`,
- * and it is why every dialog and drawer in the library leaked. Focus on a
+ * `contains(deepActiveElement())` is the shape to avoid: focus on a
  * `helix-button` reports as the `<button>` in its shadow root, which is in no
- * light-DOM container anywhere, so the trap read every reader as already
- * outside it.
+ * light-DOM container anywhere, so a trap written that way reads every reader
+ * as already outside it.
  *
  * `host` is reached without naming `ShadowRoot`, which the server has no global
  * for. This runs from a keydown handler and would never execute there, but a

package/dist/utils/format-numbers/format-numbers.js

@@ -3,10 +3,7 @@
  *
  * `Intl.NumberFormat` is expensive to construct and cheap to call, and a
  * pagination renders its count on every update, so building one per render is
- * the whole cost of the component. Three files in one family had worked that
- * out separately and each kept its own two-line cache, which is three places to
- * find the day the caching rule changes and three chances for one of them to be
- * subtly different.
+ * the whole cost of the component.
  *
  * Keyed on the locale, so a component that never changes locale builds one
  * formatter for its life and one that does builds a second and drops the first.

package/dist/utils/host-aria/host-aria.d.ts

@@ -20,8 +20,8 @@ export interface HostAria {
  * **Empty means absent, and that is the trap this exists for.** Assigning `''`
  * to `ariaLabel` is not the same as not naming the element: it is a name of no
  * characters, which a screen reader announces as an unnamed control while every
- * check for "is it labeled" passes. Every caller had written
- * `this.label === '' ? null : this.label` and one of them would eventually not.
+ * check for "is it labeled" passes. Clearing is `null`, and this is the one
+ * place that has to remember it.
  *
  * **Element references are feature-tested rather than assumed.** They are the
  * only way a host in the light DOM can point at a node in its own shadow root,

package/dist/utils/host-aria/host-aria.js

@@ -9,8 +9,8 @@
  * **Empty means absent, and that is the trap this exists for.** Assigning `''`
  * to `ariaLabel` is not the same as not naming the element: it is a name of no
  * characters, which a screen reader announces as an unnamed control while every
- * check for "is it labeled" passes. Every caller had written
- * `this.label === '' ? null : this.label` and one of them would eventually not.
+ * check for "is it labeled" passes. Clearing is `null`, and this is the one
+ * place that has to remember it.
  *
  * **Element references are feature-tested rather than assumed.** They are the
  * only way a host in the light DOM can point at a node in its own shadow root,

package/dist/utils/line-path/line-path.js

@@ -13,7 +13,7 @@ const round = (value) => Math.round(value * 100) / 100;
  *
  * Two rules do it. A tangent at a turning point is flat, so the curve arrives
  * and leaves level rather than carrying on past the peak; and where a tangent
- * is steep enough relative to its neighbours to bulge anyway, the pair is
+ * is steep enough relative to its neighbors to bulge anyway, the pair is
  * scaled back until it cannot.
  */
 const tangents = (xs, ys) => {

package/dist/utils/on-unless-false/on-unless-false.d.ts

@@ -9,11 +9,6 @@ import type { ComplexAttributeConverter } from 'lit';
  * attribute that turns it off at all, and a consumer who writes the obvious
  * thing gets the opposite of what they asked for, silently.
  *
- * Found on `Drawer.modal`, where it mattered: a tour cannot point inside a
- * modal, so `modal="false"` is exactly what a consumer reaches for, and it left
- * the drawer modal. Two others have the same shape, `Video.playsInline` and the
- * sandbox source's `tabIndents`.
- *
  * So: absent is the default, present is on, and the one string that means off
  * is the one a consumer would write. `"false"` only, and not `"0"` or `"no"`,
  * because a converter that accepts a vocabulary invites a consumer to guess at

package/dist/utils/on-unless-false/on-unless-false.js

@@ -8,11 +8,6 @@
  * attribute that turns it off at all, and a consumer who writes the obvious
  * thing gets the opposite of what they asked for, silently.
  *
- * Found on `Drawer.modal`, where it mattered: a tour cannot point inside a
- * modal, so `modal="false"` is exactly what a consumer reaches for, and it left
- * the drawer modal. Two others have the same shape, `Video.playsInline` and the
- * sandbox source's `tabIndents`.
- *
  * So: absent is the default, present is on, and the one string that means off
  * is the one a consumer would write. `"false"` only, and not `"0"` or `"no"`,
  * because a converter that accepts a vocabulary invites a consumer to guess at

package/dist/utils/read-series/read-series.d.ts

@@ -12,6 +12,10 @@ export interface SeriesPoint {
      * The machine-readable instant, if the row header carries a `<time>`.
      */
     when?: string;
+    /**
+     * The tone the cell asked for through `data-tone`, where it carries one.
+     */
+    tone?: string;
 }
 /** One column of a table, read as a series. */
 export interface Series {
@@ -25,6 +29,28 @@ export interface Series {
      */
     points: SeriesPoint[];
 }
+/**
+ * Reads a table as series, one per data column.
+ *
+ * **The table is the chart's accessible representation, not a fallback for
+ * one.** Every chart here takes its numbers from real markup rather than from a
+ * property, so the page is readable with no script at all, sortable by anything
+ * that sorts tables, and correct in a screen reader without a parallel
+ * description that has to be kept in step by hand. A `values` array would be
+ * easier to pass and would make the accessible version the thing nobody
+ * maintains.
+ *
+ * The shape is the ordinary one: a header row naming the series, a first column
+ * of row headers, and numbers in the rest. A single-column table has one series
+ * and takes its name from the caption, since a header row of one is usually
+ * absent.
+ *
+ * `data-value` wins over the cell's text, because `$1.2k` is what a reader
+ * should see and is not a number. `Number()` rather than `parseFloat`, because
+ * the second reads `12abc` as 12: a value that is nearly a number is a mistake
+ * worth dropping rather than rounding off, and a dropped point is visible where
+ * a silently truncated one is not.
+ */
 export declare const readSeries: (table: Element) => Series[];
 /** One cell of a row, as a reader sees it and as a chart measures it. */
 export interface RowCell {

package/dist/utils/read-series/read-series.js

@@ -1,25 +1,3 @@
-/**
- * Reads a table as series, one per data column.
- *
- * **The table is the chart's accessible representation, not a fallback for
- * one.** Every chart here takes its numbers from real markup rather than from a
- * property, so the page is readable with no script at all, sortable by anything
- * that sorts tables, and correct in a screen reader without a parallel
- * description that has to be kept in step by hand. A `values` array would be
- * easier to pass and would make the accessible version the thing nobody
- * maintains.
- *
- * The shape is the ordinary one: a header row naming the series, a first column
- * of row headers, and numbers in the rest. A single-column table has one series
- * and takes its name from the caption, since a header row of one is usually
- * absent.
- *
- * `data-value` wins over the cell's text, because `$1.2k` is what a reader
- * should see and is not a number. `Number()` rather than `parseFloat`, because
- * the second reads `12abc` as 12: a value that is nearly a number is a mistake
- * worth dropping rather than rounding off, and a dropped point is visible where
- * a silently truncated one is not.
- */
 /* A grid's own rows and cells, by role and by tag.
  *
  * **Both, because `helix-table` sets its roles through `ElementInternals`.**
@@ -84,14 +62,33 @@ const readGrid = (grid) => {
 /* A column with no numbers in it is not a series.
  *
  * Both readers build one entry per data column and then drop the rows whose
- * cells will not parse, so a column of notes came back as a series with a name
- * and no points. Nothing drew it, which is why it went unseen, and `Legend`
- * named it anyway: a swatch in the palette against a column no chart plotted,
- * and every series after it shifted a color.
- *
- * Found the moment tables grew columns a tooltip wanted and a drawing did not,
- * which is the arrangement `readRows` exists for. */
+ * cells will not parse, so a column of notes arrives here as a series with a
+ * name and no points. Nothing draws it, so it is invisible until `Legend` names
+ * it anyway: a swatch in the palette against a column no chart plotted, and
+ * every series after it shifted a color. */
 const plotted = (series) => series.filter((one) => one.points.length > 0);
+/**
+ * Reads a table as series, one per data column.
+ *
+ * **The table is the chart's accessible representation, not a fallback for
+ * one.** Every chart here takes its numbers from real markup rather than from a
+ * property, so the page is readable with no script at all, sortable by anything
+ * that sorts tables, and correct in a screen reader without a parallel
+ * description that has to be kept in step by hand. A `values` array would be
+ * easier to pass and would make the accessible version the thing nobody
+ * maintains.
+ *
+ * The shape is the ordinary one: a header row naming the series, a first column
+ * of row headers, and numbers in the rest. A single-column table has one series
+ * and takes its name from the caption, since a header row of one is usually
+ * absent.
+ *
+ * `data-value` wins over the cell's text, because `$1.2k` is what a reader
+ * should see and is not a number. `Number()` rather than `parseFloat`, because
+ * the second reads `12abc` as 12: a value that is nearly a number is a mistake
+ * worth dropping rather than rounding off, and a dropped point is visible where
+ * a silently truncated one is not.
+ */
 export const readSeries = (table) => {
     if (isGrid(table)) {
         return plotted(readGrid(table));

package/dist/utils/relative-time/relative-time.js

@@ -57,12 +57,11 @@ export const relativeTime = (locale) => {
            nothing: nobody acts differently at seven seconds than at four. */
         const size = Math.abs(elapsed);
         if (size < 60_000) {
-            /* Floored, which `Relative.next` has always said this is and this branch
-               alone was not: at 59,999 milliseconds the remainder is one, so a caller
-               is re-armed inside the callback that fired it. Nothing had noticed
-               because both readers go through the shared ticker, whose own
-               `Math.max(1000, ...)` was absorbing it; a caller scheduling for itself
-               would have had the busy loop the type promised it would not. */
+            /* Floored, as `Relative.next` says every branch is: at 59,999
+               milliseconds the remainder is one, so a caller scheduling for itself is
+               re-armed inside the callback that fired it. The shared ticker's own
+               `Math.max(1000, ...)` hides this from the two readers that go through
+               it. */
             return { next: Math.max(1000, 60_000 - size), text: found.format(0, 'second') };
         }
         let chosen = UNITS[1];

package/dist/utils/request-change/request-change.d.ts

@@ -10,30 +10,19 @@
  * anything moves. A component that mutated itself and then announced it would
  * leave a consumer reacting to a decision already made.
  *
- * **Control is an action, not a mode.** This used to decide whether to apply by
- * asking if the consumer had declared ownership, which meant an element that
- * had been handed a `value` applied nothing and waited to be told. That is
- * gone: the element always owns its state and always applies it, and a consumer
- * takes over for one interaction by refusing here and assigning their own. See
- * 294 for the argument, which is that a mode forks the event vocabulary by prop
- * presence, has no ergonomic spelling in HTML, and is invisible enough to need
- * an audit to make it audible.
- *
- * **The audit went with it, and that is not a loss.** It existed to warn that
- * `value="Ada"` looks like the native seed and was not one. It is one now, so
- * the trap it detected cannot happen and the machinery to detect it, two
- * `WeakMap`s and a warning judged on the second request, has nothing to do.
+ * **Control is an action, not a mode.** The element always owns its state and
+ * always applies it, and a consumer takes over for one interaction by refusing
+ * here and assigning their own. A mode instead would fork the event vocabulary
+ * by prop presence, has no ergonomic spelling in HTML, and is invisible enough
+ * to need an audit to make it audible.
  *
  * Returns whether the change was applied, so a caller that needs to know (a key
  * handler deciding whether to also move focus) can ask.
  *
- * **There is one channel, and it is the event.** `onCheckedChange`,
- * `onOpenChange`, `onValueChange` and `onActiveChange` were a second one,
- * invoked from here once the state had been applied. They were removed on
- * 19 Aug 2026, for working in fewer places than the thing they duplicated:
- * React takes any `on[A-Z]` prop into its own branch and calls
- * `addEventListener('CheckedChange', …)` with it, an event nothing dispatches,
- * so no consumer writing JSX could reach one.
+ * **There is one channel, and it is the event.** A callback property beside it
+ * (`onCheckedChange` and its kind) is unreachable from JSX: React takes any
+ * `on[A-Z]` prop into its own branch and calls
+ * `addEventListener('CheckedChange', …)` with it, an event nothing dispatches.
  */
 export interface ChangeRequestOptions<T> {
     /** Applies the change. Called only if no listener refused it. */

package/dist/utils/resolve-active-item/resolve-active-item.d.ts

@@ -16,9 +16,9 @@ export interface ActivatableItem {
  * The fallback skips disabled items and the match does not. A consumer who
  * names a disabled item meant it, and quietly moving to another would be the
  * component overruling them; but falling back *onto* a disabled item is the
- * component choosing, and it should not choose something out of play. Every
- * hand-written copy took `items[0]` either way, so a set opening on a disabled
- * first item showed it as current.
+ * component choosing, and it should not choose something out of play. Taking
+ * `items[0]` either way opens a set on a disabled first item and shows it as
+ * current.
  *
  * A plain function rather than only a method on `MixinControllerActive`,
  * because the components that need it are split across two mixins: a set whose

package/dist/utils/resolve-active-item/resolve-active-item.js

@@ -9,9 +9,9 @@
  * The fallback skips disabled items and the match does not. A consumer who
  * names a disabled item meant it, and quietly moving to another would be the
  * component overruling them; but falling back *onto* a disabled item is the
- * component choosing, and it should not choose something out of play. Every
- * hand-written copy took `items[0]` either way, so a set opening on a disabled
- * first item showed it as current.
+ * component choosing, and it should not choose something out of play. Taking
+ * `items[0]` either way opens a set on a disabled first item and shows it as
+ * current.
  *
  * A plain function rather than only a method on `MixinControllerActive`,
  * because the components that need it are split across two mixins: a set whose

package/dist/utils/restore-value/restore-value.js

@@ -7,12 +7,7 @@
  * how that is done, and per spec assigning a *different* string moves the text
  * entry cursor to the end. Measured: caret at index three in `abcdef`, assign
  * `abcXdef`, caret at seven. Assigning the same string leaves it alone, which
- * is why this was invisible until a consumer was slow.
- *
- * So a React consumer holding the value in state, which commits after the
- * event, put the caret at the end of the field after every single keystroke.
- * Typing in the middle of a word was impossible, and the class JSDoc claimed
- * the caret was the platform's business.
+ * is why this only shows against a consumer that is slow to answer.
  *
  * The offset is adjusted by the length difference rather than clamped, because
  * the common case is exactly one character wide: the reader typed, the element

package/dist/utils/scroll-item-into-view/scroll-item-into-view.js

@@ -23,13 +23,12 @@
 /**
  * The nearest ancestor that actually scrolls, crossing shadow boundaries.
  *
- * This was `item.offsetParent`, which is the nearest *positioned* ancestor and
+ * **Not `item.offsetParent`**, which is the nearest *positioned* ancestor and
  * has nothing whatever to do with overflow. The two coincide often enough to
  * look right, because a scroller frequently is positioned, and they come apart
  * exactly where it matters: put anything `position: relative` between the item
- * and the box that scrolls, and the util scrolled the thing in between, which
- * does not scroll, and reported nothing. `Tree` passes no scroller at all, so
- * it had the default on every keypress.
+ * and the box that scrolls, and the util scrolls the thing in between, which
+ * does not scroll, and reports nothing.
  *
  * The walk crosses shadow boundaries through the host, because the item is
  * almost always in one and `parentElement` is null at the root. Without that
@@ -83,7 +82,7 @@ export const scrollItemIntoView = (item, options = {}) => {
     };
     /* Whichever edge it is past, and nothing when it is past neither. A scroll of
        zero still fires a `scroll` event and still cancels a smooth one already
-       running, so the early return is behavior rather than an optimisation. */
+       running, so the early return is behavior rather than an optimization. */
     const inline = before.inline > 0 ? -before.inline : after.inline > 0 ? after.inline : 0;
     const block = before.block > 0 ? -before.block : after.block > 0 ? after.block : 0;
     if (inline === 0 && block === 0) {

package/dist/utils/slot-filled/slot-filled.d.ts

@@ -10,10 +10,8 @@
  * The answer matters because an empty wrapper is not free. A region that
  * generates a box is a flex item or a grid item whether or not it holds
  * anything, so it takes the container's gap: an announcement with no actions
- * paid the row gap twice, a switch with no label took one for a label that was
- * not there, and a blockquote with no attribution reserved a full space below
- * every quote. `display: none` is the only fix, because only a box that is not
- * generated has no gap beside it.
+ * pays the row gap twice. `display: none` is the only fix, because only a box
+ * that is not generated has no gap beside it.
  *
  * Text or an element, because neither alone is the test. An element on its own
  * counts a whitespace-only span as content; text on its own counts an icon as

package/dist/utils/slot-filled/slot-filled.js

@@ -10,10 +10,8 @@
  * The answer matters because an empty wrapper is not free. A region that
  * generates a box is a flex item or a grid item whether or not it holds
  * anything, so it takes the container's gap: an announcement with no actions
- * paid the row gap twice, a switch with no label took one for a label that was
- * not there, and a blockquote with no attribution reserved a full space below
- * every quote. `display: none` is the only fix, because only a box that is not
- * generated has no gap beside it.
+ * pays the row gap twice. `display: none` is the only fix, because only a box
+ * that is not generated has no gap beside it.
  *
  * Text or an element, because neither alone is the test. An element on its own
  * counts a whitespace-only span as content; text on its own counts an icon as

package/dist/utils/tell-disclosure/tell-disclosure.d.ts

@@ -1,16 +1,15 @@
 /**
  * Tells a slotted trigger that it opens something, and whether it is open.
  *
- * **Two components answered this by writing `aria-expanded` onto the consumer's
- * element, and that is a hydration mismatch.** `Megamenu` and `SpeedDial` both
- * did, each with a note saying why: a consumer who has to mirror `open` back
- * onto their own trigger is a consumer who will forget, and the failure is
- * silent to everyone who can see the screen. Both notes are right about the
- * gap. `Popover` refused to write anything, from the day it was written, on the
- * grounds that a component decorating a consumer's markup after upgrading is
- * one whose output a React consumer's hydration disagrees with.
+ * **Writing `aria-expanded` onto the consumer's element is a hydration
+ * mismatch, so it is not written.** The gap that answer was reaching for is
+ * real: a consumer who has to mirror `open` back onto their own trigger is a
+ * consumer who will forget, and the failure is silent to everyone who can see
+ * the screen. It is still the wrong answer, because a component decorating a
+ * consumer's markup after upgrading is one whose output a React consumer's
+ * hydration disagrees with.
  *
- * **Popover was right, measured 28 Aug 2026 against React 19.2.8.** Four
+ * **Measured 28 Aug 2026 against React 19.2.8.** Four
  * families were server-rendered as React emits them and hydrated with the
  * element definitions loaded either side of `hydrateRoot`:
  *
@@ -28,14 +27,12 @@
  * and rebuilding it, which is what the carousel's own note records blinding an
  * `<helix-aura>` two sections away.
  *
- * **A property crosses the gap that an attribute cannot, and this library
- * already knew it.** `Menu` tells its items by property "rather than an
- * attribute for that reason", in those words. React diffs the attributes it
- * rendered and never looks at a property, so the state reaches the trigger,
- * lands as `aria-expanded` inside *that element's* shadow root, and the
- * consumer's markup is exactly what they served. Both positions get what they
- * were protecting: nothing is written onto the consumer's element, and the
- * reader is still told what the control does.
+ * **A property crosses the gap that an attribute cannot.** React diffs the
+ * attributes it rendered and never looks at a property, so the state reaches
+ * the trigger, lands as `aria-expanded` inside *that element's* shadow root,
+ * and the consumer's markup is exactly what they served. Both positions get
+ * what they were protecting: nothing is written onto the consumer's element,
+ * and the reader is still told what the control does.
  *
  * **Set before upgrade is safe**, which is what lets this run without waiting
  * for a definition: `ReactiveElement` captures an instance property assigned
@@ -46,6 +43,6 @@
  * `<button slot="trigger">` has no shadow root to keep the state out of the
  * markup and no property to take it, and a consumer cannot mirror it themselves
  * because the open state belongs to the component. Saying so once is the same
- * answer `Tooltip` gives about the link it will not write for them. See #322.
+ * answer `Tooltip` gives about the link it will not write for them.
  */
 export declare const tellDisclosure: (trigger: Element | null | undefined, open: boolean) => void;

package/dist/utils/tell-disclosure/tell-disclosure.js

@@ -3,16 +3,15 @@ const warned = new WeakSet();
 /**
  * Tells a slotted trigger that it opens something, and whether it is open.
  *
- * **Two components answered this by writing `aria-expanded` onto the consumer's
- * element, and that is a hydration mismatch.** `Megamenu` and `SpeedDial` both
- * did, each with a note saying why: a consumer who has to mirror `open` back
- * onto their own trigger is a consumer who will forget, and the failure is
- * silent to everyone who can see the screen. Both notes are right about the
- * gap. `Popover` refused to write anything, from the day it was written, on the
- * grounds that a component decorating a consumer's markup after upgrading is
- * one whose output a React consumer's hydration disagrees with.
+ * **Writing `aria-expanded` onto the consumer's element is a hydration
+ * mismatch, so it is not written.** The gap that answer was reaching for is
+ * real: a consumer who has to mirror `open` back onto their own trigger is a
+ * consumer who will forget, and the failure is silent to everyone who can see
+ * the screen. It is still the wrong answer, because a component decorating a
+ * consumer's markup after upgrading is one whose output a React consumer's
+ * hydration disagrees with.
  *
- * **Popover was right, measured 28 Aug 2026 against React 19.2.8.** Four
+ * **Measured 28 Aug 2026 against React 19.2.8.** Four
  * families were server-rendered as React emits them and hydrated with the
  * element definitions loaded either side of `hydrateRoot`:
  *
@@ -30,14 +29,12 @@ const warned = new WeakSet();
  * and rebuilding it, which is what the carousel's own note records blinding an
  * `<helix-aura>` two sections away.
  *
- * **A property crosses the gap that an attribute cannot, and this library
- * already knew it.** `Menu` tells its items by property "rather than an
- * attribute for that reason", in those words. React diffs the attributes it
- * rendered and never looks at a property, so the state reaches the trigger,
- * lands as `aria-expanded` inside *that element's* shadow root, and the
- * consumer's markup is exactly what they served. Both positions get what they
- * were protecting: nothing is written onto the consumer's element, and the
- * reader is still told what the control does.
+ * **A property crosses the gap that an attribute cannot.** React diffs the
+ * attributes it rendered and never looks at a property, so the state reaches
+ * the trigger, lands as `aria-expanded` inside *that element's* shadow root,
+ * and the consumer's markup is exactly what they served. Both positions get
+ * what they were protecting: nothing is written onto the consumer's element,
+ * and the reader is still told what the control does.
  *
  * **Set before upgrade is safe**, which is what lets this run without waiting
  * for a definition: `ReactiveElement` captures an instance property assigned
@@ -48,7 +45,7 @@ const warned = new WeakSet();
  * `<button slot="trigger">` has no shadow root to keep the state out of the
  * markup and no property to take it, and a consumer cannot mirror it themselves
  * because the open state belongs to the component. Saying so once is the same
- * answer `Tooltip` gives about the link it will not write for them. See #322.
+ * answer `Tooltip` gives about the link it will not write for them.
  */
 export const tellDisclosure = (trigger, open) => {
     if (!trigger) {

package/dist/utils/tone-marks/tone-marks.d.ts

@@ -2,12 +2,10 @@ import { type HelixIcon } from '@fusion.dev/helix-icons';
 /**
  * The four status tones, as a type anything branching on them can take.
  *
- * **A subset of `tone` rather than an axis of its own, which is what the rename
- * records.** This was `HelixSeverity`, and `severity` turned out to be a sixth
- * spelling of the axis for what a thing *means*: `Callout` and `Toast.Item`
- * report a status and never a brand role, so they take four of the seven values
- * and not four values of their own. The components moved with #158; the
- * vocabulary underneath them was still saying the old word.
+ * **A subset of `tone` rather than an axis of its own.** A `severity` beside it
+ * would be a sixth spelling of the axis for what a thing *means*: `Callout` and
+ * `Toast.Item` report a status and never a brand role, so they take four of the
+ * seven values and not four values of their own.
  *
  * `Status` stays in the name because that is the half of `tone` these are: there
  * is no mark for `primary` or `accent`, a brand role having nothing to announce.
@@ -23,17 +21,13 @@ export interface ToneMark {
 /**
  * The one status vocabulary.
  *
- * It was two, defined identically in `Callout` and in `Toast.Item`, and only one
- * of the copies carried the comment saying the two must not drift. A reader
- * meets these marks in a passage and in a message and has to read them as the
- * same four things, so there is one place they come from.
+ * A reader meets these marks in a passage and in a message and has to read them
+ * as the same four things, so there is one place they come from.
  *
- * **Filled at every tone**, which is what it already was at one of them.
- * `danger` took `xCircleFill` and the other three took outlines, so a set meant
- * to be read as one vocabulary had one member drawn a different way. Filled
- * because a tone mark is a status indicator and not an action: it wants to
- * read at a glance and at a small size, where an outline at this weight loses
- * its interior.
+ * **Filled at every tone**, or a set meant to be read as one vocabulary has a
+ * member drawn a different way. Filled because a tone mark is a status
+ * indicator and not an action: it wants to read at a glance and at a small
+ * size, where an outline at this weight loses its interior.
  *
  * **The label is not the tone name.** `danger` is announced as "Error",
  * because that is the word a reader understands and `danger` is the word the API

package/dist/utils/tone-marks/tone-marks.js

@@ -2,17 +2,13 @@ import { checkCircleFill, infoFill, warningFill, xCircleFill, } from '@fusion.de
 /**
  * The one status vocabulary.
  *
- * It was two, defined identically in `Callout` and in `Toast.Item`, and only one
- * of the copies carried the comment saying the two must not drift. A reader
- * meets these marks in a passage and in a message and has to read them as the
- * same four things, so there is one place they come from.
+ * A reader meets these marks in a passage and in a message and has to read them
+ * as the same four things, so there is one place they come from.
  *
- * **Filled at every tone**, which is what it already was at one of them.
- * `danger` took `xCircleFill` and the other three took outlines, so a set meant
- * to be read as one vocabulary had one member drawn a different way. Filled
- * because a tone mark is a status indicator and not an action: it wants to
- * read at a glance and at a small size, where an outline at this weight loses
- * its interior.
+ * **Filled at every tone**, or a set meant to be read as one vocabulary has a
+ * member drawn a different way. Filled because a tone mark is a status
+ * indicator and not an action: it wants to read at a glance and at a small
+ * size, where an outline at this weight loses its interior.
  *
  * **The label is not the tone name.** `danger` is announced as "Error",
  * because that is the word a reader understands and `danger` is the word the API