@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,287 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { closestInstance, customElement, HelixElement, MixinCollection, MixinControllerActive, scrollItemIntoView, } from '@fusion.dev/helix-core';
+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',
+    'ArrowRight',
+    'ArrowLeft',
+    'Home',
+    'End',
+    '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. It was written
+           straight from the event, the same way Tabs did, which made `helix-before-activate`
+           an announcement nobody could 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.
+             *
+             * `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.
+             *
+             * `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. */
+            const current = closestInstance(event.target, HelixHeadlessTreeItem);
+            if (!current || !this.items.includes(current) || !KEYS.has(event.key)) {
+                return;
+            }
+            if (event.key === 'ArrowDown') {
+                this.move(current, 1);
+            }
+            else if (event.key === 'ArrowUp') {
+                this.move(current, -1);
+            }
+            else if (event.key === 'Home') {
+                this.focusOn(this.visibleItems[0]);
+            }
+            else if (event.key === 'End') {
+                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();
+                }
+                else if (current.isBranch) {
+                    this.move(current, 1);
+                }
+            }
+            else if (event.key === 'ArrowLeft') {
+                if (current.isBranch && current.open) {
+                    current.requestOpen(false);
+                    this.syncItems();
+                }
+                else {
+                    const parent = closestInstance(current.parentElement, HelixHeadlessTreeItem);
+                    this.focusOn(parent instanceof HelixHeadlessTreeItem ? parent : undefined);
+                }
+            }
+            else {
+                if (current.isBranch) {
+                    current.toggleOpen();
+                    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. */
+                    current.activate();
+                }
+            }
+            event.preventDefault();
+        };
+        /**
+         * 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.
+         */
+        this.handleBranch = () => {
+            this.syncItems();
+        };
+    }
+    /**
+     * 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.
+     *
+     * 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;
+            while (parent && parent !== this) {
+                if (parent instanceof HelixHeadlessTreeItem && !parent.open) {
+                    return false;
+                }
+                parent = parent.parentElement;
+            }
+            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. 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. */
+        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. */
+        const held = visible.find((item) => item.focusable);
+        const stop = held ?? chosen;
+        for (const item of this.items) {
+            item.selected = item.value !== '' && item.value === this.active;
+            item.focusable = item === stop;
+            let level = 1;
+            let parent = item.parentElement;
+            while (parent && parent !== this) {
+                if (parent instanceof HelixHeadlessTreeItem) {
+                    level += 1;
+                }
+                parent = parent.parentElement;
+            }
+            item.level = level;
+        }
+    }
+    move(from, delta) {
+        const visible = this.visibleItems;
+        const index = visible.indexOf(from);
+        const next = visible[Math.min(visible.length - 1, Math.max(0, index + delta))];
+        this.focusOn(next);
+    }
+    focusOn(item) {
+        if (!item) {
+            return;
+        }
+        for (const entry of this.items) {
+            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.
+     
+           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() {
+        super.connectedCallback();
+        this.addEventListener('helix-select', this.handleSelection);
+        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: 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. */
+        this.watcher = new MutationObserver(() => this.syncItems());
+        this.watcher.observe(this, { childList: true, subtree: true });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('helix-select', this.handleSelection);
+        this.removeEventListener('helix-before-open', this.handleBranch);
+        this.removeEventListener('helix-before-close', this.handleBranch);
+        this.removeEventListener('keydown', this.handleKeydown);
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.syncItems();
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('active')) {
+            this.syncItems();
+        }
+    }
+    render() {
+        return html `<div
+      part="tree"
+      role="tree"
+      aria-busy=${this.loading ? 'true' : nothing}
+      aria-label=${this.label}
+    >
+      <slot
+        @slotchange=${(event) => {
+            this.countRows(event);
+            this.syncItems();
+        }}
+      ></slot>
+      ${this.renderStatus(this.hasRows)}
+    </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTree.prototype, "label", void 0);
+HelixHeadlessTree = __decorate([
+    customElement('helix-headless-tree')
+], HelixHeadlessTree);
+export { HelixHeadlessTree };

package/dist/trend/index.d.ts

@@ -0,0 +1 @@
+export * from './root/trend-root.js';

package/dist/trend/index.js

@@ -0,0 +1 @@
+export * from './root/trend-root.js';

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

@@ -0,0 +1,67 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+/**
+ * @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. 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.
+ *
+ * The direction is also written as a word, because a coloured 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.
+ */
+export declare class HelixHeadlessTrend extends HelixElement {
+    /**
+     * Which way the measurement moved.
+     *
+     * Absent is neutral, so a trend with nothing to report draws a bar rather
+     * than picking a direction. Optional rather than defaulted for the reason
+     * `Stat.direction` is: a reflecting property with a default writes its
+     * attribute onto the host the moment the element upgrades, and the host is
+     * markup the consumer rendered, which React compares against what it rendered
+     * and reports as a hydration mismatch.
+     */
+    direction?: 'down' | 'neutral' | 'up';
+    /**
+     * Which direction is the improvement, for this metric.
+     *
+     * Absent states the movement without judging it, which is the honest default:
+     * revenue up is good news and latency up is bad news, and only the consumer
+     * knows which one this is. Set it once per metric and it holds while the
+     * direction changes underneath.
+     */
+    good?: 'down' | 'up';
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-trend': HelixHeadlessTrend;
+    }
+}

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

@@ -0,0 +1,106 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement } from '@fusion.dev/helix-core';
+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. 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.
+ *
+ * The direction is also written as a word, because a coloured 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. 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. */
+        /* 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. */
+        return html `<svg
+        aria-hidden="true"
+        data-glyph
+        fill="currentColor"
+        part="icon"
+        viewBox=${direction.icon.viewBox}
+      >
+        ${unsafeSVG(direction.icon.content)}
+      </svg>
+      <span part="direction">${`${direction.word}${judgment}`}</span>
+      <slot></slot>
+      <slot name="label"></slot>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessTrend.prototype, "direction", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessTrend.prototype, "good", void 0);
+HelixHeadlessTrend = __decorate([
+    customElement('helix-headless-trend')
+], HelixHeadlessTrend);
+export { HelixHeadlessTrend };

package/dist/video/index.d.ts

@@ -0,0 +1 @@
+export { HelixHeadlessVideo } from './root/video-root.js';

package/dist/video/index.js

@@ -0,0 +1 @@
+export { HelixHeadlessVideo } from './root/video-root.js';