@fusion.dev/helix-headless 0.155.0 → 0.157.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'), '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
@@ -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
@@ -102,16 +118,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 +213,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 +232,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 +256,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;