@fusion.dev/helix-headless 0.1.0 → 0.3.0

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

@@ -8,7 +8,6 @@ import { closestInstance, customElement, HelixElement, MixinCollection, MixinCon
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessTreeItem } from '../item/tree-item.js';
-/** Keys the tree handles, per the APG tree pattern. */
 const KEYS = new Set([
     'ArrowDown',
     'ArrowUp',
@@ -19,59 +18,15 @@ const KEYS = new Set([
     'Enter',
     ' ',
 ]);
-/**
- * @summary A tree of items, navigable entirely from the keyboard.
- *
- * @description
- * Focus is a single tab stop, moved with the arrow keys, which is what the tree
- * pattern requires: a sidebar of forty items should not be forty presses of Tab
- * to get past. The tree owns which item is the tab stop and moves it as focus
- * moves, so the browser's own focus order is never fought with.
- *
- * Items are found with `instanceof`, never by tag name, so the headless tier
- * does not learn about the styled one.
- *
- * @since 0.1.0
- * @status experimental
- * @category navigation
- * @aliases FileTree, Navigation tree
- * @documentation https://helix.fusion.dev/components/tree
- *
- * @slot - The tree's items.
- *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current node moves, and cancelable. The only way to refuse one.
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Dispatched by the item and listened for here, because the tree is what a consumer holds a reference to. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart empty - Shown when there are no rows to show.
- * @csspart loading - Shown while the rows are still on their way.
- * @csspart tree - The tree container.
- */
 let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinControllerActive(HelixElement)) {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the tree.
-         */
         this.label = 'Tree';
-        /* 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` cannot give.
-             *
-             * `items` is every tree item in document order and a nested one is inside
-             * 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('*')` 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;
@@ -89,8 +44,6 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
                 this.focusOn(this.visibleItems.at(-1));
             }
             else if (event.key === 'ArrowRight') {
-                // Open a closed branch, then step into it. Two presses rather than one
-                // that does both, which is what the pattern specifies.
                 if (current.isBranch && !current.open) {
                     current.requestOpen(true);
                     this.syncItems();
@@ -115,43 +68,18 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
                     this.syncItems();
                 }
                 else {
-                    /* `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();
                 }
             }
             event.preventDefault();
         };
-        /**
-         * A branch opened or closed, whoever did it.
-         *
-         * 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();
         };
     }
-    /**
-     * Every item, in the order a reader moving down would meet them.
-     *
-     * 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
-     * `instanceof` stays as the type guard because a consumer can write either
-     * tag and neither selector proves what the element is.
-     */
     get items() {
         return [...this.querySelectorAll('helix-tree-item, helix-headless-tree-item')].filter((node) => node instanceof HelixHeadlessTreeItem);
     }
-    /** Items a reader can actually reach: not inside a collapsed branch. */
     get visibleItems() {
         return this.items.filter((item) => {
             let parent = item.parentElement;
@@ -164,23 +92,9 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
             return true;
         });
     }
-    /**
-     * Pushes tree-owned state down: which item is selected, which holds the tab
-     * stop, and how deep each one sits.
-     *
-     * Depth is computed here rather than by each item counting its own ancestors,
-     * so an item moved in the tree gets the right indent without knowing it moved.
-     */
     syncItems() {
         const visible = this.visibleItems;
-        /* Through the mixin, which resolves an exact match and otherwise falls back
-           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 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) {
@@ -211,12 +125,6 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
             entry.focusable = entry === item;
         }
         item.focusItem();
-        /* 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. */
         scrollItemIntoView(item, { padding: 4 });
     }
     connectedCallback() {
@@ -225,11 +133,6 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         this.addEventListener('helix-before-open', this.handleBranch);
         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: 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.js

@@ -9,73 +9,20 @@ import { arrowDown, arrowUp, minus } from '@fusion.dev/helix-icons';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/** The three directions a measurement can have moved, and how each is drawn. */
 const DIRECTIONS = {
     down: { icon: arrowDown, word: 'Down' },
     neutral: { icon: minus, word: 'Unchanged' },
     up: { icon: arrowUp, word: 'Up' },
 };
-/**
- * Reads the direction, treating an absent or unrecognised one as neutral.
- *
- * The cast is a lie the fallback catches: an attribute is a string and a
- * consumer can write anything into it, so an unrecognised word has to draw
- * something rather than fail to index and throw inside `render`.
- */
 const readDirection = (value) => DIRECTIONS[value] ?? DIRECTIONS.neutral;
-/**
- * @summary Which way a measurement moved, and whether that is good news.
- *
- * @description
- * Three parts: a direction that is up, down or neutral, the metric that moved,
- * and a label saying over what. The arrow carries the direction and its color
- * carries the judgment, and the two are separate properties because they are
- * separate facts.
- *
- * **`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. State the metric's polarity once and the component does the part
- * that varies.
- *
- * 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.
- *
- * Both the metric and the label are bare slots. An element whose only job is to
- * assign itself a slot on connect gives its own host an attribute after
- * upgrade, which a React consumer's server markup never had.
- *
- * @since 0.1.0
- * @status stable
- * @category charts
- * @aliases Delta, Change, Movement
- * @documentation https://helix.fusion.dev/components/trend
- *
- * @slot - The metric that moved.
- * @slot label - What it moved over.
- *
- * @csspart direction - The direction as a word, for readers who are not looking.
- * @csspart icon - The arrow.
- */
 let HelixHeadlessTrend = class HelixHeadlessTrend extends HelixElement {
     render() {
         const direction = readDirection(this.direction);
-        /* Silent on a neutral move, whatever `good` says. Neither better nor worse
-           is a reading of "unchanged" that the word already carries. */
         const judgment = this.good && this.direction && this.direction !== 'neutral'
             ? this.good === this.direction
                 ? ', better'
                 : ', worse'
             : '';
-        /* 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, 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. */
         return html `<svg
         aria-hidden="true"
         data-glyph

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

@@ -26,19 +26,15 @@ import '../../menu/index.js';
  * The keys are the ones every player uses: Space and `k` to play or pause, the
  * arrows to seek and to change the volume, `m` to mute, `f` for fullscreen.
  * They are bound on this element rather than on the document, because a video
- * is not a palette: keys belong to it only while a reader is on it.
+ * is not a palette: keys belong to it only while a reader is on it. Where
+ * `controls` is set they are not bound at all, since two handlers on one press
+ * is a video that seeks twice, and the focus stop goes with them.
  *
- * **And none of them where `controls` is set.** The browser's own bar owns
- * those keys, and two handlers on one press is a video that seeks twice or
- * plays and immediately pauses. The focus stop goes with them, since the native
- * controls bring their own.
- *
- * **`<source>` and `<track>` are copied into the video, not slotted into it.**
- * A media element runs its resource selection over its own child *nodes*, and a
- * slot is one node: the sources and the caption tracks a consumer wrote were
- * assigned into the flattened tree and the video never saw any of them. It had
- * no text tracks, no current source and a `readyState` of zero, so a video
- * given sources this way did not merely lack captions, it did not play.
+ * **`<source>` and `<track>` are copied into the video, never slotted into it.**
+ * A media element runs resource selection over its own child *nodes*, and a slot
+ * is one node, so slotted sources reach it as nothing: no text tracks, no
+ * current source, `readyState` zero. A video given sources that way does not
+ * merely lack captions, it does not play.
  *
  * They are copied rather than moved, because the consumer's light DOM is theirs
  * and a framework that re-renders it would find its children gone. The copies