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

package/dist/helix-element/helix-element.js

@@ -19,9 +19,8 @@ const BOX_SIZING = css `
  *
  * The UA stylesheet's `[hidden] { display: none }` is user-agent origin, so any
  * author declaration beats it, and a component whose `:host` sets a `display`
- * is doing exactly that. `<helix-grid hidden>` stayed visible; so did
- * `<helix-empty hidden>`, `<helix-flex hidden>` and fifty-four others. The
- * audit found three of them and the real count was fifty-seven, because every
+ * is doing exactly that. Fifty-seven components stayed visible while hidden,
+ * `<helix-grid>`, `<helix-empty>` and `<helix-flex>` among them, because every
  * component that lays itself out has the same fault and nothing connects them.
  *
  * Here rather than in each sheet, for the reason `box-sizing` is here: it is a
@@ -29,14 +28,13 @@ const BOX_SIZING = css `
  * forget the fifty-eighth.
  *
  * **The selector is (0,3,0) on purpose, and the obvious (0,2,0) is not enough.**
- * A bare `:host([hidden])` beats a bare `:host`, which is what the first version
- * of this rule assumed and it was wrong: six components set their `display` from
- * an attribute selector at the *same* (0,2,0) and win on source order because
- * they are injected after this. Measured, all five still rendered while hidden:
- * `flex[inline]` at `inline-flex`, `divider[orientation="vertical"]` at
- * `inline-block`, and `text[as]`, `checkbox[appearance="card"]` and
- * `radio[appearance="card"]` at `block`. The `:not()` lifts it a step and it
- * wins from first position, so the rule can stay prepended.
+ * A bare `:host([hidden])` beats a bare `:host`, but it only ties with the
+ * `:host([attr])` rules a component uses to set its own `display`, and those win
+ * on source order because they are injected after this. Measured, elements
+ * styled that way still rendered while hidden: `flex[inline]` at `inline-flex`,
+ * `divider[orientation="vertical"]` at `inline-block`, `text[as]` at `block`.
+ * The `:not()` lifts it a step and it wins from first position, so the rule can
+ * stay prepended.
  *
  * **And the `:not()` is load-bearing beyond specificity.** `hidden="until-found"`
  * is how the platform lets find-in-page reveal collapsed content: the browser
@@ -60,30 +58,25 @@ const HIDDEN = css `
  * so.** `overflow` is what creates a scrollport: without it `scrollTop` is
  * permanently zero and every scroll API on the element is inert. So a component
  * that reads `scrollTop` and cannot declare `overflow` is one whose behavior
- * lives in somebody else's stylesheet, and six of them do exactly that.
+ * lives in somebody else's stylesheet.
  *
  * Measured before deciding: `helix-headless-scroll-area`, the component whose
  * entire purpose is scrolling, computes `overflow-y: visible` on its viewport
- * with `scrollHeight` equal to `clientHeight`. Standing alone it is a div. The
- * virtual list was worse, because it *acts* on the reading: #174 is the day it
- * pegged a renderer measuring a box that could not scroll.
- *
- * **It goes here rather than in a stylesheet, because this is where the other
- * three already are.** `BOX_SIZING`, `HIDDEN` and `SETTLED` are token-free
- * structural rules `core` ships into every shadow root, and `HIDDEN` is the
- * exact same category: the rules argue `hidden` is base-tier state because the
- * platform acts on it, and the way the headless tier makes the platform act is a
- * CSS rule shipped from here. "The headless tier has no CSS" has never meant
- * `core` has none; it means `helix/headless` must not depend on
+ * with `scrollHeight` equal to `clientHeight`. Standing alone it is a div, and
+ * the virtual list is worse because it *acts* on the reading.
+ *
+ * **It goes here rather than in a stylesheet**, beside `BOX_SIZING`, `HIDDEN`
+ * and `SETTLED`, which are the token-free structural rules `core` ships into
+ * every shadow root. "The headless tier has no CSS" has never meant `core` has
+ * none; it means `helix/headless` must not depend on
  * `@fusion.dev/helix-styles`, and a rule with no token in it does not.
  *
  * **And a rule rather than an inline style, which was the first idea and is
  * wrong.** An inline `style` on a rendered part outranks every author rule
  * short of `!important`, so a consumer wanting `overflow: hidden` on that part
- * would have to fight it, and this repository's own notes say what that is: it
- * moves the fight onto consumers, who then need `!important` of their own. A
- * shadow rule loses to a document rule, so `::part(viewport) { overflow: … }`
- * from a consumer simply wins, which is the right way round.
+ * would have to fight it and would need `!important` of their own. A shadow rule
+ * loses to a document rule, so `::part(viewport) { overflow: … }` from a
+ * consumer simply wins, which is the right way round.
  *
  * Both axes, and nothing else. Which *kind* of scrolling, how much room,
  * `overscroll-behavior`, `scroll-snap`, a gutter, a scrollbar treatment: those
@@ -91,14 +84,13 @@ const HIDDEN = css `
  * styled sheet is prepended-after so it overrides at equal specificity anyway.
  *
  * **A component marks a box whose scroll state it reads, and no other**, which
- * is narrower than "every box that ends up scrolling" and is the line that took
- * a measurement to find. `Megamenu`'s panel scrolls, and only because the
- * styled tier gives it a `max-block-size`: that is a decision, the `overflow`
- * that serves it belongs with it, and the headless tier never asks the panel
- * where it is scrolled to. Marking it anyway moved a heading four pixels,
- * because `overflow` establishes a block formatting context and margins that
- * had been collapsing stopped. A mechanism with a layout consequence is one to
- * apply exactly where it is needed.
+ * is narrower than "every box that ends up scrolling". `Megamenu`'s panel
+ * scrolls, and only because the styled tier gives it a `max-block-size`: that is
+ * a decision, the `overflow` that serves it belongs with it, and the headless
+ * tier never asks the panel where it is scrolled to. Marking it anyway moved a
+ * heading four pixels, because `overflow` establishes a block formatting context
+ * and margins that had been collapsing stopped. A mechanism with a layout
+ * consequence is one to apply exactly where it is needed.
  *
  * Three qualify: `ScrollArea`, `VirtualList` and `Carousel`, each of which
  * reads `scrollTop` or `scrollLeft` and acts on the answer.
@@ -149,20 +141,13 @@ const SCROLLER = css `
  * resolved with transitions off, so enabling them changes nothing and there is
  * nothing left to animate.
  *
- * **`:state()` and not an attribute, and that was a bug for three routes before
- * it was a preference.** This was `[data-settled]`, written onto the host with
- * `setAttribute`, and the host is the element React owns. A definition that
- * lands during module evaluation has a frame to spend before React arrives, so
- * the element wrote its own bookkeeping onto itself and React then hydrated a
- * DOM that had gained an attribute since the server wrote it. Measured across
- * three routes at the time: `/helix` clean, `/helix/theme` one diff and
- * `/helix/sandbox` three, every one of them a `data-settled=""` no server sent.
- *
- * It was worked around three times, in `use-sandbox-editor.ts`, in the sandbox
- * barrel and again on the reference pages, each deferring a registration so the
- * frame fell the other side of hydration. Every one of those is a fix for the
- * timing rather than for the cause: the cause is that a component's private
- * bookkeeping was being kept somewhere React reconciles.
+ * **`:state()` and never an attribute.** The host is the element React owns, and
+ * a definition that lands during module evaluation has a frame to spend before
+ * React arrives, so an element writing `[data-settled]` onto its own host leaves
+ * React hydrating a DOM that gained an attribute since the server wrote it.
+ * Deferring a registration so the frame falls the other side of hydration is a
+ * fix for the timing rather than for the cause, which is that a component's
+ * private bookkeeping was being kept somewhere React reconciles.
  *
  * A custom state is not in the DOM. It carries the fact to this stylesheet and
  * nothing to the markup, so a server's output and a hydrated client's agree by
@@ -189,25 +174,25 @@ const REACT_PROPS = '__reactProps$';
  * would be a scan per keystroke. Re-scanned whenever the cached key comes back
  * empty, so a second React root with a suffix of its own still resolves.
  *
- * **A miss must not erase it, and it did.** The re-scan wrote its own result
- * back unconditionally, so any dispatch from a node React does not own found
- * nothing and set the key to `undefined`, and the next React-owned node paid
- * for a full scan again. Most elements in this library are rendered by Lit
- * inside a shadow root and are exactly that kind of node, so on a real page the
- * cache was being cleared constantly by the components least able to benefit
- * from it. Measured, 20,000 dispatches: 5.3ms with a warm cache against 20.3ms
- * alternating one owned node with one that is not, which is roughly twice the
- * per-dispatch cost for the half that should have been free.
+ * **A miss must not erase it.** A re-scan that writes its own result back
+ * unconditionally sets the key to `undefined` on every dispatch from a node
+ * React does not own, and the next React-owned node pays for a full scan again.
+ * Most elements in this library are rendered by Lit inside a shadow root and are
+ * exactly that kind of node, so the cache is cleared constantly by the
+ * components least able to benefit from it. Measured, 20,000 dispatches: 5.3ms
+ * with a warm cache against 20.3ms alternating one owned node with one that is
+ * not, roughly twice the per-dispatch cost for the half that should have been
+ * free.
  *
- * So a miss now leaves the cache alone and only a *different* key replaces it,
- * which keeps the second-React-root case the note above is about.
+ * So a miss leaves the cache alone and only a *different* key replaces it, which
+ * keeps the second-React-root case the note above is about.
  *
  * **What is left is a scan per dispatch on a page with no React at all**, since
  * there is no key to find and no honest way to conclude one will never appear:
  * a root can mount at any time, and memoizing "this node is not React's" would
  * silently disable the binding for any element that dispatches before React
  * commits, which is the exact failure this whole mechanism exists to repair.
- * It is around half a microsecond and it is filed rather than hidden. See #320.
+ * It is around half a microsecond and it is filed rather than hidden.
  */
 let reactPropsKey;
 /** The props React is holding for a node, if React is holding any. */
@@ -244,9 +229,9 @@ const REMOVED = new Set(['onActiveChange', 'onCheckedChange', 'onOpenChange', 'o
  * do reject a wrong *value* on a normal attribute. Measured with `tsc`.
  *
  * That leaves runtime as the only place a typo can be caught, and React's props
- * bag as the only place to look, which the binding above already reads. Once
- * per element, like the controlled-change audit, and for the same reason: a
- * warning that repeats on every keystroke is one a consumer silences.
+ * bag as the only place to look, which the binding above already reads. Once per
+ * element, because a warning that repeats on every keystroke is one a consumer
+ * silences.
  *
  * `on:helix-open` gets its own message because it is not a mistake so much as
  * the wrong dialect. It is what the Solid types offer, correctly, and React
@@ -284,7 +269,7 @@ const auditReactProps = (host, props) => {
            bubbling, but React binds an `on` prop by reading it as the element itself
            dispatches: one merely passing through never calls this host's own
            `dispatchEvent`, so the prop is recorded and never wired.
-        
+    
            Silent when nothing registered the tag, which is a component from outside
            this library or a package built before the map existed. */
         const mine = host instanceof Element ? eventsForTag(host.localName) : undefined;
@@ -353,7 +338,7 @@ const REACT_WIRES = new Set(['scroll', 'scrollend']);
  * React binds a hyphenated prop directly on the element, so our own events are
  * reached by name and are safe to bind again: same type, same callback, same
  * capture flag is a no-op by specification. A native name is different. React
- * recognises `onChange` and `onLoad` as its own registration names and attaches
+ * recognizes `onChange` and `onLoad` as its own registration names and attaches
  * nothing to the element for either; it relies on a delegated listener at the
  * root, which sees an event only if it **bubbles**, and on a non-delegated list
  * it sets up for `<video>`, `<audio>` and `<img>` and never for a custom
@@ -364,8 +349,7 @@ const REACT_WIRES = new Set(['scroll', 'scrollend']);
  * it and the consumer's handler runs twice. A non-bubbling relay arrives
  * nowhere, and is the bug this exists to close: `<helix-avatar>` relays `load`
  * and `error`, `<helix-video>` relays `ended`, `play` and `pause`, all of them
- * declared public API, all of them silent in React until now. An avatar
- * fallback is a shipped feature that did nothing.
+ * declared public API and all of them otherwise silent in React.
  *
  * The name is React's own casing, `onError` rather than `onerror`, because that
  * is what a consumer writes and therefore what is in the props bag. Every
@@ -422,9 +406,8 @@ const bindReactHandler = (host, event) => {
  * the element; the second is what keeps this to the properties that are actually
  * broken, rather than re-applying a string that is already correct. Three
  * qualify today, `rows` on the data table and `cell` and `compare` on a table
- * column, and the other ten `attribute: false` properties in the library are
- * booleans and strings a parent writes at runtime, which no consumer passes and
- * this never touches.
+ * column; the remaining `attribute: false` properties are booleans and strings a
+ * parent writes at runtime, which no consumer passes and this never touches.
  *
  * **`null` is the one place this does not reproduce a client mount, and it is
  * deliberate.** `typeof null` is `'object'`, and React assigns a null prop on a
@@ -488,13 +471,11 @@ export class HelixElement extends LitElement {
      * `helix-pagination-size` composes `helix-select`. One template says
      * `${this.tag('select')}` and each tier answers with its own name.
      *
-     * It was the public tag in both tiers, on the argument that each imports its
-     * own element under that name. That works and costs three things: the name
-     * means two different things depending on what a consumer imported, the
-     * headless tier composes an element it does not ship, and the composition
-     * cannot be tested there at all, because there is no `helix-select` on that
-     * tier to test it against. Thirty-nine specs had to be moved back to
-     * `helix/styled` for exactly that reason.
+     * **The public tag may not be the composed one, in either tier.** Using it
+     * costs three things: the name means two different things depending on what a
+     * consumer imported, the headless tier composes an element it does not ship,
+     * and the composition cannot be tested there at all, because there is no
+     * `helix-select` on that tier to test it against.
      *
      * **A prefix rather than an override per composition**, which was the first
      * plan and does not compile. An override re-renders the fragment from the
@@ -527,25 +508,27 @@ export class HelixElement extends LitElement {
      * fact to a stylesheet through `:state()` and leaves the markup alone, so the
      * server's output and the client's agree by construction.
      *
-     * `SETTLED` carries the long version of that argument and was the first to
-     * move. `checked`, `open`, `invalid` and `has-label` followed it on 27 Aug
-     * 2026, after the same fault was reported once more from the landing page's
-     * showcase: a `default-checked` switch, a `default-checked` checkbox and a
-     * `default-open` accordion item, each writing its own resolved state onto
-     * itself before React reached the node.
+     * `SETTLED` carries the long version of that argument; `checked`, `open`,
+     * `invalid` and `has-label` are recorded the same way, each of them a state a
+     * `default-*` attribute resolves before React reaches the node.
      *
-     * **The deferral that had been holding it is not a fix and could not be.**
-     * The site imports the definitions from an effect so the upgrades fall the
-     * other side of hydration, which works only while hydration is one pass:
-     * anything that splits it, a streamed segment or a suspended boundary, puts
-     * an upgrade back inside the window. Timing cannot be the guarantee when the
-     * fact is kept somewhere React reconciles.
+     * **Deferring the definitions is not a fix and could not be.** Importing them
+     * from an effect so the upgrades fall the other side of hydration works only
+     * while hydration is one pass: anything that splits it, a streamed segment or
+     * a suspended boundary, puts an upgrade back inside the window. Timing cannot
+     * be the guarantee when the fact is kept somewhere React reconciles.
      *
      * Feature-tested rather than assumed, the way `hostAria` tests element
      * references. An engine without `CustomStateSet` records nothing and keeps
-     * whatever the resting rule draws, which is the safe direction to fail, and
-     * Lit's server shim is one of them: a custom state is a fact about a running
-     * element, and a server has nothing to say about it.
+     * whatever the resting rule draws, which is the safe direction to fail.
+     *
+     * **Lit's server shim is no longer one of them**, and this said it was.
+     * `@lit-labs/ssr-dom-shim@1.6.0` sets `this.states = new Set()` in its
+     * `ElementInternals` constructor, so the guard passes on the server and a
+     * custom state is recorded where nothing reads it, which is harmless. The
+     * engines the test is for are browsers: Safari below 17.4 and Firefox below
+     * 126. There the write is a `TypeError`, so a component that bypasses this
+     * fails to render rather than rendering without whatever the state draws.
      */
     toggleState(name, on) {
         if ('states' in this.internals) {
@@ -643,9 +626,9 @@ export class HelixElement extends LitElement {
      * suppressing transitions.
      *
      * A frame later, not now: see `SETTLED` for why `firstUpdated` itself is too
-     * early. SSR never calls this, which is correct, because the attribute
-     * describes something that happened in a browser and the server has no frame
-     * to wait for.
+     * early. SSR never calls this, which is correct, because the state describes
+     * something that happened in a browser and the server has no frame to wait
+     * for.
      */
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -663,10 +646,10 @@ export class HelixElement extends LitElement {
             this.toggleState('settled', true);
             this.resolveSettled();
             /* **Audited here as well as at dispatch, and this is the half that catches
-               the real mistake.** The audit ran only from inside `dispatchEvent`, so an
-               element holding a handler prop and sending nothing was never looked at.
-               A prop on the wrong element is exactly the case where that element has no
-               reason to dispatch, so the check could not reach the thing it is for.
+               the real mistake.** From inside `dispatchEvent` alone, an element holding
+               a handler prop and sending nothing is never looked at, and a prop on the
+               wrong element is exactly the case where that element has no reason to
+               dispatch.
       
                A frame late, alongside the settled state, because React has to have
                committed its props for there to be anything to read. Once per element

package/dist/helix-form-element/helix-form-element.d.ts

@@ -30,25 +30,21 @@ export declare class HelixFormElement extends HelixElement {
      * `aria-disabled` rather than removing the element from the accessibility
      * tree, so a screen reader can still announce that the control exists.
      *
-     * The mirror is below and was for a while only a sentence: this paragraph
-     * described it, four components had their own copies of it, and the class
-     * itself did nothing. Here is where it belongs, because here is where
-     * `disabled` is.
+     * The mirror itself is in `willUpdate` below, here rather than in each
+     * control, because here is where `disabled` is.
      */
     disabled: boolean;
     /**
      * Whether an ancestor `<fieldset disabled>` has switched this control off.
      *
      * The platform tells a form-associated element through `formDisabledCallback`
-     * and nothing here implemented it, so a control inside a disabled fieldset
-     * stayed fully typeable and announced itself as enabled. Measured: a
-     * `helix-input` in one accepted text, reported `disabled` as false, and
-     * carried no `aria-disabled`.
+     * and nothing else does, so without this a control inside a disabled fieldset
+     * stays fully typeable and announces itself as enabled.
      *
-     * What the platform already did on its own is the submission half. The same
-     * measurement showed the fieldset's controls absent from the form's entry
-     * list and the host matching `:disabled`, so the value never went anywhere.
-     * What was missing is everything a reader can see or touch.
+     * The submission half is already the platform's: measured, the fieldset's
+     * controls are absent from the form's entry list and the host matches
+     * `:disabled`, so the value never goes anywhere. What is missing without this
+     * is everything a reader can see or touch.
      *
      * State rather than the `disabled` property. Writing that would reflect an
      * attribute the consumer's server markup does not have, which React reports
@@ -63,10 +59,9 @@ export declare class HelixFormElement extends HelixElement {
      * half of it the consumer wrote.
      *
      * @internal Read by the component itself and by nothing outside it: every
-     * call in the library is `this.isDisabled`. Public, it printed a row on
+     * call in the library is `this.isDisabled`. Public, it prints a row on
      * twenty-four families in both tiers, forty-eight in all, on every form
-     * control's reference page, and it is the largest single entry in those
-     * tables.
+     * control's reference page.
      *
      * **A consumer loses nothing, which was measured rather than assumed.**
      * `element.matches(':disabled')` answers the same question, is the platform's
@@ -133,8 +128,7 @@ export declare class HelixFormElement extends HelixElement {
      * there. It is only a change to the markup when a consumer assigns it
      * imperatively later, and nothing is hydrating by then.
      *
-     * Here rather than on each control, where it was declared eight times and
-     * reflected none of them.
+     * Here rather than on each control.
      */
     name: string;
     /**

package/dist/helix-form-element/helix-form-element.js

@@ -36,25 +36,21 @@ export class HelixFormElement extends HelixElement {
          * `aria-disabled` rather than removing the element from the accessibility
          * tree, so a screen reader can still announce that the control exists.
          *
-         * The mirror is below and was for a while only a sentence: this paragraph
-         * described it, four components had their own copies of it, and the class
-         * itself did nothing. Here is where it belongs, because here is where
-         * `disabled` is.
+         * The mirror itself is in `willUpdate` below, here rather than in each
+         * control, because here is where `disabled` is.
          */
         this.disabled = false;
         /**
          * Whether an ancestor `<fieldset disabled>` has switched this control off.
          *
          * The platform tells a form-associated element through `formDisabledCallback`
-         * and nothing here implemented it, so a control inside a disabled fieldset
-         * stayed fully typeable and announced itself as enabled. Measured: a
-         * `helix-input` in one accepted text, reported `disabled` as false, and
-         * carried no `aria-disabled`.
+         * and nothing else does, so without this a control inside a disabled fieldset
+         * stays fully typeable and announces itself as enabled.
          *
-         * What the platform already did on its own is the submission half. The same
-         * measurement showed the fieldset's controls absent from the form's entry
-         * list and the host matching `:disabled`, so the value never went anywhere.
-         * What was missing is everything a reader can see or touch.
+         * The submission half is already the platform's: measured, the fieldset's
+         * controls are absent from the form's entry list and the host matches
+         * `:disabled`, so the value never goes anywhere. What is missing without this
+         * is everything a reader can see or touch.
          *
          * State rather than the `disabled` property. Writing that would reflect an
          * attribute the consumer's server markup does not have, which React reports
@@ -78,8 +74,7 @@ export class HelixFormElement extends HelixElement {
          * there. It is only a change to the markup when a consumer assigns it
          * imperatively later, and nothing is hydrating by then.
          *
-         * Here rather than on each control, where it was declared eight times and
-         * reflected none of them.
+         * Here rather than on each control.
          */
         this.name = '';
     }
@@ -92,10 +87,9 @@ export class HelixFormElement extends HelixElement {
      * half of it the consumer wrote.
      *
      * @internal Read by the component itself and by nothing outside it: every
-     * call in the library is `this.isDisabled`. Public, it printed a row on
+     * call in the library is `this.isDisabled`. Public, it prints a row on
      * twenty-four families in both tiers, forty-eight in all, on every form
-     * control's reference page, and it is the largest single entry in those
-     * tables.
+     * control's reference page.
      *
      * **A consumer loses nothing, which was measured rather than assumed.**
      * `element.matches(':disabled')` answers the same question, is the platform's
@@ -181,10 +175,10 @@ __decorate([
     property({
         /* Empty means absent, which plain reflection cannot say. `name = ''` is the
            default and Lit reflects it as `name=""`, so every button, switch and
-           calendar in the library shipped an empty name attribute the consumer
-           never wrote, and six SSR specs said so. Returning `null` removes the
-           attribute instead. Same trap `hostAria` exists for: a name of no
-           characters is not the absence of one. */
+           calendar in the library would ship an empty name attribute the consumer
+           never wrote. Returning `null` removes the attribute instead. Same trap
+           `hostAria` exists for: a name of no characters is not the absence of
+           one. */
         converter: {
             fromAttribute: (value) => value ?? '',
             toAttribute: (value) => (value === '' ? null : value),

package/dist/mixins/mixin-chart-source/mixin-chart-source.d.ts

@@ -3,13 +3,12 @@ import type { HelixElement } from '../../helix-element/helix-element.js';
 import { type Row, type Series } from '../../utils/read-series/read-series.js';
 type Constructor<T> = new (...args: any[]) => T;
 /**
- * How many colours the series palette has, and so where it starts over.
+ * How many colors the series palette has, and so where it starts over.
  *
- * Here rather than in each chart, which is what it was. Four families held the
- * same `const PALETTE = 24` and the legend held a fifth: when the palette went
- * from eight to twenty-four, one of them was missed and drew every ninth series
- * in the first color again while the legend beside it named the ninth. A
- * number two files have to agree on is a number that will stop agreeing.
+ * Here rather than in each chart, because a number two files have to agree on
+ * is a number that will stop agreeing: when the palette went from eight to
+ * twenty-four, one of five copies was missed and drew every ninth series in the
+ * first color while the legend beside it named the ninth.
  */
 export declare const PALETTE = 24;
 /** The palette slot for the nth series, counting from one and wrapping. */
@@ -41,8 +40,7 @@ export declare const seriesIndex: (depth: number) => number;
  *
  * Declared here because this is where `seriesIndex` and `PALETTE` live, and
  * because a hook repeated on four families is a hook four families have to keep
- * agreeing about, which is the mistake the `PALETTE` comment above already
- * records somebody making.
+ * agreeing about.
  *
  * The numbered twenty-four are the seam between the tiers: `chart/series.css`
  * points each at a semantic token, which is a decision and so belongs to the
@@ -118,12 +116,6 @@ export declare class MixinChartSourceInterface {
 /**
  * The half of a chart that is about finding its numbers rather than drawing.
  *
- * Four families had written this out separately, and the row that asked for it
- * set the bar: two copies is a coincidence and three is a pattern. There were
- * five copies of `for`, four of `label` and three of the caption fallback by the
- * time the line and donut charts landed, which is why this arrives now and not
- * when the second chart did.
- *
  * **A mixin rather than a controller**, by the rule the tier notes give: it
  * introduces `for` and `label`, which a consumer writes. `SourceController` is
  * the other half and stays a controller, because resolving an id and watching

package/dist/mixins/mixin-chart-source/mixin-chart-source.js

@@ -9,13 +9,12 @@ import { ChartPointerController } from '../../controllers/chart-pointer-controll
 import { SourceController } from '../../controllers/source-controller/source-controller.js';
 import { readRows, readSeries } from '../../utils/read-series/read-series.js';
 /**
- * How many colours the series palette has, and so where it starts over.
+ * How many colors the series palette has, and so where it starts over.
  *
- * Here rather than in each chart, which is what it was. Four families held the
- * same `const PALETTE = 24` and the legend held a fifth: when the palette went
- * from eight to twenty-four, one of them was missed and drew every ninth series
- * in the first color again while the legend beside it named the ninth. A
- * number two files have to agree on is a number that will stop agreeing.
+ * Here rather than in each chart, because a number two files have to agree on
+ * is a number that will stop agreeing: when the palette went from eight to
+ * twenty-four, one of five copies was missed and drew every ninth series in the
+ * first color while the legend beside it named the ninth.
  */
 export const PALETTE = 24;
 /** The palette slot for the nth series, counting from one and wrapping. */
@@ -23,12 +22,6 @@ export const seriesIndex = (depth) => (depth % PALETTE) + 1;
 /**
  * The half of a chart that is about finding its numbers rather than drawing.
  *
- * Four families had written this out separately, and the row that asked for it
- * set the bar: two copies is a coincidence and three is a pattern. There were
- * five copies of `for`, four of `label` and three of the caption fallback by the
- * time the line and donut charts landed, which is why this arrives now and not
- * when the second chart did.
- *
  * **A mixin rather than a controller**, by the rule the tier notes give: it
  * introduces `for` and `label`, which a consumer writes. `SourceController` is
  * the other half and stays a controller, because resolving an id and watching
@@ -76,11 +69,8 @@ export const MixinChartSource = (Base) => {
          * Re-resolves when the chart is pointed at a different table.
          *
          * `SourceController` watches whatever it resolved on connect, and nothing
-         * tells it the id changed. `BarChart` had this and `LineChart` and
-         * `DonutChart` did not, which is the kind of difference that survives
-         * precisely because each file looked complete on its own: pointing a bar
-         * chart at a second table worked and pointing a line chart at one left it
-         * drawing the first. Extracting the four found it.
+         * tells it the id changed. Without this, pointing a chart at a second table
+         * leaves it drawing the first, silently.
          */
         willUpdate(changed) {
             super.willUpdate(changed);
@@ -112,14 +102,11 @@ export const MixinChartSource = (Base) => {
          * what the table says, which is `$128k` and not `128000`, and often wants
          * the column beside it that nothing plotted at all.
          *
-         * **Not `rows`, and the rename is the whole point of this paragraph.** It
-         * is the source table's rows, and `rows` on a chart is a name a chart
-         * wants for itself: `helix-heatmap` takes `rows="7"` to mean a calendar
-         * week, and declaring that against a base class whose `rows` is a `Row[]`
-         * getter is a type error at best. The same fault `MixinCollection` had,
-         * where a slot counter called `rows` would have shared one field with a
-         * consumer's data property. Name the member for what it holds rather than
-         * for the shortest word available.
+         * **Not `rows`.** It is the source table's rows, and `rows` on a chart is a
+         * name a chart wants for itself: `helix-heatmap` takes `rows="7"` to mean a
+         * calendar week, and declaring that against a base class whose `rows` is a
+         * `Row[]` getter is a type error at best. Name the member for what it holds
+         * rather than for the shortest word available.
          */
         get sourceRows() {
             const element = this.source.element;

package/dist/mixins/mixin-collection/mixin-collection.d.ts

@@ -32,9 +32,7 @@ export declare class CollectionElement {
  * **Empty and loading are different answers and a reader can tell them apart.**
  * "No results" under a spinner is a lie for as long as the request is in
  * flight, and a blank box is not an answer at all: a reader cannot know whether
- * a list is empty, still arriving, or broken. Six components each rendered rows
- * and none of them said either thing, so every consumer wrote their own and
- * wrote it differently.
+ * a list is empty, still arriving, or broken.
  *
  * **`aria-busy` on the collection, not on the message.** A reader with a screen
  * reader is told the region is changing and then told once, politely, what it
@@ -46,10 +44,6 @@ export declare class CollectionElement {
  * which question it is answering, and this is the point in a component's life
  * when a consumer is most likely to be looking at stale content.
  *
- * Listbox had `empty-text` and nothing else, and Combobox forwarded it. Both
- * keep the name, so nothing a consumer wrote has moved.
- *
- *
  * **`empty` and `loading` are documented on each of the five families that
  * apply this, rather than here.** See `MixinField` for why a class-level tag on
  * a mixin reaches no manifest.