@fusion.dev/helix-headless 0.142.1 → 0.144.0

package/dist/number-input/root/number-input-root.js

@@ -4,10 +4,10 @@ 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, valueAsNumber as asNumber, customElement, fillTemplate, numberAsValue as fromNumber, HelixFormElement, holdCaret, MixinControllerValue, MixinField, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, appleTouch, valueAsNumber as asNumber, customElement, fillTemplate, formatNumber, numberAsValue as fromNumber, HelixFormElement, holdCaret, MixinControllerValue, MixinField, parseNumber, restoreValue, } from '@fusion.dev/helix-core';
 import { minus, plus } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 const SCRUB_PITCH = 4;
 const SCRUB_FINE = 16;
@@ -21,10 +21,31 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.autocomplete = '';
         this.decrementLabel = 'Decrease';
         this.incrementLabel = 'Increase';
+        this.locale = '';
         this.placeholder = '';
         this.readOnly = false;
+        this.roleDescription = 'number field';
         this.scrub = false;
         this.step = 1;
+        this.valueText = '';
+        this.wheel = false;
+        this.editing = false;
+        this.handleWheel = (event) => {
+            if (!this.wheel || !this.editing || event.deltaY === 0) {
+                return;
+            }
+            event.preventDefault();
+            if (event.deltaY < 0) {
+                this.stepUp();
+            }
+            else {
+                this.stepDown();
+            }
+        };
+        this.handleFocus = () => {
+            this.editing = true;
+        };
+        this.touchApple = appleTouch(typeof navigator === 'undefined' ? undefined : navigator);
         this.scrubFrom = 0;
         this.scrubValue = 0;
         this.scrubStart = '';
@@ -75,16 +96,14 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             restoreValue(control, this.value);
         };
         this.handleBlur = () => {
-            const control = this.control;
-            const parsed = this.numeric;
-            if (!control || parsed === null) {
-                return;
+            this.editing = false;
+            if (this.settle()) {
+                this.announceChange();
             }
-            this.requestValue(String(this.clamp(parsed)));
-            restoreValue(control, this.value);
         };
         this.handleChange = (event) => {
             event.stopPropagation();
+            this.settle();
             this.announceChange();
         };
         this.handleKeydown = (event) => {
@@ -117,20 +136,34 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             }
             event.preventDefault();
         };
+        this.handleKeypress = (event) => {
+            if (event.key === 'Enter' && !event.defaultPrevented) {
+                this.submitImplicitly();
+            }
+        };
+    }
+    get shown() {
+        const parsed = this.numeric;
+        if (this.editing || this.formatOptions === undefined || parsed === null) {
+            return this.value;
+        }
+        return formatNumber(parsed, this.locale, this.formatOptions);
     }
-    static { this.shadowRootOptions = {
-        ...HelixFormElement.shadowRootOptions,
-        delegatesFocus: true,
-    }; }
     get control() {
         return this.partNamed('control');
     }
     get numeric() {
-        if (this.value.trim() === '') {
+        const text = this.value.trim();
+        if (text === '') {
             return null;
         }
-        const parsed = Number(this.value);
-        return Number.isFinite(parsed) ? parsed : null;
+        return parseNumber(text, this.locale, this.formatOptions);
+    }
+    onStep(value) {
+        const step = Math.abs(this.step) || 1;
+        const anchor = this.min ?? 0;
+        const steps = (value - anchor) / step;
+        return Math.abs(steps - Math.round(steps)) < 1e-9;
     }
     clamp(value) {
         const step = Math.abs(this.step) || 1;
@@ -168,13 +201,10 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.nudge(large ? -(this.largeStep ?? 10) : -1);
     }
     renderLabel() {
-        if (!this.scrub) {
+        if (!this.scrub || !this.labeled) {
             return super.renderLabel();
         }
         const hidden = this.label === '' ? this.getAttribute('aria-label') : null;
-        if (this.label === '' && !hidden) {
-            return nothing;
-        }
         return html `<label
       part="label"
       for=${this.controlId}
@@ -186,6 +216,17 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
       ><slot name="label">${this.label || hidden}</slot></label
     >`;
     }
+    settle() {
+        const control = this.control;
+        const parsed = this.numeric;
+        if (!control || parsed === null) {
+            return false;
+        }
+        const before = this.value;
+        this.requestValue(String(this.clamp(parsed)));
+        restoreValue(control, this.value);
+        return this.value !== before;
+    }
     sync() {
         const control = this.control;
         this.internals.setFormValue(this.value);
@@ -212,6 +253,14 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
                 max: this.max,
             }), control);
         }
+        else if (parsed !== null && !this.onStep(parsed)) {
+            const step = Math.abs(this.step) || 1;
+            const anchor = this.min ?? 0;
+            const below = this.clamp(anchor + Math.floor((parsed - anchor) / step) * step);
+            const above = this.clamp(anchor + Math.ceil((parsed - anchor) / step) * step);
+            this.internals.setValidity({ stepMismatch: true }, fillTemplate(this.stepMismatchMessage ||
+                'Please enter a valid value. The two nearest valid values are {below} and {above}.', { above, below }), control);
+        }
         else {
             this.internals.setValidity({}, '', control);
         }
@@ -239,6 +288,9 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.releaseCaret = undefined;
         this.sync();
     }
+    get blocksImplicitSubmission() {
+        return true;
+    }
     render() {
         const parsed = this.numeric;
         const atMin = parsed !== null && this.min !== undefined && parsed <= this.min;
@@ -262,9 +314,10 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         <input
           part="control"
           id=${this.controlId}
-          .value=${this.value}
+          .value=${this.shown}
           type="text"
-          role="spinbutton"
+          role=${this.touchApple ? nothing : 'spinbutton'}
+          aria-roledescription=${this.touchApple ? this.roleDescription : nothing}
           inputmode="decimal"
           autocomplete=${this.autocomplete || nothing}
           name=${this.name || nothing}
@@ -274,13 +327,27 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
           aria-valuemin=${this.min ?? nothing}
           aria-valuemax=${this.max ?? nothing}
           aria-valuenow=${parsed ?? nothing}
+          aria-valuetext=${parsed === null
+            ? nothing
+            : this.valueText
+                ? fillTemplate(this.valueText, {
+                    value: this.formatOptions
+                        ? formatNumber(parsed, this.locale, this.formatOptions)
+                        : this.value,
+                })
+                : this.formatOptions
+                    ? formatNumber(parsed, this.locale, this.formatOptions)
+                    : nothing}
           ?disabled=${this.isDisabled}
           ?readonly=${this.readOnly}
           ?required=${this.required}
           @blur=${this.handleBlur}
           @change=${this.handleChange}
+          @focus=${this.handleFocus}
           @input=${this.handleInput}
           @keydown=${this.handleKeydown}
+          @keypress=${this.handleKeypress}
+          @wheel=${this.handleWheel}
         />
         <slot name="end"></slot>
         <button
@@ -314,12 +381,18 @@ __decorate([
 __decorate([
     property({ attribute: 'decrement-label' })
 ], HelixHeadlessNumberInput.prototype, "decrementLabel", void 0);
+__decorate([
+    property({ attribute: 'format-options', type: Object })
+], HelixHeadlessNumberInput.prototype, "formatOptions", void 0);
 __decorate([
     property({ attribute: 'increment-label' })
 ], HelixHeadlessNumberInput.prototype, "incrementLabel", void 0);
 __decorate([
     property({ attribute: 'large-step', type: Number })
 ], HelixHeadlessNumberInput.prototype, "largeStep", void 0);
+__decorate([
+    property()
+], HelixHeadlessNumberInput.prototype, "locale", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessNumberInput.prototype, "max", void 0);
@@ -338,12 +411,27 @@ __decorate([
 __decorate([
     property({ attribute: 'readonly', reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "readOnly", void 0);
+__decorate([
+    property({ attribute: 'role-description' })
+], HelixHeadlessNumberInput.prototype, "roleDescription", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "scrub", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessNumberInput.prototype, "step", void 0);
+__decorate([
+    property({ attribute: 'step-mismatch-message' })
+], HelixHeadlessNumberInput.prototype, "stepMismatchMessage", void 0);
+__decorate([
+    property({ attribute: 'value-text' })
+], HelixHeadlessNumberInput.prototype, "valueText", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessNumberInput.prototype, "wheel", void 0);
+__decorate([
+    state()
+], HelixHeadlessNumberInput.prototype, "editing", void 0);
 HelixHeadlessNumberInput = __decorate([
     customElement('helix-headless-number-input')
 ], HelixHeadlessNumberInput);

package/dist/object-inspector/root/object-inspector-root.d.ts

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
 /** One visible line of the tree: a value, where it sits, and whether it is open. */
@@ -28,9 +28,15 @@ interface Row {
  *
  * The tree is one tab stop. Up and Down move between rows, Right opens a branch
  * or moves into it, Left closes it or moves to its parent, and Home and End
- * move to the first and last rows. Focus stays on the tree, and
- * `aria-activedescendant` marks the active row. Each row carries its real
- * level, position, and set size, including in a windowed tree.
+ * move to the first and last rows. Typing moves to the next row whose key
+ * starts with what was typed, and `*` opens every branch beside the active
+ * row. Focus stays on the tree, and `aria-activedescendant` marks the active
+ * row. Each row carries its real level, position, and set size, including in
+ * a windowed tree.
+ *
+ * A new `value` keeps the branches a reader opened or closed, and the active
+ * row, where the new value still has them. A branch the old value did not have
+ * opens to `default-depth`.
  *
  * The copy button copies the active row, a branch as JSON and a string as its
  * text. So do Command+C and Control+C while the tree has focus and no text is
@@ -54,6 +60,7 @@ interface Row {
  * @csspart boolean - A `true` or `false`.
  * @csspart copy - The copy button, which copies the active row.
  * @csspart copy-button - The button inside the copy control.
+ * @csspart copy-live - The live region inside the copy button, which says its `pending-label` when the copy becomes pending under focus.
  * @csspart copy-mark - The clipboard icon, and the confirmation icon that replaces it.
  * @csspart copy-text - The words on that button, trimmed to their capitals and baseline.
  * @csspart copy-tooltip - The tooltip, forwarded from the copy button's tooltip.
@@ -110,6 +117,14 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * page's markup should not take the page down over a comma.
      */
     for: string;
+    /** How an array of one entry counts it. `{count}` is replaced with the count. */
+    itemLabel: string;
+    /** How an array of any other number of entries counts them. `{count}` is replaced with the count. */
+    itemsLabel: string;
+    /** How an object of one key counts it. `{count}` is replaced with the count. */
+    keyLabel: string;
+    /** How an object of any other number of keys counts them. `{count}` is replaced with the count. */
+    keysLabel: string;
     /**
      * Accessible name for the tree, and the text of the header where there is one.
      */
@@ -128,6 +143,11 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * reach a value.
      */
     noCopy: boolean;
+    /**
+     * The tree's accessible name when `label` is empty and the host names it
+     * with neither `aria-label` nor `aria-labelledby`.
+     */
+    treeLabel: string;
     /**
      * The value to show, when your code already holds it as an object.
      *
@@ -152,6 +172,12 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private active;
     /** Set by a keyboard move, so the next render brings the active row into view. */
     private revealing;
+    /** What has been typed toward a key, and when the last letter came. */
+    private typed;
+    /** The branches of the last value seen, by path, so a new value can tell old ones from new. */
+    private branches;
+    /** Carries a host `aria-label` and `aria-labelledby` to the tree, which is what takes focus. */
+    protected readonly aria: AriaForwardController;
     /**
      * How tall a row is taken to be before it has been drawn, in pixels.
      *
@@ -169,7 +195,15 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private readonly copier;
     /** Every visible row, in order, for the tree as it stands. */
     private flatten;
-    /** Opens every branch shallower than `defaultDepth`. */
+    /**
+     * Opens every branch shallower than `defaultDepth`.
+     *
+     * `keep` is for a new value: a branch the last value also had keeps whether
+     * a reader opened or closed it, and only a new one takes the default.
+     * **Assigning a value used to close everything**, so an inspector showing
+     * live data, a polled response or a debug panel, threw away the reader's
+     * place on every update.
+     */
     private seed;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
@@ -193,6 +227,16 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private toggle;
     private move;
     private readonly handleKeydown;
+    /** Opens every branch at the active row's level under the same parent, as `*` asks. */
+    private openSiblings;
+    /**
+     * Moves to the next row whose key starts with what was typed.
+     *
+     * Letters typed within half a second of each other run together, so `me`
+     * finds `meta` past `message`. A repeated single letter cycles through the
+     * keys that start with it.
+     */
+    private typeahead;
     private handleRowClick;
     private renderValue;
     /**

package/dist/object-inspector/root/object-inspector-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 HelixHeadlessObjectInspector_1;
-import { CopyController, customElement, elementById, fillTemplate, HelixElement, inlineStep, scrollItemIntoView, searchableById, VirtualizeController, } from '@fusion.dev/helix-core';
+import { AriaForwardController, CopyController, customElement, elementById, fillTemplate, formatNumbers, HelixElement, inlineStep, scrollItemIntoView, searchableById, VirtualizeController, } from '@fusion.dev/helix-core';
 import { caretDown, caretRight } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -22,14 +22,25 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
         this.copyValueLabel = 'Copy value';
         this.defaultDepth = 1;
         this.for = '';
+        this.itemLabel = '{count} item';
+        this.itemsLabel = '{count} items';
+        this.keyLabel = '{count} key';
+        this.keysLabel = '{count} keys';
         this.label = '';
         this.noCopy = false;
+        this.treeLabel = 'Value';
         this.value = undefined;
         this.windowed = false;
         this.read = undefined;
         this.opened = new Set();
         this.active = 0;
         this.revealing = false;
+        this.typed = { at: 0, text: '' };
+        this.branches = new Set();
+        this.aria = new AriaForwardController(this, {
+            label: true,
+            target: () => this.partNamed('tree'),
+        });
         this.virtualize = new VirtualizeController(this, {
             container: () => (this.windowed ? this.partNamed('tree') : null),
             count: () => this.rows.length,
@@ -92,8 +103,14 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
                         this.toggle(row);
                     }
                     break;
+                case '*':
+                    this.openSiblings(row);
+                    break;
                 default:
-                    return;
+                    if (event.key.length !== 1 || event.altKey || event.ctrlKey || event.metaKey) {
+                        return;
+                    }
+                    this.typeahead(event.key);
             }
             event.preventDefault();
         };
@@ -131,20 +148,28 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
         visit(this.root, '', 0, 1, 1);
         return rows;
     }
-    seed() {
+    seed(keep) {
         const opened = new Set();
+        const branches = new Set();
         const visit = (value, path, depth) => {
-            if (!branchy(value) || depth >= this.defaultDepth) {
+            if (!branchy(value)) {
                 return;
             }
-            opened.add(path);
+            branches.add(path);
+            const known = keep && this.branches.has(path);
+            if (known ? this.opened.has(path) : depth < this.defaultDepth) {
+                opened.add(path);
+            }
             for (const [name, item] of entries(value)) {
                 visit(item, child(path, name), depth + 1);
             }
         };
         visit(this.root, '', 0);
+        this.branches = branches;
         this.opened = opened;
-        this.active = 0;
+        if (!keep) {
+            this.active = 0;
+        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -152,15 +177,17 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
             this.loadedFor = this.for;
             this.load();
         }
+        const was = this.rows[this.active]?.path;
         if (changed.has('value') || changed.has('read') || changed.has('defaultDepth')) {
-            this.seed();
+            this.seed(!changed.has('defaultDepth'));
         }
         if (changed.has('value') ||
             changed.has('read') ||
             changed.has('opened') ||
             changed.has('defaultDepth')) {
             this.rows = this.flatten();
-            this.active = Math.min(this.active, Math.max(0, this.rows.length - 1));
+            const found = was === undefined ? -1 : this.rows.findIndex((row) => row.path === was);
+            this.active = found >= 0 ? found : Math.min(this.active, Math.max(0, this.rows.length - 1));
         }
     }
     firstUpdated(changed) {
@@ -229,6 +256,35 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
         this.active = Math.max(0, Math.min(to, last));
         this.revealing = true;
     }
+    openSiblings(row) {
+        const parent = row.path.slice(0, row.path.lastIndexOf('/'));
+        const opened = new Set(this.opened);
+        for (const one of this.rows) {
+            if (one.branch &&
+                one.depth === row.depth &&
+                one.path.slice(0, one.path.lastIndexOf('/')) === parent) {
+                opened.add(one.path);
+            }
+        }
+        this.opened = opened;
+    }
+    typeahead(letter) {
+        const now = Date.now();
+        const text = now - this.typed.at < 500 ? this.typed.text + letter : letter;
+        this.typed = { at: now, text };
+        const wanted = text.toLocaleLowerCase();
+        const repeated = [...wanted].every((one) => one === wanted[0]);
+        const rows = this.rows;
+        const start = wanted.length === 1 || repeated ? this.active + 1 : this.active;
+        for (let step = 0; step < rows.length; step += 1) {
+            const at = (start + step) % rows.length;
+            const key = rows[at]?.key?.toLocaleLowerCase();
+            if (key?.startsWith(repeated ? (wanted[0] ?? '') : wanted)) {
+                this.move(at);
+                return;
+            }
+        }
+    }
     handleRowClick(index, row) {
         this.active = index;
         if (row.branch) {
@@ -240,9 +296,18 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
         if (row.branch) {
             const count = entries(value).length;
             const array = Array.isArray(value);
-            const noun = array ? (count === 1 ? 'item' : 'items') : count === 1 ? 'key' : 'keys';
+            const one = new Intl.PluralRules(this.lang || undefined).select(count) === 'one';
+            const words = array
+                ? one
+                    ? this.itemLabel
+                    : this.itemsLabel
+                : one
+                    ? this.keyLabel
+                    : this.keysLabel;
             return html `<span part="summary">${array ? '[…]' : '{…}'}</span>
-        <span part="count" dir="auto">${`${count} ${noun}`}</span>`;
+        <span part="count" dir="auto"
+          >${fillTemplate(words, { count: formatNumbers(this.lang)(count) })}</span
+        >`;
         }
         if (typeof value === 'string') {
             return html `<span part="string" dir="ltr">${JSON.stringify(value)}</span>`;
@@ -288,7 +353,7 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
     renderCopyButton(row) {
         return staticHtml `<${this.tag('copy-button')}
       part="copy"
-      exportparts="button: copy-button, text: copy-text, mark: copy-mark, tooltip: copy-tooltip,
+      exportparts="button: copy-button, live: copy-live, text: copy-text, mark: copy-mark, tooltip: copy-tooltip,
         tooltip-arrow: copy-tooltip-arrow, tooltip-arrow-bottom: copy-tooltip-arrow-bottom,
         tooltip-arrow-left: copy-tooltip-arrow-left, tooltip-arrow-right: copy-tooltip-arrow-right,
         tooltip-arrow-top: copy-tooltip-arrow-top, tooltip-bottom: copy-tooltip-bottom,
@@ -310,7 +375,7 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
           role="tree"
           tabindex="0"
           ?data-scroller=${this.windowed}
-          aria-label=${this.label || 'Value'}
+          aria-label=${this.label || this.treeLabel}
           aria-activedescendant=${rows.length > 0 ? `row-${this.active}` : nothing}
           @keydown=${this.handleKeydown}
           @scroll=${() => this.virtualize.measure()}
@@ -335,12 +400,27 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessObjectInspector.prototype, "for", void 0);
+__decorate([
+    property({ attribute: 'item-label' })
+], HelixHeadlessObjectInspector.prototype, "itemLabel", void 0);
+__decorate([
+    property({ attribute: 'items-label' })
+], HelixHeadlessObjectInspector.prototype, "itemsLabel", void 0);
+__decorate([
+    property({ attribute: 'key-label' })
+], HelixHeadlessObjectInspector.prototype, "keyLabel", void 0);
+__decorate([
+    property({ attribute: 'keys-label' })
+], HelixHeadlessObjectInspector.prototype, "keysLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessObjectInspector.prototype, "label", void 0);
 __decorate([
     property({ attribute: 'no-copy', type: Boolean })
 ], HelixHeadlessObjectInspector.prototype, "noCopy", void 0);
+__decorate([
+    property({ attribute: 'tree-label' })
+], HelixHeadlessObjectInspector.prototype, "treeLabel", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessObjectInspector.prototype, "value", void 0);

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { HelixElement, type LinkModifiers } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * The options among some elements, reaching one level into a group.
@@ -34,6 +34,9 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * Filtering belongs to the owner, which hides an option with `hidden`. What
  * counts as a match differs between a select and a command palette.
  *
+ * An option with `href` is a link: choosing it follows the link and selects
+ * nothing, as an entry in a command palette that goes to a page does.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -44,7 +47,7 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * @slot end - Content after the label, such as a shortcut or a count.
  * @slot start - Content before the label, such as an icon or an avatar.
  *
- * @event {HelixSelectEvent} helix-select - The option was chosen. Cancelable: canceling it leaves the selection as it was.
+ * @event {HelixSelectEvent} helix-select - The option was chosen. Cancelable: canceling it leaves the selection as it was, and keeps the browser from following an option's `href`.
  *
  * @csspart description - The description under the label, when there is one.
  * @csspart item - The row.
@@ -53,13 +56,16 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * @csspart label - The option's label.
  * @csspart text - The label and the description under it, as one column.
  *
+ * @cssstate active - While the keyboard is on the option, which is the option `aria-activedescendant` names.
  * @cssstate selected - While the option is chosen.
  */
 export declare class HelixHeadlessOption extends HelixElement {
     /**
      * Whether this is the option the keyboard is on.
      *
-     * Written by the listbox.
+     * Written by the listbox, which writes it once a reader moves the highlight.
+     * It shows as `:state(active)`, and as a `data-active` attribute for the
+     * stylesheets written before the state existed.
      */
     active: boolean;
     /**
@@ -145,6 +151,28 @@ export declare class HelixHeadlessOption extends HelixElement {
      * Prevents the option from being chosen.
      */
     disabled: boolean;
+    /**
+     * Whether following the link downloads what it names. Only meaningful
+     * beside an `href`.
+     */
+    download: boolean;
+    /**
+     * The URL the option links to. Setting it makes the option a link: choosing
+     * it, with a press, Enter or a click, follows the link and selects nothing,
+     * as React Aria's items with `href` do. Command, Control and Shift open it
+     * where they open a link, in a new tab or a new window.
+     *
+     * `helix-select` is said first with the `href` in it, and canceling it keeps
+     * the browser from following, so a client-side router follows it instead.
+     *
+     * **The option stays an option**, and an anchor is never drawn inside it:
+     * `role="option"` sits on the host, where a listbox's
+     * `aria-activedescendant` can name it, and an `<a>` inside would be exposed
+     * as a link within the option and take its name (Menu Item's `href` records
+     * the measurement). The link is followed through an anchor made for the
+     * moment, which `followLink` describes.
+     */
+    href: string;
     /**
      * A shorter name for this choice, for where the row does not fit.
      *
@@ -158,12 +186,30 @@ export declare class HelixHeadlessOption extends HelixElement {
      * nothing for every choice.
      */
     label: string;
+    /**
+     * The link's `rel`. Set it whenever you set `target="_blank"`.
+     */
+    rel: string;
     /**
      * Whether this choice is currently chosen.
      *
      * Written by the listbox.
      */
     selected: boolean;
+    /**
+     * Where the link opens, such as `_blank`, for an option with an `href`.
+     */
+    target: string;
+    /**
+     * The words a reader types to reach this choice, where the row's own words
+     * are not them: typeahead, a filter and a combobox match against it, and a
+     * select's trigger shows it.
+     *
+     * For a row whose content is a picture, an avatar beside a name and a role,
+     * or a name written in another script, as React Aria's `textValue`. Empty
+     * reads the row's words, then `label`.
+     */
+    textValue: string;
     /**
      * The value that identifies the option, and that a form submits.
      */
@@ -207,11 +253,17 @@ export declare class HelixHeadlessOption extends HelixElement {
      * it is in every comparison too.
      *
      * **The `label` where the slot holds nothing**, which is what the row shows
-     * then, so the six read the words a reader sees.
+     * then, so the six read the words a reader sees. `text-value` wins over both,
+     * being the consumer saying outright what the words are.
      */
     get text(): string;
-    /** Sends `helix-select` for this option. Does nothing when it is disabled. */
-    select(): void;
+    /**
+     * Sends `helix-select` for this option. Does nothing when it is disabled.
+     *
+     * An option with an `href` then follows its link, unless the event was
+     * canceled, with the keys `modifiers` names held.
+     */
+    select(modifiers?: LinkModifiers): void;
     /**
      * Mirrors the chosen state where a stylesheet can select on it.
      *