@fusion.dev/helix-headless 0.2.0 → 0.3.0

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

@@ -11,130 +11,20 @@ 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,
         });
-        /**
-         * What it says where there are none.
-         */
         this.emptyText = 'No matches';
-        /**
-         * 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.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';
-        /**
-         * 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*.
-         *
-         * Without `showPopover` the panel is an ordinary positioned element and the
-         * first ancestor with `overflow: hidden` clips it, so a select inside a
-         * scrolling card is cut off where a menu in the same place is not. The two
-         * are the same shape (floating panel, trigger, dismissal), which is what
-         * `PopoverController` is, and having one of them is what stops the third copy
-         * being subtly different.
-         *
-         * 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 closes the panel and the
-             * trigger's own `toggleOpen` reopens it on the `click` that follows, so
-             * the panel can never be closed by the button that opened it.
-             *
-             * `DismissController` documents this exact failure and takes a list for
-             * it. */
             boundary: () => [
                 this.renderRoot?.querySelector('[part="surface"]'),
                 this.renderRoot?.querySelector('[part="trigger"]'),
@@ -145,44 +35,14 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             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
-             * reads the value it still holds: 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.
-             *
-             * Without this return the panel closes and a native `change` goes out
-             * whether or not the change was taken, so a consumer calling
-             * `preventDefault()` on `helix-change` keeps the old value, watches the
-             * select shut as though it had been chosen, and tells the form it moved. */
             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.
-        
-               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 is 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) => {
@@ -192,14 +52,6 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             }
         };
     }
-    /**
-     * 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;
     }
@@ -209,32 +61,12 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             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 throws on every server render
-     * and cannot be served at all.
-     *
-     * 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 ?? [])
@@ -242,17 +74,13 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             .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');
@@ -266,42 +94,16 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
         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. The listbox delegates focus, so this lands on the list
-               inside it rather than stopping at the listbox element, which is not
-               itself focusable.
-             *
-             * 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. */
             if (changed.has('open')) {
                 this.listbox?.focus();
             }
         }
         else {
             this.panel.hide();
-            /* And the filter goes with it. Without this a filterable select reopens
-               still narrowed by the old needle, with `hidden` still written on the
-               options it ruled out, so the second use of the control starts 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}
@@ -328,15 +130,6 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
       <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">
@@ -359,18 +152,9 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
       >
         <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: without one a select written without a
-           hand-slotted icon draws no mark at all saying it opens. A caret is
-           the mark, and slotting anything replaces it, which is this
-           library's rule for a content property. */
-        ''}
+        ${''}
         ${this.renderIndicator()}
       </button>
 

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

@@ -6,26 +6,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 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);