@fusion.dev/helix-headless 0.153.0 → 0.155.0

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
+import { AriaForwardController, type DataOptionItem, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { type HelixHeadlessOption } from '../../option/root/option-root.js';
 import '../../listbox/index.js';
@@ -13,7 +13,10 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * place for focus to return to when the list closes.
  *
  * Your options stay in your light DOM and are slotted through into the listbox,
- * so the listbox looks through slots to find them.
+ * so the listbox looks through slots to find them. For a list too long to draw
+ * whole, set `items` instead: the list draws only the options in sight, as
+ * Listbox's `items` does, and the trigger, its keys and the form read the
+ * whole set.
  *
  * `Select` owns the value, passes it down to the listbox, and takes changes
  * back, so the value lives in one place.
@@ -102,6 +105,8 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  *
  * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  * @cssstate open - While the list is open.
+ * @cssstate placed-bottom - While the open list sits below the trigger.
+ * @cssstate placed-top - While the open list sits above the trigger, where there was no room below.
  */
 export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
     /**
@@ -145,6 +150,20 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      * anything a consumer sets.
      */
     focusable: boolean;
+    /**
+     * The options as data, for a list too long to draw whole: each a value,
+     * which is also its words, or a record with a `value`, a `label` and
+     * `disabled`. Passed to the list, which draws only the options in sight,
+     * as Listbox's `items` does. Set, the options you write as children are
+     * not read.
+     *
+     * The trigger shows the chosen options' labels, the letters and the Left
+     * and Right keys on the closed trigger choose over the whole set, and a
+     * chosen value whose option leaves `items` drops out of `value`.
+     * `value-content` is not called for `items`. Import the Option family as
+     * well, whose elements are drawn.
+     */
+    items: readonly DataOptionItem[] | undefined;
     /**
      * The open list's name where nothing names the Select, read by screen
      * readers. The list has no visible name.
@@ -270,8 +289,15 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      * the commit creates the text node it needs.
      */
     private get display();
-    /** The chosen options, in the order they appear. None on a server or while hydrating. */
+    /** The chosen options, in the order they appear. None on a server or while hydrating, and none for `items`. */
     private get chosenOptions();
+    /** `items` as the list reads them, built once per array. */
+    private data;
+    /**
+     * Every option the select reads, in order: the records of `items`, or the
+     * option elements among its children.
+     */
+    private get entries();
     /**
      * What the trigger shows, behind a seam: what `value-content` draws for the
      * chosen options, or their words, or the placeholder.

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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, afterLinkFollowed, customElement, drawAutofill, drawStatus, HelixFormElement, hostAria, hostWords, isRtl, MixinControllerOpen, MixinControllerValue, MixinField, onApple, PopoverController, reportValues, StatusController, typesCharacter, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { AriaForwardController, afterLinkFollowed, customElement, dataOptions, drawAutofill, drawStatus, HelixFormElement, hostAria, hostWords, isRtl, MixinControllerOpen, MixinControllerValue, MixinField, onApple, PopoverController, reportValues, StatusController, sideOf, typesCharacter, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { caretDown } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -28,6 +28,7 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
         this.emptyText = 'No matches';
         this.filterable = false;
         this.focusable = true;
+        this.items = undefined;
         this.listLabel = 'Options';
         this.loading = false;
         this.loadingText = 'Loading';
@@ -43,6 +44,11 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             ],
             offset: () => 4,
             onDismiss: () => this.close(),
+            onPlace: (placement) => {
+                const side = sideOf(placement);
+                this.toggleState('placed-bottom', side === 'bottom');
+                this.toggleState('placed-top', side === 'top');
+            },
             open: () => this.open,
             place: () => this.position !== 'item-aligned',
             placement: 'bottom-start',
@@ -124,7 +130,9 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
             if (step !== 0 && !this.multiple && !(event.altKey || event.ctrlKey || event.metaKey)) {
                 event.preventDefault();
-                const reachable = listbox?.options.filter((option) => !option.hidden && !option.disabled) ?? [];
+                const reachable = this.items
+                    ? this.entries.filter((option) => !option.disabled)
+                    : (listbox?.options.filter((option) => !option.hidden && !option.disabled) ?? []);
                 const next = reachable[Math.max(0, reachable.findIndex((one) => one.value === this.value) + step)];
                 if (next) {
                     this.choose(next.value);
@@ -165,16 +173,29 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
         return this.partNamed('listbox');
     }
     get display() {
-        const words = this.chosenOptions.map((option) => option.text);
+        const chosen = new Set(this.value === '' ? [] : this.value.split(','));
+        const words = this.entries.filter((option) => chosen.has(option.value)).map((one) => one.text);
         if (words.length > 0) {
             return new Intl.ListFormat(wordsLocale(this), { style: 'short', type: 'unit' }).format(words);
         }
-        return this.value !== '' && !this.childrenKnown ? nothing : this.placeholder;
+        return this.value !== '' && !this.childrenKnown && !this.items ? nothing : this.placeholder;
     }
     get chosenOptions() {
+        if (this.items) {
+            return [];
+        }
         const chosen = new Set(this.value === '' ? [] : this.value.split(','));
         return optionsAmong(this.knownChildren).filter((option) => chosen.has(option.value));
     }
+    get entries() {
+        if (!this.items) {
+            return optionsAmong(this.knownChildren);
+        }
+        if (this.data?.from !== this.items) {
+            this.data = { from: this.items, options: dataOptions(this.items) };
+        }
+        return this.data.options;
+    }
     renderValue() {
         const chosen = this.chosenOptions;
         return this.valueContent && chosen.length > 0 ? this.valueContent(chosen) : this.display;
@@ -226,9 +247,9 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
         }
     }
     reconcileOptions() {
-        const options = optionsAmong(this.knownChildren);
-        if (this.defaultValue === '' && !this.hasAttribute('default-value')) {
-            const declared = options
+        const options = this.entries;
+        if (!this.items && this.defaultValue === '' && !this.hasAttribute('default-value')) {
+            const declared = optionsAmong(this.knownChildren)
                 .filter((option) => option.defaultSelected)
                 .map((option) => option.value);
             if (declared.length > 0) {
@@ -255,7 +276,7 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label });
-        if (this.childrenKnown) {
+        if (this.childrenKnown || this.items) {
             this.reconcileOptions();
         }
     }
@@ -298,6 +319,7 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
       .value=${this.value}
       ?multiple=${this.multiple}
       ?filterable=${this.filterable}
+      .items=${this.items}
       manual
       aria-label=${this.listName || this.listLabel || nothing}
       @keydown=${this.handleListKeydown}
@@ -357,7 +379,7 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             disabled: this.isDisabled,
             multiple: this.multiple,
             onFill: (value) => this.requestValue(value),
-            options: optionsAmong(this.knownChildren),
+            options: this.entries,
             value: this.value,
         })}`;
     }
@@ -375,6 +397,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessSelect.prototype, "focusable", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessSelect.prototype, "items", void 0);
 __decorate([
     words,
     property({ attribute: 'list-label' })

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

@@ -61,6 +61,13 @@ export declare class HelixHeadlessSkeleton extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /**
+     * The placeholder shape and the sheen inside it.
+     *
+     * A method, so a tier above can draw the placeholder as several shapes, as
+     * the styled tier draws a paragraph of lines.
+     */
+    protected renderShape(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -38,7 +38,10 @@ let HelixHeadlessSkeleton = class HelixHeadlessSkeleton extends HelixElement {
     render() {
         return html `<span part="content" ?inert=${this.loading}
         ><slot @slotchange=${() => this.requestUpdate()}></slot></span
-      ><span part="skeleton"><span part="sheen"></span></span>`;
+      >${this.renderShape()}`;
+    }
+    renderShape() {
+        return html `<span part="skeleton"><span part="sheen"></span></span>`;
     }
 };
 __decorate([

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

@@ -19,7 +19,12 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * does not draw a hundred and one marks by accident.
  *
  * A range with two thumbs is two inputs stacked on one track, because there is
- * no native two-thumb range. Each thumb keeps its own value.
+ * no native two-thumb range. Each thumb keeps its own value, and a named range
+ * submits one entry per thumb under its name, the lowest first. A range given
+ * more than two values, such as `default-value="20,50,80"`, has a thumb for
+ * each, as React Aria's slider takes any number of thumbs: each stops at its
+ * neighbors, and the ones between the first and the last are named by
+ * `thumb-label`.
  * `min-steps-between-thumbs` keeps them that many steps apart, and the readout
  * joins the two as `range-text` writes them.
  *
@@ -50,6 +55,8 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * | Page Up, Page Down | Moves the thumb by a larger step. |
  * | Home, End | Moves the thumb to its lowest or highest value. |
  *
+ * Under `readonly` none of these move the thumb, and Tab still reaches it.
+ *
  * Each thumb is an `<input type="range">` with `aria-valuetext` where the value
  * is formatted or worded. A range's thumbs say they stop at each other with
  * `aria-valuemin` and `aria-valuemax`.
@@ -63,12 +70,14 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
  * @slot hint - Help under the control, for content richer than the `hint` text.
  * @slot label - The label, for content richer than the `label` text.
+ * @slot thumb - Content drawn on the thumb, such as a glyph: a single slider's thumb, or a range's lower one. It is decoration, hidden from a screen reader.
+ * @slot thumb-end - Content drawn on a range's upper thumb.
  *
  * @event {Event} change - Fired when the user releases the thumb.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the value changes. Cancelable: call `preventDefault()` to keep the current value.
  * @event {Event} input - Fired after the value changes.
  *
- * @csspart control - The range input.
+ * @csspart control - The range input, one per thumb. On a range each carries `data-thumb`, `start`, `middle`, or `end`, and `data-index`, its place from the lowest.
  * @csspart feedback - The error message under the track.
  * @csspart field - The row that holds the control and its readout.
  * @csspart hint - The help text under the track, shown while there is no error.
@@ -77,10 +86,12 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * @csspart marker-label - The value a mark stands at, when `marker-labels` is set.
  * @csspart markers - The row of marks along the track.
  * @csspart output - The current value, shown beside the track.
- * @csspart tooltip - One thumb's value in a bubble beside it, under `tooltip`. It carries `data-thumb` on a range, `start` or `end`, and `--slider-at`, where its thumb is as a fraction of the track.
+ * @csspart thumb - One thumb's own box over the track, which holds the `thumb` or `thumb-end` slot. It carries `data-thumb` on a range, `start`, `middle`, or `end`, and `--slider-at`, where its thumb is as a fraction of the track. Draw your own thumb here and hide the native one, or leave it empty.
+ * @csspart thumbs - The layer over the track that holds each `thumb`. It is `hidden` until a thumb slot has content, and then `[part="field"]` carries `data-thumbs`.
+ * @csspart tooltip - One thumb's value in a bubble beside it, under `tooltip`. It carries `data-thumb` on a range, `start`, `middle`, or `end`, and `--slider-at`, where its thumb is as a fraction of the track.
  * @csspart tooltips - The layer over the track that holds the bubbles, under `tooltip`.
  *
- * @cssproperty --slider-at - Where a bubble's thumb is, as a fraction of the track, 0 to 1. Set on each `tooltip` part.
+ * @cssproperty --slider-at - Where a bubble's or a thumb box's thumb is, as a fraction of the track, 0 to 1. Set on each `tooltip` and `thumb` part.
  * @cssproperty --slider-fraction - The value as a fraction of the range, 0 to 1.
  * @cssproperty --slider-from - Where the filled span starts, as a fraction of the track, 0 to 1: a range's lower thumb, or a single thumb's `origin`.
  * @cssproperty --slider-marker-at - Where one marker sits, as a percentage of the track.
@@ -185,9 +196,11 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
     /**
      * Adds a second thumb, so the value is a pair.
      *
-     * The pair is one string, `"10,50"`, which is what a form submits and what
-     * `MixinControllerValue` already holds. `valueAsNumber` reads the lower of
-     * the two, since a range has no single number.
+     * The pair is one string, `"10,50"`, which is what `value` and
+     * `MixinControllerValue` hold. A form receives two entries under the name,
+     * `price=10&price=50`, as React Aria's two thumbs send theirs.
+     * `valueAsNumber` reads the lower of the two, since a range has no single
+     * number.
      */
     range: boolean;
     /**
@@ -195,12 +208,27 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      * filled in. Write it in the page's language, such as `{start} bis {end}`.
      */
     rangeText: string;
+    /**
+     * Whether a reader can see and focus the value and cannot change it. A
+     * read-only slider still submits its value.
+     *
+     * React Aria's `isReadOnly`. Each thumb stays a tab stop and says
+     * `aria-readonly`. The arrow keys, the page keys, Home, End, and a drag
+     * leave the value where it is. A script can still set `value`.
+     */
+    readOnly: boolean;
     /**
      * Shows the chosen value beside the track.
      */
     showValue: boolean;
     /** How far one press of an arrow key moves the thumb. */
     step: number;
+    /**
+     * The name of a thumb between a range's first and last, read after the
+     * slider's label, with `{index}` filled in: its place, counted from 1. The
+     * first is `minimum-label` and the last `maximum-label`.
+     */
+    thumbLabel: string;
     /**
      * Whether each thumb shows its value in a bubble beside it, as Web
      * Awesome's `with-tooltip`. The styled slider shows the bubbles while the
@@ -258,12 +286,29 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      * is what a filter with nothing filtered out looks like.
      */
     private get bounds();
+    /**
+     * A range's values, one per thumb, as numbers in order.
+     *
+     * A lone number is not a range, so it is not read as one. `willUpdate`
+     * seeds and sanitizes a range to two values or more, and anything else that
+     * arrives between the two opens fully wide, which is what "nothing filtered
+     * out" looks like.
+     */
+    private get points();
     /** Where one value sits along the track, as a fraction of it. */
     private along;
     private readonly handleInput;
     /** Relayed, because `change` does not cross a shadow boundary on its own. */
     private readonly handleChange;
-    /** Reports the value. */
+    /**
+     * Keeps a read-only thumb still under the keys that move it. Tab and every
+     * other key pass, so focus moves on.
+     */
+    private readonly handleKeydown;
+    /**
+     * Reports the value: one entry, or for a named range one entry per thumb.
+     * The joined pair is the state the browser restores.
+     */
     private sync;
     /**
      * How far along the track the thumb sits, as a fraction.
@@ -325,18 +370,35 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
     /** What a screen reader says for one thumb, where `value-text` asks. */
     private spoken;
     protected updated(changed: PropertyValues): void;
+    /** Draws, once a served slider has hydrated, what its children ask for. */
+    protected firstUpdated(changed: PropertyValues): void;
     /**
      * What a screen reader says for a thumb's value, with `{value}` filled in,
      * such as `{value} degrees`. Empty announces the number alone.
      */
     valueText: string;
+    /**
+     * Whether a `thumb` or `thumb-end` slot has content, read off the children
+     * rather than heard from `slotchange`: a declarative shadow root fires that
+     * before anything listens, so a served slider kept its layer hidden.
+     */
+    private get thumbContent();
+    private readonly handleThumbSlot;
+    /**
+     * A box for each thumb, over the track at the thumb's place, holding the
+     * `thumb` slot: a range's upper thumb holds `thumb-end`. Hidden from the
+     * accessibility tree, since each thumb is already a range with a name and a
+     * value, and `hidden` while no slot has content, so an empty layer takes no
+     * room in the row.
+     */
+    protected renderThumbs(): TemplateResult;
     /**
      * A bubble for each thumb, under `tooltip`, saying its value where it is.
      * After the thumbs, so a stylesheet can reach a bubble from a focused
      * thumb, and hidden from the accessibility tree for the reason the readout
      * is: each thumb already reports its value.
      */
-    protected renderTooltips(start: number, end: number): TemplateResult | typeof nothing;
+    protected renderTooltips(): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {