@fusion.dev/helix-headless 0.0.0-dev

package/dist/tour/stop/tour-stop.js

@@ -0,0 +1,249 @@
+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, HelixTourAskEvent, hostAria, PopoverController, } from '@fusion.dev/helix-core';
+import { property } from 'lit/decorators.js';
+import { html } from 'lit/static-html.js';
+import '../../button/index.js';
+/**
+ * @summary One stop on a tour: what it points at, and a panel to say it in.
+ *
+ * @description
+ * A stop names a target with `for` and holds whatever the consumer puts in it.
+ * It owns no content of its own, which is the whole shape of this family: the
+ * tour abstracts the three things that are genuinely hard, and the words are
+ * the consumer's.
+ *
+ * What it does own:
+ *
+ * - **Where the panel goes.** Anchored to the target through the same floating
+ *   pass every other overlay here uses.
+ * - **That it is on top.** A popover, so it is in the top layer. A tour points
+ *   at things inside dialogs, inside scrollers, inside anything with a stacking
+ *   context, and a panel in the ordinary flow loses to all three.
+ * - **When it shows.** Which is `current`, and which the root decides.
+ *
+ * What it does not own is the heading, the paragraph, the picture and the
+ * layout. Slot a `helix-card`, or a heading and a line of prose, or anything
+ * else. This was written the other way first, with `title` and `body` parts and
+ * a fixed arrangement, which is a component deciding what a tour is allowed to
+ * say.
+ *
+ * **The buttons are slot fallback, so the common case costs nothing and the
+ * uncommon one is possible.** Write nothing and get Back, Next and Skip already
+ * wired. Slot `actions` and they are yours, driven by `next()`, `back()` and
+ * `skip()` on the root, which are public for exactly that.
+ *
+ * **`for` is an id, the same as `Tooltip`'s.** The target is elsewhere on the
+ * page, and an id is the one reference a consumer can write in markup without
+ * holding an element. Resolved against the root node, so a stop inside a shadow
+ * tree points at a target in that tree.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category overlays
+ * @documentation https://helix.fusion.dev/components/tour
+ *
+ * @slot - What this stop says. A card, a heading and a line, anything.
+ * @slot actions - Replaces the controls, which are Back, Next and Skip.
+ *
+ * @event {HelixTourAskEvent} helix-tour-ask - A stop asking the tour to move, from its own controls.
+ *
+ * @csspart actions - The row the controls sit in.
+ * @csspart arrow - The point, which the floating pass places against the target.
+ * @csspart back - The control that goes to the previous stop.
+ * @csspart back-button - The inner control.
+ * @csspart bubble - The panel that points at the target.
+ * @csspart content - The region holding the slotted content.
+ * @csspart next - The control that goes on, and finishes on the last stop.
+ * @csspart next-button - The inner control.
+ * @csspart skip - The control that leaves the tour.
+ * @csspart skip-button - The inner control.
+ */
+let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * The id of the element this stop is about.
+         */
+        this.for = '';
+        /**
+         * Which side of the target the panel prefers.
+         */
+        this.placement = 'bottom';
+        /**
+         * Whether this is the stop the reader is on.
+         *
+         * Written by the root rather than by a consumer, which is the one place this
+         * family writes onto markup it does not own. It is acceptable here for a
+         * reason that did not hold for the trail or the avatar group: a tour starts
+         * closed, so there is no server state to get wrong. The server renders a
+         * closed tour, a closed tour shows nothing, and nothing can disagree.
+         */
+        this.current = false;
+        /**
+         * Whether this is the last stop, so the control says Done.
+         */
+        this.last = false;
+        /**
+         * Whether this is the first stop, so there is nowhere back to.
+         */
+        this.first = false;
+        /**
+         * Label for the control that goes back.
+         */
+        this.backLabel = 'Back';
+        /**
+         * Label for the control that goes on.
+         */
+        this.nextLabel = 'Next';
+        /**
+         * Label for the control that goes on from the last stop.
+         */
+        this.doneLabel = 'Done';
+        /**
+         * Label for the control that leaves the tour.
+         */
+        this.skipLabel = 'Skip';
+        this.floating = new PopoverController(this, {
+            anchor: () => this.target,
+            arrow: () => this.renderRoot?.querySelector('[part="arrow"]'),
+            /* A press outside does not end a tour, and this is the decision rather than
+               a stub. Everywhere else a surface closes on an outside press because
+               pressing elsewhere means the reader is finished with it. Here elsewhere
+               is the thing being pointed at: the scrim lets the pointer through on
+               purpose, so the first press a reader makes on the button the tour is
+               describing would be the press that ends the tour. Leaving is the skip
+               control and `Escape`, both of which say so. */
+            onDismiss: () => { },
+            placement: () => this.placement,
+            surface: () => this.renderRoot?.querySelector('[part="bubble"]'),
+        });
+    }
+    /** The element this stop is about, or null where the id resolves to nothing. */
+    get target() {
+        const scope = this.getRootNode();
+        return this.for === '' ? null : (scope.getElementById?.(this.for) ?? null);
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        /* `group`, not `dialog`, and this is a decision rather than a shortcut. A
+           tour must not trap focus: the reader has to be able to look at the thing
+           being pointed at, and an overlay that will not let them has hidden its
+           own subject. */
+        hostAria(this.internals, { role: 'group' });
+    }
+    updated(changed) {
+        super.updated(changed);
+        /* Shown and hidden from here rather than by a controller reading a
+           property, because `current` is written onto this element by the root and
+           is not a property this element decides. The controller does the top layer
+           and the placement; when is ours. */
+        if (this.current) {
+            this.floating.show();
+        }
+        else {
+            this.floating.hide();
+        }
+    }
+    /**
+     * Skip, back and next, behind a seam the styled tier can move.
+     *
+     * They are slot fallback rather than markup a consumer has to write, so a
+     * tour with nothing slotted still has the three controls a tour needs; and
+     * they are a method as well, so a tier above can render its own three without
+     * reimplementing the panel around them. Both are needed: the slot is for the
+     * consumer and the method is for the tier.
+     */
+    renderActions() {
+        return html `<slot name="actions">
+      <${this.tag('button')}
+        part="skip"
+      exportparts="button: skip-button" appearance="ghost" @click=${() => this.ask('skip')}>
+        ${this.skipLabel}
+      </${this.tag('button')}>
+      ${this.first
+            ? ''
+            : html `<${this.tag('button')}
+              part="back"
+      exportparts="button: back-button"
+              appearance="outlined"
+              @click=${() => this.ask('back')}
+            >
+              ${this.backLabel}
+            </${this.tag('button')}>`}
+      <${this.tag('button')}
+        part="next"
+      exportparts="button: next-button"
+        appearance="solid"
+        tone="primary"
+        @click=${() => this.ask('next')}
+      >
+        ${this.last ? this.doneLabel : this.nextLabel}
+      </${this.tag('button')}>
+    </slot>`;
+    }
+    render() {
+        return html `<div part="bubble" popover="manual" ?hidden=${!this.current}>
+      ${
+        /* The one surface in this library that draws one, and the reason is
+           worth stating because everything else here deliberately does not.
+           An arrow says which thing a panel is describing, and a menu or a
+           select does not need one: it hangs off its trigger and adjacency says
+           it. A tour panel is anchored to something it did not open, on a page
+           full of other things, and it may be flipped to the far side of its
+           target by collision. Fusion's own taste is to leave arrows off, which
+           is a fact about the house style rather than about the system. */
+        ''}
+      <div part="arrow" aria-hidden="true"></div>
+      <div part="content"><slot></slot></div>
+      <div part="actions">
+        ${this.renderActions()}
+      </div>
+    </div>`;
+    }
+    /**
+     * Says what the reader pressed and lets the root decide.
+     *
+     * A stop cannot move a tour: it does not know what is after it, and a stop
+     * that reached up to its parent to find out would be a stop that only works
+     * inside one. Composed, so the root hears it through its own slot.
+     */
+    ask(what) {
+        this.dispatchEvent(new HelixTourAskEvent({ what }));
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTourStop.prototype, "for", void 0);
+__decorate([
+    property()
+], HelixHeadlessTourStop.prototype, "placement", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessTourStop.prototype, "current", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessTourStop.prototype, "last", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessTourStop.prototype, "first", void 0);
+__decorate([
+    property({ attribute: 'back-label' })
+], HelixHeadlessTourStop.prototype, "backLabel", void 0);
+__decorate([
+    property({ attribute: 'next-label' })
+], HelixHeadlessTourStop.prototype, "nextLabel", void 0);
+__decorate([
+    property({ attribute: 'done-label' })
+], HelixHeadlessTourStop.prototype, "doneLabel", void 0);
+__decorate([
+    property({ attribute: 'skip-label' })
+], HelixHeadlessTourStop.prototype, "skipLabel", void 0);
+HelixHeadlessTourStop = __decorate([
+    customElement('helix-headless-tour-stop')
+], HelixHeadlessTourStop);
+export { HelixHeadlessTourStop };

package/dist/tree/index.d.ts

@@ -0,0 +1,2 @@
+export * from './item/tree-item.js';
+export * from './root/tree-root.js';

package/dist/tree/index.js

@@ -0,0 +1,2 @@
+export * from './item/tree-item.js';
+export * from './root/tree-root.js';

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

@@ -0,0 +1,208 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @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.
+ */
+export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
+    /**
+     * Identifies the item to the consumer, carried in `helix-select`.
+     */
+    value: string;
+    /**
+     * 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.
+     */
+    href: string;
+    /**
+     * Where the link opens, for the rare row that leaves the site.
+     */
+    target: string;
+    /**
+     * 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.
+     */
+    rel: string;
+    /**
+     * 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.
+     */
+    selected: boolean;
+    /**
+     * Depth from the root, set by the tree so indentation needs no CSS nesting.
+     *
+     * Not reflected. The tree assigns this after it upgrades, so an attribute
+     * here would be a change to markup the consumer rendered and hydration would
+     * report it. The indent it drives is written onto the row instead, inside the
+     * shadow root, which is not part of the tree React hydrates.
+     */
+    level?: number;
+    /**
+     * Whether this item holds the tree's single tab stop.
+     */
+    focusable: boolean;
+    /**
+     * Whether anything is slotted into `children`.
+     *
+     * Read after first render.
+     */
+    private branch;
+    protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * @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(): boolean;
+    /**
+     * 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(): void;
+    /** Selects this node and announces it. */
+    select(): void;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private follow;
+    private readonly handleToggleClick;
+    private readonly handleRowClick;
+    /** Everything inside the row, which is the same whichever element it is. */
+    private renderRow;
+    /**
+     * 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.
+     */
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-tree-item': HelixHeadlessTreeItem;
+    }
+}
+export {};