@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,158 @@
+import { HelixElement, KeyboardNavigationController, type Placement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @summary A menu of commands, opened from a trigger.
+ *
+ * @description
+ * The trigger is slotted and stays the consumer's own element, the same way the
+ * tooltip takes one. The surface is rendered here, in the top layer through the
+ * popover API, so it clears any ancestor with `overflow: hidden` without a
+ * `z-index` anywhere.
+ *
+ * **It drills down rather than flying out.** A submenu replaces what is on
+ * screen and a back row returns, instead of opening a second panel beside the
+ * first. Panels beside panels need a diagonal path a pointer has to travel
+ * without straying, they run off the edge of a narrow window, and on a touch
+ * screen there is no hover to open them with at all. One panel that changes
+ * what it holds has none of those problems and reads the same on a phone.
+ *
+ * The open page is held here rather than in each item, because only one page
+ * shows at a time and something has to know which. Items are told by property,
+ * not by attribute: an attribute written onto a consumer's element after it
+ * upgrades is a hydration mismatch waiting to happen.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category overlays
+ * @aliases Dropdown, Action menu
+ * @documentation https://helix.fusion.dev/components/menu
+ *
+ * @slot - The items.
+ * @slot trigger - What opens it.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
+ * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart back - The control that returns from a submenu.
+ * @csspart back-mark - The glyph on the back control of a submenu.
+ * @csspart empty - Shown when there are no items to show.
+ * @csspart header - The bar above a submenu, holding the way back and its name.
+ * @csspart loading - Shown while the items are still on their way.
+ * @csspart surface - The floating panel the menu is drawn on.
+ * @csspart title - The name of the submenu that is showing.
+ */
+export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
+    /**
+     * Preferred side.
+     *
+     * It moves if that side does not fit.
+     */
+    placement: Placement;
+    /**
+     * Space between the trigger and the surface, in pixels.
+     */
+    offset: number;
+    /**
+     * Accessible name for the surface.
+     */
+    label: string;
+    /**
+     * What the row returning from a submenu reads.
+     */
+    backLabel: string;
+    /**
+     * Which page is showing, and what is on it.
+     *
+     * This was a `page` field, a title getter and an items getter written here.
+     * None of them were about menus: a settings panel or a navigation tree wants
+     * the same thing, and could not have it without being a menu. The controller
+     * holds the same shape, so the port is a rename rather than a rewrite, and it
+     * adds a real stack: `back()` returns one level instead of to the root, which
+     * this could not do because it only ever went two deep.
+     */
+    private readonly drilldown;
+    /**
+     * Moving between rows, which is not this element's own business any more.
+     *
+     * `selects` false, because arriving at Delete must not delete: moving and
+     * choosing are one act in a radio group and two acts here, which is the
+     * distinction the controller was already drawing for `Tabs`.
+     *
+     * The origin is the selection, which took a wrong turn first and is worth
+     * recording. `focus` looks like the right reading, since a menu's current row
+     * is the focused one, but that origin also carries a rule a menu must not
+     * follow: a press that did not come from the set moves nothing. That rule is
+     * there for a tab panel, which is a tab stop beside the tabs; a menu's panel
+     * holds the rows and nothing else, and Down on a menu that has just opened is
+     * how a reader gets to the first row at all. It moved nothing, and the specs
+     * written alongside this are what said so.
+     *
+     * The horizontal pair is reserved rather than released. Right opens a
+     * submenu and left comes back, which are the platform's own bindings for a
+     * menu that drills, so those keys are spoken for here rather than unhandled.
+     */
+    protected readonly keys: KeyboardNavigationController;
+    private readonly panel;
+    /**
+     * Tells a slotted trigger the disclosure state, by property.
+     *
+     * This menu wrote nothing onto its trigger, which was the right call and cost
+     * a reader the one thing they needed: a control that opens a menu and never
+     * says so. The class note above already gives the mechanism for the way out,
+     * that items are "told by property, not by attribute", and `tellDisclosure`
+     * is that argument applied one level up. See #322.
+     */
+    private tellTrigger;
+    /** The element the surface opens against. */
+    private get trigger();
+    /** The items on the page that is showing, which is what the keys move over. */
+    private get items();
+    /** Opens the menu. */
+    show(): void;
+    /** Closes the menu, and forgets which page was showing. */
+    hide(): void;
+    /** Shows an item's submenu in place of the current page. */
+    private enter;
+    /** Returns to the page above, or closes when there is none. */
+    private leave;
+    private readonly handleSelect;
+    /**
+     * Keeps whatever has focus in sight, however it got there.
+     *
+     * This was done in the arrow branches, which meant it was true of the arrow
+     * keys and of nothing else: a row reached by Tab, or focused by the drilldown
+     * on the way into a page, could sit below the fold of a scrolled panel. On
+     * `focusin` it is one rule about focus rather than a line repeated in every
+     * branch that moves it, and it survived the arrow keys moving out to a shared
+     * controller that knows nothing about this panel.
+     */
+    private readonly handleFocusIn;
+    private readonly handleKeydown;
+    private readonly handleTriggerClick;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Walks the tree marking which rows are on the page showing.
+     *
+     * Two levels were marked by hand and nothing wrote `showingSubmenu` on a
+     * nested row, so drilling into a third-level submenu rendered the header over
+     * an empty panel: the page existed, its rows were still marked as belonging
+     * to the level above, and none of them rendered. `Drilldown.mark()` is the
+     * same walk and was already recursive.
+     *
+     * `slot === 'submenu'` rather than every child, because a row's other
+     * children are its label and its icons.
+     */
+    private mark;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-menu': HelixHeadlessMenu;
+    }
+}
+export {};

package/dist/menu/root/menu-root.js

@@ -0,0 +1,422 @@
+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 { anchorElement, customElement, DrilldownController, HelixElement, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, tellDisclosure, } from '@fusion.dev/helix-core';
+import { caretLeft } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+/**
+ * @summary A menu of commands, opened from a trigger.
+ *
+ * @description
+ * The trigger is slotted and stays the consumer's own element, the same way the
+ * tooltip takes one. The surface is rendered here, in the top layer through the
+ * popover API, so it clears any ancestor with `overflow: hidden` without a
+ * `z-index` anywhere.
+ *
+ * **It drills down rather than flying out.** A submenu replaces what is on
+ * screen and a back row returns, instead of opening a second panel beside the
+ * first. Panels beside panels need a diagonal path a pointer has to travel
+ * without straying, they run off the edge of a narrow window, and on a touch
+ * screen there is no hover to open them with at all. One panel that changes
+ * what it holds has none of those problems and reads the same on a phone.
+ *
+ * The open page is held here rather than in each item, because only one page
+ * shows at a time and something has to know which. Items are told by property,
+ * not by attribute: an attribute written onto a consumer's element after it
+ * upgrades is a hydration mismatch waiting to happen.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category overlays
+ * @aliases Dropdown, Action menu
+ * @documentation https://helix.fusion.dev/components/menu
+ *
+ * @slot - The items.
+ * @slot trigger - What opens it.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
+ * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart back - The control that returns from a submenu.
+ * @csspart back-mark - The glyph on the back control of a submenu.
+ * @csspart empty - Shown when there are no items to show.
+ * @csspart header - The bar above a submenu, holding the way back and its name.
+ * @csspart loading - Shown while the items are still on their way.
+ * @csspart surface - The floating panel the menu is drawn on.
+ * @csspart title - The name of the submenu that is showing.
+ */
+let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinControllerOpen(HelixElement)) {
+    constructor() {
+        super(...arguments);
+        /**
+         * Preferred side.
+         *
+         * It moves if that side does not fit.
+         */
+        this.placement = 'bottom-start';
+        /**
+         * Space between the trigger and the surface, in pixels.
+         */
+        this.offset = 4;
+        /**
+         * Accessible name for the surface.
+         */
+        this.label = 'Menu';
+        /**
+         * What the row returning from a submenu reads.
+         */
+        this.backLabel = 'Back';
+        /**
+         * Which page is showing, and what is on it.
+         *
+         * This was a `page` field, a title getter and an items getter written here.
+         * None of them were about menus: a settings panel or a navigation tree wants
+         * the same thing, and could not have it without being a menu. The controller
+         * holds the same shape, so the port is a rename rather than a rewrite, and it
+         * adds a real stack: `back()` returns one level instead of to the root, which
+         * this could not do because it only ever went two deep.
+         */
+        this.drilldown = new DrilldownController(this, {
+            isRow: (element) => 'isMenuItem' in element && element.isMenuItem === true,
+            root: () => [...this.children].filter((child) => child.slot !== 'trigger'),
+            slot: 'submenu',
+        });
+        /* One controller where there were two and a hand-written sequence between
+           them. It is the same three things in the same order; what it is not is a
+           third copy of them, and the second copy is how `Select` ended up never
+           reaching the top layer at all. */
+        /**
+         * Moving between rows, which is not this element's own business any more.
+         *
+         * `selects` false, because arriving at Delete must not delete: moving and
+         * choosing are one act in a radio group and two acts here, which is the
+         * distinction the controller was already drawing for `Tabs`.
+         *
+         * The origin is the selection, which took a wrong turn first and is worth
+         * recording. `focus` looks like the right reading, since a menu's current row
+         * is the focused one, but that origin also carries a rule a menu must not
+         * follow: a press that did not come from the set moves nothing. That rule is
+         * there for a tab panel, which is a tab stop beside the tabs; a menu's panel
+         * holds the rows and nothing else, and Down on a menu that has just opened is
+         * how a reader gets to the first row at all. It moved nothing, and the specs
+         * written alongside this are what said so.
+         *
+         * The horizontal pair is reserved rather than released. Right opens a
+         * submenu and left comes back, which are the platform's own bindings for a
+         * menu that drills, so those keys are spoken for here rather than unhandled.
+         */
+        this.keys = new KeyboardNavigationController(this, {
+            items: () => this.items,
+            reserved: () => ['ArrowLeft', 'ArrowRight'],
+            selects: () => false,
+        });
+        this.panel = new PopoverController(this, {
+            anchor: () => this.trigger,
+            // The host is `display: contents`, so it has no box a press can land in.
+            // What counts as inside is the surface, plus the trigger, whose own click
+            // handler decides what a press there means.
+            boundary: () => this,
+            offset: () => this.offset,
+            onDismiss: () => this.hide(),
+            placement: () => this.placement,
+            surface: () => this.renderRoot?.querySelector('[part="surface"]'),
+        });
+        this.handleSelect = (event) => {
+            const item = event.target;
+            if (!this.items.includes(item)) {
+                return;
+            }
+            const chosen = item;
+            if (chosen.hasSubmenu) {
+                // A row that opens a page has not chosen anything, so its select does not
+                // leave this element: a consumer listening for a choice would otherwise
+                // hear one every time a reader looked in a submenu.
+                event.stopPropagation();
+                this.enter(chosen);
+                return;
+            }
+            this.hide();
+        };
+        /*
+         * Moves over the page, in the direction the key points.
+         *
+         * The arrows wrap, because a menu is a ring rather than a list with ends:
+         * pressing down on the last item to reach the first is what every menu on
+         * every platform does.
+         */
+        /*
+         * Focuses an item and brings it into the surface, which is not the same act.
+         *
+         * A menu long enough to scroll had the tree's problem: the arrow keys moved
+         * focus past the bottom of the panel and the panel stayed where it was.
+         * Scrolled here rather than by the browser, because `scrollIntoView` would
+         * take the page behind the menu with it.
+         */
+        /**
+         * Keeps whatever has focus in sight, however it got there.
+         *
+         * This was done in the arrow branches, which meant it was true of the arrow
+         * keys and of nothing else: a row reached by Tab, or focused by the drilldown
+         * on the way into a page, could sit below the fold of a scrolled panel. On
+         * `focusin` it is one rule about focus rather than a line repeated in every
+         * branch that moves it, and it survived the arrow keys moving out to a shared
+         * controller that knows nothing about this panel.
+         */
+        this.handleFocusIn = (event) => {
+            const item = this.items.find((row) => row.contains(event.target));
+            if (!item) {
+                return;
+            }
+            /* `surface`, which is the part this template renders and the name the
+               whole library spells this box with.
+        
+               *Rewritten 28 Aug 2026, because it had come to say the reverse.* The
+               fault it records is real and was the other way round: the lookup asked
+               for a name the template did not render, found null, and `scrollItemIntoView`
+               ran with no scroller and took the page behind the menu with it, which is
+               the one thing that method exists to prevent. What the comment could not
+               know is that `check:vocabulary` later renamed the part *to* `surface`, so
+               a note naming `menu` as the right answer now teaches the opposite of the
+               rule that settled it. The lookup and the part have agreed since. */
+            const surface = this.renderRoot.querySelector('[part="surface"]');
+            scrollItemIntoView(item, { padding: 4, ...(surface ? { scroller: surface } : {}) });
+        };
+        this.handleKeydown = (event) => {
+            const items = this.items;
+            const at = items.indexOf(document.activeElement);
+            if (event.key === 'Escape') {
+                event.stopPropagation();
+                this.leave();
+            }
+            else if (event.key === 'ArrowRight' && items[at]?.hasSubmenu) {
+                this.enter(items[at]);
+            }
+            else if (event.key === 'ArrowLeft') {
+                this.leave();
+            }
+            else if (event.key === 'Tab') {
+                /* Out, and the panel goes with it.
+                 *
+                 * Nothing closed the menu when focus left it, so tabbing out of an open
+                 * one left a shadowed panel in the top layer sitting over whatever the
+                 * reader had tabbed to. Deliberately not prevented: focus should carry on
+                 * outward, which is what the reader asked for. And deliberately not a
+                 * focus trap, because a menu is not a modal and Tab is a way out of one. */
+                this.hide();
+                return;
+            }
+            else {
+                return;
+            }
+            event.preventDefault();
+        };
+        this.handleTriggerClick = () => {
+            if (this.open) {
+                this.hide();
+            }
+            else {
+                this.show();
+            }
+        };
+    }
+    /**
+     * Tells a slotted trigger the disclosure state, by property.
+     *
+     * This menu wrote nothing onto its trigger, which was the right call and cost
+     * a reader the one thing they needed: a control that opens a menu and never
+     * says so. The class note above already gives the mechanism for the way out,
+     * that items are "told by property, not by attribute", and `tellDisclosure`
+     * is that argument applied one level up. See #322.
+     */
+    tellTrigger() {
+        const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
+        tellDisclosure(slot?.assignedElements({ flatten: false })[0], this.open);
+    }
+    /** The element the surface opens against. */
+    get trigger() {
+        return anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this);
+    }
+    /** The items on the page that is showing, which is what the keys move over. */
+    get items() {
+        /* Disabled rows are not there for the keyboard.
+         *
+         * A disabled row renders no `tabindex` and cannot take focus, so leaving it
+         * in the list meant the arrow keys computed a move onto it, called `focus()`
+         * on something unfocusable, and stopped: the keyboard was stuck one row
+         * above every disabled item in the menu. `Drilldown` filters for the same
+         * reason. */
+        return this.drilldown.rows.filter((row) => !row.disabled);
+    }
+    /** Opens the menu. */
+    show() {
+        if (this.open || !this.requestOpen(true)) {
+            return;
+        }
+        this.updateComplete.then(() => {
+            // Raised in `updated()`, which the state change has just scheduled.
+            this.items[0]?.focus();
+        });
+    }
+    /** Closes the menu, and forgets which page was showing. */
+    hide() {
+        if (!this.open || !this.requestOpen(false)) {
+            return;
+        }
+        this.panel.hide();
+        this.drilldown.reset();
+        /* Only where the menu still had it. A dismissal that did not take focus with
+           it, a press somewhere else on the page, should leave focus where the
+           reader put it rather than yanking it back to the trigger. `Popover`
+           guards the same way, and `document.activeElement` retargets to the item
+           host here, which is what makes the containment test work. */
+        if (this.contains(document.activeElement)) {
+            this.trigger.focus();
+        }
+    }
+    /** Shows an item's submenu in place of the current page. */
+    enter(item) {
+        if (!this.drilldown.enter(item)) {
+            return;
+        }
+        this.updateComplete.then(() => this.items[0]?.focusItem());
+    }
+    /** Returns to the page above, or closes when there is none. */
+    leave() {
+        if (this.drilldown.atRoot) {
+            this.hide();
+            return;
+        }
+        /* Held before going back, because focus returns to the row that opened the
+           page being left: a reader who drills in and comes straight out should be
+           on the row they pressed, not at the top of a list they have already
+           read. */
+        const leaving = this.drilldown.page;
+        this.drilldown.back();
+        this.updateComplete.then(() => leaving?.focus());
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        /* Capture, so a drill-in never reaches a consumer's own listener on this
+           same host. The guarantee the class documents is that choosing a row that
+           opens a submenu is navigation rather than a choice, and stopping it in the
+           bubble phase stops it for ancestors and not for the siblings registered
+           here. `Drilldown` learned this already. */
+        this.addEventListener('helix-select', this.handleSelect, true);
+        this.addEventListener('keydown', this.handleKeydown);
+        this.addEventListener('focusin', this.handleFocusIn);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('helix-select', this.handleSelect, true);
+        this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('focusin', this.handleFocusIn);
+    }
+    updated(changed) {
+        super.updated(changed);
+        // Every update, so a trigger slotted after the first render is told too.
+        this.tellTrigger();
+        /* Put the panel where `open` says, however it got there. `show()` and
+           `hide()` raised and lowered it and nothing else did, so a menu opened by
+           declaring `open` rendered visible, out of the top layer and unanchored:
+           every imperative path worked and every declarative one was half-open. */
+        if (changed.has('open')) {
+            /* Here rather than a microtask later: `updated()` runs after the render,
+               so the panel is no longer `display: none` and `showPopover` is safe. */
+            if (this.open) {
+                this.panel.show();
+            }
+            else {
+                this.panel.hide();
+            }
+        }
+        // Every item shows or hides itself: which page is open is this element's
+        // business, and where an item belongs is the item's. Set as a property, so
+        // nothing is written onto a consumer's element.
+        for (const child of this.children) {
+            const item = child;
+            if (item.isMenuItem !== true) {
+                continue;
+            }
+            this.mark(item, this.drilldown.atRoot);
+        }
+    }
+    /**
+     * Walks the tree marking which rows are on the page showing.
+     *
+     * Two levels were marked by hand and nothing wrote `showingSubmenu` on a
+     * nested row, so drilling into a third-level submenu rendered the header over
+     * an empty panel: the page existed, its rows were still marked as belonging
+     * to the level above, and none of them rendered. `Drilldown.mark()` is the
+     * same walk and was already recursive.
+     *
+     * `slot === 'submenu'` rather than every child, because a row's other
+     * children are its label and its icons.
+     */
+    mark(item, onPage) {
+        item.onPage = onPage;
+        item.showingSubmenu = item === this.drilldown.page;
+        for (const child of item.children) {
+            const nested = child;
+            if (nested.isMenuItem === true && child.slot === 'submenu') {
+                this.mark(nested, item === this.drilldown.page);
+            }
+        }
+    }
+    render() {
+        return html `<slot name="trigger" @click=${this.handleTriggerClick}></slot>
+      <div
+        part="surface"
+        popover="manual"
+        role="menu"
+        aria-busy=${this.loading ? 'true' : nothing}
+        aria-label=${this.label}
+        data-drilled=${this.drilldown.atRoot ? nothing : ''}
+        ?hidden=${!this.open}
+      >
+        ${
+        // A header rather than a row in the list. The way back is not one of
+        // the things on this page, and putting it in the list means an arrow
+        // press lands on it as though it were.
+        this.drilldown.atRoot
+            ? nothing
+            : html `<div part="header">
+                <button
+                  part="back"
+                  type="button"
+                  aria-label=${this.backLabel}
+                  @click=${() => this.leave()}
+                >
+                  <svg part="back-mark" fill="currentColor" viewBox=${caretLeft.viewBox} aria-hidden="true">
+                    ${unsafeSVG(caretLeft.content)}
+                  </svg>
+                </button>
+                <span part="title">${this.drilldown.label}</span>
+              </div>`}
+        <slot @slotchange=${(event) => this.countRows(event)}></slot>
+        ${this.renderStatus(this.hasRows)}
+      </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessMenu.prototype, "placement", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMenu.prototype, "offset", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenu.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'back-label' })
+], HelixHeadlessMenu.prototype, "backLabel", void 0);
+HelixHeadlessMenu = __decorate([
+    customElement('helix-headless-menu')
+], HelixHeadlessMenu);
+export { HelixHeadlessMenu };

package/dist/meter/index.d.ts

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

package/dist/meter/index.js

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