@fusion.dev/helix-headless 0.2.0 → 0.3.0

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

@@ -7,58 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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 the
- * `helix-before-open` and `helix-before-close` requests 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`. The `role`, the
- * `aria-modal` and the scrim come from the element too, and
- * `drawer-root.ssr.spec.ts` asserts the panel carries no hand-written `inert`
- * and no hand-written `role`.
- *
- * 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 panel opens. 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),
@@ -66,82 +17,25 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
                 '--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. */
             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;
     }
@@ -152,18 +46,11 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
             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: both put the panel in the top layer, and only the first
-         * brings a backdrop, a focus trap and `inert` behind it. */
         const panel = this.panel;
         if (!panel) {
             return;
@@ -181,9 +68,6 @@ let HelixHeadlessDrawer = class HelixHeadlessDrawer extends MixinControllerOpen(
         }
     }
     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}

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

@@ -7,88 +7,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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;
-        /**
-         * 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`. Leave it off every row, including the first, and
-         * nothing in the region is tab-reachable: the keyboard cannot 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;
-        /**
-         * @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;
-        /**
-         * Identifies the row to whatever is listening.
-         */
         this.value = '';
     }
-    /** Moves focus onto the row itself. */
     focusItem() {
         this.renderRoot.querySelector('[part="item"]')?.focus();
     }
-    /** Announces that this row was chosen. */
     select() {
         if (this.disabled) {
             return;
@@ -102,19 +33,6 @@ let HelixHeadlessDrilldownItem = class HelixHeadlessDrilldownItem extends HelixE
         if (!this.onPage) {
             return nothing;
         }
-        /* A real `<button>`, and `role="menuitem"` on it.
-         *
-         * A `<div role="button">` with a click handler cannot be activated from the
-         * keyboard: Enter and Space are behavior the platform gives a real button
-         * and gives nothing else. 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: a reader would be told the count of
-         * items by one role 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"

package/dist/drilldown/root/drilldown-root.js

@@ -10,67 +10,16 @@ import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { HelixHeadlessDrilldownItem } from '../item/drilldown-item.js';
-/**
- * @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.
- */
 let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the region.
-         */
         this.label = 'Navigation';
-        /**
-         * What the control returning from a page reads.
-         */
         this.backLabel = 'Back';
         this.drilldown = new DrilldownController(this, {
             isRow: (element) => 'isDrilldownItem' in element && element.isDrilldownItem === true,
             root: () => [...this.children],
             slot: 'page',
         });
-        /* The stop follows the reader. Arrowing to a row and tabbing away and back
-           should return to where they were, not to the top of the page. */
         this.handleFocusIn = (event) => {
             const item = this.drilldown.rows.find((row) => row.contains(event.target));
             if (item && !item.disabled) {
@@ -84,10 +33,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
             if (!(item instanceof HelixHeadlessDrilldownItem) || !this.items.includes(item)) {
                 return;
             }
-            /* A row with a page drills rather than announcing. The event is stopped so
-               a consumer listening for a choice does not hear navigation as one: going
-               somewhere and choosing something are different acts, and a consumer that
-               had to tell them apart would be doing the stack's job. */
             if (this.drilldown.hasPage(item)) {
                 event.stopPropagation();
                 this.enter(item);
@@ -108,8 +53,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
                 (event.key === 'Home' ? items[0] : items[items.length - 1])?.focusItem();
                 return;
             }
-            /* Left and Escape both go back, and neither closes anything: this is a
-               region rather than an overlay, so there is nothing above it to close. */
             if (event.key === 'ArrowLeft' || event.key === 'Escape') {
                 if (this.back()) {
                     event.preventDefault();
@@ -126,21 +69,9 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
             }
         };
     }
-    /** The rows on the page showing, which is what the keys move over. */
     get items() {
         return this.drilldown.rows.filter((item) => !item.disabled);
     }
-    /**
-     * Puts the region's one tab stop on the first row of the page showing.
-     *
-     * One row holds the stop and the arrows move within, which is the roving
-     * pattern the toolbar uses and the one a `menu` wants. Every row at `-1` is
-     * a region the keyboard cannot get into at all without a pointer first.
-     *
-     * 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.
-     */
     placeTabStop() {
         const items = this.items;
         const held = items.find((item) => item.focusable);
@@ -149,7 +80,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
             item.focusable = item === stop;
         }
     }
-    /** Shows a row's page, and puts focus on the first row of it. */
     enter(item) {
         if (!this.drilldown.enter(item)) {
             return;
@@ -157,14 +87,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
         this.direction = 'forward';
         this.updateComplete.then(() => this.items[0]?.focusItem());
     }
-    /**
-     * 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() {
         const leaving = this.drilldown.page;
         if (!this.drilldown.back()) {
@@ -176,12 +98,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
     }
     connectedCallback() {
         super.connectedCallback();
-        /* Capture, and that is not a detail. A consumer listens on this host too,
-           so a bubble-phase listener here is a sibling of theirs: `stopPropagation`
-           does nothing to another listener on the same node, and whether the
-           navigation is swallowed comes down to which was registered first.
-           Capture reaches the host before the row it came from, so stopping there
-           stops it for everyone, whatever order anybody bound in. */
         this.addEventListener('helix-select', this.handleSelect, true);
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('focusin', this.handleFocusIn);
@@ -198,9 +114,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
     }
     updated(changed) {
         super.updated(changed);
-        /* Which rows are on the page showing, written onto the rows themselves
-           because only the stack knows: a row cannot see its own depth. Client
-           only, since the server has no tree to walk. */
         const page = this.drilldown.page;
         for (const child of this.children) {
             if (!(child instanceof HelixHeadlessDrilldownItem)) {
@@ -217,7 +130,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
             this.setAttribute('data-direction', this.direction);
         }
     }
-    /** Walks the tree marking which rows are on the page showing. */
     mark(item, page, onPage) {
         item.onPage = onPage;
         item.showingPage = item === page;
@@ -246,9 +158,6 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
 };
 __decorate([
     property()
-    /* Not "Menu". This component's own description is built around not being one,
-       and a default accessible name is the one place that claim reaches a
-       reader. */
 ], HelixHeadlessDrilldown.prototype, "label", void 0);
 __decorate([
     property({ attribute: 'back-label' })

package/dist/element-events.generated.js

@@ -1,8 +1,3 @@
-/* Generated by `bun run gen:element-events` from this package's manifest. Do not edit.
- *
- * Which events each tag dispatches, registered so the React prop audit can tell
- * a handler on the wrong element from one on the right one. See
- * `helix/core/src/events/element-events.ts`. */
 import { registerElementEvents } from '@fusion.dev/helix-core';
 registerElementEvents({
     'helix-headless-accordion-item': ['helix-before-close', 'helix-before-open', 'toggle'],

package/dist/empty/root/empty-root.js

@@ -7,44 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Says that a region has nothing in it, and what to do about it.
- *
- * @description
- * An empty region with no explanation is indistinguishable from one that failed
- * to load, so this exists to tell the difference: what would be here, and the
- * one action that would put something here.
- *
- * `role="status"` on a polite live region, because an empty view usually
- * arrives in place of content that was being fetched. Announcing it is the only
- * way a screen-reader user learns the search returned nothing, rather than
- * being left waiting.
- *
- * Every region is a bare slot. The reference ships an `empty-state-heading` and
- * an `empty-state-actions` whose only job is to assign themselves a slot on
- * connect, which is a component for something the consumer can write.
- *
- * @since 0.1.0
- * @status stable
- * @category feedback
- * @aliases Placeholder, NoResults, Blank
- * @documentation https://helix.fusion.dev/components/empty
- *
- * @slot - Why, and what to do about it.
- * @slot actions - The way out.
- * @slot heading - What is missing.
- * @slot icon - A mark above the heading.
- */
 let HelixHeadlessEmpty = class HelixHeadlessEmpty extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the state is announced when it appears.
-         *
-         * On by default: an empty view almost always replaces something that was
-         * loading. Turn it off for one that was on the page from the start, which
-         * has nothing to announce because nothing changed.
-         */
         this.noAnnounce = false;
     }
     willUpdate(changed) {