@fusion.dev/helix-headless 0.156.0 → 0.158.0

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

@@ -13,8 +13,11 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     constructor() {
         super(...arguments);
         this.bandBelow = 640;
+        this.closeDelay = 220;
         this.label = '';
+        this.openDelay = 120;
         this.openOn = 'hover';
+        this.placement = 'bottom-start';
         this.narrow = false;
         this.handleWidth = (event) => {
             this.narrow = event.matches;
@@ -25,9 +28,10 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             onDismiss: () => this.close(),
             open: () => this.open,
             place: () => !this.banded,
-            placement: () => 'bottom-start',
+            placement: () => this.placement,
             surface: () => this.partNamed('surface'),
         });
+        this.settledOnce = false;
         this.keys = new KeyboardNavigationController(this, {
             items: () => !this.parentElement?.shadowRoot
                 ? HelixHeadlessMegamenu_1.bar
@@ -72,7 +76,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
                 return;
             }
             const showing = HelixHeadlessMegamenu_1.bar.showing;
-            this.schedule(showing && showing !== this ? 0 : HelixHeadlessMegamenu_1.OPEN_DELAY, () => {
+            this.schedule(showing && showing !== this ? 0 : this.openDelay, () => {
                 this.requestOpen(true);
             });
         };
@@ -80,7 +84,7 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             if (this.openOn !== 'hover' || event.pointerType !== 'mouse') {
                 return;
             }
-            this.schedule(HelixHeadlessMegamenu_1.CLOSE_DELAY, () => {
+            this.schedule(this.closeDelay, () => {
                 this.requestOpen(false);
             });
         };
@@ -142,9 +146,17 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     }
     tellTrigger() {
         const slotted = this.slotted;
-        if (slotted) {
+        if (!slotted || slotted.localName.includes('-')) {
             tellDisclosure(slotted, this.open);
+            return;
+        }
+        if (slotted !== this.told) {
+            if (!this.settledOnce || slotted.hasAttribute('aria-expanded')) {
+                return;
+            }
+            this.told = slotted;
         }
+        slotted.setAttribute('aria-expanded', String(this.open));
     }
     get slotted() {
         const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
@@ -156,6 +168,10 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     get navigationControl() {
         return this.trigger;
     }
+    markCurrent() {
+        const current = [...this.querySelectorAll('[aria-current="page"]')].some((link) => !link.closest('[slot="trigger"]'));
+        this.toggleState('current', current);
+    }
     close() {
         if (!this.requestOpen(false)) {
             return;
@@ -180,8 +196,6 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         }
         return this.trigger.getBoundingClientRect().bottom;
     }
-    static { this.OPEN_DELAY = 120; }
-    static { this.CLOSE_DELAY = 220; }
     schedule(delay, then) {
         this.stop();
         this.timer = setTimeout(then, delay);
@@ -203,6 +217,19 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.addEventListener('pointerleave', this.handlePointerLeave);
         this.addEventListener('focusout', this.handleFocusOut);
         this.addEventListener('keydown', this.handleKeyDown);
+        this.markCurrent();
+        if (typeof MutationObserver === 'function') {
+            this.currentWatch = new MutationObserver(() => this.markCurrent());
+            this.currentWatch.observe(this, {
+                attributeFilter: ['aria-current'],
+                childList: true,
+                subtree: true,
+            });
+        }
+        void this.whenSettled.then(() => {
+            this.settledOnce = true;
+            this.tellTrigger();
+        });
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -215,6 +242,8 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.removeEventListener('pointerleave', this.handlePointerLeave);
         this.removeEventListener('focusout', this.handleFocusOut);
         this.removeEventListener('keydown', this.handleKeyDown);
+        this.currentWatch?.disconnect();
+        this.currentWatch = undefined;
         HelixHeadlessMegamenu_1.bar.remove(this);
         this.stop();
     }
@@ -297,12 +326,21 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
 __decorate([
     property({ attribute: 'band-below', type: Number })
 ], HelixHeadlessMegamenu.prototype, "bandBelow", void 0);
+__decorate([
+    property({ attribute: 'close-delay', type: Number })
+], HelixHeadlessMegamenu.prototype, "closeDelay", void 0);
 __decorate([
     property()
 ], HelixHeadlessMegamenu.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'open-delay', type: Number })
+], HelixHeadlessMegamenu.prototype, "openDelay", void 0);
 __decorate([
     property({ attribute: 'open-on' })
 ], HelixHeadlessMegamenu.prototype, "openOn", void 0);
+__decorate([
+    property()
+], HelixHeadlessMegamenu.prototype, "placement", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessMegamenu.prototype, "variant", void 0);

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { HelixElement, PopoverController } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../kbd/index.js';
 /**
@@ -34,6 +34,9 @@ import '../../kbd/index.js';
  * React Aria's menu item does with its description: a reader hears "Copy",
  * then "Copies the selection".
  *
+ * A development build warns when a row has no words to be named by, such as a
+ * row holding only an icon with no label.
+ *
  * 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.
@@ -63,8 +66,11 @@ import '../../kbd/index.js';
  * @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.
+ * @csspart surface - The panel a submenu opens in beside the row, under the menu's `submenus="flyout"`.
  *
  * @cssstate checked - The row is checked.
+ * @cssstate submenu-mark - Under `submenus="flyout"`, a row in this row's submenu can be ticked or opens a submenu, so the submenu keeps its trailing column.
+ * @cssstate submenu-start - Under `submenus="flyout"`, a row in this row's submenu has content before its label, so the submenu keeps its leading column.
  */
 export declare class HelixHeadlessMenuItem extends HelixElement {
     /**
@@ -114,6 +120,16 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * one of a set of anything.
      */
     exclusive: boolean;
+    /**
+     * @internal Whether this row's submenu is open beside it, under
+     * `submenus="flyout"`. Written by the menu.
+     */
+    expanded: boolean;
+    /**
+     * @internal Whether the menu opens submenus beside their rows, under
+     * `submenus="flyout"`. Written by the menu.
+     */
+    flyout: boolean;
     /**
      * The URL the row links to. Setting it renders the row as a link.
      *
@@ -228,6 +244,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     /**
      * Re-reads whether anything is before the label.
      *
@@ -291,6 +308,12 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * on the row, which is the whole of what moving here means.
      */
     focusItem(): void;
+    /**
+     * The panel a flyout submenu opens in, beside the row and in the top layer.
+     * The menu around it says when, and answers a press outside and Escape, so
+     * its own dismissal does nothing.
+     */
+    protected readonly flyoutPanel: PopoverController;
     /** Chooses the row, the same as pressing it. */
     select(): void;
     /**

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, slotFilled, } from '@fusion.dev/helix-core';
+import { ariaChord, auditName, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, isRtl, onApple, PopoverController, 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';
@@ -19,6 +19,8 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.disabled = false;
         this.download = false;
         this.exclusive = false;
+        this.expanded = false;
+        this.flyout = false;
         this.href = '';
         this.onPage = true;
         this.rel = '';
@@ -47,6 +49,14 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
             this.submenu = (slot?.assignedElements().length ?? 0) > 0;
         };
+        this.flyoutPanel = new PopoverController(this, {
+            anchor: () => this.partNamed('item'),
+            boundary: () => this,
+            onDismiss: () => { },
+            open: () => this.flyout && this.expanded && this.onPage && this.submenu,
+            placement: () => (isRtl(this) ? 'left-start' : 'right-start'),
+            surface: () => (this.flyout ? this.partNamed('surface') : null),
+        });
         this.handleClick = () => {
             this.choose();
         };
@@ -80,11 +90,23 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.start = named('start');
         this.end = named('end');
         this.description = named('description');
+        const rows = this.knownChildren.filter((child) => child.slot === 'submenu' && child.isMenuItem);
+        this.toggleState('submenu-start', this.flyout && rows.some((row) => row.querySelector(':scope > [slot="start"]') !== null));
+        this.toggleState('submenu-mark', this.flyout &&
+            rows.some((row) => row.checkable ||
+                row.checked ||
+                [...row.children].some((child) => child.slot === 'submenu')));
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
     }
+    updated(changed) {
+        super.updated(changed);
+        if (this.partNamed('item')) {
+            auditName(this, () => this.partNamed('item') ?? undefined, 'Give the row words in its default slot, or a label on the icon it holds.');
+        }
+    }
     renderDescription() {
         return html `<slot
       id="description"
@@ -213,6 +235,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         return html `${linked
             ? html `<a
             part="item"
+            id=${this.flyout ? 'row' : nothing}
             href=${this.href}
             target=${this.target || nothing}
             rel=${this.rel || nothing}
@@ -221,6 +244,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             aria-checked=${checkedState}
             aria-describedby=${this.describedBy}
             aria-haspopup=${submenu ? 'menu' : nothing}
+            aria-expanded=${this.flyout && submenu ? String(this.expanded) : nothing}
             aria-keyshortcuts=${keys}
             tabindex="-1"
             @click=${this.handleClick}
@@ -228,17 +252,27 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
           >${inside}</a>`
             : html `<div
             part="item"
+            id=${this.flyout ? 'row' : nothing}
             role=${role}
             aria-checked=${checkedState}
             aria-describedby=${this.describedBy}
             aria-disabled=${this.disabled ? 'true' : nothing}
             aria-haspopup=${submenu ? 'menu' : nothing}
+            aria-expanded=${this.flyout && submenu ? String(this.expanded) : nothing}
             aria-keyshortcuts=${keys}
             tabindex=${this.disabled ? nothing : '-1'}
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
           >${inside}</div>`}
-      <div hidden><slot name="submenu" @slotchange=${this.readSubmenu}></slot></div>`;
+      ${this.flyout
+            ? html `<div
+              part="surface"
+              popover="manual"
+              role="menu"
+              aria-labelledby="row"
+              ?hidden=${!(this.expanded && submenu)}
+            ><slot name="submenu" @slotchange=${this.readSubmenu}></slot></div>`
+            : html `<div hidden><slot name="submenu" @slotchange=${this.readSubmenu}></slot></div>`}`;
     }
 };
 __decorate([
@@ -256,6 +290,12 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessMenuItem.prototype, "exclusive", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMenuItem.prototype, "expanded", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMenuItem.prototype, "flyout", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "href", void 0);

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

@@ -10,15 +10,24 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * ancestor with `overflow: hidden` does not clip it and it needs no `z-index`.
  *
  * Slot a `helix-button` or `helix-icon-button` as the trigger, and the menu
- * tells it that it opens a menu and whether the menu is open. A plain
- * `<button>` can only be told by writing attributes onto your markup, which
- * the menu does not do, so give it `aria-haspopup="menu"` and set its
- * `aria-expanded` from the `toggle` event.
+ * tells it that it opens a menu and whether the menu is open, inside its own
+ * shadow root. On a plain element, such as a `<button>`, the menu writes
+ * `aria-haspopup="menu"` and `aria-expanded`, from a frame after its own first
+ * render, so a server's markup is never changed while a framework hydrates it.
+ * It never writes `aria-expanded` where you wrote it yourself.
  *
- * Submenus drill down. A submenu replaces the panel's content, and a back row
- * returns to the previous page. One panel avoids the diagonal pointer path that
- * side-by-side panels need, stays inside a narrow window, and works on touch
- * screens, which have no hover.
+ * Submenus drill down by default. A submenu replaces the panel's content, and a
+ * back row returns to the previous page. One panel stays inside a narrow
+ * window, and works on touch screens, which have no hover.
+ *
+ * **`submenus="flyout"` opens each submenu in a panel of its own beside its
+ * row**, as React Aria's `SubmenuTrigger` and Radix's `Sub` do. Resting the
+ * pointer on the row opens it, and a pointer crossing toward the open panel
+ * over the rows between keeps it open, as Radix's grace area does. Right Arrow
+ * opens a row's submenu on its first row, and Left Arrow or Escape closes it
+ * and returns focus to the row, the two arrows swapping on a right-to-left
+ * page. The row says `aria-expanded`, and the panel is a `menu` named by the
+ * row.
  *
  * The root holds which page is open, because only one page shows at a time. It
  * sets this on items as a property, never as an attribute. An attribute written
@@ -33,8 +42,8 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * 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.
+ * right-to-left page. Left Arrow on the top page does nothing. 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
@@ -46,7 +55,14 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * 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.
+ * to where it was. A touch or a pen held still on the area opens it too, on
+ * every browser, since iOS sends no `contextmenu` for one.
+ *
+ * **A trigger with its own action.** With `open-on="long-press"`, a press on
+ * the trigger is the trigger's own, and a press held for half a second opens
+ * the menu, as React Aria's `trigger="longPress"` does. Alt+Down or Alt+Up
+ * opens it from the keyboard, and the trigger is described by
+ * `long-press-label`, which says so.
  *
  * @since 0.1.0
  * @status stable
@@ -77,6 +93,10 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @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.
+ * @cssstate placed-bottom - While the open panel sits below its trigger.
+ * @cssstate placed-left - While the open panel sits to the left of its trigger.
+ * @cssstate placed-right - While the open panel sits to the right of its trigger.
+ * @cssstate placed-top - While the open panel sits above its trigger.
  * @cssstate start - A row on the current page has content in its leading column, so every row keeps that column.
  */
 export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
@@ -102,16 +122,58 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * `aria-labelledby` on the host names it too, and wins over both.
      */
     label: string;
+    /** Whether submenus open beside their rows. */
+    private get flies();
+    /** The rows of the top page, read through each section. */
+    private get topRows();
+    /** The rows of a submenu, or of the top page for null. */
+    private rowsOf;
+    /** The row whose submenu holds a row, or null for a row of the top page. */
+    private holderOf;
+    /** The submenus open, from the top page down to the deepest. */
+    private get openPages();
+    /**
+     * The submenu the keys move in under `flyout`: the one holding the row with
+     * focus, or the deepest open one.
+     */
+    private get keyPage();
+    /** Opens a submenu and closes the ones below it, or closes them all for null. */
+    private openPage;
+    /**
+     * The description a trigger gives under `open-on="long-press"`, saying how
+     * to open the menu. Translate it with the rest of your interface.
+     */
+    longPressLabel: string;
     /**
      * Space between the trigger and the surface, in pixels.
      */
     offset: number;
+    /** Whether the trigger opens the menu only on a held press. */
+    private get pressHeld();
+    /**
+     * Watches the trigger for a held press: under `open-on="long-press"`, and
+     * for a touch or a pen on a context menu's area.
+     */
+    private readonly longPress;
+    /** Where a held press on a context menu's area is, to open the menu there. */
+    private heldAt;
+    /**
+     * What opens the menu from its trigger. `long-press` leaves a press to the
+     * trigger's own action and opens the menu on a press held for half a second,
+     * or on Alt+Down or Alt+Up.
+     */
+    openOn: 'click' | 'long-press';
     /**
      * The side the menu opens on, when there is room.
      *
      * It moves if that side does not fit.
      */
     placement: Placement;
+    /**
+     * How a submenu opens. `drill` shows it in place of the page showing, with
+     * a way back. `flyout` opens it in a panel of its own beside its row.
+     */
+    submenus: 'drill' | 'flyout';
     /**
      * Which page is showing, and what is on it.
      *
@@ -155,6 +217,10 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * hydration mismatch waiting to happen.
      */
     private tellTrigger;
+    /** Whether a frame has passed since the first render, after which a plain trigger may be told. */
+    private settledOnce;
+    /** The plain trigger this menu writes `aria-expanded` on. */
+    private told;
     /** The element the surface opens against. */
     private get trigger();
     /** The items on the page that is showing, which is what the keys move over. */
@@ -170,6 +236,8 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * the area's corner where the keyboard asked and the event has no position.
      */
     private readonly handleContextMenu;
+    /** Opens a context menu at a point in the viewport, or moves an open one there. */
+    private openContextAt;
     /** Shows an item's submenu in place of the current page. */
     private enter;
     /** Returns to the page above, or closes when there is none. */
@@ -192,6 +260,53 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      */
     private handleClosedKeydown;
     private readonly handleTriggerClick;
+    /** Whether an event came from the slotted trigger, or the area of a context menu. */
+    private fromTrigger;
+    /**
+     * A press on the trigger starting: the start of a held one under
+     * `open-on="long-press"`, or a touch or a pen held on a context menu's area.
+     */
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    private readonly handlePointerCancel;
+    /**
+     * Takes the click a held press ends in, ahead of the trigger's own
+     * listeners, so a press that opened the menu does not also do the trigger's
+     * action. In capture, on the host, which is above a slotted trigger.
+     */
+    private readonly handleHeldClick;
+    /** The control the menu has described, so the description can be taken back. */
+    private described;
+    /**
+     * Describes the trigger by `long-press-label` under `open-on="long-press"`,
+     * or takes it back, by the host, which carries the words as its label, as
+     * `SpeedDial` does. On the consumer's own element only once a reader has
+     * reached it, which is after hydration.
+     */
+    private describeTrigger;
+    /** A reader reaching the trigger, which is late enough to describe a plain one. */
+    private readonly handleTriggerFocusIn;
+    /** The row the pointer last rested on, under `flyout`. */
+    private hovered;
+    /** The wait before a rested-on row opens or closes a submenu. */
+    private hoverTimer;
+    /**
+     * The triangle from where the pointer left a row with an open submenu to the
+     * near edge of that submenu, and until when it holds.
+     */
+    private grace;
+    private stopHover;
+    /**
+     * A mouse resting on a row, under `flyout`: focus follows it, and after a
+     * moment the row's submenu opens, or the submenus below the row's own page
+     * close. Not while the pointer is crossing toward an open submenu.
+     */
+    private readonly handleHover;
+    /** The pointer leaving a row whose submenu is open, which starts the grace area. */
+    private readonly handleRowOut;
+    /** Whether the pointer is inside the grace area, while it holds. */
+    private inGrace;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;