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

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

@@ -42,37 +42,39 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessOption extends HelixElement {
     /**
-     * Whether this choice can be made.
+     * Whether this is the option the keyboard is on.
+     *
+     * Written by the listbox.
      */
-    disabled: boolean;
+    active: boolean;
     /**
-     * A second line under the words, for what the choice actually is.
+     * A second destination for this row, taken with the modifier held.
      *
-     * A palette row reads better as a name and a caption than as one sentence
-     * carrying both: "Helix" and "the design system" are two facts, and a comma
-     * between them makes a reader parse the punctuation to find where the name
-     * ends. Matching still reads the label, so what somebody types is matched
-     * against the name rather than against prose about it.
+     * **An attribute rather than a second row, which is the whole point.** A
+     * palette of eighty-eight components that offered each of them a reference
+     * page and a sandbox as separate entries would be a palette of a hundred and
+     * seventy-six, and one earns its keep by getting a reader to one thing in
+     * three keystrokes. The row already carries the first destination, so the
+     * second belongs beside it.
      *
-     * **A property and not a slot, which is the departure worth explaining.** The
-     * area rules say a content property is its slot's fallback, and that holds for
-     * a region always drawn: `Avatar`'s initials, `Tooltip`'s text. This one is
-     * usually absent, and a wrapped slot generates a box whether or not it is
-     * filled, so every option without a caption would carry an empty line. The
-     * detection that would avoid it does not exist, `:host(:has())` being invalid
-     * and the server having no children to inspect. A property is known at render
-     * time, so the component can decline to draw the box at all.
+     * Declared here and acted on by whatever owns the list, the same division
+     * selection already uses: an option says what it is and the listbox decides
+     * what happens. `Command` is the only owner that reads it today, because a
+     * select has one destination by definition.
      *
-     * It does not reflect, per the rule that payload state stays off the host: a
-     * string is not a fact a selector needs.
+     * Absent is a row with one destination, which is nearly every row.
      */
-    description?: string;
+    alternate: string;
     /**
-     * Whether this is the option the keyboard is on.
+     * What the second destination is, for a reader who cannot see the footer.
      *
-     * Written by the listbox.
+     * A row with two destinations needs both said, or a screen reader is told
+     * about one of them and the other is a key nobody mentioned. It goes to
+     * `aria-description` rather than into the name: the name is the row's own
+     * words and stays what a reader searched for, and the second destination is a
+     * fact about what pressing a key would do, which is what a description is.
      */
-    active: boolean;
+    alternateLabel: string;
     /**
      * Whether the markup declared this one chosen, which is what a reset returns to.
      *
@@ -93,11 +95,31 @@ export declare class HelixHeadlessOption extends HelixElement {
     /** What the markup said, read once at construction for the reason above. */
     private seeded;
     /**
-     * Whether this choice is currently chosen.
+     * A second line under the words, for what the choice actually is.
      *
-     * Written by the listbox.
+     * A palette row reads better as a name and a caption than as one sentence
+     * carrying both: "Helix" and "the design system" are two facts, and a comma
+     * between them makes a reader parse the punctuation to find where the name
+     * ends. Matching still reads the label, so what somebody types is matched
+     * against the name rather than against prose about it.
+     *
+     * **A property and not a slot, which is the departure worth explaining.** The
+     * area rules say a content property is its slot's fallback, and that holds for
+     * a region always drawn: `Avatar`'s initials, `Tooltip`'s text. This one is
+     * usually absent, and a wrapped slot generates a box whether or not it is
+     * filled, so every option without a caption would carry an empty line. The
+     * detection that would avoid it does not exist, `:host(:has())` being invalid
+     * and the server having no children to inspect. A property is known at render
+     * time, so the component can decline to draw the box at all.
+     *
+     * It does not reflect, per the rule that payload state stays off the host: a
+     * string is not a fact a selector needs.
      */
-    selected: boolean;
+    description?: string;
+    /**
+     * Whether this choice can be made.
+     */
+    disabled: boolean;
     /**
      * A shorter name for this choice, for where the row does not fit.
      *
@@ -108,37 +130,15 @@ export declare class HelixHeadlessOption extends HelixElement {
      */
     label: string;
     /**
-     * Identifies this choice, and is what a form submits.
-     */
-    value: string;
-    /**
-     * A second destination for this row, taken with the modifier held.
-     *
-     * **An attribute rather than a second row, which is the whole point.** A
-     * palette of eighty-eight components that offered each of them a reference
-     * page and a sandbox as separate entries would be a palette of a hundred and
-     * seventy-six, and one earns its keep by getting a reader to one thing in
-     * three keystrokes. The row already carries the first destination, so the
-     * second belongs beside it.
-     *
-     * Declared here and acted on by whatever owns the list, the same division
-     * selection already uses: an option says what it is and the listbox decides
-     * what happens. `Command` is the only owner that reads it today, because a
-     * select has one destination by definition.
+     * Whether this choice is currently chosen.
      *
-     * Absent is a row with one destination, which is nearly every row.
+     * Written by the listbox.
      */
-    alternate: string;
+    selected: boolean;
     /**
-     * What the second destination is, for a reader who cannot see the footer.
-     *
-     * A row with two destinations needs both said, or a screen reader is told
-     * about one of them and the other is a key nobody mentioned. It goes to
-     * `aria-description` rather than into the name: the name is the row's own
-     * words and stays what a reader searched for, and the second destination is a
-     * fact about what pressing a key would do, which is what a description is.
+     * Identifies this choice, and is what a form submits.
      */
-    alternateLabel: string;
+    value: string;
     /**
      * The words, for a listbox that has to match text against them.
      *
@@ -146,20 +146,19 @@ export declare class HelixHeadlessOption extends HelixElement {
      * the content is where a consumer naturally puts it and asking for both is
      * asking for two things to disagree.
      *
-     * **The default slot's content, not the element's.** This was
-     * `this.textContent`, which is every descendant text node an option holds,
-     * and an option holds three slots: the words, plus `start` for an icon and
-     * `end` for a shortcut or a count. Neither of those is what a reader
-     * searched for, and both were being run onto the end of it.
-     *
-     * **Six things read this and all six were wrong.** The collapsed field of
-     * Select and of Combobox show it, the listbox filters on it, Combobox
-     * matches typed text against it, completes inline from it, and labels a
-     * chosen tag with it. Measured on a font picker whose options carry a
-     * two-letter specimen in `end`: the field read `Noto Sans Linear BAg`, and
-     * typing `ag` matched 1,892 of 1,893 options, every row containing the
-     * sample. An option with a keyboard shortcut in its end slot has the same
-     * fault and a worse one, every row carrying one matching every letter of it.
+     * **The default slot's content, never `this.textContent`.** An option holds
+     * three slots: the words, plus `start` for an icon and `end` for a shortcut
+     * or a count. Neither of the latter two is what a reader searched for, and
+     * `textContent` runs both onto the end of it. Measured on a font picker whose
+     * options carry a two-letter specimen in `end`: the field read
+     * `Noto Sans Linear BAg`, and typing `ag` matched 1,892 of 1,893 options,
+     * every row containing the sample. An option with a keyboard shortcut in its
+     * end slot has the same fault and a worse one, every row carrying one matching
+     * every letter of it.
+     *
+     * Six things read this: the collapsed field of Select and of Combobox, the
+     * listbox's filter, Combobox's match against typed text, its inline
+     * completion, and the label on a chosen tag.
      *
      * A node goes to the default slot when it names no other, which is the rule
      * the platform applies at assignment. Asking the same question here rather
@@ -172,17 +171,17 @@ export declare class HelixHeadlessOption extends HelixElement {
     /**
      * Mirrors the chosen state where a stylesheet can select on it.
      *
-     * **A custom state and not the `selected` attribute it used to reflect.** The
-     * parent writes this: a listbox choosing a row, a tab strip moving the tab, a
-     * radio group answering for its set. Reflected, that put the element's own
-     * bookkeeping onto markup a consumer wrote and a consumer's server never sent,
-     * which React reconciles and reports as a mismatch, and which a serialized
-     * element pasted back declares as a choice nobody made. `ElementInternals`
-     * holds it instead, where it is not in the DOM at all.
+     * **A custom state, and never the `selected` attribute.** The parent writes
+     * this: a listbox choosing a row, a tab strip moving the tab, a radio group
+     * answering for its set. Reflected, that puts the element's own bookkeeping
+     * onto markup a consumer wrote and a consumer's server never sent, which React
+     * reconciles and reports as a mismatch, and which a serialized element pasted
+     * back declares as a choice nobody made. `ElementInternals` holds it instead,
+     * where it is not in the DOM at all.
      *
      * Reading `selected` is unaffected and so is writing it: the attribute still
      * seeds the property, which is what `<helix-option selected>` in a consumer's
-     * markup means. What stops is the write back. See 302 and 304.
+     * markup means. What stops is the write back.
      */
     protected willUpdate(changed: PropertyValues): void;
     protected render(): TemplateResult;

package/dist/option/root/option-root.js

@@ -50,37 +50,12 @@ import { property } from 'lit/decorators.js';
 let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether this choice can be made.
-         */
-        this.disabled = false;
         /**
          * Whether this is the option the keyboard is on.
          *
          * Written by the listbox.
          */
         this.active = false;
-        /** What the markup said, read once at construction for the reason above. */
-        this.seeded = this.hasAttribute('selected');
-        /**
-         * Whether this choice is currently chosen.
-         *
-         * Written by the listbox.
-         */
-        this.selected = false;
-        /**
-         * A shorter name for this choice, for where the row does not fit.
-         *
-         * `<option label>`'s own meaning: the text a chooser shows when it has less
-         * room than the row does, which is what a select's closed trigger has. Empty
-         * means the row's own content, which is the common case and is why this is not
-         * simply the accessible name.
-         */
-        this.label = '';
-        /**
-         * Identifies this choice, and is what a form submits.
-         */
-        this.value = '';
         /**
          * A second destination for this row, taken with the modifier held.
          *
@@ -109,6 +84,31 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
          * fact about what pressing a key would do, which is what a description is.
          */
         this.alternateLabel = '';
+        /** What the markup said, read once at construction for the reason above. */
+        this.seeded = this.hasAttribute('selected');
+        /**
+         * Whether this choice can be made.
+         */
+        this.disabled = false;
+        /**
+         * A shorter name for this choice, for where the row does not fit.
+         *
+         * `<option label>`'s own meaning: the text a chooser shows when it has less
+         * room than the row does, which is what a select's closed trigger has. Empty
+         * means the row's own content, which is the common case and is why this is not
+         * simply the accessible name.
+         */
+        this.label = '';
+        /**
+         * Whether this choice is currently chosen.
+         *
+         * Written by the listbox.
+         */
+        this.selected = false;
+        /**
+         * Identifies this choice, and is what a form submits.
+         */
+        this.value = '';
     }
     /**
      * Whether the markup declared this one chosen, which is what a reset returns to.
@@ -138,20 +138,19 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
      * the content is where a consumer naturally puts it and asking for both is
      * asking for two things to disagree.
      *
-     * **The default slot's content, not the element's.** This was
-     * `this.textContent`, which is every descendant text node an option holds,
-     * and an option holds three slots: the words, plus `start` for an icon and
-     * `end` for a shortcut or a count. Neither of those is what a reader
-     * searched for, and both were being run onto the end of it.
+     * **The default slot's content, never `this.textContent`.** An option holds
+     * three slots: the words, plus `start` for an icon and `end` for a shortcut
+     * or a count. Neither of the latter two is what a reader searched for, and
+     * `textContent` runs both onto the end of it. Measured on a font picker whose
+     * options carry a two-letter specimen in `end`: the field read
+     * `Noto Sans Linear BAg`, and typing `ag` matched 1,892 of 1,893 options,
+     * every row containing the sample. An option with a keyboard shortcut in its
+     * end slot has the same fault and a worse one, every row carrying one matching
+     * every letter of it.
      *
-     * **Six things read this and all six were wrong.** The collapsed field of
-     * Select and of Combobox show it, the listbox filters on it, Combobox
-     * matches typed text against it, completes inline from it, and labels a
-     * chosen tag with it. Measured on a font picker whose options carry a
-     * two-letter specimen in `end`: the field read `Noto Sans Linear BAg`, and
-     * typing `ag` matched 1,892 of 1,893 options, every row containing the
-     * sample. An option with a keyboard shortcut in its end slot has the same
-     * fault and a worse one, every row carrying one matching every letter of it.
+     * Six things read this: the collapsed field of Select and of Combobox, the
+     * listbox's filter, Combobox's match against typed text, its inline
+     * completion, and the label on a chosen tag.
      *
      * A node goes to the default slot when it names no other, which is the rule
      * the platform applies at assignment. Asking the same question here rather
@@ -175,17 +174,17 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
     /**
      * Mirrors the chosen state where a stylesheet can select on it.
      *
-     * **A custom state and not the `selected` attribute it used to reflect.** The
-     * parent writes this: a listbox choosing a row, a tab strip moving the tab, a
-     * radio group answering for its set. Reflected, that put the element's own
-     * bookkeeping onto markup a consumer wrote and a consumer's server never sent,
-     * which React reconciles and reports as a mismatch, and which a serialized
-     * element pasted back declares as a choice nobody made. `ElementInternals`
-     * holds it instead, where it is not in the DOM at all.
+     * **A custom state, and never the `selected` attribute.** The parent writes
+     * this: a listbox choosing a row, a tab strip moving the tab, a radio group
+     * answering for its set. Reflected, that puts the element's own bookkeeping
+     * onto markup a consumer wrote and a consumer's server never sent, which React
+     * reconciles and reports as a mismatch, and which a serialized element pasted
+     * back declares as a choice nobody made. `ElementInternals` holds it instead,
+     * where it is not in the DOM at all.
      *
      * Reading `selected` is unaffected and so is writing it: the attribute still
      * seeds the property, which is what `<helix-option selected>` in a consumer's
-     * markup means. What stops is the write back. See 302 and 304.
+     * markup means. What stops is the write back.
      */
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -202,11 +201,10 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
             this.alternate !== '' && this.alternateLabel !== '' ? this.alternateLabel : null;
         /* A pointer reaches `select()` the way every other choosable row in this
            library does, from a `@click` in its own template: `Tabs.Tab`,
-           `Tree.Item` and `Menu.Item` all bind one. This had none, and nothing else
-           listened for a click either, so an option could be chosen with the
-           keyboard and not with a mouse. A select was unusable with a pointer for
-           as long as it has existed, which nothing caught because every spec for it
-           chooses by calling `select()` or by pressing a key. */
+           `Tree.Item` and `Menu.Item` all bind one. Nothing else listens for a click
+           on an option, so removing this leaves a select the keyboard can use and a
+           pointer cannot. A spec that chooses by calling `select()` or by pressing a
+           key cannot tell the difference. */
         return html `<div part="item" @click=${() => this.select()}>
       <slot name="start"></slot>
       <span part="text">
@@ -218,29 +216,29 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
     }
 };
 __decorate([
-    property({ reflect: true, type: Boolean })
-], HelixHeadlessOption.prototype, "disabled", void 0);
+    property({ attribute: 'data-active', reflect: true, type: Boolean })
+], HelixHeadlessOption.prototype, "active", void 0);
 __decorate([
     property()
-], HelixHeadlessOption.prototype, "description", void 0);
+], HelixHeadlessOption.prototype, "alternate", void 0);
 __decorate([
-    property({ attribute: 'data-active', reflect: true, type: Boolean })
-], HelixHeadlessOption.prototype, "active", void 0);
+    property({ attribute: 'alternate-label' })
+], HelixHeadlessOption.prototype, "alternateLabel", void 0);
 __decorate([
-    property({ type: Boolean })
-], HelixHeadlessOption.prototype, "selected", void 0);
+    property()
+], HelixHeadlessOption.prototype, "description", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessOption.prototype, "disabled", void 0);
 __decorate([
     property()
 ], HelixHeadlessOption.prototype, "label", void 0);
 __decorate([
-    property()
-], HelixHeadlessOption.prototype, "value", void 0);
+    property({ type: Boolean })
+], HelixHeadlessOption.prototype, "selected", void 0);
 __decorate([
     property()
-], HelixHeadlessOption.prototype, "alternate", void 0);
-__decorate([
-    property({ attribute: 'alternate-label' })
-], HelixHeadlessOption.prototype, "alternateLabel", void 0);
+], HelixHeadlessOption.prototype, "value", void 0);
 HelixHeadlessOption = __decorate([
     customElement('helix-headless-option')
 ], HelixHeadlessOption);

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

@@ -4,13 +4,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Links to the headings on this page, marking the one being read.
  *
  * @description
- * A table of contents, named for the job. Three of the obvious names are taken
- * by things that are not this: `Outline` is a CSS property and the focus ring's
- * whole vocabulary, `Contents` is `display: contents` and the `content` part
- * half this library renders, and `TableOfContents` would sit beside `Table` and
- * `TableColumn` and read as a third part of that family. `Outline` sits beside
- * `Navigation`, which is the same job at the other scale: one navigates a site, the
- * other navigates a document.
+ * A table of contents, named for the job. It sits beside `Navigation`, which is
+ * the same job at the other scale: one navigates a site, the other navigates a
+ * document. `Contents` and `TableOfContents` are both taken by something else,
+ * `display: contents` and the `content` part in one case and the `Table` family
+ * in the other.
  *
  * **The links are the consumer's own anchors**, the same as `Navigation`. A router
  * renders its own `<a>` and cannot render one inside this shadow root, and the
@@ -52,18 +50,6 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessOutline extends HelixElement {
     private readonly indicator;
-    /**
-     * Accessible name for the navigation.
-     */
-    label: string;
-    /**
-     * How far below the top of the window a heading counts as reached, in pixels.
-     *
-     * The reading line. A page with a sticky masthead sets this to its height, or
-     * a little more: without it the current section changes as a heading slides
-     * under the chrome rather than as it reaches the top of what can be seen.
-     */
-    offset: number;
     /**
      * How a click on one of these links travels to its section.
      *
@@ -86,6 +72,18 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * JavaScript rather than CSS decides.
      */
     behavior: ScrollBehavior;
+    /**
+     * Accessible name for the navigation.
+     */
+    label: string;
+    /**
+     * How far below the top of the window a heading counts as reached, in pixels.
+     *
+     * The reading line. A page with a sticky masthead sets this to its height, or
+     * a little more: without it the current section changes as a heading slides
+     * under the chrome rather than as it reaches the top of what can be seen.
+     */
+    offset: number;
     /**
      * The id of the section being read, or empty before anything is measured.
      *
@@ -124,16 +122,16 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * leaves the position a hair under the height at the very bottom and an exact
      * comparison never fires.
      *
-     * **All three numbers off the same element**, which this did not do: it added
-     * `scrollY` and `innerHeight`, both of the window, and compared them against
-     * `documentElement.scrollHeight`. Those are one coordinate system only while
-     * the viewport is what scrolls, and the body takes that job the moment it
-     * becomes a scroll container. Measured on a page whose body is
+     * **All three numbers off the same element.** Adding the window's `scrollY`
+     * and `innerHeight` and comparing them against
+     * `documentElement.scrollHeight` mixes two coordinate systems, which agree
+     * only while the viewport is what scrolls, and the body takes that job the
+     * moment it becomes a scroll container. Measured on a page whose body is
      * `overflow: clip visible`, which is a pair CSS resolves by making the
      * `visible` axis `auto`: `documentElement.scrollTop` read 1126 at the bottom
      * of the page and `window.scrollY` read 240, so a contents rail never learned
-     * it had reached the end and its last item stayed unreachable. That page is
-     * this library's own base layer.
+     * it had reached the end and its last item stayed unreachable. This library's
+     * own base layer produces exactly that page.
      *
      * `clientHeight` rather than `innerHeight` for the same reason, and because it
      * is the one that excludes a scrollbar, which is what `scrollHeight` is
@@ -150,9 +148,6 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * The two things an `IntersectionObserver` cannot see, and one listener for
      * both.
      *
-     * This component's own note said the observer keeps the marker honest without
-     * a scroll listener. It was wrong twice.
-     *
      * *At the bottom*, arriving at the end of a page changes no intersection: a
      * short last section is fully visible long before the final pixel, so its
      * ratio reached 1 and stopped moving. Nothing fires for the scroll that ends
@@ -167,27 +162,25 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * heading has not crossed yet, and no callback follows for the rest of the
      * way.
      *
-     * There was a listener already, added for the first of those, and it compared
-     * two numbers and marked only when the answer *changed*. That was too clever
-     * by half: it fixed the bottom and could not fix the settle. Marking once per
-     * animation frame while a scroll is happening covers both and every other case
-     * of the same shape, and the cost is what `mark()` costs, a `getBoundingClientRect`
-     * per section on frames a reader is already scrolling through. Passive, and
-     * coalesced to one call per frame however many events arrive.
+     * Marking once per animation frame while a scroll is happening covers both,
+     * where a listener that marks only when its own comparison changes fixes the
+     * bottom and cannot fix the settle. The cost is what `mark()` costs, a
+     * `getBoundingClientRect` per section on frames a reader is already scrolling
+     * through. Passive, and coalesced to one call per frame however many events
+     * arrive.
      */
     private readonly handleScroll;
     /**
      * Gives every section the same reading line the marker uses.
      *
-     * `offset` described where the top of the readable area is and was read by
-     * exactly one thing, the marker. Click a link and the browser put the heading
-     * against the very top of the window, underneath the sticky masthead whose
-     * height the consumer had just finished measuring for us. So the component
-     * knew about the chrome when deciding what you were reading and forgot about
-     * it when taking you somewhere, which is the same number meaning two things.
+     * `offset` says where the top of the readable area is, so it has to govern
+     * where a click lands as much as what the marker calls current. Read by the
+     * marker alone, a click puts the heading against the very top of the window
+     * and underneath the sticky masthead the consumer measured the offset from,
+     * which is the same number meaning two things.
      *
      * `scroll-margin-block-start` rather than an interception, because it is the
-     * property the platform provides for exactly this and the UA honours it on
+     * property the platform provides for exactly this and the UA honors it on
      * ordinary fragment navigation, on `scrollIntoView`, and on a browser
      * restoring a position. Nothing has to be taken over to get it.
      *
@@ -212,7 +205,8 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * The thresholds are what make the trigger frequent enough: an observer fires
      * on entering and leaving, and a long section scrolled slowly crosses neither
      * for a long time. Asking for a callback at each quarter of visibility is
-     * cheap and keeps the marker honest without a scroll listener.
+     * cheap. It is still only a trigger: see `handleScroll` for the two cases no
+     * intersection can see.
      */
     private watch;
     /**