@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,381 @@
+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, HelixSelectEvent, MixinControllerOpen, } from '@fusion.dev/helix-core';
+import { caretDown } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+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.
+ *
+ * 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.
+ *
+ * A branch is any item with something slotted into `children`, detected in
+ * `firstUpdated` rather than declared by the consumer. That is a client-side
+ * enhancement by necessity, since the server cannot inspect children, so the
+ * server renders the node as a leaf and the twisty appears on hydration. It
+ * appears rather than disappearing, which is the harmless direction.
+ *
+ * **`href` makes the row itself the link.** A tree used as navigation is a list
+ * of links, and the row is what a reader presses: with the anchor slotted into
+ * the name instead, everything outside the words is dead, Enter does nothing,
+ * and there is no middle-click, no status bar and no open-in-new-tab. Given an
+ * `href` the row *is* an `<a>`, so the platform provides all of that and the
+ * keyboard needs no handler at all.
+ *
+ * It changes the shape of the ARIA, which is why it is a property and not the
+ * default. An anchor cannot contain the group, since the group holds more
+ * anchors and nesting them is invalid, so the row carries `treeitem` and the
+ * group becomes its sibling under a presentational wrapper. That is exactly the
+ * navigation flavor of the tree pattern, and the arrangement without an `href`
+ * stays as it was: `treeitem` containing `group`, which is what an `<li>`
+ * holding a `<ul>` is.
+ *
+ * A consumer whose framework owns routing slots its own link instead and leaves
+ * `href` unset. The row follows that one too, so the whole row works either
+ * way; what the anchor adds is what only a real anchor can give.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases TreeNode, Branch, Leaf
+ * @documentation https://helix.fusion.dev/components/tree
+ *
+ * @slot - The item's label.
+ * @slot children - Nested items, which make this a branch.
+ * @slot end - After the label, at the row's far side. A count, or a state.
+ * @slot start - Before the label, after the chevron. A mark about the item.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before a branch closes, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before a branch opens, and cancelable.
+ * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart group - The container for nested items.
+ * @csspart item - The node, and the focus target unless `href` moves it to the row.
+ * @csspart label - The label text.
+ * @csspart row - The clickable label row, which is an `<a>` where `href` is set.
+ * @csspart toggle - The expand and collapse control.
+ *
+ * @cssproperty --tree-level - How deep this row sits, counting from zero, for the indent.
+ */
+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.
+         *
+         * Unset by default, and unreflected: a tree of choosable nodes is not a tree
+         * of links, and an empty `href` written onto every row would be a link to the
+         * 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.
+         *
+         * Set by the consumer rather than derived from `target`: `noreferrer` is a
+         * decision about their own analytics and a component should not make it for
+         * them. `noopener` is not needed as a default either, since every browser
+         * this library supports implies it for `target="_blank"` already.
+         */
+        this.rel = '';
+        /**
+         * Whether this item is the current one.
+         *
+         * 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.
+         *
+         * 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.
+         */
+        this.selected = false;
+        /**
+         * Whether this item holds the tree's single tab stop.
+         */
+        this.focusable = false;
+        /**
+         * Whether anything is slotted into `children`.
+         *
+         * Read after first render.
+         */
+        this.branch = false;
+        this.handleToggleClick = (event) => {
+            /* Only where the row is a link, and then it has to stop: the row would
+               navigate away from the branch the reader was trying to open. Without an
+               `href` the whole row toggles, which is what a tree of folders wants, so
+               there is nothing here to intercept. */
+            event.preventDefault();
+            event.stopPropagation();
+            this.toggleOpen();
+        };
+        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. */
+            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. */
+            if (this.branch && this.href === '') {
+                if (!onLink) {
+                    this.toggleOpen();
+                }
+                return;
+            }
+            this.select();
+            /* Following it here as well would follow it twice and, where a consumer's
+               router is listening, route twice. */
+            if (!onLink) {
+                this.follow();
+            }
+        };
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        const slot = this.renderRoot.querySelector('slot[name="children"]');
+        this.branch = (slot?.assignedElements().length ?? 0) > 0;
+        slot?.addEventListener('slotchange', () => {
+            this.branch = slot.assignedElements().length > 0;
+        });
+    }
+    /**
+     * @internal Read by the tree to identify a branch across the light DOM,
+     * which is cheaper than `instanceof` and is why this is public rather than
+     * protected. A consumer asks `branch`, which is the property they set.
+     */
+    get isBranch() {
+        return this.branch;
+    }
+    /**
+     * Moves focus to this node.
+     *
+     * Which element that is moves with `href`: the thing carrying `treeitem` is
+     * the thing the tree's roving tab stop lives on, and with a link that is the
+     * row rather than the wrapper around it.
+     */
+    focusItem() {
+        /* `preventScroll`, because the browser's own answer to a focus is to walk
+           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. */
+        this.renderRoot
+            .querySelector(this.href === '' ? '[part="item"]' : '[part="row"]')
+            ?.focus({ preventScroll: true });
+    }
+    /** Selects this node and announces it. */
+    select() {
+        this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
+    }
+    /**
+     * Chooses this node the way a reader does, from a press or from Enter.
+     *
+     * 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.
+     */
+    activate() {
+        this.select();
+        this.follow();
+    }
+    /**
+     * Follows a link slotted into the name, if there is one.
+     *
+     * A row is wider than the words in it: the indent, the padding, and with the
+     * chevron at the far end most of the row's width are all outside the anchor,
+     * so a reader who pressed the row anywhere but on the text got nothing. The
+     * words are the consumer's own content and this does not rewrite them, so
+     * what it does instead is press the link they put there.
+     *
+     * The consumer's anchor rather than an `href` of this element's own,
+     * deliberately: a framework's link component is what carries prefetching and
+     * client-side routing, and a plain `<a href>` rendered in here would be a
+     * full page load on a site that had neither. A synthetic click is what those
+     * components listen for, so both keep working.
+     *
+     * `querySelector` on the light DOM, not the render root: the link is the
+     * consumer's, and it is scoped to this item's own name rather than to the
+     * whole subtree, or a branch would follow the first link belonging to one of
+     * its children.
+     */
+    follow() {
+        /* Its own row first, where `href` made one. Pressed with a pointer the
+           anchor has already navigated and this never runs; from the keyboard it
+           has not, because the tree calls `preventDefault` on every key it handles
+           and that is what would otherwise swallow Enter on a link. */
+        const own = this.renderRoot?.querySelector('a[part="row"]');
+        if (own) {
+            own.click();
+            return;
+        }
+        for (const node of this.children) {
+            if (node.slot !== '') {
+                continue;
+            }
+            const link = node instanceof HTMLAnchorElement ? node : node.querySelector('a[href]');
+            if (link) {
+                link.click();
+                return;
+            }
+        }
+    }
+    /** Everything inside the row, which is the same whichever element it is. */
+    renderRow() {
+        return html `${this.branch
+            ? html `<svg
+            part="toggle"
+            fill="currentColor"
+            viewBox=${caretDown.viewBox}
+            aria-hidden="true"
+            @click=${this.href === '' ? nothing : this.handleToggleClick}
+          >
+          ${unsafeSVG(caretDown.content)}
+        </svg>`
+            : nothing}
+      <slot name="start"></slot>
+      <span part="label"><slot></slot></span>
+      <slot name="end"></slot>`;
+    }
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('selected', this.selected);
+    }
+    render() {
+        /* Where the semantics sit, which `href` decides.
+         *
+         * A link row carries them itself and the wrapper drops to `none`, because
+         * an anchor cannot contain the group: the group holds more anchors and
+         * nesting them is invalid markup that no assistive technology reads the way
+         * it looks. So the row becomes the `treeitem` and the group becomes its
+         * 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. */
+        const linked = this.href !== '';
+        const level = this.level ?? 1;
+        const expanded = this.branch ? (this.open ? 'true' : 'false') : nothing;
+        const tabIndex = this.focusable ? '0' : '-1';
+        return html `<div
+        part="item"
+        role=${linked ? 'none' : 'treeitem'}
+        aria-expanded=${linked ? nothing : expanded}
+        aria-selected=${linked ? nothing : this.selected ? 'true' : 'false'}
+        aria-level=${linked ? nothing : level}
+        tabindex=${linked ? nothing : tabIndex}
+      >
+        ${linked
+            ? html `<a
+                part="row"
+                role="treeitem"
+                href=${this.href}
+                target=${this.target || nothing}
+                rel=${this.rel || nothing}
+                aria-expanded=${expanded}
+                aria-selected=${this.selected ? 'true' : 'false'}
+                aria-level=${level}
+                tabindex=${tabIndex}
+                style="--tree-level: ${level}"
+                @click=${this.handleRowClick}
+              >${this.renderRow()}</a>`
+            : html `<div
+                part="row"
+                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>\`
+             holding a \`<ul>\` is. -->
+        <div part="group" role="group" ?hidden=${!this.open}>
+          <slot name="children"></slot>
+        </div>
+      </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTreeItem.prototype, "value", void 0);
+__decorate([
+    property()
+], HelixHeadlessTreeItem.prototype, "href", void 0);
+__decorate([
+    property()
+], HelixHeadlessTreeItem.prototype, "target", void 0);
+__decorate([
+    property()
+], HelixHeadlessTreeItem.prototype, "rel", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessTreeItem.prototype, "selected", void 0);
+__decorate([
+    property({ attribute: 'level', type: Number })
+], HelixHeadlessTreeItem.prototype, "level", void 0);
+__decorate([
+    state()
+], HelixHeadlessTreeItem.prototype, "focusable", void 0);
+__decorate([
+    state()
+], HelixHeadlessTreeItem.prototype, "branch", void 0);
+HelixHeadlessTreeItem = __decorate([
+    customElement('helix-headless-tree-item')
+], HelixHeadlessTreeItem);
+export { HelixHeadlessTreeItem };

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

@@ -0,0 +1,88 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
+/**
+ * @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.
+ */
+export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
+    /**
+     * Accessible name for the tree.
+     */
+    label: string;
+    private watcher;
+    /**
+     * 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.
+     */
+    private get items();
+    /** Items a reader can actually reach: not inside a collapsed branch. */
+    private get visibleItems();
+    private readonly handleSelection;
+    /**
+     * 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.
+     */
+    private syncItems;
+    private move;
+    private focusOn;
+    private readonly handleKeydown;
+    /**
+     * 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.
+     */
+    private readonly handleBranch;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-tree': HelixHeadlessTree;
+    }
+}
+export {};