@fusion.dev/helix-headless 0.0.0-dev

package/dist/scroll-area/root/scroll-area-root.js

@@ -0,0 +1,215 @@
+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, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+/** Which edges have something past them, as a set of tokens. */
+const EDGES = ['block-start', 'block-end', 'inline-start', 'inline-end'];
+/**
+ * @summary A scrolling box that says there is more.
+ *
+ * @description
+ * **The whole component is one fact a stylesheet cannot work out for itself:
+ * which edges have content past them.** A fade at the bottom of a list is easy
+ * to draw and impossible to decide, because CSS has no reading of scroll
+ * position. So this measures and says, in `data-more`, and the styled tier
+ * draws whatever it likes on the edges named.
+ *
+ * **Tokens rather than four attributes**, so a stylesheet asks
+ * `[data-more~="block-end"]` the way it would ask about a class. Four booleans
+ * say the same thing in four selectors and read worse at every use.
+ *
+ * **A scrolling region takes the keyboard when it scrolls, and not before.**
+ * A box a reader can only reach with a pointer is a box some readers cannot
+ * read at all, which is what `tabindex` answers here. Only while it overflows:
+ * a tab stop on a box with nothing to scroll is a stop that does nothing, and a
+ * form full of them is worse than the problem.
+ *
+ * `role="region"` only with a `label`, because an unnamed region is an
+ * announcement with no content: a screen reader says "region" and the reader
+ * has learned nothing they did not already know.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @category layout
+ * @aliases Scroller, Overflow, Scroll container
+ * @documentation https://helix.fusion.dev/components/scroll-area
+ *
+ * @slot - What scrolls.
+ *
+ * @csspart edges - Where the sideways edge cues are drawn.
+ * @csspart viewport - The scrolling box.
+ */
+let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Names the region, for a reader arriving at it out of context.
+         *
+         * Without one there is no region: see the note on the class.
+         */
+        this.label = '';
+        /**
+         * Which edges have content past them, measured rather than guessed.
+         */
+        this.more = [];
+        /**
+         * Whether there is anything to scroll at all, which decides the tab stop.
+         */
+        this.scrolls = false;
+        /**
+         * Reads the four edges off the box.
+         *
+         * A pixel of slack on each, because a scroller at its end is routinely a
+         * fraction short of it: browsers round scroll positions differently under
+         * zoom and on a display that is not at one to one, and a fade that never
+         * quite goes out at the bottom of a fully scrolled list is the bug that
+         * costs.
+         */
+        this.measure = () => {
+            const box = this.scroller;
+            if (!box) {
+                return;
+            }
+            const slack = 1;
+            const found = [];
+            if (box.scrollTop > slack) {
+                found.push('block-start');
+            }
+            if (box.scrollTop + box.clientHeight < box.scrollHeight - slack) {
+                found.push('block-end');
+            }
+            if (box.scrollLeft > slack) {
+                found.push('inline-start');
+            }
+            if (box.scrollLeft + box.clientWidth < box.scrollWidth - slack) {
+                found.push('inline-end');
+            }
+            this.more = found;
+            this.scrolls = box.scrollHeight > box.clientHeight || box.scrollWidth > box.clientWidth;
+        };
+        this.handleSlotChange = (event) => {
+            const slot = event.target;
+            for (const assigned of slot.assignedElements({ flatten: true })) {
+                this.watcher?.observe(assigned);
+            }
+            this.measure();
+        };
+    }
+    /**
+     * The box that actually scrolls, for anything that needs to move it.
+     *
+     * **Public because the alternative is silence.** Bringing a row into view
+     * means telling a scroll utility which box to scroll, and the scrolling box
+     * here is inside a shadow root: a consumer holding a reference to this
+     * element holds the host, which does not scroll, and `scrollBy` on it is a
+     * no-op that reports nothing. That is exactly how `scrollItemIntoView`'s
+     * `offsetParent` default fails, and the sandbox sidebar spent an afternoon
+     * scrolled to zero because of it.
+     *
+     * The element rather than a method of our own, because the utilities that
+     * want it already take one, and `Tree`, `Combobox` and anything windowing a
+     * long list all want the same thing from it.
+     */
+    get scroller() {
+        return this.renderRoot?.querySelector('[part="viewport"]') ?? null;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        /* Both the box and what is in it. The box changing size is a layout change
+           and the content changing size is a data change, and a fade that only
+           answered one of them was wrong every time a list was filtered. */
+        this.watcher = new ResizeObserver(this.measure);
+        /* And what it watches, which was registered only in `firstUpdated`.
+         *
+         * The observer was already rebuilt here, so this looked like the one
+         * component that had the lifecycle right, and it was half right. A fresh
+         * observer watches nothing until something calls `observe`, and only
+         * `firstUpdated` did, which runs once for the life of the element. So a
+         * scroll area moved in the DOM came back with a new observer registered on
+         * no targets: the fades stopped answering a resize or a filtered list, and
+         * the component went on rendering.
+         *
+         * Guarded on `hasUpdated`, because the first connection happens before the
+         * first render and there is no scroller to find yet. `check:observers`
+         * holds it, and had to be tightened to see it: asking for `new` *or*
+         * `observe` passed this on the half that was fine. */
+        if (this.hasUpdated) {
+            this.watchContent();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    firstUpdated(changed) {
+        super.firstUpdated?.(changed);
+        this.watchContent();
+        this.measure();
+    }
+    /** Registers the box and everything slotted into it, which is what resizes. */
+    watchContent() {
+        const box = this.scroller;
+        if (!box || !this.watcher) {
+            return;
+        }
+        this.watcher.observe(box);
+        for (const child of box.querySelectorAll('slot')) {
+            for (const assigned of child.assignedElements({ flatten: true })) {
+                this.watcher.observe(assigned);
+            }
+        }
+    }
+    updated(changed) {
+        super.updated?.(changed);
+        /* On the host rather than the viewport, so a consumer can style from the
+           outside without reaching through a part. */
+        this.toggleAttribute('data-scrolls', this.scrolls);
+        if (this.more.length > 0) {
+            this.setAttribute('data-more', this.more.join(' '));
+        }
+        else {
+            this.removeAttribute('data-more');
+        }
+    }
+    render() {
+        return html `<div
+      data-scroller
+      part="viewport"
+      role=${this.label ? 'region' : nothing}
+      aria-label=${this.label || nothing}
+      tabindex=${this.scrolls ? '0' : nothing}
+      @scroll=${this.measure}
+    >
+      <slot @slotchange=${this.handleSlotChange}></slot>
+    </div>
+    <!-- The block edges are drawn on the host, which has two pseudo-elements and
+         no more. The sideways pair needs two of its own, and an element to hang
+         them on is cheaper than the arithmetic that would fit four edges into
+         two: they can then be placed with logical properties, which is what
+         makes inline-start the right-hand edge when the reader reads that way. -->
+    <div
+      part="edges"
+      aria-hidden="true"
+    ></div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessScrollArea.prototype, "label", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "more", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "scrolls", void 0);
+HelixHeadlessScrollArea = __decorate([
+    customElement('helix-headless-scroll-area')
+], HelixHeadlessScrollArea);
+export { HelixHeadlessScrollArea };
+export { EDGES };

package/dist/select/index.d.ts

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

package/dist/select/index.js

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

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

@@ -0,0 +1,170 @@
+import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../listbox/index.js';
+declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @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.
+ */
+export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
+    protected readonly aria: AriaForwardController;
+    /**
+     * 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.
+     */
+    filterable: boolean;
+    /**
+     * 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.
+     */
+    loading: boolean;
+    /**
+     * What the list says while they are on their way.
+     */
+    loadingText: string;
+    /**
+     * What it says where there are none.
+     */
+    emptyText: string;
+    /**
+     * Whether more than one option can be the answer.
+     */
+    multiple: boolean;
+    /**
+     * Shown on the trigger while nothing is chosen.
+     */
+    placeholder: string;
+    /**
+     * 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(): number;
+    set selectedIndex(at: number);
+    /** Which kind of chooser this is, in the platform's two words. */
+    get type(): string;
+    /**
+     * 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.
+     */
+    private get listbox();
+    protected readonly panel: PopoverController;
+    /**
+     * 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.
+     */
+    private get display();
+    /** Closes the list and puts focus back where it came from. */
+    private close;
+    private readonly handleChange;
+    private readonly handleTriggerKeydown;
+    /** Reports the answer and the verdict on it. */
+    private sync;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * 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.
+     */
+    protected renderListbox(): TemplateResult;
+    /**
+     * 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.
+     */
+    protected renderIndicator(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-select': HelixHeadlessSelect;
+    }
+}
+export {};