@fusion.dev/helix-headless 0.0.0-dev

package/dist/drawer/root/drawer-root.js

@@ -0,0 +1,222 @@
+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 { CommandController, customElement, HelixElement, MixinControllerOpen, onUnlessFalse, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary A panel that slides in from an edge.
+ *
+ * @description
+ * Takes `MixinControllerOpen`, so `open`, `defaultOpen`, and `OpenChange` behave exactly
+ * as they do on an accordion item, and a consumer already knows the API.
+ *
+ * Modal by default, which is three things together and not one: focus is
+ * trapped inside, Escape and an outside press close it, and the page behind is
+ * covered. A panel with the look of a modal and none of its behavior is worse
+ * than an inline one, because it invites the reader to treat it as blocking.
+ *
+ * Content stays mounted when closed, so it is in the server's markup and can
+ * animate. A closed `<dialog>` is already out of the tab order and out of the
+ * accessibility tree, so nothing here writes `inert`.
+ *
+ * **This described a hand-written `inert` until 21 Aug 2026, and had done since
+ * the panel became a `<dialog>`.** The rewrite took the `role`, the
+ * `aria-modal`, the scrim and the `inert` with it, because the element brings
+ * all four, and the comments at the two call sites say so. The class doc did
+ * not, and `drawer-root.ssr.spec.ts` has asserted the panel carries no `inert`
+ * the whole time: a spec three files away existing to contradict the prose is
+ * the same shape as `Stat`'s `detail` slot, which is what `check:references`
+ * was written after and is the half it cannot see.
+ *
+ * Opened declaratively with the platform's invoker attributes:
+ *
+ * ```html
+ * <helix-button commandfor="nav" command="--toggle">Menu</helix-button>
+ * <helix-drawer id="nav">…</helix-drawer>
+ * ```
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category overlays
+ * @aliases Sheet, Sidebar, Panel, Off-canvas
+ * @documentation https://helix.fusion.dev/components/drawer
+ *
+ * @slot - The drawer's content.
+ * @slot header - Content pinned above the scrolling area.
+ *
+ * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the panel closes, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the drawer opens or closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart content - The scrolling content region.
+ * @csspart header - The header region.
+ * @csspart panel - The sliding panel.
+ */
+let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(HelixElement) {
+    constructor() {
+        super(...arguments);
+        /* Opened and closed from anywhere on the page, without a line of script:
+           `<helix-button commandfor="…" command="--show">`. The same three commands
+           the dialog answers, because they are the same act: a drawer and a dialog
+           differ in where they sit, not in what opening one means. */
+        this.commands = new CommandController(this, {
+            commands: {
+                '--close': () => this.requestOpen(false),
+                '--show': () => this.requestOpen(true),
+                '--toggle': () => this.toggleOpen(),
+            },
+        });
+        /**
+         * Accessible name for the panel.
+         */
+        this.label = '';
+        /**
+         * Whether the drawer blocks the page behind it.
+         *
+         * Turning this off removes the focus trap and the scrim together, because
+         * they are one decision: a panel that traps focus without covering the page
+         * strands the reader, and one that covers without trapping lets them tab
+         * behind the cover.
+         *
+         * Not reflected. It stays `true` by default, since a drawer that silently
+         * lost its focus trap because a consumer forgot a word would be worse than an
+         * attribute on the host, and nothing selects on it: the scrim is rendered or
+         * not, rather than shown or hidden by CSS.
+         */
+        this.modal = true;
+        /** What a value set before the element existed is kept in. */
+        this.returned = '';
+        /**
+         * Escape, routed through the request so a listener can refuse it.
+         *
+         * A native dialog closes itself on Escape, which would shut the drawer while
+         * the consumer's state still said open: the bug that makes a modal impossible
+         * to reopen. `Dialog` intercepts it for the same reason.
+         */
+        this.handleCancel = (event) => {
+            event.preventDefault();
+            this.requestOpen(false);
+        };
+        /** A close that happened anyway is reflected back rather than argued with. */
+        this.handleClose = (event) => {
+            if (this.open) {
+                this.requestOpen(false);
+            }
+            /* And under the platform's own name, from the host. `close` on a `<dialog>`
+               neither bubbles nor is composed, so the one the browser just fired reaches
+               nobody outside this shadow root, which is the same reason `Avatar` relays
+               `load`. Announced after the state has moved, so a consumer binding
+               `onClose` reads a dialog that is already shut.
+        
+               `cancel` is deliberately not relayed. `handleCancel` prevents it so that
+               Escape is a request rather than an act, so the native one never completes:
+               relaying it would announce a dismissal that was refused. See 296. */
+            this.relayNativeEvent(event);
+        };
+        /**
+         * A press on the backdrop, which lands on the dialog element itself.
+         *
+         * The panel fills only part of the dialog's box, so a press beside it hits
+         * the dialog and not a child. A native `<dialog>` does not close on that, and
+         * it is the gesture that most obviously means close.
+         */
+        this.handleBackdrop = (event) => {
+            if (event.target === this.panel && this.modal) {
+                this.requestOpen(false);
+            }
+        };
+    }
+    /**
+     * What the dialog closed with, the way `<dialog>` reports it.
+     *
+     * **The whole point of a `<dialog>` returning a value is lost behind a shadow
+     * boundary**, which is where this one is: `querySelector` does not reach the
+     * element, so a consumer could neither set the value nor read it back. A
+     * drawer asking which of its actions dismissed it is the ordinary case and had
+     * no answer.
+     *
+     * Written before `open` is set to false rather than passed to a `close(value)`
+     * call, because this component has no such method: it is driven by `open`
+     * alone, and `Dialog`'s `close()` is the one that takes the value directly.
+     *
+     * Held here as well as on the element, so a value set before the first render
+     * survives to it and a consumer reading one back gets what they wrote.
+     */
+    get returnValue() {
+        return this.panel?.returnValue ?? this.returned;
+    }
+    set returnValue(value) {
+        this.returned = value;
+        const panel = this.panel;
+        if (panel) {
+            panel.returnValue = value;
+        }
+    }
+    /** The panel, which is a real `<dialog>`. */
+    get panel() {
+        return this.renderRoot?.querySelector('[part="panel"]') ?? null;
+    }
+    updated(changed) {
+        super.updated(changed);
+        /* After render, and only on a difference: `showModal()` on an open dialog
+           throws and `close()` on a shut one fires a second `close` event.
+         *
+         * `showModal` when modal and `show` when not, which is the whole of what
+         * `modal` means now: both put the panel in the top layer, and only the
+         * first brings a backdrop, a focus trap and `inert` behind it. This was a
+         * hand-built `position: fixed` panel with a scrim div, a focus trap and a
+         * dismisser, none of which the platform needed telling. */
+        const panel = this.panel;
+        if (!panel) {
+            return;
+        }
+        if (this.open && !panel.open) {
+            if (this.modal) {
+                panel.showModal();
+            }
+            else {
+                panel.show();
+            }
+        }
+        else if (!this.open && panel.open) {
+            panel.close();
+        }
+    }
+    render() {
+        /* No `role`, no `aria-modal`, no `inert`, no `tabindex`: a `<dialog>` opened
+           with `showModal()` carries all four, and each hand-written version was a
+           thing that could drift from what the element actually did. */
+        return html `<dialog
+      part="panel"
+      closedby=${this.closedBy ?? nothing}
+      aria-label=${this.label || 'Drawer'}
+      @cancel=${this.handleCancel}
+      @click=${this.handleBackdrop}
+      @close=${this.handleClose}
+    >
+      <div part="header"><slot name="header"></slot></div>
+      <div part="content"><slot></slot></div>
+    </dialog>`;
+    }
+};
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessDrawer.prototype, "placement", void 0);
+__decorate([
+    property()
+], HelixHeadlessDrawer.prototype, "label", void 0);
+__decorate([
+    property({ converter: onUnlessFalse })
+], HelixHeadlessDrawer.prototype, "modal", void 0);
+__decorate([
+    property({ attribute: 'closedby', reflect: true })
+], HelixHeadlessDrawer.prototype, "closedBy", void 0);
+HelixHeadlessDrawer = __decorate([
+    customElement('helix-headless-drawer')
+], HelixHeadlessDrawer);
+export { HelixHeadlessDrawer };

package/dist/drilldown/index.d.ts

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

package/dist/drilldown/index.js

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

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

@@ -0,0 +1,87 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type TemplateResult } from 'lit';
+/**
+ * @summary One row of a drill-down, which may hold a page of its own.
+ *
+ * @description
+ * A row that opens a page *contains* that page: its rows are this row's own
+ * children, assigned to the `page` slot. The tree is the structure, so there
+ * are no ids to wire and a consumer who moves a row has moved its page with it.
+ *
+ * **It renders one of three things**, and which one is the stack's business
+ * rather than its own. On the page showing, it is a row. Showing its own page,
+ * it contributes that page's rows and nothing else, because its row belongs to
+ * the page above. On neither, it renders nothing at all: the rows are in the
+ * light DOM and come back untouched, so there is no state to keep and nothing
+ * to hide with an attribute this element would have to write onto itself.
+ *
+ * Choosing is announced, never applied. The row dispatches and the stack
+ * decides whether that means drilling in or choosing a command.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Panel item, Drill row
+ * @documentation https://helix.fusion.dev/components/drilldown
+ *
+ * @slot - The words naming this row.
+ * @slot end - After the words, usually a mark or a count.
+ * @slot page - The rows of the page this one opens.
+ * @slot start - Before the words, usually an icon.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart item - The row itself.
+ * @csspart label - The words.
+ */
+export declare class HelixHeadlessDrilldownItem extends HelixElement {
+    /**
+     * Whether the row can be reached at all.
+     */
+    disabled: boolean;
+    /**
+     * Identifies the row to whatever is listening.
+     */
+    value: string;
+    /**
+     * @internal Read by a parent to identify its children across the light DOM,
+     * which is cheaper than `instanceof` and is why this is public rather than
+     * protected. Not a consumer's to read or set.
+     */
+    readonly isDrilldownItem = true;
+    /**
+     * Whether the page showing is the one this row is on.
+     *
+     * Written by the stack.
+     */
+    onPage: boolean;
+    /**
+     * Whether this row's own page is the one showing.
+     *
+     * Written by the stack.
+     */
+    showingPage: boolean;
+    /**
+     * Whether this row holds the region's tab stop. Written by the stack.
+     *
+     * A drill-down keeps one stop and moves within it on the arrows, so every
+     * other row is at `-1`. Every row was, including the first, which left
+     * nothing in the region tab-reachable at all: the keyboard could not get in
+     * without first clicking something with a pointer.
+     *
+     * No attribute, the same as `Button`'s: this is coordination between
+     * elements, and writing `tabindex` onto a host the consumer rendered is a
+     * change a React consumer's hydration reports and does not patch up. The stop
+     * lands inside this shadow root instead.
+     */
+    focusable: boolean;
+    /** Moves focus onto the row itself. */
+    focusItem(): void;
+    /** Announces that this row was chosen. */
+    select(): void;
+    protected render(): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-drilldown-item': HelixHeadlessDrilldownItem;
+    }
+}

package/dist/drilldown/item/drilldown-item.js

@@ -0,0 +1,152 @@
+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 } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @summary One row of a drill-down, which may hold a page of its own.
+ *
+ * @description
+ * A row that opens a page *contains* that page: its rows are this row's own
+ * children, assigned to the `page` slot. The tree is the structure, so there
+ * are no ids to wire and a consumer who moves a row has moved its page with it.
+ *
+ * **It renders one of three things**, and which one is the stack's business
+ * rather than its own. On the page showing, it is a row. Showing its own page,
+ * it contributes that page's rows and nothing else, because its row belongs to
+ * the page above. On neither, it renders nothing at all: the rows are in the
+ * light DOM and come back untouched, so there is no state to keep and nothing
+ * to hide with an attribute this element would have to write onto itself.
+ *
+ * Choosing is announced, never applied. The row dispatches and the stack
+ * decides whether that means drilling in or choosing a command.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @aliases Panel item, Drill row
+ * @documentation https://helix.fusion.dev/components/drilldown
+ *
+ * @slot - The words naming this row.
+ * @slot end - After the words, usually a mark or a count.
+ * @slot page - The rows of the page this one opens.
+ * @slot start - Before the words, usually an icon.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart item - The row itself.
+ * @csspart label - The words.
+ */
+let HelixHeadlessDrilldownItem = class HelixHeadlessDrilldownItem extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether the row can be reached at all.
+         */
+        this.disabled = false;
+        /**
+         * Identifies the row to whatever is listening.
+         */
+        this.value = '';
+        /**
+         * @internal Read by a parent to identify its children across the light DOM,
+         * which is cheaper than `instanceof` and is why this is public rather than
+         * protected. Not a consumer's to read or set.
+         */
+        this.isDrilldownItem = true;
+        /**
+         * Whether the page showing is the one this row is on.
+         *
+         * Written by the stack.
+         */
+        this.onPage = true;
+        /**
+         * Whether this row's own page is the one showing.
+         *
+         * Written by the stack.
+         */
+        this.showingPage = false;
+        /**
+         * Whether this row holds the region's tab stop. Written by the stack.
+         *
+         * A drill-down keeps one stop and moves within it on the arrows, so every
+         * other row is at `-1`. Every row was, including the first, which left
+         * nothing in the region tab-reachable at all: the keyboard could not get in
+         * without first clicking something with a pointer.
+         *
+         * No attribute, the same as `Button`'s: this is coordination between
+         * elements, and writing `tabindex` onto a host the consumer rendered is a
+         * change a React consumer's hydration reports and does not patch up. The stop
+         * lands inside this shadow root instead.
+         */
+        this.focusable = false;
+    }
+    /** Moves focus onto the row itself. */
+    focusItem() {
+        this.renderRoot.querySelector('[part="item"]')?.focus();
+    }
+    /** Announces that this row was chosen. */
+    select() {
+        if (this.disabled) {
+            return;
+        }
+        this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
+    }
+    render() {
+        if (this.showingPage) {
+            return html `<slot name="page"></slot>`;
+        }
+        if (!this.onPage) {
+            return nothing;
+        }
+        /* A real `<button>`, and `role="menuitem"` on it.
+         *
+         * It was a `<div role="button">` with a click handler and nothing else, so
+         * the row could not be activated from the keyboard at all: Enter and Space
+         * are behavior the platform gives a real button and gives nothing else,
+         * and neither was handled here. Same argument `Button` makes for rendering
+         * one rather than reproducing it.
+         *
+         * `menuitem` because the stack says `role="menu"`, and a menu whose
+         * children are buttons is not a menu: the roles contradicted each other and
+         * a reader was told the count of items by one and the kind of them by the
+         * other.
+         *
+         * `aria-disabled` rather than `disabled`, so a row that cannot be chosen is
+         * still reachable and still announces why. `select()` is what refuses. */
+        return html `<button
+      part="item"
+      type="button"
+      role="menuitem"
+      aria-disabled=${this.disabled ? 'true' : nothing}
+      tabindex=${this.focusable ? '0' : '-1'}
+      @click=${() => this.select()}
+    >
+      <slot name="start"></slot>
+      <span part="label"><slot></slot></span>
+      <slot name="end"></slot>
+    </button>`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessDrilldownItem.prototype, "disabled", void 0);
+__decorate([
+    property()
+], HelixHeadlessDrilldownItem.prototype, "value", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessDrilldownItem.prototype, "onPage", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessDrilldownItem.prototype, "showingPage", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessDrilldownItem.prototype, "focusable", void 0);
+HelixHeadlessDrilldownItem = __decorate([
+    customElement('helix-headless-drilldown-item')
+], HelixHeadlessDrilldownItem);
+export { HelixHeadlessDrilldownItem };

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

@@ -0,0 +1,115 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessDrilldown_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
+/**
+ * @summary A stack of pages, one showing at a time, with a way back.
+ *
+ * @description
+ * One panel that changes rather than panels opening beside each other. That is
+ * the right shape wherever there is no room for a second column: a phone has
+ * none, and a touch screen has no hover to open one with.
+ *
+ * **Not a `Menu`, and the difference is what it is for rather than how it
+ * looks.** A menu is a thing that opens from a trigger and closes when it is
+ * done; this is a region that sits where it is put, inside a drawer or a
+ * sidebar or a settings panel. `Menu` drills too, through the same controller,
+ * because a menu deep enough to need pages wants exactly this behavior without
+ * being this component.
+ *
+ * **Navigation, never a value.** Rows are places to go and commands to run, so
+ * nothing here is form-associated and nothing is submitted. A drill-down that
+ * reported a value would be a `Listbox` whose options happen to nest, and that
+ * is the component to reach for instead.
+ *
+ * **The tree is the state.** A row that opens a page contains that page, so the
+ * stack holds one reference and reads the rest from the DOM. See
+ * `DrilldownController`, which is where this behavior lives and which `Menu`
+ * shares.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category navigation
+ * @aliases Panel, Nested list, Drill-in
+ * @documentation https://helix.fusion.dev/components/drilldown
+ *
+ * @slot - The rows of the top page.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when a row with no page is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart back - The control that returns one page.
+ * @csspart back-mark - The glyph on the back control.
+ * @csspart empty - Shown when there are no entries to show.
+ * @csspart header - The bar above a page, holding the way back and its name.
+ * @csspart loading - Shown while the entries are still on their way.
+ * @csspart page - The region the rows are in.
+ * @csspart title - The name of the page showing.
+ */
+export declare class HelixHeadlessDrilldown extends HelixHeadlessDrilldown_base {
+    /**
+     * Accessible name for the region.
+     */
+    label: string;
+    /**
+     * What the control returning from a page reads.
+     */
+    backLabel: string;
+    /**
+     * Which way the last move went, for whatever animates the change.
+     *
+     * Reflected as `data-direction`, because the styled tier cannot know it: both
+     * moves replace one page with another, and only the stack knows whether the
+     * reader went deeper or came back. Without it a slide has to pick one
+     * direction and be wrong half the time.
+     *
+     * **Undefined until a move has happened**, which is what "the last move" means
+     * before there has been one. It defaulted to `forward` and was written on the
+     * first update, which cost two things: an attribute on the host that a
+     * consumer's server never sent, reported as a hydration mismatch, and a first
+     * page that animated itself in on load, since an animation is not a transition
+     * and the settle guard does not suppress it.
+     */
+    private direction?;
+    private readonly drilldown;
+    /** The rows on the page showing, which is what the keys move over. */
+    private get items();
+    /**
+     * Puts the region's one tab stop on the first row of the page showing.
+     *
+     * Every row rendered at `-1`, so nothing in the region was tab-reachable and
+     * the keyboard could not get in at all without a pointer first. One row holds
+     * the stop and the arrows move within, which is the roving pattern the
+     * toolbar uses and the one a `menu` wants.
+     *
+     * Called after every update, because the set changes with the page: drilling
+     * in replaces the rows outright, and the stop has to land on rows that are
+     * actually showing.
+     */
+    private placeTabStop;
+    /** Shows a row's page, and puts focus on the first row of it. */
+    private enter;
+    /**
+     * Returns one page, and reports whether there was one to return to.
+     *
+     * Focus lands on the row that opened the page being left, which is why the
+     * row is read before going back rather than after: 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.
+     */
+    back(): boolean;
+    private readonly handleFocusIn;
+    private readonly handleSelect;
+    private readonly handleKeydown;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** Walks the tree marking which rows are on the page showing. */
+    private mark;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-drilldown': HelixHeadlessDrilldown;
+    }
+}
+export {};