@fusion.dev/helix-headless 0.145.0 → 0.146.0

package/dist/listbox/root/listbox-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, countLabel, customElement, DelayController, DisabledCascadeController, HelixFilterEvent, HelixFormElement, hostAria, MixinCollection, MixinControllerValue, MixinField, rangeAdd, reportValues, requestChange, scrollItemIntoView, Typeahead, typesCharacter, } from '@fusion.dev/helix-core';
+import { AriaForwardController, countLabel, customElement, DelayController, DisabledCascadeController, HelixFilterEvent, HelixFormElement, HelixLoadMoreEvent, hostAria, MixinCollection, MixinControllerValue, MixinField, rangeAdd, reportValues, requestChange, scrollItemIntoView, Typeahead, typesCharacter, } from '@fusion.dev/helix-core';
 import { magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -70,6 +70,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         this.filterable = false;
         this.filterDelay = 0;
         this.filterLabel = 'Filter';
+        this.loadError = '';
         this.manual = false;
         this.multiple = false;
         this.resultLabel = '{count} result';
@@ -192,6 +193,18 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             this.takeFilter(control);
         };
         this.filtering = new DelayController(this, { renders: false });
+        this.askedAt = -1;
+        this.handleScroll = (event) => {
+            const items = event.currentTarget;
+            const count = this.options.length;
+            if (this.loading || count === this.askedAt || items.clientHeight === 0) {
+                return;
+            }
+            if (items.scrollHeight - items.scrollTop - items.clientHeight <= items.clientHeight) {
+                this.askedAt = count;
+                this.dispatchEvent(new HelixLoadMoreEvent());
+            }
+        };
         this.handleFilterKeydown = (event) => {
             if (event.key === 'Enter' || FIELD_MOVES.has(event.key)) {
                 this.flushFilter();
@@ -471,6 +484,8 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         }
         this.toggleState('empty', !this.showsOptions);
         this.toggleState('loading', this.loading);
+        this.toggleState('error', this.loadError !== '');
+        this.toggleState('no-results', this.noResults);
     }
     seedDeclared() {
         if (this.owned || this.defaultValue !== '' || this.hasAttribute('default-value')) {
@@ -545,13 +560,37 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             : true;
     }
     renderStatus(hasContent) {
+        if (this.loadError !== '') {
+            return html `<p part="error"><slot name="error">${this.loadError}</slot></p>`;
+        }
         if (!this.loading && hasContent) {
             return nothing;
         }
-        return this.loading
-            ? html `<p part="loading"><slot name="loading">${this.loadingText}</slot></p>`
+        if (this.loading) {
+            return html `<p part="loading"><slot name="loading">${this.loadingText}</slot></p>`;
+        }
+        const given = this.noResultsText !== undefined ||
+            this.querySelector?.(':scope > [slot="no-results"]') != null;
+        return this.noResults && given
+            ? html `<p part="empty"><slot name="no-results">${this.noResultsText ?? this.emptyText}</slot></p>`
             : html `<p part="empty"><slot name="empty">${this.emptyText}</slot></p>`;
     }
+    get noResults() {
+        return (this.counted &&
+            !this.loading &&
+            this.filter !== '' &&
+            this.options.length > 0 &&
+            !this.hasMatches);
+    }
+    renderLive(hasContent) {
+        if (this.loadError !== '') {
+            return html `<span part="live" role="status">${this.loadError}</span>`;
+        }
+        if (this.noResults && this.noResultsText !== undefined) {
+            return html `<span part="live" role="status">${this.noResultsText}</span>`;
+        }
+        return super.renderLive(hasContent);
+    }
     render() {
         const shown = this.showsOptions;
         return html `${this.renderGroupLabel()}
@@ -588,6 +627,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         aria-required=${this.required ? 'true' : nothing}
         ${''}
         tabindex=${this.filterable ? nothing : this.isDisabled ? -1 : 0}
+        @scroll=${this.handleScroll}
       >
         <slot @slotchange=${() => this.place()}></slot>
         ${this.renderStatus(shown)}
@@ -616,12 +656,18 @@ __decorate([
 __decorate([
     property({ attribute: 'filter-label' })
 ], HelixHeadlessListbox.prototype, "filterLabel", void 0);
+__decorate([
+    property({ attribute: 'load-error' })
+], HelixHeadlessListbox.prototype, "loadError", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessListbox.prototype, "manual", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessListbox.prototype, "multiple", void 0);
+__decorate([
+    property({ attribute: 'no-results-text' })
+], HelixHeadlessListbox.prototype, "noResultsText", void 0);
 __decorate([
     property({ attribute: 'result-label' })
 ], HelixHeadlessListbox.prototype, "resultLabel", void 0);

package/dist/loader/busy.d.ts

@@ -15,3 +15,13 @@
 export declare const claimBusy: (region: Element) => void;
 /** Takes a claim back, and the attribute with the last one. */
 export declare const releaseBusy: (region: Element) => void;
+/**
+ * Calls `found` with the region `find` answers once it is in `root`, and
+ * returns the call that stops waiting.
+ *
+ * For a loader whose region is not on the page yet: a framework often draws
+ * the loader before the list it stands for, and a region looked up once, a
+ * frame after connecting, was never marked. Watches for children and ids being
+ * written, and stops at the first answer.
+ */
+export declare const awaitRegion: (root: Node, find: () => Element | null, found: (region: Element) => void) => (() => void);

package/dist/loader/busy.js

@@ -22,3 +22,14 @@ export const releaseBusy = (region) => {
         CLAIMS.set(region, held - 1);
     }
 };
+export const awaitRegion = (root, find, found) => {
+    const observer = new MutationObserver(() => {
+        const region = find();
+        if (region) {
+            observer.disconnect();
+            found(region);
+        }
+    });
+    observer.observe(root, { attributeFilter: ['id'], childList: true, subtree: true });
+    return () => observer.disconnect();
+};

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

@@ -22,11 +22,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * **`for` names the region being loaded**, and the loader sets
  * `aria-busy="true"` on it for as long as the loader is on the page, so a
  * screen reader waits for the region rather than reading it half filled. Two
- * loaders in one region hold it busy until the last one leaves.
+ * loaders in one region hold it busy until the last one leaves. A region drawn
+ * after the loader is marked when it arrives.
  *
  * **`delay` keeps a quick load from flashing a loader.** The loader stays
  * hidden, and silent, for that many milliseconds, and appears only if the work
- * is still going.
+ * is still going. While it waits it carries `:state(waiting)`.
  *
  * @since 0.1.0
  * @status stable
@@ -40,6 +41,8 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @csspart mark - The region that holds the slotted content at the center.
  * @csspart svg - The rotating circle pair.
  * @csspart track - The full circle behind the indicator.
+ *
+ * @cssstate waiting - The loader is waiting out its `delay`, hidden and silent.
  */
 export declare class HelixHeadlessLoader extends HelixElement {
     /**
@@ -67,6 +70,10 @@ export declare class HelixHeadlessLoader extends HelixElement {
     private readonly due;
     /** The region this loader marked busy, so it is the one released. */
     private region;
+    /** Stops waiting for a region `for` names that is not on the page yet. */
+    private stopAwaiting;
+    /** Whether `for` has named an element while the loader was on the page. */
+    private found;
     /** Whether the loader is still waiting out its `delay`. */
     private get waiting();
     connectedCallback(): void;

package/dist/loader/root/loader-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 { customElement, DelayController, elementById, HelixElement, hostAria, } from '@fusion.dev/helix-core';
+import { customElement, DelayController, elementById, HelixElement, hostAria, reportRuntime, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-import { claimBusy, releaseBusy } from '../busy.js';
+import { awaitRegion, claimBusy, releaseBusy } from '../busy.js';
 let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
     constructor() {
         super(...arguments);
@@ -16,6 +16,7 @@ let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
         this.label = 'Loading';
         this.due = new DelayController(this);
         this.region = null;
+        this.found = false;
     }
     get waiting() {
         return this.delay > 0 && !this.due.elapsed;
@@ -29,10 +30,26 @@ let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        if (this.stopAwaiting && !this.found) {
+            reportRuntime({
+                kind: 'missing-target',
+                message: `<${this.localName} for="${this.for}"> named no element in its tree while it was on ` +
+                    'the page, so no region was marked busy. Give the region that id.',
+                tag: this.localName,
+            });
+        }
+        this.stopAwaiting?.();
+        this.stopAwaiting = undefined;
         this.release();
     }
     mark() {
-        const region = this.isConnected && this.for !== '' ? elementById(this, this.for) : null;
+        this.stopAwaiting?.();
+        this.stopAwaiting = undefined;
+        const named = this.isConnected && this.for !== '';
+        const region = named ? elementById(this, this.for) : null;
+        if (named && !region) {
+            this.stopAwaiting = awaitRegion(this.getRootNode(), () => elementById(this, this.for), () => this.mark());
+        }
         if (region === this.region) {
             return;
         }
@@ -40,6 +57,7 @@ let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
         if (region) {
             claimBusy(region);
             this.region = region;
+            this.found = true;
         }
     }
     release() {
@@ -51,6 +69,7 @@ let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
     updated(changed) {
         super.updated(changed);
         if (changed.has('for') && changed.get('for') !== undefined) {
+            this.found = false;
             this.mark();
         }
     }
@@ -59,6 +78,7 @@ let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
         hostAria(this.internals, { label: this.label, role: 'progressbar' });
         this.internals.ariaBusy = 'true';
         this.internals.ariaHidden = this.waiting ? 'true' : null;
+        this.toggleState('waiting', this.waiting);
     }
     render() {
         return html `<svg part="svg" viewBox="0 0 24 24" aria-hidden="true" ?hidden=${this.waiting}>

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

@@ -21,11 +21,27 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * along the row and see each section.
  *
  * When one panel opens in place of another, each says which way the reader
- * moved, as Radix's `data-motion` does: the one opening is
- * `:state(from-start)` or `:state(from-end)`, by where the one closing sits in
- * the bar, and the one closing is `:state(to-start)` or `:state(to-end)`. A
- * stylesheet slides them on that. Put megamenus in a `Navigation` with
- * `arrows` and the arrow keys move between their triggers.
+ * moved, as Radix's `data-motion` does. Moving toward the end of the bar, the
+ * one opening is `:state(from-end)` and the one closing is `:state(to-start)`;
+ * moving back, they are `:state(from-start)` and `:state(to-end)`. A
+ * stylesheet slides them on that. Start and end follow the reading direction,
+ * so on a right-to-left page the end is on the left. A panel that opens or
+ * closes on its own carries none of the four. A press on another megamenu's
+ * trigger hands over the same way as hovering it.
+ *
+ * While a panel is open its surface carries its own size, as
+ * `--megamenu-surface-inline-size` and `--megamenu-surface-block-size`, and a
+ * panel that took over from another also carries that one's size, as
+ * `--megamenu-from-inline-size` and `--megamenu-from-block-size`. Radix's
+ * navigation menu publishes the same pair from its shared viewport, so a
+ * stylesheet can grow or shrink one panel into the next.
+ *
+ * Put megamenus in a `Navigation` with `arrows` and the arrow keys move
+ * between their triggers. Down Arrow on the trigger of an open panel moves
+ * focus to the panel's first link, Escape closes the panel and returns focus
+ * to its trigger, and Tab moves through the panel's links and closes it on the
+ * way out. The trigger says `aria-expanded`, and the panel is a group named by
+ * `label`.
  *
  * @since 0.1.0
  * @status stable
@@ -43,14 +59,18 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * @csspart surface - The floating panel that opens.
  * @csspart trigger - The default trigger button, shown when the `trigger` slot is empty.
  *
+ * @cssproperty --megamenu-from-block-size - The height of the panel this one took over from, written on the surface while it is open.
+ * @cssproperty --megamenu-from-inline-size - The width of the panel this one took over from, written on the surface while it is open.
+ * @cssproperty --megamenu-surface-block-size - The panel's own height, written on the surface while it is open.
+ * @cssproperty --megamenu-surface-inline-size - The panel's own width, written on the surface while it is open.
  * @cssproperty --megamenu-top - Where the panel starts, measured from the bar above it.
  *
- * @cssstate from-end - The panel opened in place of one later in the bar, so it can enter from that side.
- * @cssstate from-start - The panel opened in place of one earlier in the bar.
+ * @cssstate from-end - The panel opened in place of one earlier in the bar, so it can enter from the end side.
+ * @cssstate from-start - The panel opened in place of one later in the bar, so it can enter from the start side.
  * @cssstate narrow - The page is narrower than `band-below`, so the panel is shown as a band whatever its variant.
  * @cssstate open - The panel is open, and the trigger is shown as current.
- * @cssstate to-end - The panel closed because one later in the bar opened, so it can leave toward it.
- * @cssstate to-start - The panel closed because one earlier in the bar opened.
+ * @cssstate to-end - The panel closed because one earlier in the bar opened, so it can leave toward the end.
+ * @cssstate to-start - The panel closed because one later in the bar opened, so it can leave toward the start.
  */
 export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
     /**
@@ -135,6 +155,11 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * the consumer slotted, or the button drawn in its place.
      */
     get navigationControl(): HTMLElement;
+    /**
+     * Down Arrow on the trigger of an open panel moves focus to the panel's first
+     * link or control, as Radix's navigation menu does.
+     */
+    private readonly handleKeyDown;
     /** Shuts it and puts the reader back where they were. */
     private close;
     /**
@@ -257,9 +282,25 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * overruled.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Clears the direction of every panel but the two in a hand-over, so only
+     * the latest move is ever described.
+     */
+    private static settle;
+    /** Whether the panel is closing because another one opened in its place. */
+    private handedOver;
+    /** The panel's size the last time it was open, in pixels. */
+    private size;
+    /** The size of the panel this one took over from, if it took over. */
+    private from;
+    /**
+     * Writes the panel's size onto its surface, and the size of the panel it
+     * took over from, for a stylesheet that grows one into the next.
+     */
+    private measure;
     /**
      * Says which way the reader moved when one panel took over from another.
-     * Nothing clears all four, for a panel opened on its own.
+     * Nothing clears all four, for a panel opened or closed on its own.
      */
     private motion;
     protected updated(changed: PropertyValues): void;

package/dist/megamenu/root/megamenu-root.js

@@ -5,10 +5,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessMegamenu_1;
-import { anchorElement, customElement, deepContains, HelixElement, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
+import { anchorElement, customElement, deepContains, focusableElements, HelixElement, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 let showing;
+const connected = new Set();
+let pressed;
+const release = () => {
+    setTimeout(() => {
+        pressed = undefined;
+    });
+};
 let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -21,13 +28,27 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.panel = new PopoverController(this, {
             anchor: () => this.trigger,
-            boundary: () => this,
+            boundary: () => [...connected],
             onDismiss: () => this.close(),
             open: () => this.open,
             place: () => !this.banded,
             placement: () => 'bottom-start',
             surface: () => this.partNamed('surface'),
         });
+        this.handleKeyDown = (event) => {
+            if (event.key !== 'ArrowDown' || !this.open || event.defaultPrevented) {
+                return;
+            }
+            const trigger = this.trigger;
+            if (!event.composedPath().includes(trigger)) {
+                return;
+            }
+            const first = focusableElements(this).find((element) => element !== trigger && !element.closest('[slot="trigger"]'));
+            if (first) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
         this.handleScroll = () => {
             if (!this.open || !this.banded) {
                 return;
@@ -40,6 +61,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.handlePointerDown = (event) => {
             this.pointer = event.pointerType;
+            pressed = this;
+            window.addEventListener('pointerup', release, { capture: true, once: true });
+            window.addEventListener('pointercancel', release, { capture: true, once: true });
         };
         this.handlePointerEnter = (event) => {
             if (this.openOn !== 'hover' || event.pointerType !== 'mouse') {
@@ -62,6 +86,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             if (!this.open || next === null || deepContains(this, next)) {
                 return;
             }
+            if (pressed !== undefined && pressed !== this && deepContains(pressed, next)) {
+                return;
+            }
             this.requestOpen(false);
         };
         this.handleTriggerClick = (event) => {
@@ -72,6 +99,10 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             }
             if (event.detail === 0 || (this.pointer !== undefined && this.pointer !== 'mouse')) {
                 this.requestOpen(!this.open);
+                return;
+            }
+            if (!this.open) {
+                this.requestOpen(true);
             }
         };
         this.handleContentClick = (event) => {
@@ -88,6 +119,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             }
             this.requestOpen(false);
         };
+        this.handedOver = false;
     }
     static { HelixHeadlessMegamenu_1 = this; }
     get banded() {
@@ -159,12 +191,14 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     connectedCallback() {
         super.connectedCallback();
         this.watchWidth();
+        connected.add(this);
         window.addEventListener('scroll', this.handleScroll, { capture: true, passive: true });
         this.addEventListener('pointerdown', this.handlePointerDown);
         this.addEventListener('click', this.handleContentClick);
         this.addEventListener('pointerenter', this.handlePointerEnter);
         this.addEventListener('pointerleave', this.handlePointerLeave);
         this.addEventListener('focusout', this.handleFocusOut);
+        this.addEventListener('keydown', this.handleKeyDown);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -176,6 +210,8 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.removeEventListener('pointerenter', this.handlePointerEnter);
         this.removeEventListener('pointerleave', this.handlePointerLeave);
         this.removeEventListener('focusout', this.handleFocusOut);
+        this.removeEventListener('keydown', this.handleKeyDown);
+        connected.delete(this);
         this.stop();
         if (showing === this) {
             showing = undefined;
@@ -191,15 +227,49 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             const forward = previous !== undefined &&
                 (previous.compareDocumentPosition(this) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
             this.motion(previous ? (forward ? 'from-end' : 'from-start') : undefined);
+            this.from = previous?.size;
+            HelixHeadlessMegamenu_1.settle(this, previous);
             if (previous) {
-                previous.motion(forward ? 'to-end' : 'to-start');
-                previous.requestOpen(false);
+                previous.motion(forward ? 'to-start' : 'to-end');
+                previous.handedOver = true;
+                if (!previous.requestOpen(false)) {
+                    previous.handedOver = false;
+                    previous.motion(undefined);
+                }
             }
             showing = this;
+            return;
         }
-        else if (showing === this) {
+        if (showing === this) {
             showing = undefined;
         }
+        if (!this.handedOver) {
+            HelixHeadlessMegamenu_1.settle();
+        }
+        this.handedOver = false;
+    }
+    static settle(...moving) {
+        for (const megamenu of connected) {
+            if (!moving.includes(megamenu)) {
+                megamenu.motion(undefined);
+            }
+        }
+    }
+    measure() {
+        const surface = this.partNamed('surface');
+        if (!surface) {
+            return;
+        }
+        surface.style.removeProperty('--megamenu-from-inline-size');
+        surface.style.removeProperty('--megamenu-from-block-size');
+        const box = surface.getBoundingClientRect();
+        this.size = { block: Math.round(box.height), inline: Math.round(box.width) };
+        surface.style.setProperty('--megamenu-surface-inline-size', `${this.size.inline}px`);
+        surface.style.setProperty('--megamenu-surface-block-size', `${this.size.block}px`);
+        if (this.from) {
+            surface.style.setProperty('--megamenu-from-inline-size', `${this.from.inline}px`);
+            surface.style.setProperty('--megamenu-from-block-size', `${this.from.block}px`);
+        }
     }
     motion(to) {
         this.toggleState('from-end', to === 'from-end');
@@ -216,6 +286,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.tellTrigger();
         if (this.open) {
             this.band();
+            this.measure();
         }
     }
     renderTrigger() {

package/dist/menu/item/menu-item.d.ts

@@ -29,13 +29,25 @@ import '../../kbd/index.js';
  * nothing: the shortcut is the page's to bind. Other trailing words, such as a
  * count, go in the `end` slot.
  *
+ * The row is named by its label alone. Words in `description`, a line under the
+ * label, and in `end` describe it instead, through `aria-describedby`, as
+ * React Aria's menu item does with its description: a reader hears "Copy",
+ * then "Copies the selection".
+ *
+ * The check mark and the caret are the fallbacks of the `check` and `chevron`
+ * slots, so a mark of your own replaces either by being slotted. Neither is
+ * read as part of the row's name.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Menu option, Menu row
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The label.
- * @slot end - Words after the label, such as a count or a detail, beside any `shortcut`.
+ * @slot check - Replaces the check mark of a checked row, such as with your own icon.
+ * @slot chevron - Replaces the caret of a row that opens a submenu.
+ * @slot description - A line under the label that describes the row. It describes the row to a screen reader and is not part of its name.
+ * @slot end - Words after the label, such as a count or a detail, beside any `shortcut`. They describe the row and are not part of its name.
  * @slot start - Content before the label, such as an icon.
  * @slot submenu - The rows of a submenu that this row opens.
  *
@@ -48,6 +60,8 @@ import '../../kbd/index.js';
  * when it opens a submenu. A row never shows both, so they share one column.
  * @csspart shortcut - The key drawn for `shortcut`.
  * @csspart shortcut-kbd - The key inside it.
+ * @csspart shortcut-key - One key of the shortcut's chord, such as `Ctrl`.
+ * @csspart shortcut-separator - The `+` between two keys of the shortcut, where the platform writes one.
  * @csspart start - The leading column that holds the `start` slot. It is always rendered.
  *
  * @cssstate checked - The row is checked.
@@ -201,6 +215,8 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
     private start;
     /** Whether anything is slotted after the label, read the way `start` is. */
     private end;
+    /** Whether anything is slotted under the label, read the way `start` is. */
+    private description;
     /**
      * Both answers, from the children, before each render.
      *
@@ -223,13 +239,25 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
     private readonly readStart;
     /** Re-reads whether anything is after the label, as `readStart` does before it. */
     private readonly readEnd;
+    /** Re-reads whether anything is under the label, as `readStart` does before it. */
+    private readonly readDescription;
+    /**
+     * The line under the label. The slot is hidden from the row's name and named
+     * by the row's `aria-describedby`, which reads it all the same: a description
+     * is read from what it points at, hidden or not. No box of its own, so a row
+     * with no description lays out as it did; `data-empty` says which it is.
+     */
+    protected renderDescription(): TemplateResult;
+    /** What describes the row: the line under its label and the words after it. */
+    private get describedBy();
     /**
      * The trailing column: the shortcut's key, then whatever is slotted in `end`.
      * Drawn by `Kbd`, interpolated so each tier draws its own.
      *
      * The key is hidden from the accessibility tree, since the row's
      * `aria-keyshortcuts` says it in words a screen reader reads as keys: inside
-     * the row its glyphs became part of the row's name.
+     * the row its glyphs became part of the row's name. The `end` words are
+     * hidden from the name too, and describe the row instead.
      */
     protected renderEnd(): TemplateResult;
     /**
@@ -311,6 +339,27 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * both announces and navigates.
      */
     private readonly handleKeydown;
+    /**
+     * The trailing mark: the caret of a row that opens a page, or the tick of a
+     * checked one, each the fallback of a slot a mark of your own replaces.
+     *
+     * One trailing column, and a row is never both: a way into a page has nothing
+     * to tick, and a choice opens nothing. The tick sits after the label rather
+     * than before it, so the labels start at the edge of the row and the marks
+     * line up down the side they are read from.
+     *
+     * `data-mirror` is what tells the two apart. They share a part name because
+     * they share a column, and only one of them is directional: a caret has to
+     * mirror in a right-to-left document and a tick must not, which Unicode's own
+     * mirroring list agrees on. The attribute is on an element in this shadow
+     * root rather than on the host, so it is the divider's `data-empty` and not a
+     * hydration hazard.
+     *
+     * Nothing to mark, so nothing is drawn. The column this would have sat in is
+     * reserved by the menu when some row on the page needs one, so the labels
+     * still line up without every row carrying an empty box to line them up with.
+     */
+    protected renderMark(submenu: boolean): TemplateResult | typeof nothing;
     protected render(): TemplateResult | typeof nothing;
 }
 declare global {