@aceshooting/lyra-ui 1.2.0 → 2.1.0

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

@@ -0,0 +1,91 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+export type MenuItemType = 'normal' | 'checkbox';
+export interface MenuItemChangeDetail {
+    value: string;
+    checked: boolean;
+}
+/**
+ * `<lyra-menu-item>` — a single action row inside `<lyra-menu>`'s default
+ * slot. Not meaningful on its own (there is no standalone "click a menu item"
+ * use case) — it exists purely as `<lyra-menu>`'s light-DOM child, the same
+ * relationship `<lyra-option>` has to `<lyra-combobox>`/`<lyra-select>`.
+ *
+ * `role="menuitem"` and the roving `tabindex` both live on *this host
+ * element*, not an internal shadow-DOM button — mirroring `<lyra-tree-node>`'s
+ * identical choice (see that class's doc). `<lyra-menu>` is the sole owner of
+ * this element's `tabIndex`: it flips exactly one navigable item's `tabIndex`
+ * to `0` (the rest sit at `-1`) as its roving-tabindex highlight moves, and
+ * calls `.focus()` directly on this host to move real DOM focus there.
+ * `[part="base"]` is purely a visual box with no interactive semantics of its
+ * own — see the class doc on `<lyra-menu>` for why real DOM focus (rather
+ * than `aria-activedescendant`) was chosen for this pair.
+ *
+ * Enter/Space activation is handled by `<lyra-menu>`'s own delegated
+ * `keydown` listener calling `select()` on whichever item is currently
+ * roving-focused (mirrors `<lyra-tree>` calling `current.select()` from its
+ * own keydown handler) — this element only wires a plain `click` listener
+ * itself, so `select()` fires identically whether the item was reached by
+ * mouse or keyboard.
+ *
+ * `type="checkbox"` (mirroring `wa-dropdown-item`'s identical `type` option)
+ * renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with
+ * `aria-checked` reflecting `checked` and a checkmark glyph shown once
+ * `checked` is `true`. Activating a `checkbox`-type item (click, or the
+ * parent's Enter/Space handling via `select()`) toggles `checked` and fires
+ * `lyra-menu-item-change` *in addition to* the usual `lyra-menu-item-select`
+ * — the latter is never suppressed, so a parent `<lyra-menu>` still closes
+ * and re-fires its consolidated `lyra-menu-select` exactly as it does for a
+ * `type="normal"` item. `type="normal"` (the default) renders and behaves
+ * exactly as before this option existed — no role, rendering, or event
+ * differences.
+ *
+ * @customElement lyra-menu-item
+ * @slot - The item's label content.
+ * @slot icon - Optional leading icon.
+ * @event lyra-menu-item-select - This item was activated (click, or the
+ * parent `<lyra-menu>`'s own Enter/Space handling of the roving-focused
+ * item). No detail payload — a listener already has `event.target` (this
+ * element) to read `value` off of, and `<lyra-menu>` itself consumes this
+ * event to close and re-fire it as its own consolidated `lyra-menu-select`
+ * (`detail: { value }`) rather than requiring a consumer to listen on every
+ * individual item — listen there instead unless you specifically need a
+ * per-item handler.
+ * @event lyra-menu-item-change - A `type="checkbox"` item was activated and
+ * its `checked` state toggled. `detail: { value, checked }` — the item's own
+ * `value` and its new `checked` value. Fired in addition to (never instead
+ * of) `lyra-menu-item-select` above. Never fired for `type="normal"`.
+ * @csspart base - The row (`role` lives on the host — see the class doc).
+ * @csspart icon - Wrapper around the `icon` slot. Not rendered at all when the slot is empty.
+ * @csspart label - Wrapper around the default slot.
+ * @csspart checkmark - The checkmark glyph shown when a `type="checkbox"` item is `checked`. Not rendered at all for `type="normal"`.
+ */
+export declare class LyraMenuItem extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** An id/value the parent `<lyra-menu>`'s `lyra-menu-select` detail keys off of. */
+    value: string;
+    /** Disables selection and excludes this item from `<lyra-menu>`'s roving-tabindex nav entirely. */
+    disabled: boolean;
+    /** Visual treatment for a dangerous action (e.g. "Delete") — tints the row with `--lyra-color-danger`. */
+    destructive: boolean;
+    /** `'checkbox'` renders `role="menuitemcheckbox"` with a toggleable `checked` state and a
+     *  checkmark glyph, mirroring `wa-dropdown-item`'s identical `type` option — see the class doc. */
+    type: MenuItemType;
+    /** Whether a `type="checkbox"` item is checked. Meaningless (ignored) for `type="normal"`. */
+    checked: boolean;
+    private hasIconSlot;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /** Fires `lyra-menu-item-select` (no-op while `disabled`). Called by this element's own
+     *  click handler, and by `<lyra-menu>`'s Enter/Space keydown handling of the active item.
+     *  For `type="checkbox"`, also toggles `checked` and fires `lyra-menu-item-change` first --
+     *  see the class doc. */
+    select(): void;
+    private onIconSlotChange;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-menu-item': LyraMenuItem;
+    }
+}

package/dist/components/menu/menu-item.js

@@ -0,0 +1,206 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 { html, nothing, svg } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { styles } from './menu-item.styles.js';
+// Mirrors the shared icon set's viewBox/stroke conventions
+// (internal/icons.ts's chevronIcon()/closeIcon()/etc.) without adding a
+// checkmark glyph to that module -- it's off limits here -- so this one-off
+// icon still reads as part of the same visual language as the rest of the
+// library's inline icons. Same approach lyra-checkbox's own local
+// checkmark/indeterminate glyphs (and lyra-chat-message's local retryIcon())
+// take for the identical reason.
+const GLYPH_VIEW_BOX = '0 0 24 24';
+const GLYPH_STROKE_WIDTH = '1.75';
+function checkmarkGlyph() {
+    return svg `
+    <svg
+      part="checkmark"
+      width="1em"
+      height="1em"
+      viewBox=${GLYPH_VIEW_BOX}
+      fill="none"
+      stroke="currentColor"
+      stroke-width=${GLYPH_STROKE_WIDTH}
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    ><polyline points="5 12.5 10 17.5 19 6.5"></polyline></svg>
+  `;
+}
+/**
+ * `<lyra-menu-item>` — a single action row inside `<lyra-menu>`'s default
+ * slot. Not meaningful on its own (there is no standalone "click a menu item"
+ * use case) — it exists purely as `<lyra-menu>`'s light-DOM child, the same
+ * relationship `<lyra-option>` has to `<lyra-combobox>`/`<lyra-select>`.
+ *
+ * `role="menuitem"` and the roving `tabindex` both live on *this host
+ * element*, not an internal shadow-DOM button — mirroring `<lyra-tree-node>`'s
+ * identical choice (see that class's doc). `<lyra-menu>` is the sole owner of
+ * this element's `tabIndex`: it flips exactly one navigable item's `tabIndex`
+ * to `0` (the rest sit at `-1`) as its roving-tabindex highlight moves, and
+ * calls `.focus()` directly on this host to move real DOM focus there.
+ * `[part="base"]` is purely a visual box with no interactive semantics of its
+ * own — see the class doc on `<lyra-menu>` for why real DOM focus (rather
+ * than `aria-activedescendant`) was chosen for this pair.
+ *
+ * Enter/Space activation is handled by `<lyra-menu>`'s own delegated
+ * `keydown` listener calling `select()` on whichever item is currently
+ * roving-focused (mirrors `<lyra-tree>` calling `current.select()` from its
+ * own keydown handler) — this element only wires a plain `click` listener
+ * itself, so `select()` fires identically whether the item was reached by
+ * mouse or keyboard.
+ *
+ * `type="checkbox"` (mirroring `wa-dropdown-item`'s identical `type` option)
+ * renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with
+ * `aria-checked` reflecting `checked` and a checkmark glyph shown once
+ * `checked` is `true`. Activating a `checkbox`-type item (click, or the
+ * parent's Enter/Space handling via `select()`) toggles `checked` and fires
+ * `lyra-menu-item-change` *in addition to* the usual `lyra-menu-item-select`
+ * — the latter is never suppressed, so a parent `<lyra-menu>` still closes
+ * and re-fires its consolidated `lyra-menu-select` exactly as it does for a
+ * `type="normal"` item. `type="normal"` (the default) renders and behaves
+ * exactly as before this option existed — no role, rendering, or event
+ * differences.
+ *
+ * @customElement lyra-menu-item
+ * @slot - The item's label content.
+ * @slot icon - Optional leading icon.
+ * @event lyra-menu-item-select - This item was activated (click, or the
+ * parent `<lyra-menu>`'s own Enter/Space handling of the roving-focused
+ * item). No detail payload — a listener already has `event.target` (this
+ * element) to read `value` off of, and `<lyra-menu>` itself consumes this
+ * event to close and re-fire it as its own consolidated `lyra-menu-select`
+ * (`detail: { value }`) rather than requiring a consumer to listen on every
+ * individual item — listen there instead unless you specifically need a
+ * per-item handler.
+ * @event lyra-menu-item-change - A `type="checkbox"` item was activated and
+ * its `checked` state toggled. `detail: { value, checked }` — the item's own
+ * `value` and its new `checked` value. Fired in addition to (never instead
+ * of) `lyra-menu-item-select` above. Never fired for `type="normal"`.
+ * @csspart base - The row (`role` lives on the host — see the class doc).
+ * @csspart icon - Wrapper around the `icon` slot. Not rendered at all when the slot is empty.
+ * @csspart label - Wrapper around the default slot.
+ * @csspart checkmark - The checkmark glyph shown when a `type="checkbox"` item is `checked`. Not rendered at all for `type="normal"`.
+ */
+export class LyraMenuItem extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** An id/value the parent `<lyra-menu>`'s `lyra-menu-select` detail keys off of. */
+        this.value = '';
+        /** Disables selection and excludes this item from `<lyra-menu>`'s roving-tabindex nav entirely. */
+        this.disabled = false;
+        /** Visual treatment for a dangerous action (e.g. "Delete") — tints the row with `--lyra-color-danger`. */
+        this.destructive = false;
+        /** `'checkbox'` renders `role="menuitemcheckbox"` with a toggleable `checked` state and a
+         *  checkmark glyph, mirroring `wa-dropdown-item`'s identical `type` option — see the class doc. */
+        this.type = 'normal';
+        /** Whether a `type="checkbox"` item is checked. Meaningless (ignored) for `type="normal"`. */
+        this.checked = false;
+        // [part='icon'] never matches a bare :empty selector -- see menu-item.styles.ts's
+        // own comment on that part. Same fix as lyra-tool-call-chip's hasDetailSlot.
+        this.hasIconSlot = false;
+        this.onIconSlotChange = (e) => {
+            this.hasIconSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    connectedCallback() {
+        super.connectedCallback();
+        // A safe, focusable-but-out-of-tab-order baseline before <lyra-menu> ever
+        // gets a chance to assign roving-tabindex state (e.g. a standalone
+        // fixture in a test, or the brief window before the parent's own
+        // slotchange handler runs). <lyra-menu> is the sole subsequent owner of
+        // this property -- see the class doc.
+        if (this.tabIndex !== 0)
+            this.tabIndex = -1;
+    }
+    willUpdate(changed) {
+        // role/aria-disabled/aria-checked live on the host (see the class doc),
+        // so they're plain imperative attribute writes here rather than part of
+        // render()'s shadow-DOM template -- mirrors lyra-tree-node's identical
+        // willUpdate.
+        const isCheckbox = this.type === 'checkbox';
+        this.setAttribute('role', isCheckbox ? 'menuitemcheckbox' : 'menuitem');
+        if (isCheckbox) {
+            this.setAttribute('aria-checked', this.checked ? 'true' : 'false');
+        }
+        else {
+            // Kept absent entirely for type="normal" -- see the class doc's "no
+            // role, rendering, or event differences" guarantee for that default.
+            this.removeAttribute('aria-checked');
+        }
+        if (this.disabled) {
+            this.setAttribute('aria-disabled', 'true');
+            // Defense-in-depth mirroring connectedCallback's baseline above:
+            // <lyra-menu>'s roving-tabindex bookkeeping (activeIndex) only gets a
+            // chance to resync once real focus actually moves (via its own
+            // focusin listener), so a `disabled` flip must proactively strip this
+            // item out of the roving target and drop any focus it's currently
+            // holding right here -- regardless of what the parent's activeIndex
+            // still thinks -- so a disabled item can never remain the roving
+            // target or retain focus.
+            if (changed.has('disabled')) {
+                this.tabIndex = -1;
+                if (document.activeElement === this)
+                    this.blur();
+            }
+        }
+        else {
+            this.removeAttribute('aria-disabled');
+        }
+        if (changed.has('disabled')) {
+            this.emit('lyra-menu-item-state-change', { disabled: this.disabled, hidden: this.hidden });
+        }
+    }
+    /** Fires `lyra-menu-item-select` (no-op while `disabled`). Called by this element's own
+     *  click handler, and by `<lyra-menu>`'s Enter/Space keydown handling of the active item.
+     *  For `type="checkbox"`, also toggles `checked` and fires `lyra-menu-item-change` first --
+     *  see the class doc. */
+    select() {
+        if (this.disabled)
+            return;
+        if (this.type === 'checkbox') {
+            this.checked = !this.checked;
+            this.emit('lyra-menu-item-change', { value: this.value, checked: this.checked });
+        }
+        this.emit('lyra-menu-item-select');
+    }
+    render() {
+        return html `
+      <span part="base" @click=${() => this.select()}>
+        <span part="icon" aria-hidden="true" ?hidden=${!this.hasIconSlot}>
+          <slot name="icon" @slotchange=${this.onIconSlotChange}></slot>
+        </span>
+        <span part="label"><slot></slot></span>
+        ${this.type === 'checkbox' && this.checked ? checkmarkGlyph() : nothing}
+      </span>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraMenuItem.prototype, "value", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraMenuItem.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraMenuItem.prototype, "destructive", void 0);
+__decorate([
+    property()
+], LyraMenuItem.prototype, "type", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraMenuItem.prototype, "checked", void 0);
+__decorate([
+    state()
+], LyraMenuItem.prototype, "hasIconSlot", void 0);
+defineElement('menu-item', LyraMenuItem);

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

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/menu/menu-item.styles.js

@@ -0,0 +1,75 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* The host itself is the focusable role="menuitem" target (see the class
+       doc) -- the ring paints on [part='base'] instead of the host's own
+       box, matching lyra-tree-node's identical :host(:focus-visible)
+       delegation, so it always hugs the visible row rather than any
+       host-level margin/inline layout quirks. */
+    outline: none;
+    border-radius: var(--lyra-radius);
+  }
+  :host(:focus-visible) [part='base'] {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: calc(-1 * var(--lyra-focus-ring-width));
+  }
+  [part='base'] {
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+    padding: var(--lyra-space-xs) var(--lyra-space-s);
+    border-radius: var(--lyra-radius);
+    cursor: pointer;
+    font: inherit;
+    color: inherit;
+    line-height: 1.3;
+  }
+  [part='base']:hover {
+    background: var(--lyra-color-brand-quiet);
+  }
+  :host([disabled]) [part='base'] {
+    /* Shared library-wide disabled-state token -- see lyra-checkbox/lyra-select. */
+    opacity: var(--lyra-opacity-disabled);
+    cursor: not-allowed;
+  }
+  :host([disabled]) [part='base']:hover {
+    background: none;
+  }
+  :host([destructive]) [part='base'] {
+    color: var(--lyra-color-danger);
+  }
+  :host([destructive]) [part='base']:hover {
+    background: var(--lyra-color-danger-quiet);
+  }
+  [part='icon'] {
+    display: inline-flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    line-height: 1;
+  }
+  /* [part='icon'][hidden] rather than a bare :empty selector -- the part
+     always contains a literal <slot> child element regardless of assigned
+     content, so :empty never matches (same fix as lyra-select's
+     [part='hint']/[part='error']). Real emptiness is tracked in JS
+     (hasIconSlot) and reflected via the hidden attribute instead. */
+  [part='icon'][hidden] {
+    display: none;
+  }
+  [part='label'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  /* Only ever present in the DOM at all for a checked type="checkbox" item
+     (see menu-item.ts's render()) -- no [hidden]-toggling needed, unlike
+     [part='icon'] above, since there's no always-present <slot> child here
+     to keep visually empty in between. */
+  [part='checkmark'] {
+    flex: 0 0 auto;
+    color: var(--lyra-color-brand);
+  }
+`;

package/dist/components/menu/menu.d.ts

@@ -0,0 +1,167 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import type { Placement } from '@floating-ui/dom';
+import { LyraElement } from '../../internal/lyra-element.js';
+import './menu-item.js';
+export interface MenuSelectDetail {
+    value: string;
+}
+/**
+ * `<lyra-menu>` — an anchored dropdown of `<lyra-menu-item>` actions, opened
+ * from a consumer-supplied trigger (typically an icon button). A close, drop-
+ * in-shaped replacement for reaching outside this library for a third-party
+ * dropdown to build a gear menu, an avatar menu, or a history row's overflow
+ * menu: click the trigger, a positioned menu appears, clicking an item both
+ * performs the action *and* closes the menu.
+ *
+ * **ARIA pattern — `role="menu"`/`role="menuitem"` with real roving DOM
+ * focus, not a listbox.** Two coherent, mutually-exclusive shapes were
+ * available here: (a) `role="listbox"`/`role="option"` with
+ * `aria-activedescendant`, the pattern `<lyra-select>`'s trigger-button +
+ * popup listbox uses, where DOM focus never leaves the trigger; or (b)
+ * `role="menu"`/`role="menuitem"` with real focus moving between actual
+ * focusable rows, the WAI-ARIA "menu button" pattern. This picks (b):
+ * `<lyra-menu-item>` rows are real, independently-focusable elements (see
+ * that class's own doc), which is the more natural fit for a menu
+ * specifically — unlike a listbox's rows, a menu's rows are conventionally
+ * button-/link-shaped, and every well-known native/OS menu (and this
+ * family's own `<lyra-tree>`/`<lyra-tree-node>` pair, which this component's
+ * roving-tabindex plumbing directly mirrors) already moves real focus rather
+ * than merely a virtual `aria-activedescendant` pointer. `role`/`tabIndex`
+ * are consistently the menu-button shape throughout — never mixed with
+ * listbox/option.
+ *
+ * Interaction contract (mirrors the WAI-ARIA APG "menu button" pattern):
+ * - Click the trigger (or Enter/Space on it, via the trigger's own native
+ *   `click` activation) toggles the menu, moving focus to the first
+ *   non-disabled item on open.
+ * - ArrowDown/ArrowUp on the trigger while closed also open it, focusing the
+ *   first/last non-disabled item respectively.
+ * - Once open, ArrowDown/ArrowUp move the roving focus among non-disabled
+ *   items (wrapping past either end — the recommended, and more common,
+ *   menu-widget behavior, unlike `<lyra-select>`'s clamped listbox nav).
+ *   Home/End jump to the first/last non-disabled item. Enter/Space activate
+ *   the focused item. Escape closes and returns focus to the trigger. Tab
+ *   closes the menu without trapping focus (the browser's own default Tab
+ *   behavior proceeds untouched). A printable keypress runs type-ahead:
+ *   roving focus jumps to the next non-disabled item whose text starts with
+ *   the accumulated buffer, cycling from just after the active item (mirrors
+ *   `<lyra-select>`'s identical listbox type-ahead).
+ * - A click outside both the trigger and the open popup closes it (mirrors
+ *   `<lyra-select>`'s `onDocPointer` exactly) — this does *not* refocus the
+ *   trigger, since the outside click itself already moved focus somewhere
+ *   the user chose; Escape and a committed selection *do* refocus the
+ *   trigger, since those are dismissals with nowhere else for focus to go.
+ *
+ * The trigger element itself is read from the `trigger` slot's assigned
+ * element (first one, if several are assigned) and enhanced imperatively
+ * with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls` — the same
+ * "reach into a consumer-owned light-DOM element to complete its a11y
+ * wiring" approach `<lyra-dialog>` documents for its own heading detection,
+ * necessary here because those attributes belong on the actual interactive
+ * trigger, which lives outside this component's own shadow root.
+ *
+ * The popup is always rendered (never `display:none`) so `.focus()` calls on
+ * its content work synchronously the instant it opens — visually hidden via
+ * `visibility`/`opacity` instead (identical to `<lyra-select>`'s own
+ * `[part="listbox"]`). `visibility` is an inherited CSS property that
+ * pierces the `<slot>` projection boundary, so every closed-state
+ * `<lyra-menu-item>` is automatically excluded from sequential (Tab-key)
+ * navigation with no separate JS bookkeeping.
+ *
+ * @customElement lyra-menu
+ * @slot trigger - The consumer's own trigger element (typically an icon
+ * button). Clicking it toggles the menu; it's positioned against via
+ * `internal/positioner.js`'s `place()`.
+ * @slot - `<lyra-menu-item>` elements, plus optionally plain `<hr>` dividers
+ * between groups (native `<hr>` already carries an implicit `separator`
+ * role, matching what `role="menu"` expects between item groups).
+ * @event lyra-show - The menu opened. Not fired for markup that renders
+ * `open` true from the start (mirrors `<lyra-select>`'s identical guard).
+ * @event lyra-hide - The menu closed. Same first-render guard as `lyra-show`.
+ * @event lyra-menu-select - A `<lyra-menu-item>` was activated. `detail: {
+ * value }` — the consolidated re-fire of that item's own
+ * `lyra-menu-item-select` (see `<lyra-menu-item>`'s doc for why listening
+ * here, rather than on every item, is the recommended approach). Always
+ * followed by the menu closing and focus returning to the trigger.
+ * @csspart trigger - The wrapper around the `trigger` slot (the positioning anchor).
+ * @csspart popup - The positioned floating panel.
+ * @csspart list - The `role="menu"` container wrapping the default slot.
+ */
+export declare class LyraMenu extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Whether the menu is open. */
+    open: boolean;
+    /**
+     * Optional placement override forwarded to `place()`. Defaults to whatever `place()` itself
+     * defaults to. A `left`/`right` side is resolved through `rtlAwareSide` semantics (see
+     * `internal/rtl.ts`) so e.g. `placement="left-start"` still anchors to the menu's trailing edge
+     * under RTL rather than pinning to the physical left.
+     */
+    placement?: Placement;
+    /** Accessible name for the `role="menu"` popup — override with something
+     *  specific (e.g. "Row actions") when a page has more than one menu. */
+    label: string;
+    private items;
+    private activeIndex;
+    private triggerEl?;
+    private cleanup?;
+    private itemStateObserver?;
+    private _isFirstUpdate;
+    private pendingFocus;
+    private readonly listId;
+    private typeAheadBuffer;
+    private typeAheadTimer?;
+    protected willUpdate(): void;
+    protected updated(changed: PropertyValues): void;
+    private reposition;
+    disconnectedCallback(): void;
+    private show;
+    /** `refocusTrigger` is only ever `true` for a dismissal with nowhere else
+     *  for focus to land (Escape, a committed selection) -- see the class
+     *  doc's interaction contract for why an outside click deliberately omits it. */
+    private hide;
+    private onDocPointer;
+    private onTriggerClick;
+    private onTriggerKeyDown;
+    private onTriggerSlotChange;
+    /** `aria-haspopup`/`aria-expanded`/`aria-controls` belong on the actual
+     *  interactive trigger, which is consumer-owned light-DOM content outside
+     *  this component's own shadow root -- see the class doc. */
+    private syncTriggerA11y;
+    private onItemsSlotChange;
+    private isNavigable;
+    /** Rehomes roving focus immediately when an active item becomes disabled or hidden. */
+    private onItemStateChange;
+    private onItemSelect;
+    /** Flips exactly one non-disabled item's `tabIndex` to `0` (the roving
+     *  target) and every other item's to `-1` -- see `<lyra-menu-item>`'s doc
+     *  for why this is the sole authority over that property. */
+    private applyRovingTabIndex;
+    /** Moves the roving focus (and real DOM focus) to the first/last
+     *  non-disabled item. A no-op when there are none -- focus then simply
+     *  stays on the trigger (see onTriggerKeyDown's Escape safety net). */
+    private focusRoving;
+    private setActiveItem;
+    /** Resyncs `activeIndex` (and the roving `tabindex`) to wherever real DOM
+     *  focus actually lands, for any path that doesn't go through
+     *  `setActiveItem()` -- e.g. a real mousedown on an item, which focuses it
+     *  even while `disabled` (`tabIndex="-1"` remains mouse-focusable per
+     *  spec). Without this, `activeIndex` goes stale the moment focus moves any
+     *  other way, and subsequent Arrow-key navigation computes its next item
+     *  from that stale position instead of from where focus actually is. A
+     *  no-op for `setActiveItem()`'s own `.focus()` call, since `activeIndex`
+     *  there is already set to match before focus moves. */
+    private onListFocusIn;
+    private onListKeyDown;
+    /** Standard WAI-ARIA APG menu-button type-ahead: moves the roving focus to
+     *  the next non-disabled item whose text content starts with the
+     *  accumulated buffer, cycling from just after the currently active item
+     *  -- mirrors `<lyra-select>`'s identical listbox type-ahead. */
+    private typeAhead;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-menu': LyraMenu;
+    }
+}