@fusion.dev/helix-headless 0.144.0 → 0.145.0

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

@@ -45,7 +45,8 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * for each layer, which sets the layer's `hidden` attribute. Layers with the
  * same `group`, such as a route and its dotted legs, share one tile. A tile
  * sends `helix-before-toggle` from the layer first, so you can store the
- * choice or refuse it.
+ * choice or refuse it, and `helix-toggle` from it once `hidden` holds the
+ * choice.
  *
  * Imagery, a `helix-map-raster` with `ground`, is a map type and not a tile.
  * The menu opens with a card for each type, Standard, Hybrid, and Satellite,
@@ -80,6 +81,7 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @event {HelixMapRotateEvent} helix-map-rotate - A rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response.
  * @event {HelixMapTiltEvent} helix-map-tilt - The 3D button, or Shift with Up or Down, was pressed. Tilt your map in response.
  * @event {HelixMapZoomEvent} helix-map-zoom - A zoom button or key was pressed, with a direction. Zoom your map in response.
+ * @event {HelixToggleEvent} helix-toggle - A layer's tile in the layers menu showed or hid it. Sent from the layer once its `hidden` attribute holds the choice, with `checked` true when it is shown.
  *
  * @csspart attribution - The strip under the map that holds the credit.
  * @csspart compass - The compass and the pan and rotate buttons around it.
@@ -291,7 +293,9 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
      * **Asked first, from the layer.** The tile wrote `hidden` onto the
      * consumer's element and said nothing, so a page could neither keep the
      * choice nor keep its own state in step. The request comes from the first
-     * layer of the tile, which is the element the page wrote.
+     * layer of the tile, which is the element the page wrote. Once `hidden`
+     * holds the answer, the same layer sends `helix-toggle`, the request's verb
+     * without `before`, since the platform has no word for a layer shown.
      */
     private showLayers;
     /** Asks for a map type, and sends `change` once it holds. */

package/dist/map/root/map-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 { customElement, fillTemplate, formatNumbers, HelixActivateEvent, HelixBeforeChangeEvent, HelixBeforeToggleEvent, HelixElement, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, hostAria, KeyboardNavigationController, MixinViewport, requestChange, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, formatNumbers, HelixActivateEvent, HelixBeforeChangeEvent, HelixBeforeToggleEvent, HelixElement, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixToggleEvent, hostAria, KeyboardNavigationController, MixinViewport, requestChange, } from '@fusion.dev/helix-core';
 import { buildings, cloudRain, dotsNine, leaf, mountains, path, polygon, stack, target, } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -210,7 +210,7 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         if (!first) {
             return;
         }
-        requestChange({
+        const applied = requestChange({
             apply: () => {
                 for (const layer of layers) {
                     layer.hidden = !shown;
@@ -221,6 +221,9 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
             host: first,
             next: shown,
         });
+        if (applied) {
+            first.dispatchEvent(new HelixToggleEvent({ checked: shown }));
+        }
     }
     chooseMapType(type) {
         const applied = requestChange({

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

@@ -20,6 +20,13 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * which. Hover is the default because in a navigation bar people expect to move
  * 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.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -38,8 +45,12 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  *
  * @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 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.
  */
 export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
     /**
@@ -119,6 +130,11 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
     private get slotted();
     /** Whatever the consumer slotted, or the button rendered in its place. */
     private get trigger();
+    /**
+     * @internal The control a `Navigation`'s arrow keys move to: the trigger
+     * the consumer slotted, or the button drawn in its place.
+     */
+    get navigationControl(): HTMLElement;
     /** Shuts it and puts the reader back where they were. */
     private close;
     /**
@@ -241,6 +257,11 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      * overruled.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Says which way the reader moved when one panel took over from another.
+     * Nothing clears all four, for a panel opened on its own.
+     */
+    private motion;
     protected updated(changed: PropertyValues): void;
     /**
      * The control that opens it, behind a seam the styled tier can move.

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

@@ -117,6 +117,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;
@@ -184,8 +187,13 @@ 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);
+            if (previous) {
+                previous.motion(forward ? 'to-end' : 'to-start');
+                previous.requestOpen(false);
             }
             showing = this;
         }
@@ -193,6 +201,12 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             showing = undefined;
         }
     }
+    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);
         if (changed.has('bandBelow')) {

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,30 @@ 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.
+ *
  * @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 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 start - The leading column that holds the `start` slot. It is always rendered.
  *
  * @cssstate checked - The row is checked.
@@ -100,19 +110,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 +131,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 +199,8 @@ 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;
     /**
      * Both answers, from the children, before each render.
      *
@@ -205,6 +221,17 @@ 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;
+    /**
+     * 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.
+     */
+    protected renderEnd(): TemplateResult;
     /**
      * Re-reads whether anything is in the submenu, from whichever slot is current.
      *

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,22 @@ 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.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.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
             this.submenu = (slot?.assignedElements().length ?? 0) > 0;
@@ -65,11 +73,25 @@ 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');
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
     }
+    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"
+              aria-hidden="true"
+              keys=${this.shortcut}
+            ></${kbd}>`}<slot name="end" @slotchange=${this.readEnd}></slot
+    ></span>`;
+    }
     focus() {
         this.partNamed('item')?.focus();
     }
@@ -142,10 +164,12 @@ 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>
+        ${this.renderEnd()}
         ${submenu
             ? html `<svg
                 part="mark"
@@ -177,6 +201,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             role=${role}
             aria-checked=${checkedState}
             aria-haspopup=${submenu ? 'menu' : nothing}
+            aria-keyshortcuts=${keys}
             tabindex="-1"
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
@@ -187,6 +212,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             aria-checked=${checkedState}
             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 +244,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 +262,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "start", void 0);
+__decorate([
+    state()
+], HelixHeadlessMenuItem.prototype, "end", void 0);
 HelixHeadlessMenuItem = __decorate([
     customElement('helix-headless-menu-item')
 ], HelixHeadlessMenuItem);

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

@@ -24,6 +24,16 @@ 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.
+ *
+ * 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 +41,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 +67,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 +119,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 +143,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. */

package/dist/menu/root/menu-root.js

@@ -9,16 +9,20 @@ import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+const isSection = (element) => 'isMenuSection' in element && element.isMenuSection === true;
 let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinControllerOpen(HelixElement)) {
     constructor() {
         super(...arguments);
         this.backLabel = 'Back';
+        this.context = false;
         this.label = '';
         this.offset = 4;
         this.placement = 'bottom-start';
         this.drilldown = new DrilldownController(this, {
             isRow: (element) => 'isMenuItem' in element && element.isMenuItem === true,
-            root: () => [...this.children].filter((child) => child.slot !== 'trigger'),
+            root: () => [...this.children]
+                .filter((child) => child.slot !== 'trigger')
+                .flatMap((child) => (isSection(child) ? [...child.children] : [child])),
             slot: 'submenu',
         });
         this.keys = new KeyboardNavigationController(this, {
@@ -32,7 +36,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             target: () => this.partNamed('surface'),
         });
         this.panel = new PopoverController(this, {
-            anchor: () => this.trigger,
+            anchor: () => this.context && this.point
+                ? this.renderRoot?.querySelector('#point')
+                : this.trigger,
             boundary: () => this,
             offset: () => this.offset,
             onDismiss: () => this.hide(),
@@ -40,6 +46,28 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             placement: () => this.placement,
             surface: () => this.partNamed('surface'),
         });
+        this.handleContextMenu = (event) => {
+            if (!this.context) {
+                return;
+            }
+            const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
+            const areas = slot?.assignedElements({ flatten: true }) ?? [];
+            if (!event.composedPath().some((node) => areas.includes(node))) {
+                return;
+            }
+            event.preventDefault();
+            const box = this.trigger.getBoundingClientRect();
+            const keyed = event.clientX === 0 && event.clientY === 0;
+            this.point = keyed ? { x: box.left, y: box.top } : { x: event.clientX, y: event.clientY };
+            if (this.open) {
+                this.requestUpdate();
+                this.updateComplete.then(() => this.panel.reposition());
+                return;
+            }
+            const active = deepActiveElement();
+            this.returnTo = active instanceof HTMLElement ? active : undefined;
+            this.show();
+        };
         this.handleSelect = (event) => {
             const item = event.target;
             if (!this.items.includes(item)) {
@@ -93,6 +121,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             event.preventDefault();
         };
         this.handleTriggerClick = () => {
+            if (this.context) {
+                return;
+            }
             if (this.open) {
                 this.hide();
             }
@@ -130,8 +161,11 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.panel.hide();
         this.drilldown.reset();
         if (deepContains(this, deepActiveElement())) {
-            this.trigger.focus();
+            ;
+            (this.context ? (this.returnTo ?? this.trigger) : this.trigger).focus();
         }
+        this.point = undefined;
+        this.returnTo = undefined;
     }
     enter(item) {
         if (!this.drilldown.enter(item)) {
@@ -149,7 +183,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.updateComplete.then(() => leaving?.focus());
     }
     handleClosedKeydown(event) {
-        if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') {
+        if (this.context || (event.key !== 'ArrowDown' && event.key !== 'ArrowUp')) {
             return;
         }
         const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
@@ -165,17 +199,30 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.addEventListener('helix-select', this.handleSelect, true);
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('focusin', this.handleFocusIn);
+        this.addEventListener('contextmenu', this.handleContextMenu);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelect, true);
         this.removeEventListener('keydown', this.handleKeydown);
         this.removeEventListener('focusin', this.handleFocusIn);
+        this.removeEventListener('contextmenu', this.handleContextMenu);
     }
     updated(changed) {
         super.updated(changed);
-        this.tellTrigger();
+        if (!this.context) {
+            this.tellTrigger();
+        }
         for (const child of this.children) {
+            if (isSection(child)) {
+                child.onPage = this.drilldown.atRoot;
+                for (const row of child.children) {
+                    if (row.isMenuItem === true) {
+                        this.mark(row, this.drilldown.atRoot);
+                    }
+                }
+                continue;
+            }
             const item = child;
             if (item.isMenuItem !== true) {
                 continue;
@@ -217,7 +264,14 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         }
     }
     render() {
-        return html `<slot name="trigger" @click=${this.handleTriggerClick}></slot>
+        const point = this.context && this.point;
+        return html `<slot name="trigger" @click=${this.handleTriggerClick}></slot>${point
+            ? html `<span
+            id="point"
+            aria-hidden="true"
+            style="position: fixed; left: 0; top: 0; translate: ${point.x}px ${point.y}px"
+          ></span>`
+            : nothing}
       <div
         part="surface"
         popover="manual"
@@ -250,6 +304,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
 __decorate([
     property({ attribute: 'back-label' })
 ], HelixHeadlessMenu.prototype, "backLabel", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessMenu.prototype, "context", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "label", void 0);

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

@@ -0,0 +1,55 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A group of rows in a menu, under a heading.
+ *
+ * @description
+ * The rows inside it are the menu's rows: the arrow keys and typed letters move
+ * through them with the rest, and a set of `exclusive` rows is still the run
+ * of them next to each other. The section is a `group` named by its heading,
+ * as React Aria's menu section is, so a screen reader says which group a row
+ * is in as it arrives.
+ *
+ * A section goes on the menu's first page. A submenu's page takes rows and
+ * dividers.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Menu group, Menu heading
+ * @documentation https://fusion.dev/helix/components/menu
+ *
+ * @slot - The rows.
+ * @slot heading - The heading, for content richer than `label`.
+ *
+ * @csspart heading - The words that name the section.
+ * @csspart section - The group that holds the heading and the rows.
+ */
+export declare class HelixHeadlessMenuSection extends HelixElement {
+    /**
+     * The heading's words, when they are plain text. Content in the `heading`
+     * slot replaces it.
+     */
+    label: string;
+    /**
+     * @internal Set by the menu: whether the section is on the page showing. A
+     * property, because the menu writes it after the section upgrades.
+     */
+    onPage: boolean;
+    /** @internal What a menu reads to tell a section from a row. */
+    readonly isMenuSection = true;
+    /**
+     * Whether anything is slotted as the heading, read from the children before
+     * each render and from the slot after. A section with neither this nor a
+     * `label` draws no heading.
+     */
+    private heading;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    private readonly readHeading;
+    protected render(): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-menu-section': HelixHeadlessMenuSection;
+    }
+}