@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,263 @@
+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, DrilldownController, HelixElement, hostAria, MixinCollection, } from '@fusion.dev/helix-core';
+import { caretLeft } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+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) {
+                for (const row of this.drilldown.rows) {
+                    row.focusable = row === item;
+                }
+            }
+        };
+        this.handleSelect = (event) => {
+            const item = event.target;
+            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);
+            }
+        };
+        this.handleKeydown = (event) => {
+            const items = this.items;
+            const current = items.findIndex((item) => item.matches(':focus-within'));
+            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                event.preventDefault();
+                const step = event.key === 'ArrowDown' ? 1 : -1;
+                const next = (current + step + items.length) % Math.max(items.length, 1);
+                items[current === -1 ? 0 : next]?.focusItem();
+                return;
+            }
+            if (event.key === 'Home' || event.key === 'End') {
+                event.preventDefault();
+                (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();
+                    event.stopPropagation();
+                }
+                return;
+            }
+            if (event.key === 'ArrowRight' && current !== -1) {
+                const item = items[current];
+                if (item && this.drilldown.hasPage(item)) {
+                    event.preventDefault();
+                    this.enter(item);
+                }
+            }
+        };
+    }
+    /** 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.
+     *
+     * 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.
+     */
+    placeTabStop() {
+        const items = this.items;
+        const held = items.find((item) => item.focusable);
+        const stop = held ?? items[0];
+        for (const item of this.drilldown.rows) {
+            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;
+        }
+        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()) {
+            return false;
+        }
+        this.direction = 'back';
+        this.updateComplete.then(() => leaving?.focusItem());
+        return true;
+    }
+    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);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('helix-select', this.handleSelect, true);
+        this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('focusin', this.handleFocusIn);
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label, role: 'menu' });
+    }
+    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)) {
+                continue;
+            }
+            this.mark(child, page, page === null);
+        }
+        this.placeTabStop();
+        this.toggleAttribute('data-drilled', !this.drilldown.atRoot);
+        if (this.direction === undefined) {
+            this.removeAttribute('data-direction');
+        }
+        else {
+            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;
+        for (const child of item.children) {
+            if (child instanceof HelixHeadlessDrilldownItem && child.slot === 'page') {
+                this.mark(child, page, item === page);
+            }
+        }
+    }
+    render() {
+        return html `${this.drilldown.atRoot
+            ? ''
+            : html `<div part="header">
+            <button part="back" type="button" aria-label=${this.backLabel} @click=${() => this.back()}>
+              <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>`}
+      <div aria-busy=${this.loading ? 'true' : nothing} part="page">
+        <slot @slotchange=${(event) => this.countRows(event)}></slot>
+        ${this.renderStatus(this.hasRows)}
+      </div>`;
+    }
+};
+__decorate([
+    property()
+    /* Not "Menu", which is what it was: 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' })
+], HelixHeadlessDrilldown.prototype, "backLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessDrilldown.prototype, "direction", void 0);
+HelixHeadlessDrilldown = __decorate([
+    customElement('helix-headless-drilldown')
+], HelixHeadlessDrilldown);
+export { HelixHeadlessDrilldown };

package/dist/element-events.generated.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/element-events.generated.js

@@ -0,0 +1,125 @@
+/* Generated by `bun run 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'],
+    'helix-headless-announcement': ['helix-dismiss'],
+    'helix-headless-app-header': ['helix-scrolled'],
+    'helix-headless-avatar': ['error', 'load'],
+    'helix-headless-carousel': ['helix-select'],
+    'helix-headless-chat': ['helix-before-pin'],
+    'helix-headless-chat-composer': ['helix-send'],
+    'helix-headless-chat-message': ['helix-send'],
+    'helix-headless-checkbox': ['change', 'helix-before-toggle', 'input'],
+    'helix-headless-checkbox-group': ['change', 'helix-before-change', 'input'],
+    'helix-headless-color-input': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'input',
+        'toggle',
+    ],
+    'helix-headless-color-picker': [
+        'change',
+        'helix-before-change',
+        'helix-copy',
+        'helix-sample-end',
+        'helix-sample-start',
+        'input',
+    ],
+    'helix-headless-combobox': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'helix-create',
+        'input',
+        'toggle',
+    ],
+    'helix-headless-command': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
+    'helix-headless-copy-button': ['helix-copy'],
+    'helix-headless-data-table': ['helix-filter', 'helix-navigate', 'helix-sort'],
+    'helix-headless-date-input': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'input',
+        'toggle',
+    ],
+    'helix-headless-date-picker': ['change', 'helix-before-change', 'helix-navigate', 'input'],
+    'helix-headless-dialog': ['close', 'helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-drawer': ['close', 'helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-drilldown': ['helix-select'],
+    'helix-headless-drilldown-item': ['helix-select'],
+    'helix-headless-file-input': ['change', 'helix-before-change', 'input'],
+    'helix-headless-heatmap': ['helix-resize'],
+    'helix-headless-image': ['error', 'load'],
+    'helix-headless-input': ['change', 'helix-before-change', 'input'],
+    'helix-headless-kbd': ['helix-shortcut'],
+    'helix-headless-listbox': ['change', 'helix-before-change', 'helix-filter', 'input'],
+    'helix-headless-megamenu': ['helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-menu': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
+    'helix-headless-menu-item': ['helix-select'],
+    'helix-headless-notification': ['helix-dismiss', 'helix-read'],
+    'helix-headless-notifications': ['helix-read'],
+    'helix-headless-number-input': ['change', 'helix-before-change', 'input'],
+    'helix-headless-option': ['helix-select'],
+    'helix-headless-outline': ['helix-before-activate'],
+    'helix-headless-pagination': ['helix-navigate'],
+    'helix-headless-pagination-size': ['helix-before-change'],
+    'helix-headless-pin-input': ['change', 'helix-before-change', 'helix-complete', 'input'],
+    'helix-headless-popover': ['helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-radio': ['helix-select'],
+    'helix-headless-radio-group': ['change', 'helix-before-change', 'input'],
+    'helix-headless-rating': ['change', 'helix-before-change', 'input'],
+    'helix-headless-select': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'input',
+        'toggle',
+    ],
+    'helix-headless-slider': ['change', 'helix-before-change', 'input'],
+    'helix-headless-speed-dial': ['helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-speed-dial-item': ['helix-select'],
+    'helix-headless-splitter': ['helix-before-collapse', 'helix-before-resize'],
+    'helix-headless-step': ['helix-select'],
+    'helix-headless-steps': ['helix-activate', 'helix-before-activate'],
+    'helix-headless-switch': ['change', 'helix-before-toggle', 'input'],
+    'helix-headless-tab': ['helix-select'],
+    'helix-headless-tabs': ['helix-activate', 'helix-before-activate', 'helix-select'],
+    'helix-headless-tag': ['helix-dismiss'],
+    'helix-headless-textarea': ['change', 'helix-before-change', 'input'],
+    'helix-headless-time-input': [
+        'change',
+        'helix-before-change',
+        'helix-before-close',
+        'helix-before-open',
+        'input',
+        'toggle',
+    ],
+    'helix-headless-time-picker': ['change', 'helix-before-change', 'input'],
+    'helix-headless-toast-item': ['helix-dismiss'],
+    'helix-headless-toggle': ['helix-select'],
+    'helix-headless-toggle-group': ['change', 'helix-before-change', 'helix-select', 'input'],
+    'helix-headless-tooltip': ['helix-before-close', 'helix-before-open', 'toggle'],
+    'helix-headless-tour': [
+        'helix-before-activate',
+        'helix-before-close',
+        'helix-complete',
+        'toggle',
+    ],
+    'helix-headless-tour-stop': ['helix-tour-ask'],
+    'helix-headless-tree': ['helix-activate', 'helix-before-activate', 'helix-select'],
+    'helix-headless-tree-item': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
+    'helix-headless-video': ['ended', 'helix-next', 'helix-previous', 'pause', 'play'],
+    'helix-headless-video-playlist': ['helix-activate', 'helix-before-activate'],
+    'helix-headless-video-playlist-item': ['helix-select'],
+    'helix-headless-video-playlist-menu': ['helix-select'],
+});

package/dist/empty/index.d.ts

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

package/dist/empty/index.js

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

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

@@ -0,0 +1,47 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @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.
+ */
+export declare class HelixHeadlessEmpty extends HelixElement {
+    /**
+     * 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.
+     */
+    noAnnounce: boolean;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-empty': HelixHeadlessEmpty;
+    }
+}

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

@@ -0,0 +1,68 @@
+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, 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) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { role: this.noAnnounce ? '' : 'status' });
+        this.internals.ariaLive = this.noAnnounce ? null : 'polite';
+    }
+    render() {
+        return html `<slot name="icon"></slot>
+      <slot name="heading"></slot>
+      <slot></slot>
+      <slot name="actions"></slot>`;
+    }
+};
+__decorate([
+    property({ attribute: 'no-announce', reflect: true, type: Boolean })
+], HelixHeadlessEmpty.prototype, "noAnnounce", void 0);
+HelixHeadlessEmpty = __decorate([
+    customElement('helix-headless-empty')
+], HelixHeadlessEmpty);
+export { HelixHeadlessEmpty };

package/dist/file-input/index.d.ts

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

package/dist/file-input/index.js

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