@fusion.dev/helix-headless 0.145.0 → 0.147.0

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

@@ -1,5 +1,5 @@
-import { HelixElement, PopoverController } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { HelixElement, KeyboardNavigationController, PopoverController } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary A section of a navigation with a trigger that opens a panel of links.
@@ -21,11 +21,36 @@ 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.
+ *
+ * The panel's default slot is the `columns` part and draws no box, so a sheet
+ * can give the columns one of their own. While a panel is open, an
+ * `indicator` slot is rendered beside its trigger, as Radix's indicator
+ * marks the open one: slot a mark of your own, such as a bar or an arrow
+ * pointing at the panel, and it shows only while the panel is open. The styled
+ * tier rests it on the trigger's bottom edge.
+ *
+ * Left and Right Arrow move between the triggers of the megamenus beside this
+ * one, and Home and End go to the first and the last, as Radix's navigation
+ * menu does. In a `Navigation`, which holds them in a slot, the arrows are the
+ * navigation's, and move between its destinations under its `arrows`. 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
@@ -34,25 +59,34 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * @documentation https://fusion.dev/helix/components/megamenu
  *
  * @slot - The panel's contents, such as your own lists of links and their headings.
+ * @slot indicator - A mark for the open trigger, shown while the panel is open, such as a bar or an arrow pointing at the panel.
  * @slot trigger - The control that opens the panel. When it is empty, a button named by `label` is shown.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The panel is about to close. Cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - The panel is about to open. Cancelable.
  * @event {ToggleEvent} toggle - The panel opened or closed. Carries `newState` and `oldState`.
  *
+ * @csspart columns - The panel's default slot. It draws no box until a sheet gives it a `display`.
+ * @csspart indicator - The `indicator` slot, rendered while the panel is open.
  * @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 {
+    /** The bar's one open panel, shared by every megamenu on the page. */
+    private static readonly bar;
     /**
      * The page width, in pixels, below which a card panel is shown as a band. At
      * zero, it never is.
@@ -135,6 +169,22 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * the consumer slotted, or the button drawn in its place.
      */
     get navigationControl(): HTMLElement;
+    /**
+     * The arrows along a bar of megamenus that no component holds in a slot.
+     *
+     * Each megamenu's trigger is one stop, and a press counts only from a
+     * trigger, so an arrow among an open panel's links stays with the panel.
+     * Down and Up are reserved: Down enters an open panel. A megamenu whose
+     * parent is a component, and so holds it in a slot, passes no stops, so a
+     * `Navigation` around it decides the arrows, on or off, for every
+     * destination at once.
+     */
+    protected readonly keys: KeyboardNavigationController;
+    /**
+     * 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;
     /**
@@ -252,14 +302,22 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      *
      * Before the render rather than after it, because the popover controller
      * raises the panel from its own `hostUpdated`, which runs before `updated`:
-     * settled there, the two would be up together for a frame. The other closes
-     * through `requestOpen`, so a consumer holding it open is asked rather than
-     * overruled.
+     * settled there, the two would be up together for a frame. The bookkeeping
+     * is `HandOver`'s.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /** 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;
@@ -271,6 +329,13 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * has one reaches this without reimplementing the panel below it.
      */
     protected renderTrigger(): TemplateResult;
+    /**
+     * The mark under the trigger, while the panel is open. Rendered only then,
+     * so a mark of your own needs no rule to hide it while the panel is closed,
+     * and hidden from the accessibility tree: the trigger's `aria-expanded`
+     * already says the panel is open.
+     */
+    protected renderIndicator(): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {

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

@@ -5,10 +5,10 @@ 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, KeyboardNavigationController, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-let showing;
+import { HandOver } from '../hand-over.js';
 let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -21,13 +21,45 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.panel = new PopoverController(this, {
             anchor: () => this.trigger,
-            boundary: () => this,
+            boundary: () => [...HelixHeadlessMegamenu_1.bar.connected],
             onDismiss: () => this.close(),
             open: () => this.open,
             place: () => !this.banded,
             placement: () => 'bottom-start',
             surface: () => this.partNamed('surface'),
         });
+        this.keys = new KeyboardNavigationController(this, {
+            items: () => !this.parentElement?.shadowRoot
+                ? HelixHeadlessMegamenu_1.bar.alongside(this).map((megamenu) => ({
+                    contains: (node) => {
+                        const control = megamenu.trigger;
+                        return node === control || control.contains(node);
+                    },
+                    disabled: false,
+                    focusItem: () => megamenu.trigger.focus(),
+                    select: () => { },
+                    selected: false,
+                }))
+                : [],
+            origin: 'focus',
+            reserved: () => ['ArrowDown', 'ArrowUp'],
+            selects: () => false,
+            wrap: false,
+        });
+        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,11 +72,13 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.handlePointerDown = (event) => {
             this.pointer = event.pointerType;
+            HelixHeadlessMegamenu_1.bar.press(this);
         };
         this.handlePointerEnter = (event) => {
             if (this.openOn !== 'hover' || event.pointerType !== 'mouse') {
                 return;
             }
+            const showing = HelixHeadlessMegamenu_1.bar.showing;
             this.schedule(showing && showing !== this ? 0 : HelixHeadlessMegamenu_1.OPEN_DELAY, () => {
                 this.requestOpen(true);
             });
@@ -62,6 +96,10 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             if (!this.open || next === null || deepContains(this, next)) {
                 return;
             }
+            const pressed = HelixHeadlessMegamenu_1.bar.pressed;
+            if (pressed !== undefined && pressed !== this && deepContains(pressed, next)) {
+                return;
+            }
             this.requestOpen(false);
         };
         this.handleTriggerClick = (event) => {
@@ -72,6 +110,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) => {
@@ -90,6 +132,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
     }
     static { HelixHeadlessMegamenu_1 = this; }
+    static { this.bar = new HandOver((megamenu, to) => megamenu.motion(to)); }
     get banded() {
         return this.variant === 'band' || this.narrow;
     }
@@ -159,12 +202,14 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     connectedCallback() {
         super.connectedCallback();
         this.watchWidth();
+        HelixHeadlessMegamenu_1.bar.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,10 +221,9 @@ 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);
+        HelixHeadlessMegamenu_1.bar.remove(this);
         this.stop();
-        if (showing === this) {
-            showing = undefined;
-        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -187,18 +231,25 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             return;
         }
         if (this.open) {
-            const previous = showing && showing !== this ? showing : undefined;
-            const forward = previous !== undefined &&
-                (previous.compareDocumentPosition(this) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
-            this.motion(previous ? (forward ? 'from-end' : 'from-start') : undefined);
-            if (previous) {
-                previous.motion(forward ? 'to-end' : 'to-start');
-                previous.requestOpen(false);
-            }
-            showing = this;
+            this.from = HelixHeadlessMegamenu_1.bar.open(this)?.size;
+            return;
         }
-        else if (showing === this) {
-            showing = undefined;
+        HelixHeadlessMegamenu_1.bar.close(this);
+    }
+    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) {
@@ -216,6 +267,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.tellTrigger();
         if (this.open) {
             this.band();
+            this.measure();
         }
     }
     renderTrigger() {
@@ -230,8 +282,13 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
       </button>
     </slot>`;
     }
+    renderIndicator() {
+        return this.open
+            ? html `<slot name="indicator" part="indicator" aria-hidden="true"></slot>`
+            : nothing;
+    }
     render() {
-        return html `${this.renderTrigger()}
+        return html `${this.renderTrigger()}${this.renderIndicator()}
       <div
         part="surface"
         id="panel"
@@ -240,7 +297,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         role="group"
         ?hidden=${!this.open}
       >
-        <slot></slot>
+        <slot part="columns"></slot>
       </div>`;
     }
 };

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 {

package/dist/menu/item/menu-item.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 { ariaChord, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, onApple, requestChange, } from '@fusion.dev/helix-core';
+import { ariaChord, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, onApple, requestChange, slotFilled, } from '@fusion.dev/helix-core';
 import { caretRight, check } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -30,13 +30,18 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.submenu = false;
         this.start = false;
         this.end = false;
+        this.description = false;
         this.readStart = () => {
             const slot = this.renderRoot.querySelector('slot[name="start"]');
-            this.start = (slot?.assignedNodes().length ?? 0) > 0;
+            this.start = slotFilled(slot);
         };
         this.readEnd = () => {
             const slot = this.renderRoot.querySelector('slot[name="end"]');
-            this.end = (slot?.assignedNodes().length ?? 0) > 0;
+            this.end = slotFilled(slot);
+        };
+        this.readDescription = () => {
+            const slot = this.renderRoot.querySelector('slot[name="description"]');
+            this.description = slotFilled(slot);
         };
         this.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
@@ -74,11 +79,27 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.submenu = named('submenu');
         this.start = named('start');
         this.end = named('end');
+        this.description = named('description');
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
     }
+    renderDescription() {
+        return html `<slot
+      id="description"
+      name="description"
+      aria-hidden="true"
+      ?data-empty=${!this.description}
+      @slotchange=${this.readDescription}
+    ></slot>`;
+    }
+    get describedBy() {
+        const ids = [this.description ? 'description' : '', this.end ? 'end-words' : '']
+            .filter((id) => id !== '')
+            .join(' ');
+        return ids === '' ? nothing : ids;
+    }
     renderEnd() {
         const kbd = this.tag('kbd');
         return html `<span part="end" ?data-empty=${!this.end && this.shortcut === ''}
@@ -86,10 +107,10 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             ? nothing
             : staticHtml `<${kbd}
               part="shortcut"
-              exportparts="kbd: shortcut-kbd"
+              exportparts="kbd: shortcut-kbd, key: shortcut-key, separator: shortcut-separator"
               aria-hidden="true"
               keys=${this.shortcut}
-            ></${kbd}>`}<slot name="end" @slotchange=${this.readEnd}></slot
+            ></${kbd}>`}<slot id="end-words" name="end" aria-hidden="true" @slotchange=${this.readEnd}></slot
     ></span>`;
     }
     focus() {
@@ -152,6 +173,23 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.tick();
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
+    renderMark(submenu) {
+        if (submenu) {
+            return html `<slot name="chevron" aria-hidden="true"
+        ><svg part="mark" data-mirror fill="currentColor" viewBox=${caretRight.viewBox} aria-hidden="true">
+          ${unsafeSVG(caretRight.content)}
+        </svg></slot
+      >`;
+        }
+        if (this.checked) {
+            return html `<slot name="check" aria-hidden="true"
+        ><svg part="mark" fill="currentColor" viewBox=${check.viewBox} aria-hidden="true">
+          ${unsafeSVG(check.content)}
+        </svg></slot
+      >`;
+        }
+        return nothing;
+    }
     render() {
         if (this.showingSubmenu) {
             return html `<slot name="submenu" @slotchange=${this.readSubmenu}></slot>`;
@@ -169,28 +207,9 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
           ><slot name="start" @slotchange=${this.readStart}></slot
         ></span>
         <slot></slot>
+        ${this.renderDescription()}
         ${this.renderEnd()}
-        ${submenu
-            ? html `<svg
-                part="mark"
-                data-mirror
-                fill="currentColor"
-                viewBox=${caretRight.viewBox}
-                aria-hidden="true"
-              >
-                ${unsafeSVG(caretRight.content)}
-              </svg>`
-            : this.checked
-                ? html `<svg
-                  part="mark"
-                  fill="currentColor"
-                  viewBox=${check.viewBox}
-                  aria-hidden="true"
-                >
-                  ${unsafeSVG(check.content)}
-                </svg>`
-                :
-                    nothing}`;
+        ${this.renderMark(submenu)}`;
         return html `${linked
             ? html `<a
             part="item"
@@ -200,6 +219,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             ?download=${this.download}
             role=${role}
             aria-checked=${checkedState}
+            aria-describedby=${this.describedBy}
             aria-haspopup=${submenu ? 'menu' : nothing}
             aria-keyshortcuts=${keys}
             tabindex="-1"
@@ -210,6 +230,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             part="item"
             role=${role}
             aria-checked=${checkedState}
+            aria-describedby=${this.describedBy}
             aria-disabled=${this.disabled ? 'true' : nothing}
             aria-haspopup=${submenu ? 'menu' : nothing}
             aria-keyshortcuts=${keys}
@@ -265,6 +286,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "end", void 0);
+__decorate([
+    state()
+], HelixHeadlessMenuItem.prototype, "description", void 0);
 HelixHeadlessMenuItem = __decorate([
     customElement('helix-headless-menu-item')
 ], HelixHeadlessMenuItem);

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

@@ -28,6 +28,20 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * its heading. Between runs of rows, a `<helix-divider announced>` is a
  * separator a screen reader announces.
  *
+ * Keys: Enter, Space or Down Arrow on the trigger opens the menu on its first
+ * row, and Up Arrow on its last. In the menu, Up and Down Arrow move between
+ * rows, Home and End go to the first and the last, a typed letter moves to
+ * the next row whose name starts with it, Enter and Space choose, Right Arrow
+ * opens a row's submenu and Left Arrow goes back, the two swapping on a
+ * right-to-left page, and Escape closes the menu and returns focus to the
+ * trigger. Tab closes it and moves on.
+ *
+ * While it is open, the surface carries the trigger's width as
+ * `--floating-anchor-inline-size` and the room left below it as
+ * `--floating-available-block-size`, as Radix's dropdown menu publishes its
+ * trigger's width, for a menu as wide as its trigger:
+ * `helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.
+ *
  * With `context`, the trigger is an area and the menu is its context menu: a
  * right-click, a long press, Shift+F10 or the menu key over the area opens it
  * at the pointer, or at the area's corner from the keyboard, as Radix's context
@@ -57,6 +71,9 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @csspart surface - The floating panel the menu is drawn on.
  * @csspart title - The name of the submenu that is showing.
  *
+ * @cssproperty --floating-anchor-inline-size - The trigger's width, written on the panel while it is open, as in `min-inline-size: var(--floating-anchor-inline-size)`. Read it; a value set here is written over.
+ * @cssproperty --floating-available-block-size - The room between the panel and the edge of the screen it opens toward, written on the panel while it is open. Read it; a value set here is written over.
+ *
  * @cssstate drilled - A submenu's page is showing, so content that is not a row can hide with the top page.
  * @cssstate mark - A row on the current page has a checkbox or a link, so every row keeps the trailing column.
  * @cssstate open - While the menu is open.

package/dist/menu/root/menu-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, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, slottedWords, tellDisclosure, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, slottedWords, tellDisclosure, typeaheadBy, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -29,7 +29,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             items: () => (this.open ? this.items : []),
             reserved: () => ['ArrowLeft', 'ArrowRight'],
             selects: () => false,
-            typeahead: (item) => slottedWords(item, ['']),
+            typeahead: typeaheadBy((item) => slottedWords(item, [''])),
         });
         this.aria = new AriaForwardController(this, {
             label: true,