@fusion.dev/helix-headless 0.147.0 → 0.148.0

package/dist/canvas/snap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where a card lands on a board that snaps: the arithmetic of a ruling, kept
+ * apart from the board that applies it.
+ *
+ * Every value is in the document's own units, and a step of nothing, zero or
+ * less is no snapping at all, so a board without `snap` moves exactly as it
+ * did before there was one.
+ */
+/** A box on the board, in the document's own units. */
+export interface SnapBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A value at the nearest multiple of `step`, or the value as it is where there
+ * is no step. A drag lets go wherever the hand is, and lands on the line
+ * nearest it.
+ */
+export declare const snapTo: (value: number, step: number | undefined) => number;
+/**
+ * The next multiple of `step` from `value`, the way a key points: `way` is `1`
+ * or `-1`.
+ *
+ * **On to the next line, and never back onto the same one.** A card sitting
+ * between two lines goes to the line ahead of it, and one on a line goes a
+ * whole step, so every press moves the card and every press lands on a line.
+ */
+export declare const stepTo: (value: number, way: number, step: number) => number;
+/**
+ * A box resized from a corner, with the edges that corner moves snapped, and
+ * held to a least size.
+ *
+ * Only the moving edges: the corner opposite the one in hand stays where it
+ * was, as it does without a ruling. Where the line nearest is inside the least
+ * size, the box stays at the least size rather than turning inside out.
+ */
+export declare const snapBox: (box: SnapBox, start: SnapBox, corner: string, step: number | undefined, least: {
+    width: number;
+    height: number;
+}) => SnapBox;

package/dist/canvas/snap.js

@@ -0,0 +1,32 @@
+const snaps = (step) => step !== undefined && Number.isFinite(step) && step > 0;
+export const snapTo = (value, step) => snaps(step) ? Math.round(value / step) * step : value;
+export const stepTo = (value, way, step) => {
+    if (way === 0) {
+        return value;
+    }
+    const at = value / step;
+    const near = Math.round(at);
+    const on = Math.abs(at - near) < 1e-9 ? near : at;
+    return (way > 0 ? Math.floor(on) + 1 : Math.ceil(on) - 1) * step;
+};
+export const snapBox = (box, start, corner, step, least) => {
+    if (!snaps(step)) {
+        return box;
+    }
+    const left = corner.endsWith('left');
+    const top = corner.startsWith('top');
+    const right = start.x + start.width;
+    const bottom = start.y + start.height;
+    const width = left
+        ? Math.max(least.width, right - snapTo(box.x, step))
+        : Math.max(least.width, snapTo(box.x + box.width, step) - start.x);
+    const height = top
+        ? Math.max(least.height, bottom - snapTo(box.y, step))
+        : Math.max(least.height, snapTo(box.y + box.height, step) - start.y);
+    return {
+        height,
+        width,
+        x: left ? right - width : start.x,
+        y: top ? bottom - height : start.y,
+    };
+};

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { ChildrenController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary Shows one slide of several, with controls to move between them.
@@ -727,9 +727,10 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * that changes an assignment is this component calling `assign`, so a slide
      * appended by a consumer would reach no slot, render nowhere and be counted by
      * nothing. A default slot needs no watcher, taking whatever is there; a manual
-     * one does. `Chat` watches for the same reason.
+     * one does. `Chat` watches for the same reason, through the same core
+     * controller.
      */
-    private watcher;
+    protected readonly childWatch: ChildrenController;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /** Pauses without forgetting that the reader wanted it running. */

package/dist/carousel/root/carousel-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 { capturePointer, customElement, fillTemplate, HelixActivateEvent, HelixElement, HelixSelectEvent, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { ChildrenController, capturePointer, customElement, fillTemplate, HelixActivateEvent, HelixElement, HelixSelectEvent, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
 import { caretLeft, caretRight, play, stop } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -185,7 +185,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         };
         this.scrollFrame = 0;
         this.stopped = false;
-        this.watcher = undefined;
+        this.childWatch = new ChildrenController(this);
         this.pause = () => {
             if (!this.stopped) {
                 this.rotating = false;
@@ -388,8 +388,6 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         super.connectedCallback();
         this.addEventListener('focusin', this.pause);
         this.addEventListener('pointerenter', this.pause);
-        this.watcher = new MutationObserver(() => this.requestUpdate());
-        this.watcher.observe(this, { childList: true });
         this.watchPane();
         if (this.hasUpdated) {
             this.runTimer();
@@ -403,8 +401,6 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         }
         this.removeEventListener('focusin', this.pause);
         this.removeEventListener('pointerenter', this.pause);
-        this.watcher?.disconnect();
-        this.watcher = undefined;
         this.sizes?.disconnect();
         this.sizes = undefined;
         this.watched = undefined;

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { ChildrenController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { type HelixHeadlessChatMessage } from '../message/chat-message.js';
 /** One turn handed over as data, which is what `turns` holds. */
@@ -253,8 +253,18 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * a turn is told again only when they change.
      */
     private words;
-    /** Watches for turns arriving, since a manual slot hears nothing about them. */
-    private watcher;
+    /**
+     * Watches for turns arriving, since a manual slot hears nothing about them.
+     *
+     * **A turn that arrives after first paint reaches nothing on its own.**
+     * Slots are assigned by hand here, so appending a child assigns it to
+     * nothing, fires no `slotchange`, and schedules no render: the transcript
+     * went on showing "Nothing to show" over six children it already had, and
+     * the one thing a conversation does is grow. Measured with
+     * `assignedElements()` at zero against `children` at nine. Children only,
+     * never a turn's own text, which a streaming turn rewrites every frame.
+     */
+    protected readonly childWatch: ChildrenController;
     /** Watches the turns' own `state`, which is when one of them settles. */
     private settling;
     /** Watches the turns and the log for size, which scrolling does not report. */

package/dist/chat/root/chat-root.js

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessChat_1;
-import { customElement, fillTemplate, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, VirtualizeController, whenHydrated, wordsConverter, } from '@fusion.dev/helix-core';
+import { ChildrenController, customElement, fillTemplate, HelixBeforePinEvent, HelixElement, HelixHistoryEvent, HelixPinEvent, hostAria, MixinCollection, onUnlessFalse, requestChange, VirtualizeController, whenHydrated, wordsConverter, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { keyed } from 'lit/directives/keyed.js';
@@ -56,7 +56,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.announcement = '';
         this.said = 0;
         this.words = TURN_WORDS;
-        this.watcher = undefined;
+        this.childWatch = new ChildrenController(this, () => this.handleSlotChange());
         this.settling = undefined;
         this.grower = undefined;
         this.watched = [];
@@ -349,8 +349,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     }
     connectedCallback() {
         super.connectedCallback();
-        this.watcher = new MutationObserver(this.handleSlotChange);
-        this.watcher.observe(this, { childList: true });
         this.settling = new MutationObserver(this.handleSettle);
         this.settling.observe(this, { attributeFilter: ['state'], subtree: true });
         this.opening = true;
@@ -363,8 +361,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        this.watcher?.disconnect();
-        this.watcher = undefined;
         this.settling?.disconnect();
         this.settling = undefined;
         this.grower?.disconnect();

package/dist/checkbox-group/root/checkbox-group-root.d.ts

@@ -96,8 +96,21 @@ export declare class HelixHeadlessCheckboxGroup extends HelixHeadlessCheckboxGro
      */
     get values(): string[];
     set values(next: string[]);
+    /**
+     * Writes the set the boxes are given at the next update: by value, or, for
+     * a set a press decided, by box.
+     */
+    private choose;
     /** The values last written, which the boxes are given at the next update. */
     private declared;
+    /**
+     * The boxes to check at the next update, where a press on a box or on the
+     * select-all box decided the set.
+     *
+     * **By box, since boxes can share a value.** Boxes written with no `value`
+     * all submit `on`, and pushed by value, a press on one checked every one.
+     */
+    private checking;
     /**
      * Whether `declared` has yet to reach the boxes.
      *

package/dist/checkbox-group/root/checkbox-group-root.js

@@ -5,19 +5,20 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessCheckboxGroup_1;
-import { commaList, customElement, DisabledCascadeController, HelixBeforeChangeEvent, HelixFormElement, hostAria, MixinField, toggleEvery, } from '@fusion.dev/helix-core';
+import { commaList, customElement, DisabledCascadeController, HelixBeforeChangeEvent, HelixFormElement, hostAria, MixinField, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import { HelixHeadlessCheckbox } from '../../checkbox/root/checkbox-root.js';
 import '../../checkbox/index.js';
-import { selectAllState } from '../select-all.js';
+import { selectAllPress, selectAllState } from '../select-all.js';
 let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadlessCheckboxGroup extends MixinField(HelixFormElement) {
     constructor() {
         super(...arguments);
         this.selectAll = false;
         this.selectAllLabel = 'Select all';
         this.declared = [];
+        this.checking = undefined;
         this.pending = false;
         this.watched = new Set();
         this.member = {
@@ -41,14 +42,13 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
                 return;
             }
             const wanted = event.detail.checked;
-            const next = this.boxes
-                .filter((box) => (box === changed ? wanted : box.checked))
-                .map((box) => box.value);
+            const checking = this.boxes.filter((box) => (box === changed ? wanted : box.checked));
+            const next = checking.map((box) => box.value);
             if (!this.dispatchEvent(new HelixBeforeChangeEvent({ value: next.join(',') }))) {
                 event.preventDefault();
                 return;
             }
-            this.values = next;
+            this.choose(next, checking);
             this.announceInput();
             this.announceChange();
         };
@@ -60,12 +60,14 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
         this.handleSelectAll = (event) => {
             event.preventDefault();
             event.stopPropagation();
-            const boxes = this.setBoxes();
-            const next = toggleEvery(boxes.filter((box) => box.checked).map((box) => box.value), boxes.filter((box) => !box.disabled).map((box) => box.value), boxes.map((box) => box.value));
+            const boxes = this.boxes;
+            const pressed = selectAllPress(this.setBoxes());
+            const checking = boxes.filter((_, at) => pressed[at]);
+            const next = checking.map((box) => box.value);
             if (!this.dispatchEvent(new HelixBeforeChangeEvent({ value: next.join(',') }))) {
                 return;
             }
-            this.values = next;
+            this.choose(next, checking);
             this.announceInput();
             this.announceChange();
         };
@@ -86,8 +88,12 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
             : boxes.filter((box) => box.checked).map((box) => box.value);
     }
     set values(next) {
+        this.choose(next);
+    }
+    choose(next, boxes) {
         const previous = this.value;
         this.declared = [...next];
+        this.checking = boxes ? new Set(boxes) : undefined;
         this.pending = true;
         this.requestUpdate('value', previous);
     }
@@ -125,8 +131,10 @@ let HelixHeadlessCheckboxGroup = HelixHeadlessCheckboxGroup_1 = class HelixHeadl
         }
         this.pending = false;
         const wanted = new Set(this.declared);
+        const checking = this.checking;
+        this.checking = undefined;
         for (const box of boxes) {
-            box.checked = wanted.has(box.value);
+            box.checked = checking ? checking.has(box) : wanted.has(box.value);
         }
     }
     connectedCallback() {

package/dist/checkbox-group/select-all.d.ts

@@ -19,3 +19,14 @@ export declare const selectAllState: (boxes: readonly SetBox[]) => {
     checked: boolean;
     indeterminate: boolean;
 };
+/**
+ * What a press on the select-all box does to each box, in the set's order:
+ * every enabled box checked, or every one cleared once all of them are, with a
+ * disabled box keeping its state. A set with no enabled box stays as it is.
+ *
+ * **By box and not by value**, so boxes that share a value, such as boxes
+ * written with none, which all submit `on`, are each moved on their own: by
+ * value, one checked box made every box with its value count as checked, and
+ * the press cleared the set where it should have filled it.
+ */
+export declare const selectAllPress: (boxes: readonly SetBox[]) => boolean[];

package/dist/checkbox-group/select-all.js

@@ -5,3 +5,8 @@ export const selectAllState = (boxes) => {
     const checked = counted.length > 0 && ticked === counted.length;
     return { checked, indeterminate: ticked > 0 && !checked };
 };
+export const selectAllPress = (boxes) => {
+    const enabled = boxes.filter((box) => !box.disabled);
+    const every = enabled.length > 0 && enabled.every((box) => box.checked);
+    return boxes.map((box) => (box.disabled ? box.checked : !every));
+};

package/dist/code-block/root/code-block-root.d.ts

@@ -78,7 +78,7 @@ import '../../copy-button/index.js';
  * @csspart gutter - The line numbers beside the code, shown when `line-numbers` is set.
  * @csspart header - The bar that holds the name and the copy button, shown when there is a name.
  * @csspart hunk - In a diff, a `@@` line saying where the lines under it are.
- * @csspart label - The file name or language, where one is given.
+ * @csspart label - The block's name: its `label`, or its `language` where it has no label.
  * @csspart marker - In a diff, the `+`, `-`, or space that starts a line.
  * @csspart new - In a split diff, the new version's `<pre>`.
  * @csspart number - In a diff, a line number.
@@ -151,18 +151,20 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      */
     highlight?: (code: string, language: string) => string;
     /**
-     * The block's name, usually a file name or a language.
+     * The block's name, usually a file name, drawn in the header.
      *
-     * In a diff, each file is named from the patch, and this names a patch that
-     * carries no name of its own.
+     * Absent, the block is named by `language` where there is one. In a diff,
+     * each file is named from the patch, and this names a patch that carries no
+     * name of its own.
      */
     label: string;
     /**
      * The language the code is written in, such as `ts` or `css`, handed to
      * `highlight` as its second argument.
      *
-     * Absent hands it an empty string. It draws nothing of its own: the block's
-     * name is `label`.
+     * A block with no `label` is named by it, in the header and on the copy
+     * button, as a docs site names a snippet by its language. Absent hands
+     * `highlight` an empty string and names nothing.
      */
     language: string;
     /**

package/dist/code-block/root/code-block-root.js

@@ -109,10 +109,11 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         const gutter = this.lineNumbers
             ? html `<span part="gutter" aria-hidden="true">${lines === 0 ? nothing : gutterNumbers(lines)}</span>`
             : nothing;
-        return html `${this.renderHeader(this.label)}
+        const name = this.label || this.language;
+        return html `${this.renderHeader(name)}
       <div part="frame">
         <pre id="block" part="block">${gutter}${code}</pre>
-        ${this.label ? nothing : this.renderCopy()}
+        ${name ? nothing : this.renderCopy()}
       </div>${this.renderExpand()}`;
     }
     renderExpand() {
@@ -140,7 +141,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     renderCopy(value, name) {
         return this.noCopy ? nothing : this.renderCopyButton(value, name);
     }
-    renderCopyButton(value = this.text, name = this.label) {
+    renderCopyButton(value = this.text, name = this.label || this.language) {
         return html `<${this.tag('copy-button')}
       part="copy"
       exportparts="button: copy-button, text: copy-text, mark: copy-mark, live: copy-live, spinner: copy-spinner, tooltip: copy-tooltip,

package/dist/color-picker/root/color-picker-root.js

@@ -4,14 +4,14 @@ 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 { CopyController, capturePointer, clamp, colorName, customElement, drawIcon, fillTemplate, formatColor, formatNumber, HelixFormElement, HelixSampleEndEvent, HelixSampleStartEvent, hostAria, hueName, isRtl, KeyboardNavigationController, localeOf, MixinControllerValue, MixinPickerFeedback, parseColor, rovingStop, splitValues, toCss, wordsConverter, } from '@fusion.dev/helix-core';
+import { CopyController, capturePointer, clamp, colorName, customElement, drawIcon, fillTemplate, focusItemOf, formatColor, formatNumber, HelixFormElement, HelixSampleEndEvent, HelixSampleStartEvent, hostAria, hueName, isRtl, KeyboardNavigationController, localeOf, MixinControllerValue, MixinPickerFeedback, parseColor, rovingStop, splitValues, toCss, wordsConverter, } from '@fusion.dev/helix-core';
 import { eyedropper } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { live } from 'lit/directives/live.js';
 import { html } from 'lit/static-html.js';
 import { channelFields, writeChannel } from '../channels.js';
-import { hueAt } from '../wheel.js';
+import { areaAt, hueAt } from '../wheel.js';
 import '../../button/index.js';
 import '../../button-group/index.js';
 import '../../slider/index.js';
@@ -99,15 +99,12 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
             items: () => [
                 ...(this.renderRoot?.querySelectorAll('[part="swatches"] [part="swatch"]') ??
                     []),
-            ].map((swatch, index) => ({
-                contains: (node) => swatch === node,
-                disabled: false,
-                focusItem: () => {
+            ].map((swatch, index) => focusItemOf(swatch, {
+                focus: () => {
                     this.swatchAt = index;
                     swatch.focus();
                 },
-                select: () => { },
-                selected: false,
+                owns: (node) => node === swatch,
             })),
             origin: 'focus',
             selects: () => false,
@@ -165,10 +162,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
             if (box.width === 0 || box.height === 0) {
                 return;
             }
-            const fromLeft = Math.min(1, Math.max(0, (event.clientX - box.left) / box.width));
-            const across = isRtl(grid) ? 1 - fromLeft : fromLeft;
-            const down = Math.min(1, Math.max(0, (event.clientY - box.top) / box.height));
-            this.move({ brightness: Math.round((1 - down) * 100), saturation: Math.round(across * 100) });
+            this.move(areaAt(event.clientX, event.clientY, box, isRtl(grid)));
         };
         this.handleWheelPointer = (event) => {
             const wheel = event.currentTarget;

package/dist/color-picker/wheel.d.ts

@@ -15,3 +15,14 @@ export interface WheelBox {
  * whatever the writing direction, since a circle has no line of text.
  */
 export declare const hueAt: (x: number, y: number, box: WheelBox) => number;
+/**
+ * The saturation and brightness at a point in the color square, 0 to 100:
+ * brightness falls downward, and saturation runs along the line, the way the
+ * two ramps under the square do, being native ranges. On a right-to-left page
+ * (`rtl`) it grows toward the left. A point outside the square is held to its
+ * edge.
+ */
+export declare const areaAt: (x: number, y: number, box: WheelBox, rtl: boolean) => {
+    brightness: number;
+    saturation: number;
+};

package/dist/color-picker/wheel.js

@@ -1,6 +1,15 @@
+import { clamp } from '@fusion.dev/helix-core';
 export const hueAt = (x, y, box) => {
     const across = x - (box.left + box.width / 2);
     const down = y - (box.top + box.height / 2);
     const degrees = Math.round((Math.atan2(across, -down) * 180) / Math.PI);
     return (degrees + 360) % 360;
 };
+export const areaAt = (x, y, box, rtl) => {
+    const fromLeft = clamp((x - box.left) / box.width, 0, 1);
+    const down = clamp((y - box.top) / box.height, 0, 1);
+    return {
+        brightness: Math.round((1 - down) * 100),
+        saturation: Math.round((rtl ? 1 - fromLeft : fromLeft) * 100),
+    };
+};

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

@@ -17,13 +17,33 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * reopened combobox starts from the whole list.
  *
  * Focus stays in the text field. The arrow keys move through the list with the
- * listbox's public `navigate` method. `role="combobox"` is on the input itself.
- * ArrowDown and ArrowUp open the list on the chosen option, and Enter chooses
- * the highlighted one. As typing narrows the list, a screen reader hears how
- * many options are left, such as "3 results". Space, Home, End and letters edit the text, and Enter in
- * a closed field is left to the form. Emptying the field and leaving it clears
- * a single choice; Escape puts the chosen words back, and a second Escape on
- * the closed field clears the choice.
+ * listbox's public `navigate` method. As typing narrows the list, a screen
+ * reader hears how many options are left, such as "3 results". Emptying the
+ * field and leaving it clears a single choice.
+ *
+ * **Keyboard.**
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Down, Up | On a closed field, opens the list on the chosen option, or the first or the last. In the open list, moves the highlight, round from the last option to the first. |
+ * | Page Down, Page Up | In the open list, moves the highlight by as many options as the list shows at once. |
+ * | Enter | Chooses the highlighted option. With nothing left in the list, creates what was typed with `creatable`, or takes it with `allows-custom-value`. On a closed field, submits the form. |
+ * | Escape | Closes the list and puts the chosen words back. On a closed field, a second Escape clears a single choice. |
+ * | Tab | Closes the list and moves on. |
+ * | Backspace | With `multiple`, on an empty field, removes the last tag. |
+ * | Space, Home, End, letters | Edit the text. |
+ *
+ * **ARIA.** The input is the `combobox`, named by the label, with
+ * `aria-expanded`, `aria-controls` naming the list, `aria-autocomplete`
+ * (`both` with `suggest`, `list` otherwise) and `aria-activedescendant` on
+ * the highlighted option. The list is the listbox `Listbox` describes.
+ *
+ * On Apple devices, where VoiceOver does not read the option the field points
+ * to, the field says it in a live region as the highlight moves, says how many
+ * options there are as the list opens, and says a choice once it is made, as
+ * React Aria's combobox does there.
+ *
+ * Set `autocomplete` to let a browser's autofill choose an option.
  *
  * With `multiple`, each chosen option is a tag in the field with its own remove
  * control. The panel stays open and the filter clears after each choice, so the
@@ -83,6 +103,7 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @csspart listbox-loading - Shown while the options are loading.
  * @csspart listbox-search - The region holding the field that narrows the list.
  * @csspart listbox-search-field - The filter field inside that region.
+ * @csspart live - The region VoiceOver hears the highlight, the count and a choice from on Apple devices, drawn once there is one to say. Visually hidden in the styled tier.
  * @csspart rest - The count of choices held beyond `max-tags`. A `<button>` with `expandable`, a `<span>` without it.
  * @csspart surface - The floating panel.
  * @csspart tag - One chosen option.
@@ -94,13 +115,22 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @csspart tag-start - The category before the label.
  * @csspart tags - The row of chosen options, when `multiple` is set.
  *
+ * @cssstate blank - While nothing is chosen.
  * @cssstate error - While `load-error` is set.
  * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
+ * @cssstate loading - While `loading` is set.
  * @cssstate no-results - What was typed hid every option of a list that has some.
  * @cssstate open - While the list is open.
  */
 export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
     protected readonly aria: AriaForwardController;
+    /** The region VoiceOver hears the highlight, the count and a choice from. */
+    private readonly status;
+    /**
+     * The option, or the create row, the region last said: `null` for none,
+     * and `undefined` until it has spoken since the list opened.
+     */
+    private told;
     /**
      * Whether text that names no option is taken as the value, as React Aria's
      * `allowsCustomValue`.
@@ -113,12 +143,19 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      */
     allowsCustomValue: boolean;
     /**
-     * What the browser may autofill in the text field, as a platform token.
+     * What the browser may autofill, as a platform token such as `country`.
      *
      * **Defaults to `off`, which is not the platform's default and is the
      * point.** The field filters a list rather than collecting a value, so a
      * browser offering to fill it with a saved address is competing for the same
      * keystrokes as the listbox. A consumer who wants autofill can still ask.
+     *
+     * Set, a combobox whose answer is one of its options keeps a hidden native
+     * `<select>` with the same options for the browser to fill, as React Aria's
+     * combobox and Select do, and the option the browser picks, by its value or
+     * its words, becomes the value. The text field itself stays `off`, so the
+     * browser fills the answer and not the filter. With `allows-custom-value`
+     * the token goes on the text field, whose words are the answer.
      */
     autocomplete: string;
     /**
@@ -155,10 +192,11 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
     listLabel: string;
     /**
      * What the list says when its options could not be loaded, such as after a
-     * request to a server fails. Empty is no error. Passed to the list, which
-     * shows it under any options there are and tells screen readers.
+     * request to a server fails. Empty, null or no attribute is no error, so
+     * removing the attribute clears it. Passed to the list, which shows it
+     * under any options there are and tells screen readers.
      */
-    loadError: string;
+    loadError: string | null;
     /**
      * Whether the options are still loading.
      *
@@ -236,6 +274,11 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      * two.
      */
     resultsLabel: string;
+    /**
+     * What VoiceOver hears for a chosen option, as the highlight reaches it and
+     * once it is chosen, on Apple devices. `{name}` is the option's words.
+     */
+    selectedLabel: string;
     /**
      * Whether the field completes the word as the user types.
      *
@@ -459,6 +502,20 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      * is missing.
      */
     private linkActive;
+    /**
+     * Says the highlight, and the count as the list opens, where VoiceOver
+     * would not.
+     *
+     * **VoiceOver does not read the option `aria-activedescendant` points to**
+     * while focus is in a text field, so on Apple devices the arrows moved
+     * through the list in silence. React Aria says the option there, with
+     * "selected" where it is chosen, and how many there are as the list opens.
+     * Only when the highlight moves to another option, so an update that leaves
+     * it where it was says nothing.
+     */
+    private tell;
+    /** How many options there are, said as the list opens, until an option is said with it. */
+    private counted;
     /**
      * Takes what the list announced and stops it there.
      *
@@ -565,6 +622,8 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      */
     private renderCreate;
     protected render(): TemplateResult;
+    /** Whether a browser's autofill fills the hidden select, rather than the text field. */
+    private get fills();
 }
 declare global {
     interface HTMLElementTagNameMap {