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

package/dist/tree/item/tree-item.js

@@ -13,14 +13,12 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
  * @summary One node in a tree.
  *
  * @description
- * **`open`, on `MixinControllerOpen`, where it was a bare `expanded` boolean.**
- * A branch showing its children is the same state a disclosure holds, and
- * `AccordionItem` has been on that mixin all along. Written here by hand it had
- * neither half of what the mixin gives: `this.expanded = !this.expanded`
- * announced nothing, so a consumer could not know a branch had opened, and
- * could not own the state either. `aria-expanded` is still what the row
- * renders, because that is the attribute a tree uses; the property is what
- * changed, not the semantics.
+ * **`open`, on `MixinControllerOpen`, rather than a bare boolean of its own.** A
+ * branch showing its children is the same state a disclosure holds, and
+ * `AccordionItem` is on that mixin too. A hand-written toggle announces nothing,
+ * so a consumer can neither know a branch opened nor own the state.
+ * `aria-expanded` is still what the row renders, because that is the attribute a
+ * tree uses; the property is what differs, not the semantics.
  *
  * An element rather than a slot because it owns state: whether it is open,
  * whether it is selected, and whether it is the one holding focus.
@@ -81,10 +79,6 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Identifies the item to the consumer, carried in `helix-select`.
-         */
-        this.value = '';
         /**
          * Where this node goes, which makes its row a real link.
          *
@@ -93,10 +87,6 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
          * current page on every item a consumer never asked to be one.
          */
         this.href = '';
-        /**
-         * Where the link opens, for the rare row that leaves the site.
-         */
-        this.target = '';
         /**
          * What the link declares about where it goes.
          *
@@ -111,16 +101,21 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
          *
          * Not reflected, for the reason `level` below gives in full: the tree assigns
          * this after it upgrades, so the attribute would be a change to markup the
-         * consumer rendered and hydration would report it. It reflected, one line
-         * from the paragraph saying why it must not.
+         * consumer rendered and hydration would report it. Mirroring to
+         * `data-selected` on the host instead is the same fault under another name.
          *
-         * The stylesheet reads it from the row inside this shadow root, which is the
-         * answer `level` gives one paragraph down: the indent it drives is written
-         * onto the row rather than onto the host, because the row is not part of the
-         * tree React hydrates. Mirroring to `data-selected` on the host instead was
-         * the same fault with a different name, and React said so.
+         * The stylesheet reads it from the row inside this shadow root, because the
+         * row is not part of the tree React hydrates.
          */
         this.selected = false;
+        /**
+         * Where the link opens, for the rare row that leaves the site.
+         */
+        this.target = '';
+        /**
+         * Identifies the item to the consumer, carried in `helix-select`.
+         */
+        this.value = '';
         /**
          * Whether this item holds the tree's single tab stop.
          */
@@ -142,14 +137,10 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
         };
         this.handleRowClick = (event) => {
             /* A press that landed on a link is that link's, whichever branch of this
-               runs. It was asked on one side and not the other, and the missing half
-               cost a feature: a row can hold a link in its `end` slot, which is what
-               the documentation sidebar puts there to get back to the index, and
-               pressing it collapsed the branch on the way out. Measured in Chrome,
-               `open` false and the route changed from the one press.
-        
-               "There is nowhere else for the press to mean" was true of a row holding
-               a label, and a slot is somewhere else. */
+               runs, and the test has to be made on both sides. A row can hold a link in
+               its `end` slot, and asked on one side only, pressing that link collapses
+               the branch on the way out: one press, `open` false and the route
+               changed. */
             const onLink = event.composedPath().some((node) => node instanceof HTMLAnchorElement);
             /* A branch that is also a link goes where it points, and its chevron is
                what opens it. A branch that is not toggles from anywhere in the row. */
@@ -195,10 +186,8 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
            every scrollable ancestor and reveal the element, which is
            `scrollIntoView` by another route and takes the page with it. The root
            calls `scrollItemIntoView` on the next line precisely to avoid that, and
-           without this the careful call was arriving after the thing it exists to
-           prevent had already happened. It was also hiding whether that util worked
-           at all: measured in Chrome, a tree in a scroller scrolled either way, so
-           the util could have been scrolling nothing and nobody would have seen. */
+           without this the careful call arrives after the thing it exists to
+           prevent has already happened. */
         this.renderRoot
             .querySelector(this.href === '' ? '[part="item"]' : '[part="row"]')
             ?.focus({ preventScroll: true });
@@ -212,9 +201,9 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
      *
      * Selecting and following are two things and this is where they meet, so the
      * pointer and the keyboard take one path to the same end. The tree calls this
-     * rather than `select` for the keyboard, which is what fixes Enter: a nav
-     * tree whose rows are links could be walked with the arrows and not entered,
-     * because choosing announced a value and nothing listened for it.
+     * rather than `select` for the keyboard, or a nav tree whose rows are links
+     * could be walked with the arrows and never entered: choosing announces a
+     * value and nothing listens for it.
      */
     activate() {
         this.select();
@@ -281,9 +270,9 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
     /**
      * 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
+     * **A custom state, never a reflected `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`
@@ -291,7 +280,7 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
      *
      * Reading `selected` is unaffected and so is writing it: the attribute still
      * seeds the property, which is what `<helix-tree-item 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);
@@ -307,8 +296,7 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
          * sibling, which is the navigation flavor of the pattern.
          *
          * Without one, nothing changes: the wrapper is the `treeitem` and holds the
-         * group, which is what an `<li>` holding a `<ul>` is, and what this was
-         * fixed to be when the group rendered outside the node it belonged to. */
+         * group, which is what an `<li>` holding a `<ul>` is. */
         const linked = this.href !== '';
         const level = this.level ?? 1;
         const expanded = this.branch ? (this.open ? 'true' : 'false') : nothing;
@@ -340,10 +328,10 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
                 style="--tree-level: ${level}"
                 @click=${this.handleRowClick}
               >${this.renderRow()}</div>`}
-        <!-- Inside the treeitem, not beside it. It rendered as a sibling, so
-             the row's \`aria-expanded\` described a group the row did not own and
-             the branch reported children it had no relationship to. The pattern
-             is \`treeitem\` containing \`group\`, which is also what an \`<li>\`
+        <!-- Inside the treeitem, not beside it. As a sibling, the row's
+             \`aria-expanded\` describes a group the row does not own and the
+             branch reports children it has no relationship to. The pattern is
+             \`treeitem\` containing \`group\`, which is also what an \`<li>\`
              holding a \`<ul>\` is. -->
         <div part="group" role="group" ?hidden=${!this.open}>
           <slot name="children"></slot>
@@ -351,15 +339,12 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
       </div>`;
     }
 };
-__decorate([
-    property()
-], HelixHeadlessTreeItem.prototype, "value", void 0);
 __decorate([
     property()
 ], HelixHeadlessTreeItem.prototype, "href", void 0);
 __decorate([
-    property()
-], HelixHeadlessTreeItem.prototype, "target", void 0);
+    property({ attribute: 'level', type: Number })
+], HelixHeadlessTreeItem.prototype, "level", void 0);
 __decorate([
     property()
 ], HelixHeadlessTreeItem.prototype, "rel", void 0);
@@ -367,8 +352,11 @@ __decorate([
     property({ type: Boolean })
 ], HelixHeadlessTreeItem.prototype, "selected", void 0);
 __decorate([
-    property({ attribute: 'level', type: Number })
-], HelixHeadlessTreeItem.prototype, "level", void 0);
+    property()
+], HelixHeadlessTreeItem.prototype, "target", void 0);
+__decorate([
+    property()
+], HelixHeadlessTreeItem.prototype, "value", void 0);
 __decorate([
     state()
 ], HelixHeadlessTreeItem.prototype, "focusable", void 0);

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

@@ -38,10 +38,9 @@ export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
     /**
      * Every item, in the order a reader moving down would meet them.
      *
-     * Selected by tag rather than by walking everything and filtering. `'*'` built
-     * an array of every descendant element in the tree, labels and icons and
-     * whatever a consumer slotted into a row included, and threw most of it away;
-     * on a tree of any size that is the array a single arrow press rebuilds.
+     * Selected by tag, never by `'*'` and a filter: this is the array a single
+     * arrow press rebuilds, and `'*'` makes it every descendant element in the
+     * tree, labels and icons and whatever a consumer slotted into a row included.
      *
      * The two tag names rather than `instanceof` on everything: a styled
      * `helix-tree-item` extends the base, so both names are needed, and the
@@ -66,12 +65,10 @@ export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
     /**
      * A branch opened or closed, whoever did it.
      *
-     * The keyboard paths called `syncItems` by hand and the pointer path did not,
-     * so collapsing a branch by clicking its chevron left the tab stop on a row
-     * inside the subtree that had just been hidden: the tree kept its one stop
-     * and the stop was on something nobody could see or reach. Listening for the
-     * item's own open events covers every way a branch can move, including a
-     * consumer setting `open` directly.
+     * Listening for the item's own open events rather than calling `syncItems`
+     * from each keyboard path: that misses the pointer, and collapsing a branch
+     * by clicking its chevron then leaves the tree's one tab stop on a row inside
+     * the subtree just hidden. It also covers a consumer setting `open` directly.
      */
     private readonly handleBranch;
     connectedCallback(): void;

package/dist/tree/root/tree-root.js

@@ -54,25 +54,24 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
          * Accessible name for the tree.
          */
         this.label = 'Tree';
-        /* Through the mixin, so a consumer can refuse the change. It was written
-           straight from the event, the same way Tabs did, which made `helix-before-activate`
-           an announcement nobody could answer. */
+        /* Through the mixin, so a consumer can refuse the change. Writing the value
+           straight from the event makes `helix-before-activate` an announcement
+           nobody can answer. */
         this.handleSelection = (event) => {
             this.requestActive(event.detail.value);
             this.syncItems();
         };
         this.handleKeydown = (event) => {
-            /* The innermost item the press came from, which `find` could not give.
+            /* The innermost item the press came from, which `find` cannot give.
              *
              * `items` is every tree item in document order and a nested one is inside
-             * all of its ancestors, so `entry.contains(target)` matched the outermost
-             * ancestor first: every key pressed on a nested node moved the root of its
-             * branch instead. The deeper the node, the further the answer was wrong,
-             * and the shallow cases it was written against all looked right.
+             * all of its ancestors, so `entry.contains(target)` matches the outermost
+             * ancestor first and every key pressed on a nested node moves the root of
+             * its branch instead. The shallow cases all look right.
              *
              * `closestInstance` walks up by identity and crosses shadow roots on the
-             * way, which is the util that exists for exactly this. `closest('*')` was
-             * also a no-op: it returns the element it was called on. */
+             * way, which is the util that exists for exactly this. `closest('*')` is a
+             * no-op: it returns the element it was called on. */
             const current = closestInstance(event.target, HelixHeadlessTreeItem);
             if (!current || !this.items.includes(current) || !KEYS.has(event.key)) {
                 return;
@@ -116,10 +115,10 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
                     this.syncItems();
                 }
                 else {
-                    /* `activate`, not `select`. Enter announced the choice and stopped
-                       there, so a tree used as navigation could be walked with the arrows
-                       and never entered: the pointer had a link under it to press and the
-                       keyboard had nothing. */
+                    /* `activate`, not `select`. Announcing the choice and stopping there
+                       leaves a tree used as navigation walkable with the arrows and never
+                       enterable: the pointer has a link under it and the keyboard has
+                       nothing. */
                     current.activate();
                 }
             }
@@ -128,12 +127,10 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         /**
          * A branch opened or closed, whoever did it.
          *
-         * The keyboard paths called `syncItems` by hand and the pointer path did not,
-         * so collapsing a branch by clicking its chevron left the tab stop on a row
-         * inside the subtree that had just been hidden: the tree kept its one stop
-         * and the stop was on something nobody could see or reach. Listening for the
-         * item's own open events covers every way a branch can move, including a
-         * consumer setting `open` directly.
+         * Listening for the item's own open events rather than calling `syncItems`
+         * from each keyboard path: that misses the pointer, and collapsing a branch
+         * by clicking its chevron then leaves the tree's one tab stop on a row inside
+         * the subtree just hidden. It also covers a consumer setting `open` directly.
          */
         this.handleBranch = () => {
             this.syncItems();
@@ -142,10 +139,9 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
     /**
      * Every item, in the order a reader moving down would meet them.
      *
-     * Selected by tag rather than by walking everything and filtering. `'*'` built
-     * an array of every descendant element in the tree, labels and icons and
-     * whatever a consumer slotted into a row included, and threw most of it away;
-     * on a tree of any size that is the array a single arrow press rebuilds.
+     * Selected by tag, never by `'*'` and a filter: this is the array a single
+     * arrow press rebuilds, and `'*'` makes it every descendant element in the
+     * tree, labels and icons and whatever a consumer slotted into a row included.
      *
      * The two tag names rather than `instanceof` on everything: a styled
      * `helix-tree-item` extends the base, so both names are needed, and the
@@ -178,16 +174,13 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
     syncItems() {
         const visible = this.visibleItems;
         /* Through the mixin, which resolves an exact match and otherwise falls back
-           to the first item. The comment here used to add "which skips a disabled
-           one", and a tree item has no `disabled` property at all, so the claim was
-           about a check that could not be running. `Tree.Item` is the only
-           selectable row in the library without one, which is worth knowing and is
-           not this line's business to fix. */
+           to the first item. No disabled rows are skipped, because `Tree.Item` is
+           the only selectable row in the library with no `disabled` property. */
         const chosen = this.resolveActive(visible);
-        /* The keyboard keeps its place. The stop was bound to the selection on
-           every sync, so a branch opening or a child arriving threw the reader back
-           to the selected row from wherever they had arrowed to. It only moves when
-           the row holding it is no longer reachable. */
+        /* The keyboard keeps its place: the stop moves only when the row holding it
+           is no longer reachable. Bound to the selection instead, a branch opening
+           or a child arriving throws the reader back to the selected row from
+           wherever they had arrowed to. */
         const held = visible.find((item) => item.focusable);
         const stop = held ?? chosen;
         for (const item of this.items) {
@@ -218,11 +211,9 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
             entry.focusable = entry === item;
         }
         item.focusItem();
-        /* And bring it into view, which arrow keys through a long tree did not do
-           at all: focus moved to an item below the fold and the tree stayed where
-           it was, so a reader navigating a sidebar of forty items was moving
-           something they could not see.
-     
+        /* And bring it into view, or focus lands below the fold and the tree stays
+           where it is.
+    
            Not `scrollIntoView`, which scrolls every scrollable ancestor including
            the page. A reader who pressed Down in a sidebar did not ask the document
            to move. */
@@ -235,10 +226,10 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         this.addEventListener('helix-before-close', this.handleBranch);
         this.addEventListener('keydown', this.handleKeydown);
         /* Nested items arrive on a *branch's* slot, not on this element's, so the
-           root's `slotchange` never fires for them: a subtree rendered after first
-           paint got no `level`, no `selected` and no `focusable`, and sat at the
-           wrong indent with no way into it. A framework filling a branch on demand,
-           which is what a lazy tree is, hit this every time. */
+           root's `slotchange` never fires for them: without this, a subtree
+           rendered after first paint gets no `level`, no `selected` and no
+           `focusable`, and sits at the wrong indent with no way into it. A
+           framework filling a branch on demand is exactly that case. */
         this.watcher = new MutationObserver(() => this.syncItems());
         this.watcher.observe(this, { childList: true, subtree: true });
     }

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

@@ -12,12 +12,10 @@ import { type TemplateResult } from 'lit';
  * **`good` is absent by default, so an unjudged trend is gray.** Every
  * dashboard convention says up is green, and for churn, latency, error rate,
  * cost and bounce rate that convention is a lie told in the most legible color
- * on the page. A component that guesses is wrong roughly a third of the time
- * and silent about it; one that waits to be told is uninformative until it is,
- * which is the cheaper failure. State the metric's polarity once and the
- * component does the part that varies.
+ * on the page. State the metric's polarity once and the component does the part
+ * that varies.
  *
- * The direction is also written as a word, because a coloured arrow says
+ * The direction is also written as a word, because a colored arrow says
  * nothing to a reader who is not looking at it. `part="direction"` is what the
  * styled tier clips out of sight and leaves in the accessibility tree.
  *

package/dist/trend/root/trend-root.js

@@ -35,12 +35,10 @@ const readDirection = (value) => DIRECTIONS[value] ?? DIRECTIONS.neutral;
  * **`good` is absent by default, so an unjudged trend is gray.** Every
  * dashboard convention says up is green, and for churn, latency, error rate,
  * cost and bounce rate that convention is a lie told in the most legible color
- * on the page. A component that guesses is wrong roughly a third of the time
- * and silent about it; one that waits to be told is uninformative until it is,
- * which is the cheaper failure. State the metric's polarity once and the
- * component does the part that varies.
+ * on the page. State the metric's polarity once and the component does the part
+ * that varies.
  *
- * The direction is also written as a word, because a coloured arrow says
+ * The direction is also written as a word, because a colored arrow says
  * nothing to a reader who is not looking at it. `part="direction"` is what the
  * styled tier clips out of sight and leaves in the accessibility tree.
  *
@@ -73,13 +71,11 @@ let HelixHeadlessTrend = class HelixHeadlessTrend extends HelixElement {
         /* One interpolation rather than two, so the phrase is one text node.
            Lit SSR writes a `<!--lit-part-->` marker around every binding, and two
            bindings put a pair of comments between "Up" and ", worse" in the served
-           markup. No screen reader is confused by adjacent text nodes, but the
-           server output should read as the thing the DOM will hold, and a test
-           against it should be able to say so in one string. */
+           markup, which a spec then cannot assert in one string. */
         /* Written out rather than through `drawIcon`, because this one needs a
            `part` and a part behind an interpolation is one the manifest cannot see:
            the helper's `part=${…}` binding took `[part="icon"]` out of the
-           stylesheet's reach and `check:selectors` said so. */
+           stylesheet's reach. */
         return html `<svg
         aria-hidden="true"
         data-glyph