@fusion.dev/helix-headless 0.0.0-dev

package/dist/select/root/select-root.js

@@ -0,0 +1,419 @@
+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 { AriaForwardController, customElement, HelixFormElement, hostAria, MixinControllerOpen, MixinControllerValue, MixinField, PopoverController, } from '@fusion.dev/helix-core';
+import { caretDown } from '@fusion.dev/helix-icons';
+import { nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import { html } from 'lit/static-html.js';
+import '../../listbox/index.js';
+/**
+ * @summary A closed list that opens to be chosen from.
+ *
+ * @description
+ * **A trigger and a `Listbox`, not a listbox reimplemented behind a button.**
+ * The list this opens is the same element a consumer can use on its own, with
+ * the same keyboard, the same filtering and the same multi-select rules. What
+ * Select adds is the closing: a trigger that says what is chosen, a surface
+ * that floats, and somewhere for focus to go back to.
+ *
+ * The options are the consumer's, in the consumer's light DOM, slotted through
+ * into the listbox. That is why the listbox walks through slots to find them:
+ * from its point of view the options belong to something else.
+ *
+ * **What it does not do is duplicate the value.** `Select` owns it, hands it
+ * down, and takes changes back; the listbox is the thing being operated and not
+ * a second place the answer lives.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Dropdown, Picker
+ * @documentation https://helix.fusion.dev/components/select
+ *
+ * @slot - The options, and any groups of them.
+ * @slot end - After it, for a count, a unit, or a clear button.
+ * @slot hint - Richer than a string.
+ * @slot indicator - The mark on the trigger saying this opens, usually a caret.
+ * @slot label - Richer than a string.
+ * @slot start - Before the chosen value, for an icon or a prefix.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Relayed from the listbox when the answer changes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {Event} input - Announced once the value has moved.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart feedback - What is wrong with it.
+ * @csspart hint - Help under the trigger.
+ * @csspart indicator - The caret saying the control opens. Replaced by slotting one.
+ * @csspart label - The question, over the trigger.
+ * @csspart listbox - The list inside it.
+ * @csspart listbox-empty - Shown when a filter has hidden everything.
+ * @csspart listbox-feedback - What is wrong with it.
+ * @csspart listbox-filter-icon - The mark beside that field.
+ * @csspart listbox-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart listbox-hint - Help under the list.
+ * @csspart listbox-items - The list itself.
+ * @csspart listbox-label - The question, over the list.
+ * @csspart listbox-loading - Shown while the options are still on their way.
+ * @csspart listbox-search - The region holding the field that narrows the list.
+ * @csspart listbox-search-field - The field itself.
+ * @csspart surface - The floating panel.
+ * @csspart trigger - The closed control, which says what is chosen.
+ * @csspart value - The chosen option's text inside the trigger.
+ */
+let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(MixinControllerValue(MixinField(HelixFormElement))) {
+    constructor() {
+        super(...arguments);
+        /* A consumer's `aria-describedby` names ids in their own tree and the control
+           is in this shadow root, so the reference has to be carried down as an
+           element rather than copied as an id. See `AriaForwardController`: measured
+           in Chrome's own tree, the host held the description and the control the
+           reader is actually on was exposed without it. */
+        this.aria = new AriaForwardController(this, {
+            target: () => this.renderRoot?.querySelector('[part="trigger"]') ?? null,
+        });
+        /**
+         * Whether the list can be narrowed by typing.
+         *
+         * Passed to the listbox rather than acted on here, because the listbox owns
+         * the filtering, the empty state and the keyboard. This property existed and
+         * was never read: it reflected, it type-checked, and nothing anywhere
+         * rendered a field. API that does nothing is worse than API that is missing,
+         * because a consumer sets it and believes it.
+         */
+        this.filterable = false;
+        /**
+         * Whether the options are still on their way.
+         *
+         * Passed straight to the list, which is where the rows are and so where the
+         * message belongs. Two components saying "Loading" about one request is a
+         * consumer wiring the same flag twice.
+         */
+        this.loading = false;
+        /**
+         * What the list says while they are on their way.
+         */
+        this.loadingText = 'Loading';
+        /**
+         * What it says where there are none.
+         */
+        this.emptyText = 'No matches';
+        /**
+         * Whether more than one option can be the answer.
+         */
+        this.multiple = false;
+        /**
+         * Shown on the trigger while nothing is chosen.
+         */
+        this.placeholder = 'Choose';
+        /* The surface floats *and is in the top layer*, which it was not.
+         *
+         * It had a `FloatingController` and a `DismissController` and never called
+         * `showPopover`, so the panel was an ordinary positioned element and the
+         * first ancestor with `overflow: hidden` clipped it. A select inside a
+         * scrolling card was cut off where a menu in the same place was not, and the
+         * two are the same shape: floating panel, trigger, dismissal. That is what
+         * `PopoverController` is, and having one of them is what stops the third copy
+         * being subtly different again.
+         *
+         * Held off the trigger by the controller rather than by a margin on the
+         * panel. A margin is inside the box the controller measures, so it would be
+         * counted once in the placement and again in the layout, and the gap would
+         * change as the panel flipped above the trigger for want of room. */
+        this.panel = new PopoverController(this, {
+            anchor: () => this.renderRoot?.querySelector('[part="trigger"]'),
+            /* The surface *and* the trigger.
+             *
+             * A control is not always one element: the button that opens this panel is
+             * part of it, and a press on it is not a press outside. Scoped to the
+             * surface alone, `pointerdown` on the trigger closed the panel and the
+             * trigger's own `toggleOpen` reopened it on the `click` that followed, so
+             * the panel could never be closed by the button that opened it. Measured
+             * across all five popover-bearing components: Menu, Popover and Tooltip
+             * already named their invoker; this one and its three siblings did not, and
+             * all four stayed open on a second press where Menu closed.
+             *
+             * `DismissController` documents this exact failure and takes a list for it.
+             * The list was the fix; using it was the part that did not happen here. */
+            boundary: () => [
+                this.renderRoot?.querySelector('[part="surface"]'),
+                this.renderRoot?.querySelector('[part="trigger"]'),
+            ],
+            offset: () => 4,
+            onDismiss: () => this.close(),
+            placement: 'bottom-start',
+            surface: () => this.renderRoot?.querySelector('[part="surface"]'),
+        });
+        this.handleChange = (event) => {
+            /* From the event, not from the listbox.
+             *
+             * The event carries the value being *proposed*, and it is dispatched before
+             * it is applied, which is what makes it refusable. Reading the listbox here
+             * therefore read the value it still held: one choice behind, and on the
+             * first choice nothing at all.
+             *
+             * And the listbox never applies it anyway. The select passes `.value` down,
+             * which is a consumer declaring ownership, so the listbox inside the panel
+             * is controlled by the select and correctly waits to be told. That is the
+             * right arrangement, and it makes reading the listbox's own value the one
+             * thing that can never work. */
+            const next = event.detail.value;
+            /* Nothing happens on a refusal, and everything did.
+             *
+             * The panel closed and a native `change` went out whether or not the change
+             * was taken, so a consumer calling `preventDefault()` on `helix-change`
+             * kept the old value, watched the select shut as though it had been chosen,
+             * and told the form it had moved. Refusing a change should leave the
+             * control exactly where it was. */
+            if (!this.requestValue(next)) {
+                event.stopPropagation();
+                return;
+            }
+            /* Closed on a choice, unless more than one can be made: a multi-select that
+               shut after each pick would be a control the reader has to reopen to use
+               again. */
+            if (!this.multiple) {
+                this.close();
+            }
+            /* The listbox's request is stopped and this element's own has already gone
+               out, from `requestValue` above: two elements announcing one choice is
+               what a consumer would have to deduplicate. The comment here used to say
+               the listbox's was "left to travel", which the line below it has always
+               contradicted.
+        
+               And no `change` is dispatched here. `requestValue` announces `input` and
+               `change` through the mixin, the way every other discrete control does, so
+               a second one from this line was a second `change` per choice: measured on
+               the styled tier at three, one from the mixin, one from here, and one from
+               the listbox before it was stopped. */
+            event.stopPropagation();
+        };
+        this.handleTriggerKeydown = (event) => {
+            if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                this.requestOpen(true);
+            }
+        };
+    }
+    /**
+     * Which option is chosen, as an index, or `-1` where none is.
+     *
+     * Read off the listbox this renders, which owns the options and is where the
+     * same two properties are implemented. Delegating rather than recomputing is
+     * what keeps a composed control and the control inside it from answering
+     * differently: they are one chooser to a consumer.
+     */
+    get selectedIndex() {
+        return this.listbox?.selectedIndex ?? -1;
+    }
+    set selectedIndex(at) {
+        const listbox = this.listbox;
+        if (listbox) {
+            listbox.selectedIndex = at;
+        }
+    }
+    /** Which kind of chooser this is, in the platform's two words. */
+    get type() {
+        return this.multiple ? 'select-multiple' : 'select-one';
+    }
+    /**
+     * The list inside the surface, or nothing where there is no DOM to hold one.
+     *
+     * The optional chain is the server. `renderRoot` is a property Lit's element
+     * shim does not carry, and this getter is reached from `display`, which is
+     * read during `render`: without it the select threw on every server render
+     * and could not be served at all. Found by writing its SSR spec, which is
+     * the only thing that would have found it, because the client is where every
+     * other path runs and the client always has a root.
+     *
+     * The other reads of `renderRoot` here are inside callbacks the controllers
+     * invoke, and a controller only runs on a connected element, so they cannot
+     * be reached from the server and are left plain.
+     */
+    get listbox() {
+        return this.renderRoot?.querySelector('[part="listbox"]') ?? null;
+    }
+    /**
+     * What the trigger says: the chosen options' words, or the placeholder.
+     *
+     * Read off the options rather than stored, because the words are the
+     * consumer's content and storing a copy is storing something that goes stale
+     * the moment they change it.
+     */
+    get display() {
+        const chosen = new Set(this.value === '' ? [] : this.value.split(','));
+        const words = (this.listbox?.options ?? [])
+            .filter((option) => chosen.has(option.value))
+            .map((option) => option.text);
+        return words.length > 0 ? words.join(', ') : this.placeholder;
+    }
+    /** Closes the list and puts focus back where it came from. */
+    close() {
+        if (!this.open) {
+            return;
+        }
+        this.requestOpen(false);
+        // Back to the trigger, because focus is inside a panel that is going away
+        // and a reader who loses it lands at the top of the document.
+        this.renderRoot.querySelector('[part="trigger"]')?.focus();
+    }
+    /** Reports the answer and the verdict on it. */
+    sync() {
+        this.internals.setFormValue(this.value === '' ? null : this.value);
+        this.reportRequired(this.value === '', 'Choose one to continue.', 'trigger');
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { label: this.label });
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.sync();
+        this.linkHost();
+        if (this.open) {
+            /* Driven from `updated` rather than from a `show()` method, because the
+               open state is the property and a consumer may set it directly. The
+               controller is idempotent, so arriving here twice for the same open
+               costs nothing. */
+            this.panel.show();
+            /* Into the list, which is where the keyboard has to be for the arrows to
+               mean anything. It reached the listbox element and stopped there, that
+               element not being focusable, so focus stayed on the trigger and every
+               arrow press went to the page. The listbox delegates focus now, so this
+               lands on the list inside it.
+             *
+             * Only on the update that opened it. `updated` runs for any change while
+             * the panel is up, a filter keystroke or a value arriving, and moving
+             * focus on each of those is a focus thief: harmless while the listbox was
+             * unfocusable, and a real one the moment it was made to work. */
+            if (changed.has('open')) {
+                this.listbox?.focus();
+            }
+        }
+        else {
+            this.panel.hide();
+            /* And the filter goes with it. A filterable select reopened still narrowed
+               with the old needle in its search box, and `hidden` still written on the
+               options it had ruled out, so the second use of the control started from
+               the first one's leftovers. Closing is where a search ends. */
+            this.listbox?.requestFilter('');
+        }
+    }
+    /**
+     * The list the trigger opens, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own
+     * list, wrap this one, or pass it a property the base does not know about,
+     * without reimplementing the whole template. The tag is interpolated rather
+     * than written, so `tier` resolves it: this renders the base listbox, and a
+     * styled subclass that sets `tier` renders the styled one from the same
+     * template.
+     */
+    renderListbox() {
+        return html `<${this.tag('listbox')}
+      empty-text=${this.emptyText}
+      loading-text=${this.loadingText}
+      ?loading=${this.loading}
+      part="listbox"
+      exportparts="empty: listbox-empty, feedback: listbox-feedback, filter-icon: listbox-filter-icon,
+        filter-mark: listbox-filter-mark, hint: listbox-hint, items: listbox-items,
+        label: listbox-label, loading: listbox-loading, search: listbox-search,
+        search-field: listbox-search-field"
+      .value=${this.value}
+      ?multiple=${this.multiple}
+      ?filterable=${this.filterable}
+      aria-label=${this.label || nothing}
+      @helix-before-change=${this.handleChange}
+      @change=${this.stopInner}
+      @input=${this.stopInner}
+    >
+      <!-- The trigger's words are read off the options, and on the first
+           render there are none: the slot has not been assigned yet, so a
+           select with a value came up showing its placeholder. Assignment
+           changes no property, so nothing else would schedule the update
+           that fixes it. -->
+      <slot @slotchange=${() => this.requestUpdate()}></slot>
+    </${this.tag('listbox')}>`;
+    }
+    /**
+     * The caret saying the control opens, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     */
+    renderIndicator() {
+        return html `<slot name="indicator">
+      <svg part="indicator" fill="currentColor" viewBox=${caretDown.viewBox} aria-hidden="true">
+        ${unsafeSVG(caretDown.content)}
+      </svg>
+    </slot>`;
+    }
+    render() {
+        return html `${this.renderLabel()}
+      <button
+        part="trigger"
+        id="control"
+        type="button"
+        aria-haspopup="listbox"
+        aria-expanded=${this.open ? 'true' : 'false'}
+        aria-describedby=${this.describedBy ?? nothing}
+        ?disabled=${this.isDisabled}
+        @click=${() => this.toggleOpen()}
+        @keydown=${this.handleTriggerKeydown}
+      >
+        <slot name="start"></slot>
+        <span part="value">${this.display}</span>
+        ${
+        /* Before the indicator, not after it. The caret is the affordance
+           saying the control opens, so it stays the last thing in the trigger
+           whatever else is put in front of it. */
+        ''}
+        <slot name="end"></slot>
+        ${
+        /* The slot has a fallback, and had none: a select written without a
+           hand-slotted icon drew no mark at all saying it opens, and every
+           example in the family passes one, which is what hid it. A caret is
+           the mark, and slotting anything replaces it, which is this
+           library's rule for a content property. */
+        ''}
+        ${this.renderIndicator()}
+      </button>
+
+      <div part="surface" popover="manual" ?hidden=${!this.open}>
+        ${this.renderListbox()}
+      </div>
+      ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessSelect.prototype, "filterable", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessSelect.prototype, "loading", void 0);
+__decorate([
+    property({ attribute: 'loading-text' })
+], HelixHeadlessSelect.prototype, "loadingText", void 0);
+__decorate([
+    property({ attribute: 'empty-text' })
+], HelixHeadlessSelect.prototype, "emptyText", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessSelect.prototype, "multiple", void 0);
+__decorate([
+    property()
+], HelixHeadlessSelect.prototype, "placeholder", void 0);
+HelixHeadlessSelect = __decorate([
+    customElement('helix-headless-select')
+], HelixHeadlessSelect);
+export { HelixHeadlessSelect };

package/dist/skeleton/index.d.ts

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

package/dist/skeleton/index.js

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

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

@@ -0,0 +1,31 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Stands in for content that has not arrived.
+ *
+ * @description
+ * Carries `aria-busy` and a polite live region, so a reader using a screen
+ * reader is told the region is filling rather than told nothing and left to
+ * wonder. Both go through `ElementInternals`, which writes no attribute.
+ *
+ * Holds no `shape`. Whether a placeholder is a line, a block or a circle is
+ * presentation, and putting it here would give the headless tier an appearance
+ * property, which is the one thing that tier is for not having.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category feedback
+ * @aliases Placeholder, Shimmer, Ghost
+ * @documentation https://helix.fusion.dev/components/skeleton
+ *
+ * @csspart skeleton - The placeholder surface.
+ */
+export declare class HelixHeadlessSkeleton extends HelixElement {
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-skeleton': HelixHeadlessSkeleton;
+    }
+}

package/dist/skeleton/root/skeleton-root.js

@@ -0,0 +1,42 @@
+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 } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+/**
+ * @summary Stands in for content that has not arrived.
+ *
+ * @description
+ * Carries `aria-busy` and a polite live region, so a reader using a screen
+ * reader is told the region is filling rather than told nothing and left to
+ * wonder. Both go through `ElementInternals`, which writes no attribute.
+ *
+ * Holds no `shape`. Whether a placeholder is a line, a block or a circle is
+ * presentation, and putting it here would give the headless tier an appearance
+ * property, which is the one thing that tier is for not having.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category feedback
+ * @aliases Placeholder, Shimmer, Ghost
+ * @documentation https://helix.fusion.dev/components/skeleton
+ *
+ * @csspart skeleton - The placeholder surface.
+ */
+let HelixHeadlessSkeleton = class HelixHeadlessSkeleton extends HelixElement {
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.internals.ariaBusy = 'true';
+        this.internals.ariaLive = 'polite';
+    }
+    render() {
+        return html `<span part="skeleton"></span>`;
+    }
+};
+HelixHeadlessSkeleton = __decorate([
+    customElement('helix-headless-skeleton')
+], HelixHeadlessSkeleton);
+export { HelixHeadlessSkeleton };

package/dist/slider/index.d.ts

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

package/dist/slider/index.js

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