@fusion.dev/helix-headless 0.144.0 → 0.146.0

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() {
@@ -117,6 +149,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     get trigger() {
         return anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this.partNamed('trigger') ?? this);
     }
+    get navigationControl() {
+        return this.trigger;
+    }
     close() {
         if (!this.requestOpen(false)) {
             return;
@@ -156,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();
@@ -173,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;
@@ -184,14 +223,59 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             return;
         }
         if (this.open) {
-            if (showing && showing !== this) {
-                showing.requestOpen(false);
+            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);
+            this.from = previous?.size;
+            HelixHeadlessMegamenu_1.settle(this, previous);
+            if (previous) {
+                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');
+        this.toggleState('from-start', to === 'from-start');
+        this.toggleState('to-end', to === 'to-end');
+        this.toggleState('to-start', to === 'to-start');
     }
     updated(changed) {
         super.updated?.(changed);
@@ -202,6 +286,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.tellTrigger();
         if (this.open) {
             this.band();
+            this.measure();
         }
     }
     renderTrigger() {

package/dist/menu/index.d.ts

@@ -1,2 +1,3 @@
 export * from './item/menu-item.js';
 export * from './root/menu-root.js';
+export * from './section/menu-section.js';

package/dist/menu/index.js

@@ -1,2 +1,3 @@
 export * from './item/menu-item.js';
 export * from './root/menu-root.js';
+export * from './section/menu-section.js';

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

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+import '../../kbd/index.js';
 /**
  * @summary One row in a menu: a command, a choice, or a way into a submenu.
  *
@@ -23,21 +24,44 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * attribute. An attribute written onto your element after it upgrades causes a
  * hydration mismatch.
  *
+ * `shortcut` shows a row's keyboard shortcut after its label, drawn by `Kbd`
+ * in the platform's glyphs, and gives the row `aria-keyshortcuts`. It binds
+ * 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 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.
  *
  * @event {HelixBeforeToggleEvent} helix-before-toggle - A choice row is about to be checked or unchecked, carrying the state asked for. Cancelable: cancel it to keep the row as it is.
  * @event {HelixSelectEvent} helix-select - The row was chosen. Cancelable: cancel it to keep the menu open.
  *
+ * @csspart end - The trailing column that holds the shortcut and the `end` slot. It is always rendered.
  * @csspart item - The row, which is an `<a>` where `href` is set.
  * @csspart mark - The trailing mark: a check mark when the row is checked, or a caret
  * 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.
@@ -100,19 +124,16 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * roves, which is the same maneuver `Tree.Item` makes and the reason `href`
      * changes the markup rather than only adding an attribute.
      *
-     * **`Option` cannot have this and the reason is worth knowing**, since a
-     * command palette is the obvious place to want it. A listbox has to keep
-     * focus somewhere else, in the text field for a combobox, so it says which
-     * option is current with `aria-activedescendant`. That reference can only
-     * point at the option's host, measured: assigning
-     * `ariaActiveDescendantElement` an element inside a sibling shadow root reads
-     * back `null`. So `role="option"` is pinned to the host, and an anchor under
-     * it hits the naming failure above. A menu has no such constraint because
-     * focus really moves to the row.
+     * **`Option` takes an `href` too, and keeps its role a different way.** A
+     * listbox keeps focus somewhere else, in the text field for a combobox, and
+     * names the current option with `aria-activedescendant`, which can only point
+     * at the option's host. So an option stays `role="option"` on its host, draws
+     * no anchor, and follows its link through an anchor made for the moment. A
+     * menu has no such constraint, because focus really moves to the row.
      */
     href: string;
     /**
-     * Whether the row is on the menu page that is showing.
+     * @internal Whether the row is on the menu page that is showing.
      *
      * Set by the menu, and a property rather than an attribute for that reason.
      * Public because the menu has to reach it, and not something a consumer
@@ -124,7 +145,14 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     rel: string;
     /**
-     * Whether the page showing is this row's submenu, or one below it.
+     * The row's keyboard shortcut as a chord, such as `mod+s`, shown after the
+     * label in the platform's glyphs and given to the row as
+     * `aria-keyshortcuts`. `mod` is Command on an Apple keyboard and Control
+     * elsewhere. Showing a shortcut does not bind it.
+     */
+    shortcut: string;
+    /**
+     * @internal Whether the page showing is this row's submenu, or one below it.
      *
      * Separate from `onPage`, and it has to be. A row that opened a page is not
      * itself on that page, so both are false for it, and rendering nothing on
@@ -185,6 +213,10 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * exactly the thing that is.
      */
     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.
      *
@@ -205,6 +237,29 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * is never rebuilt and never fires on its way out.
      */
     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 `end` words are
+     * hidden from the name too, and describe the row instead.
+     */
+    protected renderEnd(): TemplateResult;
     /**
      * Re-reads whether anything is in the submenu, from whichever slot is current.
      *
@@ -284,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,11 +4,13 @@ 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, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, requestChange, } from '@fusion.dev/helix-core';
+import { ariaChord, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, onApple, requestChange, } 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';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import { html as staticHtml } from 'lit/static-html.js';
+import '../../kbd/index.js';
 let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
     constructor() {
         super(...arguments);
@@ -20,16 +22,27 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.href = '';
         this.onPage = true;
         this.rel = '';
+        this.shortcut = '';
         this.showingSubmenu = false;
         this.target = '';
         this.value = '';
         this.isMenuItem = true;
         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.readEnd = () => {
+            const slot = this.renderRoot.querySelector('slot[name="end"]');
+            this.end = (slot?.assignedNodes().length ?? 0) > 0;
+        };
+        this.readDescription = () => {
+            const slot = this.renderRoot.querySelector('slot[name="description"]');
+            this.description = (slot?.assignedNodes().length ?? 0) > 0;
+        };
         this.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
             this.submenu = (slot?.assignedElements().length ?? 0) > 0;
@@ -65,11 +78,41 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         const named = (name) => this.knownChildren.some((child) => child.slot === name);
         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 === ''}
+      >${this.shortcut === ''
+            ? nothing
+            : staticHtml `<${kbd}
+              part="shortcut"
+              exportparts="kbd: shortcut-kbd, key: shortcut-key, separator: shortcut-separator"
+              aria-hidden="true"
+              keys=${this.shortcut}
+            ></${kbd}>`}<slot id="end-words" name="end" aria-hidden="true" @slotchange=${this.readEnd}></slot
+    ></span>`;
+    }
     focus() {
         this.partNamed('item')?.focus();
     }
@@ -130,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>`;
@@ -142,31 +202,14 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         const ticks = this.checkable || this.checked;
         const role = ticks ? (this.exclusive ? 'menuitemradio' : 'menuitemcheckbox') : 'menuitem';
         const checkedState = ticks ? (this.checked ? 'true' : 'false') : nothing;
+        const keys = this.shortcut === '' ? nothing : ariaChord(this.shortcut, !this.hydrating && onApple());
         const inside = html `<span part="start" ?data-empty=${!this.start}
           ><slot name="start" @slotchange=${this.readStart}></slot
         ></span>
         <slot></slot>
-        ${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.renderDescription()}
+        ${this.renderEnd()}
+        ${this.renderMark(submenu)}`;
         return html `${linked
             ? html `<a
             part="item"
@@ -176,7 +219,9 @@ 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"
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
@@ -185,8 +230,10 @@ 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}
             tabindex=${this.disabled ? nothing : '-1'}
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
@@ -218,6 +265,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "rel", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenuItem.prototype, "shortcut", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessMenuItem.prototype, "showingSubmenu", void 0);
@@ -233,6 +283,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "start", void 0);
+__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

@@ -24,6 +24,30 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * sets this on items as a property, never as an attribute. An attribute written
  * onto your element after it upgrades causes a hydration mismatch.
  *
+ * Group rows under a heading with `Menu.Section`, which is a `group` named by
+ * 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
+ * menu does. A press on the area does not open it, and closing it returns focus
+ * to where it was.
+ *
  * @since 0.1.0
  * @status stable
  * @category overlays
@@ -31,7 +55,7 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The items.
- * @slot trigger - The control that opens the menu.
+ * @slot trigger - The control that opens the menu, or with `context` the area a context menu opens over.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The menu is about to close. Cancelable: cancel it to keep it open.
  * @event {HelixBeforeOpenEvent} helix-before-open - The menu is about to open. Cancelable: cancel it to keep it closed.
@@ -57,6 +81,11 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * The text of the row that returns from a submenu.
      */
     backLabel: string;
+    /**
+     * Whether the menu is the trigger's context menu: it opens where the reader
+     * asks for one, with a right-click, a long press, Shift+F10 or the menu key.
+     */
+    context: boolean;
     /**
      * Accessible name for the surface.
      *
@@ -104,6 +133,10 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     protected readonly keys: KeyboardNavigationController;
     /** Carries a host `aria-label` and `aria-labelledby` to the surface. */
     protected readonly aria: AriaForwardController;
+    /** Where a context menu was asked for, in the viewport, while it is open. */
+    private point;
+    /** Where focus was when a context menu opened, so closing it returns there. */
+    private returnTo;
     private readonly panel;
     /**
      * Tells a slotted trigger the disclosure state, by property.
@@ -124,6 +157,11 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private openAt;
     /** Closes the menu and returns it to its first page. */
     hide(): void;
+    /**
+     * Opens a context menu where the reader asked for it: at the pointer, or at
+     * the area's corner where the keyboard asked and the event has no position.
+     */
+    private readonly handleContextMenu;
     /** Shows an item's submenu in place of the current page. */
     private enter;
     /** Returns to the page above, or closes when there is none. */