@fusion.dev/helix-headless 0.155.0 → 0.157.0

package/dist/number-input/root/number-input-root.d.ts

@@ -25,17 +25,24 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * The locale's group separators are read in every field, so `1,234` is a
  * number in `en-US`.
  *
- * On iOS and iPadOS the field is a plain text field, with no
- * `role="spinbutton"`, which VoiceOver reads as a slider you cannot type in,
- * and no role description, so VoiceOver says the field is required. React
- * Aria's NumberField does the same.
+ * The field and its two buttons sit in a `role="group"`, and the field carries
+ * `role-label`, "number field" in English, as its `aria-roledescription`, as
+ * React Aria's NumberField does. On iOS and iPadOS the field is a plain text
+ * field, with no `role="spinbutton"`, which VoiceOver reads as a slider you
+ * cannot type in, and no role description, so VoiceOver says the field is
+ * required. React Aria's NumberField does the same.
  *
  * Validity follows the platform's rules: `min`, `max`, and `step` are checked
  * and reported through the host's own `setValidity`, under the platform's flag
  * names.
  *
  * Stepping is separate from typing, so a number is not corrected while you type
- * it.
+ * it. While you type, the form holds the number the text reads as, so a field
+ * showing `$2,500.50` gives the form 2500.5, and text that is not a number
+ * gives it nothing, as a native number field does.
+ *
+ * Holding a stepper button down steps once, then again after 400 milliseconds,
+ * then every 60 milliseconds until you let go, as React Aria's NumberField does.
  *
  * **Keyboard.** The field is one tab stop, and the stepper buttons are not in
  * the tab order.
@@ -56,9 +63,11 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * @aliases NumberField, Stepper, InputNumber
  * @documentation https://fusion.dev/helix/components/number-input
  *
+ * @slot decrement-icon - Replaces the icon on the step down button.
  * @slot end - Content after the number, such as a unit.
  * @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 increment-icon - Replaces the icon on the step up button.
  * @slot label - The label, for content richer than the `label` text.
  * @slot start - Content before the number, such as a unit or an icon.
  *
@@ -70,7 +79,7 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * @csspart decrement - The button that steps the value down.
  * @csspart decrement-mark - The icon on the step down button.
  * @csspart feedback - The message that says what is wrong.
- * @csspart field - The box that holds the whole control.
+ * @csspart field - The box that holds the whole control, a `role="group"` around the field and its buttons.
  * @csspart hint - Help text under the field, shown while there is no feedback.
  * @csspart increment - The button that steps the value up.
  * @csspart increment-mark - The icon on the step up button.
@@ -175,6 +184,15 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * Prevents editing. The value is still submitted with the form.
      */
     readOnly: boolean;
+    /**
+     * The words screen readers announce for the field's role, set as its
+     * `aria-roledescription`. Translate it with the rest of your text, or empty
+     * it to leave the role as `spinbutton`.
+     *
+     * Never written on iOS and iPadOS, where a role description stops VoiceOver
+     * saying that the field is required.
+     */
+    roleLabel: string;
     /**
      * Makes the label a grip that changes the value when it is dragged.
      *
@@ -292,6 +310,26 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * having to repeat both.
      */
     stepDown(large?: boolean): void;
+    /** The timer of a held stepper button. */
+    private repeat;
+    /** Whether a pointer press stepped already, so the click that ends it does not step again. */
+    private pressStepped;
+    /**
+     * A stepper button pressed with a pointer steps at once, and again while it
+     * is held.
+     *
+     * Captured, so letting go outside the button still ends the hold. A click
+     * with no press before it, from a screen reader or a script, steps once in
+     * `handleStepperClick`.
+     */
+    private readonly handleStepperDown;
+    /**
+     * Ends a hold. The click that follows a release arrives in the same task,
+     * so the press is forgotten after it.
+     */
+    private readonly stopRepeat;
+    private readonly handleStepperClick;
+    disconnectedCallback(): void;
     /**
      * The label is the surface, which is where the convention already is.
      *
@@ -391,6 +429,17 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * what a reader pressing them meant.
      */
     private readonly handleKeydown;
+    /**
+     * What the form holds for the field: the number the text reads as.
+     *
+     * The text as written where it is already a plain number, so a value of
+     * `0.50` is sent as written. A number written in the locale or the format,
+     * `$2,500.50` or `1.234,5`, is sent as the number, 2500.5 or 1234.5, so a
+     * form read while the field still has focus gets what a submit would. Text
+     * that is not a number is sent as empty, as a native number field sends it.
+     * The text itself is the state the browser restores.
+     */
+    private submitted;
     /**
      * Reports the value and a verdict on it.
      *
@@ -433,6 +482,14 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
     private readonly handleKeypress;
     /** @internal A single line of text counts against implicit submission. */
     protected get blocksImplicitSubmission(): boolean;
+    /**
+     * The step down button's icon, as the `decrement-icon` slot's fallback, so an
+     * icon of your own replaces it by being slotted, and a tier above by
+     * overriding this.
+     */
+    protected renderDecrementIcon(): TemplateResult;
+    /** The step up button's icon, behind the same seam as `renderDecrementIcon`. */
+    protected renderIncrementIcon(): TemplateResult;
     protected render(): TemplateResult;
     /**
      * The value as a number, or `NaN` while the control is empty.

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

@@ -12,6 +12,9 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { decimals, formatGrain, strideOf } from '../grain.js';
 const SCRUB_PITCH = 4;
 const SCRUB_FINE = 16;
+const PLAIN = /^-?(\d+(\.\d*)?|\.\d+)$/;
+const REPEAT_DELAY = 400;
+const REPEAT_EVERY = 60;
 let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinControllerValue(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
@@ -28,6 +31,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.rangeOverflowMessage = 'Value must be {max} or less.';
         this.rangeUnderflowMessage = 'Value must be {min} or more.';
         this.readOnly = false;
+        this.roleLabel = 'number field';
         this.scrub = false;
         this.stepMismatchMessage = 'Please enter a valid value. The two nearest valid values are {below} and {above}.';
         this.valueText = '';
@@ -49,6 +53,53 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             this.editing = true;
         };
         this.touchApple = appleTouch(typeof navigator === 'undefined' ? undefined : navigator);
+        this.pressStepped = false;
+        this.handleStepperDown = (event) => {
+            if (event.button !== 0) {
+                return;
+            }
+            const button = event.currentTarget;
+            const up = button.getAttribute('part') === 'increment';
+            clearTimeout(this.repeat);
+            this.pressStepped = true;
+            button.setPointerCapture?.(event.pointerId);
+            const step = () => {
+                const before = this.value;
+                if (up) {
+                    this.stepUp();
+                }
+                else {
+                    this.stepDown();
+                }
+                this.repeat = this.value === before ? undefined : setTimeout(step, REPEAT_EVERY);
+            };
+            step();
+            if (this.repeat !== undefined) {
+                clearTimeout(this.repeat);
+                this.repeat = setTimeout(step, REPEAT_DELAY);
+            }
+        };
+        this.stopRepeat = () => {
+            clearTimeout(this.repeat);
+            this.repeat = undefined;
+            if (this.pressStepped) {
+                setTimeout(() => {
+                    this.pressStepped = false;
+                });
+            }
+        };
+        this.handleStepperClick = (event) => {
+            if (this.pressStepped) {
+                this.pressStepped = false;
+                return;
+            }
+            if (event.currentTarget.getAttribute('part') === 'increment') {
+                this.stepUp();
+            }
+            else {
+                this.stepDown();
+            }
+        };
         this.scrubFrom = 0;
         this.scrubValue = 0;
         this.scrubStart = '';
@@ -240,6 +291,10 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
     stepDown(large = false) {
         this.nudge(large ? -(this.largeStep ?? 10) : -1);
     }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.stopRepeat();
+    }
     renderLabel() {
         if (!this.scrub || !this.labeled) {
             return super.renderLabel();
@@ -267,13 +322,20 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         restoreValue(control, this.shown);
         return this.value !== before;
     }
+    submitted(parsed) {
+        const text = this.value.trim();
+        if (parsed === null) {
+            return '';
+        }
+        return PLAIN.test(text) ? text : String(parsed);
+    }
     sync() {
         const control = this.control;
-        this.internals.setFormValue(this.value);
+        const parsed = this.numeric;
+        this.internals.setFormValue(this.submitted(parsed), this.value);
         if (!control) {
             return;
         }
-        const parsed = this.numeric;
         if (this.readOnly) {
             this.internals.setValidity({});
         }
@@ -329,23 +391,39 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
     get blocksImplicitSubmission() {
         return true;
     }
+    renderDecrementIcon() {
+        return html `<slot name="decrement-icon" aria-hidden="true"
+      ><svg part="decrement-mark" fill="currentColor" viewBox=${minus.viewBox} aria-hidden="true">
+        ${unsafeSVG(minus.content)}
+      </svg></slot
+    >`;
+    }
+    renderIncrementIcon() {
+        return html `<slot name="increment-icon" aria-hidden="true"
+      ><svg part="increment-mark" fill="currentColor" viewBox=${plus.viewBox} aria-hidden="true">
+        ${unsafeSVG(plus.content)}
+      </svg></slot
+    >`;
+    }
     render() {
         const parsed = this.numeric;
         const atMin = parsed !== null && this.min !== undefined && parsed <= this.min;
         const atMax = parsed !== null && this.max !== undefined && parsed >= this.max;
         return html `${this.renderLabel()}
-      <div part="field">
+      <div part="field" role="group">
         <button
           part="decrement"
           type="button"
           aria-label=${this.decrementLabel}
           tabindex="-1"
           ?disabled=${this.isDisabled || this.readOnly || atMin}
-          @click=${() => this.stepDown()}
+          @click=${this.handleStepperClick}
+          @lostpointercapture=${this.stopRepeat}
+          @pointercancel=${this.stopRepeat}
+          @pointerdown=${this.handleStepperDown}
+          @pointerup=${this.stopRepeat}
         >
-          <svg part="decrement-mark" fill="currentColor" viewBox=${minus.viewBox} aria-hidden="true">
-            ${unsafeSVG(minus.content)}
-          </svg>
+          ${this.renderDecrementIcon()}
         </button>
         <slot name="start"></slot>
         ${''}
@@ -355,6 +433,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
           .value=${this.shown}
           type="text"
           role=${this.touchApple ? nothing : 'spinbutton'}
+          aria-roledescription=${this.touchApple || this.roleLabel === '' ? nothing : this.roleLabel}
           inputmode="decimal"
           autocomplete=${this.autocomplete || nothing}
           name=${this.name || nothing}
@@ -393,11 +472,13 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
           aria-label=${this.incrementLabel}
           tabindex="-1"
           ?disabled=${this.isDisabled || this.readOnly || atMax}
-          @click=${() => this.stepUp()}
+          @click=${this.handleStepperClick}
+          @lostpointercapture=${this.stopRepeat}
+          @pointercancel=${this.stopRepeat}
+          @pointerdown=${this.handleStepperDown}
+          @pointerup=${this.stopRepeat}
         >
-          <svg part="increment-mark" fill="currentColor" viewBox=${plus.viewBox} aria-hidden="true">
-            ${unsafeSVG(plus.content)}
-          </svg>
+          ${this.renderIncrementIcon()}
         </button>
       </div>
       ${this.renderHint()}${this.renderFeedback()}`;
@@ -453,6 +534,10 @@ __decorate([
 __decorate([
     property({ attribute: 'readonly', reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "readOnly", void 0);
+__decorate([
+    words,
+    property({ attribute: 'role-label' })
+], HelixHeadlessNumberInput.prototype, "roleLabel", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "scrub", void 0);

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

@@ -2,6 +2,24 @@ import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
 import { type Row } from '../rows.js';
+/** What a `renderValue` function is told about the entry it draws. */
+export interface ObjectInspectorEntry {
+    /** How deep the entry is, from 0 at the root. */
+    depth: number;
+    /** The property name or array index the value is under, absent for the root. */
+    key: string | undefined;
+    /** The entry's path, as `active` writes it: `/meta/tags/0`. */
+    path: string;
+    /** What kind of value it is, as JSON names it: `array`, `boolean`, `null`, `number`, `object` or `string`. Anything else is `other`. */
+    type: 'array' | 'boolean' | 'null' | 'number' | 'object' | 'other' | 'string';
+}
+/**
+ * Draws one entry's value, for an inspector given `renderValue`.
+ *
+ * Returns anything Lit renders, such as a template from `html`, a string, or a
+ * DOM node, or `undefined` to draw the value as the inspector does.
+ */
+export type ObjectInspectorRenderer = (value: unknown, entry: ObjectInspectorEntry) => unknown;
 /**
  * @summary A structured value shown as a tree, where you can close branches,
  * see how many entries each holds, and copy any part.
@@ -65,6 +83,12 @@ import { type Row } from '../rows.js';
  * selected. The button sits beside the tree, because assistive technology
  * cannot reliably reach a button inside a tree item.
  *
+ * **Your own drawing of a value.** `renderValue` is a function from a value and
+ * its entry, its path, key, depth and type, to what Lit renders, such as a
+ * link for a URL or a swatch for a color. Return `undefined` to draw the value
+ * as the inspector does. What you draw sits in the `value` part, after the
+ * key. Filtering and copying still read the value itself.
+ *
  * `windowed` draws only the rows in view, for values with thousands of entries.
  * The box needs a height for windowing to work. The styled tier sets one, and
  * in the headless tier you set it yourself.
@@ -119,6 +143,7 @@ import { type Row } from '../rows.js';
  * @csspart summary - The brackets that stand for a branch's contents.
  * @csspart toggle - The caret on a branch. It points down when the branch is open and sideways when it is closed.
  * @csspart tree - The tree grid that holds the rows.
+ * @csspart value - What `renderValue` drew for an entry, in place of its own drawing.
  *
  * @cssproperty --object-inspector-level - How deep a row is, from 0 at the root, for indenting it.
  */
@@ -229,6 +254,16 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * reach a value.
      */
     noCopy: boolean;
+    /**
+     * Draws an entry's value your way, given the value and its entry. Set it as
+     * a property.
+     *
+     * It returns what Lit renders: a template from `html`, a string, or a DOM
+     * node. `undefined` draws the value as the inspector does, so a function can
+     * draw some entries and leave the rest, such as only the strings under
+     * `/links`.
+     */
+    renderValue: ObjectInspectorRenderer | undefined;
     /**
      * What a screen reader hears when a filter matches one entry, where
      * `results-label` should not say it. `{count}` is the count.
@@ -397,7 +432,7 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private readonly handleFilterInput;
     /** Down from the filter field goes to the active row, where the matches are. */
     private readonly handleFilterKeydown;
-    private renderValue;
+    private drawValue;
     /**
      * One entry, named for its state where it holds one.
      *

package/dist/object-inspector/root/object-inspector-root.js

@@ -14,6 +14,18 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html as staticHtml } from 'lit/static-html.js';
 import '../../copy-button/index.js';
 import { cursorFor, entries, flatten, search, seed, siblingBranches, withAncestors, } from '../rows.js';
+const kindOf = (value) => {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    const type = typeof value;
+    return type === 'boolean' || type === 'number' || type === 'object' || type === 'string'
+        ? type
+        : 'other';
+};
 let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends HelixElement {
     constructor() {
         super(...arguments);
@@ -393,8 +405,17 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
             this.toggle(row);
         }
     }
-    renderValue(row) {
+    drawValue(row) {
         const { value } = row;
+        const drawn = this.renderValue?.(value, {
+            depth: row.depth,
+            key: row.key,
+            path: row.path,
+            type: kindOf(value),
+        });
+        if (drawn !== undefined) {
+            return html `<span part="value">${drawn}</span>`;
+        }
         if (row.branch) {
             const count = entries(value).length;
             const array = Array.isArray(value);
@@ -439,7 +460,7 @@ let HelixHeadlessObjectInspector = class HelixHeadlessObjectInspector extends He
             >
               ${unsafeSVG((row.open ? caretDown : caretRight).content)}
             </svg>`
-            : nothing}${row.key === undefined ? nothing : html `<span part="key">${row.key}</span>: `}${this.renderValue(row)}</div>
+            : nothing}${row.key === undefined ? nothing : html `<span part="key">${row.key}</span>: `}${this.drawValue(row)}</div>
     </div>`;
     }
     hasFocusedRow() {
@@ -563,6 +584,9 @@ __decorate([
 __decorate([
     property({ attribute: 'no-copy', type: Boolean })
 ], HelixHeadlessObjectInspector.prototype, "noCopy", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessObjectInspector.prototype, "renderValue", void 0);
 __decorate([
     property({ attribute: 'result-label' })
 ], HelixHeadlessObjectInspector.prototype, "resultLabel", void 0);

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

@@ -37,6 +37,12 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * 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.
  *
+ * The option's name is its label alone, as React Aria's `slot="label"` makes
+ * it: what is in `start` and `end`, an avatar's initials or a shortcut, is
+ * drawn and not read as part of the name. The description is read as the
+ * option's description. A name you give with `aria-label` or
+ * `aria-labelledby` wins over both.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -61,6 +67,8 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * @cssstate active - While the keyboard is on the option, which is the option `aria-activedescendant` names.
  * @cssstate disabled - While the option cannot be chosen.
  * @cssstate has-indicator - An icon is slotted into `indicator`.
+ * @cssstate hovered - While a mouse or a pen is over the option. A touch sets no hover, as React Aria's `data-hovered` does not.
+ * @cssstate pressed - While a pointer presses the option, from the press to the release.
  * @cssstate selected - While the option is chosen.
  */
 export declare class HelixHeadlessOption extends HelixElement {
@@ -188,6 +196,17 @@ export declare class HelixHeadlessOption extends HelixElement {
      * nothing for every choice.
      */
     label: string;
+    /**
+     * The page of commands this option opens, by name, where choosing it would
+     * otherwise run it.
+     *
+     * Declared here and acted on by whatever owns the list, as `alternate` is.
+     * `Command` is the only owner that reads it: choosing the option shows the
+     * commands slotted as `page:` and the name, such as `slot="page:theme"`,
+     * and Backspace in an empty filter goes back. Empty is an option that opens
+     * nothing, which is nearly every option.
+     */
+    opens: string;
     /**
      * The link's `rel`. Set it whenever you set `target="_blank"`.
      */
@@ -291,6 +310,19 @@ export declare class HelixHeadlessOption extends HelixElement {
      * consumer's markup means. What stops is the write back.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The name is the label part and the description the description part, by
+     * reference, because the host's own content runs `start` and `end` into its
+     * name: an option with initials and a shortcut was called `P Priya Shah ⌘P`.
+     * The alternate destination is part of the description where there is a
+     * caption to read with it. A name the consumer wrote on the host wins.
+     */
+    protected updated(changed: PropertyValues): void;
+    /** A hover from a mouse or a pen, which a touch does not make. */
+    private readonly handlePointerEnter;
+    private readonly handlePointerLeave;
+    private readonly handlePointerDown;
+    private readonly handlePointerUp;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/option/root/option-root.js

@@ -4,8 +4,8 @@ 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 { customElement, followLink, HelixElement, HelixSelectEvent, slotFilled, } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { customElement, followLink, HelixElement, HelixSelectEvent, hostAria, slotFilled, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 export const optionsAmong = (elements) => {
     const isOption = (element) => 'text' in element && 'value' in element && 'selected' in element;
@@ -21,12 +21,26 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
         this.download = false;
         this.href = '';
         this.label = '';
+        this.opens = '';
         this.rel = '';
         this.selected = false;
         this.selectionFollowsActive = false;
         this.target = '';
         this.textValue = '';
         this.value = '';
+        this.handlePointerEnter = (event) => {
+            this.toggleState('hovered', event.pointerType !== 'touch');
+        };
+        this.handlePointerLeave = () => {
+            this.toggleState('hovered', false);
+            this.toggleState('pressed', false);
+        };
+        this.handlePointerDown = (event) => {
+            this.toggleState('pressed', event.button === 0 && !this.disabled);
+        };
+        this.handlePointerUp = () => {
+            this.toggleState('pressed', false);
+        };
     }
     get defaultSelected() {
         return this.hasAttribute('selected');
@@ -62,6 +76,21 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
         this.toggleState('active', this.active);
         this.toggleState('disabled', this.disabled);
     }
+    updated(changed) {
+        super.updated(changed);
+        const named = this.hasAttribute('aria-label') || this.hasAttribute('aria-labelledby');
+        const label = this.partNamed('label');
+        const caption = this.partNamed('description');
+        const alternate = this.renderRoot.querySelector('[data-alternate]');
+        const described = [
+            ...(caption ? [caption] : this.knownChildren.filter((child) => child.slot === 'description')),
+            ...(alternate ? [alternate] : []),
+        ];
+        hostAria(this.internals, {
+            describedBy: described,
+            labelledBy: named || !label ? [] : [label],
+        });
+    }
     render() {
         this.internals.role = 'option';
         this.internals.ariaSelected =
@@ -69,19 +98,26 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
                 ? String(this.selected || (this.selectionFollowsActive && this.active))
                 : null;
         this.internals.ariaDisabled = this.disabled ? 'true' : null;
-        this.internals.ariaDescription =
-            this.alternate !== '' && this.alternateLabel !== '' ? this.alternateLabel : null;
+        const alternate = this.alternate !== '' && this.alternateLabel !== '';
+        const captioned = Boolean(this.description) || this.knownChildren.some((child) => child.slot === 'description');
+        this.internals.ariaDescription = alternate && !captioned ? this.alternateLabel : null;
         return html `<div
       part="item${this.selected ? ' item-selected' : ''}${this.active ? ' item-active' : ''}"
       @click=${(event) => this.select(event)}
+      @pointercancel=${this.handlePointerUp}
+      @pointerdown=${this.handlePointerDown}
+      @pointerenter=${this.handlePointerEnter}
+      @pointerleave=${this.handlePointerLeave}
+      @pointerup=${this.handlePointerUp}
     >
       <slot name="start"></slot>
       <span part="text">
         <span part="label"><slot>${this.label}</slot></span>
         ${this.description
             ? html `<span part="description"><slot name="description">${this.description}</slot></span>`
-            : html `<slot name="description"></slot>`}
+            : html `<slot name="description" @slotchange=${() => this.requestUpdate()}></slot>`}
       </span>
+      ${alternate && captioned ? html `<span data-alternate hidden>${this.alternateLabel}</span>` : nothing}
       <slot name="end"></slot>
       <slot
         name="indicator"
@@ -114,6 +150,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessOption.prototype, "label", void 0);
+__decorate([
+    property()
+], HelixHeadlessOption.prototype, "opens", void 0);
 __decorate([
     property()
 ], HelixHeadlessOption.prototype, "rel", void 0);

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

@@ -48,11 +48,15 @@ import { type Branch } from '../levels.js';
  *
  * @slot - The links, as anchors with fragment hrefs, or lists holding them.
  * @slot heading - A heading above the links, such as "On this page". It names the navigation.
+ * @slot indicator - A mark of your own, drawn inside the `indicator` part, where `--indicator-x`, `--indicator-y`, `--indicator-inline-size` and `--indicator-block-size` reach it.
  *
  * @event {HelixActivateEvent} helix-activate - Fired when the section in view changes, with its id as the value. It reports the scroll position and cannot be prevented.
  *
  * @csspart heading - The box holding the `heading` slot, above the navigation.
- * @csspart indicator - The mark that moves to the section in view.
+ * @csspart indicator - The mark that moves to the link of the section in view. It carries that link's
+ *   place and size as `--indicator-x`, `--indicator-y`, `--indicator-inline-size` and
+ *   `--indicator-block-size`, and `data-placed` once it has been placed, for a mark you draw
+ *   and animate yourself.
  * @csspart nav - The navigation landmark.
  */
 export declare class HelixHeadlessOutline extends HelixElement {
@@ -150,7 +154,7 @@ export declare class HelixHeadlessOutline extends HelixElement {
      * nothing was announced, and nothing said why.
      */
     private get links();
-    /** The children that are the content, which is all of them but the heading. */
+    /** The children that are the content, which is all of them but the heading and the mark. */
     private get content();
     /**
      * The links of a flat run, which the render puts into lists, or `undefined`

package/dist/outline/root/outline-root.js

@@ -8,6 +8,7 @@ import { customElement, elementById, HelixActivateEvent, HelixElement, Indicator
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { levelOf, nest } from '../levels.js';
+const OWN_SLOTS = new Set(['heading', 'indicator']);
 const isFragment = (element) => element instanceof HTMLAnchorElement && element.getAttribute('href')?.startsWith('#') === true;
 let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     constructor() {
@@ -97,7 +98,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             : [...element.querySelectorAll('a[href^="#"]')].filter(isFragment));
     }
     get content() {
-        return this.knownChildren.filter((child) => child.slot !== 'heading');
+        return this.knownChildren.filter((child) => !OWN_SLOTS.has(child.slot));
     }
     get run() {
         const content = this.content;
@@ -238,6 +239,9 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         const root = this.renderRoot;
         const heading = root?.querySelector?.('slot[name="heading"]');
         heading?.assign?.(...this.knownChildren.filter((child) => child.slot === 'heading'));
+        root
+            ?.querySelector?.('slot[name="indicator"]')
+            ?.assign?.(...this.knownChildren.filter((child) => child.slot === 'indicator'));
         const run = this.run;
         if (run) {
             for (const slot of root?.querySelectorAll?.('slot[data-link]') ?? []) {
@@ -249,7 +253,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             return;
         }
         const plain = root?.querySelector?.('nav > slot:not([role])');
-        plain?.assign?.(...[...this.childNodes].filter((node) => node instanceof Element ? node.slot !== 'heading' : node instanceof Text));
+        plain?.assign?.(...[...this.childNodes].filter((node) => node instanceof Element ? !OWN_SLOTS.has(node.slot) : node instanceof Text));
     }
     updated(changed) {
         super.updated(changed);
@@ -269,7 +273,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         return html `<div part="heading"><slot name="heading" @slotchange=${this.nameByHeading}></slot></div>
       <nav part="nav" aria-label=${this.label} @slotchange=${this.handleSlotChange}>
       ${run ? this.renderList(nest(run.map((link) => levelOf(link.getAttribute('data-level'))))) : html `<slot></slot>`}
-      <span part="indicator" aria-hidden="true"></span>
+      <span part="indicator" aria-hidden="true"><slot name="indicator"></slot></span>
     </nav>`;
     }
     renderList(branches) {