@aceshooting/lyra-ui 5.1.0 → 6.0.0

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

@@ -45,16 +45,27 @@ export interface LyraMenuEventMap {
  *   items (wrapping past either end — the recommended, and more common,
  *   menu-widget behavior, unlike `<lr-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
- *   `<lr-select>`'s identical listbox type-ahead). All of the above (except
- *   Escape) only respond to keydowns from a real `<lr-menu-item>` target,
- *   so a slotted non-item control (e.g. a date input) keeps its own full
- *   default keyboard behavior. Escape from such a slotted control closes the
- *   menu too, but only when `closeOnEscapeAnywhere` is set — it defaults to
+ *   the focused item. Escape closes and returns focus to the trigger. 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 `<lr-select>`'s identical
+ *   listbox type-ahead). All of the above (except Escape and Tab) only
+ *   respond to keydowns from a real `<lr-menu-item>` target, so a slotted
+ *   non-item control (e.g. a date input) keeps its own full default keyboard
+ *   behavior.
+ * - Tab never traps focus and never calls `preventDefault()` — the browser's
+ *   own Tab navigation always proceeds untouched. It closes the menu only
+ *   when focus is on its way *out* of the popup: with a focusable in the
+ *   `header`/`footer` region on the far side of the keypress, the menu stays
+ *   open so native Tab can carry focus there instead. With neither region
+ *   filled, Tab closes exactly as it always has. Tabbing past the popup's
+ *   last focusable in either direction closes it too, including from slotted
+ *   non-item content — which previously left the menu open while focus
+ *   walked away.
+ * - Escape from `header`/`footer` content closes the menu and refocuses the
+ *   trigger unconditionally, mirroring `<lr-popover>`'s handling of arbitrary
+ *   popup content. `closeOnEscapeAnywhere` governs only the *legacy* shape —
+ *   non-item content slotted into the **default** slot — and defaults to
  *   `false`, so existing consumers keep today's behavior unchanged.
  * - A click outside both the trigger and the open popup closes it (mirrors
  *   `<lr-select>`'s `onDocPointer` exactly) — this does *not* refocus the
@@ -62,6 +73,14 @@ export interface LyraMenuEventMap {
  *   the user chose; Escape and a committed selection *do* refocus the
  *   trigger, since those are dismissals with nowhere else for focus to go.
  *
+ * `show(focus?)` and `hide(options?)` are the public imperative pair, for the cases the trigger
+ * can't express: a slotted "Apply"/"Done" button inside the menu, a keyboard shortcut, a parent
+ * restoring UI state. `hide({ focusTrigger: true })` is the one that also returns DOM focus to the
+ * trigger — use it whenever the interaction that closed the menu hasn't already put focus
+ * somewhere the user chose. Writing `open` directly still works and is fully equivalent apart from
+ * the focus moves: the roving-tabindex reset is centralized in `updated()`, so `el.open = false`
+ * never leaves a stale `tabindex="0"` tab stop on the last active item.
+ *
  * 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
@@ -84,7 +103,16 @@ export interface LyraMenuEventMap {
  * `internal/positioner.js`'s `place()`.
  * @slot - `<lr-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).
+ * role, matching what `role="menu"` expects between item groups). Arbitrary
+ * non-item content still renders here for backward compatibility, but the
+ * `header`/`footer` slots below are the supported place for it.
+ * @slot header - Composed content rendered above the items and *outside* the
+ * `role="menu"` list — a filter/search field, a section title, a summary row.
+ * Keeps its own full default keyboard behavior, is reachable with Tab from
+ * the items, and is ARIA-valid (arbitrary content inside `role="menu"` is
+ * not). Collapses to no box at all while unfilled.
+ * @slot footer - Same as `header`, rendered below the items — an
+ * "Apply"/"Done" button, a link to a fuller settings page, a count.
  * @event lr-show - The menu opened. Not fired for markup that renders
  * `open` true from the start (mirrors `<lr-select>`'s identical guard).
  * @event lr-hide - The menu closed. Same first-render guard as `lr-show`.
@@ -95,7 +123,11 @@ export interface LyraMenuEventMap {
  * 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 header - The wrapper around the `header` slot, above the list and
+ * outside `role="menu"`. `display: none` while the slot is unfilled.
  * @csspart list - The `role="menu"` container wrapping the default slot.
+ * @csspart footer - The wrapper around the `footer` slot, below the list and
+ * outside `role="menu"`. `display: none` while the slot is unfilled.
  */
 export declare class LyraMenu extends LyraElement<LyraMenuEventMap> {
     static styles: import("lit").CSSResultGroup[];
@@ -117,13 +149,17 @@ export declare class LyraMenu extends LyraElement<LyraMenuEventMap> {
      *  precedence (see `effectiveLabel`). */
     label: string;
     /** Extends the Escape-closes-and-refocuses-trigger behavior to keydown
-     *  events originating from slotted non-item content within `[part="list"]`
-     *  (e.g. a date input or a custom section slotted alongside
-     *  `<lr-menu-item>`s), not just from a real `<lr-menu-item>`. Default
-     *  `false` leaves Escape from slotted non-item content with full default
-     *  keyboard behavior, matching every existing consumer. Arrow/Home/End/
-     *  Enter/Space stay scoped to real `<lr-menu-item>` targets regardless of
-     *  this property — only Escape is affected. */
+     *  events originating from non-item content slotted into the **default**
+     *  slot, i.e. rendered within `[part="list"]` alongside the
+     *  `<lr-menu-item>`s. Default `false` leaves Escape from such content with
+     *  full default keyboard behavior, matching every existing consumer.
+     *  Arrow/Home/End/Enter/Space stay scoped to real `<lr-menu-item>` targets
+     *  regardless of this property — only Escape is affected.
+     *
+     *  It has no bearing on the `header`/`footer` slots, which sit outside
+     *  `[part="list"]` and always close on Escape. Prefer those for composed
+     *  controls: they are keyboard-reachable and ARIA-valid, whereas arbitrary
+     *  content inside `role="menu"` is an `aria-required-children` violation. */
     closeOnEscapeAnywhere: boolean;
     private items;
     private activeIndex;
@@ -135,15 +171,48 @@ export declare class LyraMenu extends LyraElement<LyraMenuEventMap> {
     private readonly listId;
     private typeAheadBuffer;
     private typeAheadTimer?;
-    protected willUpdate(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(): void;
+    private onRegionSlotChange;
+    /**
+     * Reflects "is this slot filled?" onto the host so the stylesheet can collapse an unfilled
+     * header/footer wrapper to no box at all, and can skip the divider border next to an empty
+     * list. `:empty` cannot do this job: Chromium's `:empty` does not ignore the whitespace-only
+     * text nodes Lit leaves inside a part, so a `[part='header']:empty` rule never matches.
+     *
+     * The polarity is deliberate -- `data-has-header`/`data-has-footer` are *absent* for a menu
+     * with neither slot filled, and `data-list-empty` is absent for a menu that has items, so the
+     * overwhelmingly common shape gains no host attribute of any kind.
+     */
+    private syncRegionState;
     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;
+    /**
+     * Opens the menu, moving roving focus to the first (or, with `'last'`, the last) non-disabled
+     * item. A no-op when already open. Public so a consumer can open the menu from something other
+     * than the `trigger`-slotted element -- a keyboard shortcut, a context-menu gesture, a parent
+     * component restoring UI state -- without reproducing `pendingFocus`'s bookkeeping by hand.
+     * Deliberately thin: `updated()` remains the single owner of positioning, the outside-click
+     * listener, the `lr-show`/`lr-hide` events, and the initial focus move, so `el.open = true`
+     * behaves identically apart from the focus target.
+     */
+    show(focus?: 'first' | 'last'): void;
+    /**
+     * Closes the menu. A no-op when already closed.
+     *
+     * `options.focusTrigger` returns DOM focus to the `trigger`-slotted element, synchronously. Pass
+     * it for a dismissal with nowhere else for focus to land -- a slotted "Apply"/"Done" button
+     * inside the menu, a keyboard shortcut, Escape-like handling of your own. Leave it unset when
+     * the interaction that closed the menu has already put focus somewhere the user chose (an
+     * outside click, a Tab out) -- see the class doc's interaction contract.
+     *
+     * Deliberately thin, and deliberately *not* the owner of the roving-tabindex reset: that lives
+     * in `updated()` so a bare `el.open = false` gets it too.
+     */
+    hide(options?: {
+        focusTrigger?: boolean;
+    }): void;
     private onDocPointer;
     private onTriggerClick;
     private onTriggerKeyDown;
@@ -177,6 +246,32 @@ export declare class LyraMenu extends LyraElement<LyraMenuEventMap> {
      *  there is already set to match before focus moves. */
     private onListFocusIn;
     private onListKeyDown;
+    private popupPart;
+    /**
+     * Whether a Tab/Shift+Tab keypress would move focus out of `[part='popup']` altogether, rather
+     * than to another focusable inside it. The popup's Tab sequence is
+     * `[header focusables, the list, footer focusables]`, and the list contributes exactly one stop
+     * -- the roving `tabindex="0"` item.
+     *
+     * Non-item content slotted into the *default* slot is deliberately not part of that sequence
+     * from an item's point of view: Tab from an `<lr-menu-item>` closes the menu exactly as it
+     * always has unless there is a real region to move into. Tab *from* such content is still
+     * measured against its default-slot neighbors, so a legacy two-control filter row keeps
+     * working -- only tabbing past the last of them now closes the menu, which is the dismissal
+     * hole this seals (previously the item-target gate swallowed the keypress entirely and focus
+     * walked out of the popup while the menu stayed open).
+     */
+    private tabWouldLeavePopup;
+    /**
+     * Bound to `[part='popup']` rather than `[part='list']` so it also sees keydowns from the
+     * `header`/`footer` regions, which sit outside the `role="menu"` list.
+     *
+     * Escape from those regions closes unconditionally, matching `<lr-popover>`'s own handling of
+     * arbitrary popup content. `closeOnEscapeAnywhere` keeps governing only the legacy case --
+     * non-item content still slotted into the *default* slot -- so Escape bubbling up from inside
+     * the list is left entirely to `onListKeyDown`.
+     */
+    private onPopupKeyDown;
     /** 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

package/dist/components/layout/menu/menu.class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menu.class.d.ts","sourceRoot":"","sources":["../../../../src/components/layout/menu/menu.class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAErE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAMhE,OAAO,sBAAsB,CAAC;AAE9B,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAClC,SAAS,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAClC,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;CACjD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,qBAAa,QAAS,SAAQ,WAAW,CAAC,gBAAgB,CAAC;IACzD,MAAM,CAAC,MAAM,iCAAgC;IAE7C,gCAAgC;IACY,IAAI,UAAS;IAEzD;;;;;OAKG;IAC0B,SAAS,CAAC,EAAE,SAAS,CAAC;IAEnD;;;;;;6CAMyC;IAC7B,KAAK,SAAU;IAE3B;;;;;;;mDAO+C;IACqB,qBAAqB,UAAS;IAQlG,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,WAAW,CAAM;IAEzB,OAAO,CAAC,SAAS,CAAC,CAAc;IAChC,OAAO,CAAC,OAAO,CAAC,CAAa;IAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAmB;IAC7C,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAK9C,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,cAAc,CAAC,CAAgC;IAEvD,SAAS,CAAC,UAAU,IAAI,IAAI,CAE3B;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAmC/C;IAED,OAAO,CAAC,UAAU;IAUlB,oBAAoB,IAAI,IAAI,CAc3B;IAED,OAAO,CAAC,IAAI;IAMZ;;qFAEiF;IACjF,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,YAAY,CAElB;IAEF,OAAO,CAAC,cAAc,CAEpB;IAEF,OAAO,CAAC,gBAAgB,CAsBtB;IAEF,OAAO,CAAC,mBAAmB,CAczB;IAEF;;iEAE6D;IAC7D,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB,CAmCvB;IAEF,OAAO,CAAC,WAAW;IAInB,uFAAuF;IACvF,OAAO,CAAC,iBAAiB,CAgBvB;IAEF,OAAO,CAAC,YAAY,CAKlB;IAEF;;iEAE6D;IAC7D,OAAO,CAAC,mBAAmB;IAM3B;;2EAEuE;IACvE,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,aAAa;IAMrB;;;;;;;;4DAQwD;IACxD,OAAO,CAAC,aAAa,CAOnB;IAEF,OAAO,CAAC,aAAa,CAyDnB;IAEF;;;mEAG+D;IAC/D,OAAO,CAAC,SAAS;IAqBjB;;;;8CAI0C;IAC1C,OAAO,KAAK,cAAc,GAEzB;IAED,MAAM,IAAI,cAAc,CAoBvB;CACF;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,QAAQ,CAAC;KACrB;CACF"}
+{"version":3,"file":"menu.class.d.ts","sourceRoot":"","sources":["../../../../src/components/layout/menu/menu.class.ts"],"names":[],"mappings":"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"}

package/dist/components/layout/menu/menu.class.js

@@ -10,6 +10,7 @@ import { LyraElement } from '../../../internal/lyra-element.js';
 import { place } from '../../../internal/positioner.js';
 import { rtlAwarePlacement } from '../../../internal/rtl.js';
 import { nextId } from '../../../internal/a11y.js';
+import { collectFocusableElements, deepActiveElement } from '../../../internal/overlay-manager.js';
 import { styles } from './menu.styles.js';
 import { LyraMenuItem } from './menu-item.class.js';
 import './menu-item.class.js';
@@ -48,16 +49,27 @@ import './menu-item.class.js';
  *   items (wrapping past either end — the recommended, and more common,
  *   menu-widget behavior, unlike `<lr-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
- *   `<lr-select>`'s identical listbox type-ahead). All of the above (except
- *   Escape) only respond to keydowns from a real `<lr-menu-item>` target,
- *   so a slotted non-item control (e.g. a date input) keeps its own full
- *   default keyboard behavior. Escape from such a slotted control closes the
- *   menu too, but only when `closeOnEscapeAnywhere` is set — it defaults to
+ *   the focused item. Escape closes and returns focus to the trigger. 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 `<lr-select>`'s identical
+ *   listbox type-ahead). All of the above (except Escape and Tab) only
+ *   respond to keydowns from a real `<lr-menu-item>` target, so a slotted
+ *   non-item control (e.g. a date input) keeps its own full default keyboard
+ *   behavior.
+ * - Tab never traps focus and never calls `preventDefault()` — the browser's
+ *   own Tab navigation always proceeds untouched. It closes the menu only
+ *   when focus is on its way *out* of the popup: with a focusable in the
+ *   `header`/`footer` region on the far side of the keypress, the menu stays
+ *   open so native Tab can carry focus there instead. With neither region
+ *   filled, Tab closes exactly as it always has. Tabbing past the popup's
+ *   last focusable in either direction closes it too, including from slotted
+ *   non-item content — which previously left the menu open while focus
+ *   walked away.
+ * - Escape from `header`/`footer` content closes the menu and refocuses the
+ *   trigger unconditionally, mirroring `<lr-popover>`'s handling of arbitrary
+ *   popup content. `closeOnEscapeAnywhere` governs only the *legacy* shape —
+ *   non-item content slotted into the **default** slot — and defaults to
  *   `false`, so existing consumers keep today's behavior unchanged.
  * - A click outside both the trigger and the open popup closes it (mirrors
  *   `<lr-select>`'s `onDocPointer` exactly) — this does *not* refocus the
@@ -65,6 +77,14 @@ import './menu-item.class.js';
  *   the user chose; Escape and a committed selection *do* refocus the
  *   trigger, since those are dismissals with nowhere else for focus to go.
  *
+ * `show(focus?)` and `hide(options?)` are the public imperative pair, for the cases the trigger
+ * can't express: a slotted "Apply"/"Done" button inside the menu, a keyboard shortcut, a parent
+ * restoring UI state. `hide({ focusTrigger: true })` is the one that also returns DOM focus to the
+ * trigger — use it whenever the interaction that closed the menu hasn't already put focus
+ * somewhere the user chose. Writing `open` directly still works and is fully equivalent apart from
+ * the focus moves: the roving-tabindex reset is centralized in `updated()`, so `el.open = false`
+ * never leaves a stale `tabindex="0"` tab stop on the last active item.
+ *
  * 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
@@ -87,7 +107,16 @@ import './menu-item.class.js';
  * `internal/positioner.js`'s `place()`.
  * @slot - `<lr-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).
+ * role, matching what `role="menu"` expects between item groups). Arbitrary
+ * non-item content still renders here for backward compatibility, but the
+ * `header`/`footer` slots below are the supported place for it.
+ * @slot header - Composed content rendered above the items and *outside* the
+ * `role="menu"` list — a filter/search field, a section title, a summary row.
+ * Keeps its own full default keyboard behavior, is reachable with Tab from
+ * the items, and is ARIA-valid (arbitrary content inside `role="menu"` is
+ * not). Collapses to no box at all while unfilled.
+ * @slot footer - Same as `header`, rendered below the items — an
+ * "Apply"/"Done" button, a link to a fuller settings page, a count.
  * @event lr-show - The menu opened. Not fired for markup that renders
  * `open` true from the start (mirrors `<lr-select>`'s identical guard).
  * @event lr-hide - The menu closed. Same first-render guard as `lr-show`.
@@ -98,7 +127,11 @@ import './menu-item.class.js';
  * 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 header - The wrapper around the `header` slot, above the list and
+ * outside `role="menu"`. `display: none` while the slot is unfilled.
  * @csspart list - The `role="menu"` container wrapping the default slot.
+ * @csspart footer - The wrapper around the `footer` slot, below the list and
+ * outside `role="menu"`. `display: none` while the slot is unfilled.
  */
 export class LyraMenu extends LyraElement {
     constructor() {
@@ -114,13 +147,17 @@ export class LyraMenu extends LyraElement {
          *  precedence (see `effectiveLabel`). */
         this.label = 'Menu';
         /** Extends the Escape-closes-and-refocuses-trigger behavior to keydown
-         *  events originating from slotted non-item content within `[part="list"]`
-         *  (e.g. a date input or a custom section slotted alongside
-         *  `<lr-menu-item>`s), not just from a real `<lr-menu-item>`. Default
-         *  `false` leaves Escape from slotted non-item content with full default
-         *  keyboard behavior, matching every existing consumer. Arrow/Home/End/
-         *  Enter/Space stay scoped to real `<lr-menu-item>` targets regardless of
-         *  this property — only Escape is affected. */
+         *  events originating from non-item content slotted into the **default**
+         *  slot, i.e. rendered within `[part="list"]` alongside the
+         *  `<lr-menu-item>`s. Default `false` leaves Escape from such content with
+         *  full default keyboard behavior, matching every existing consumer.
+         *  Arrow/Home/End/Enter/Space stay scoped to real `<lr-menu-item>` targets
+         *  regardless of this property — only Escape is affected.
+         *
+         *  It has no bearing on the `header`/`footer` slots, which sit outside
+         *  `[part="list"]` and always close on Escape. Prefer those for composed
+         *  controls: they are keyboard-reachable and ARIA-valid, whereas arbitrary
+         *  content inside `role="menu"` is an `aria-required-children` violation. */
         this.closeOnEscapeAnywhere = false;
         // Plain instance fields, not @state() -- render()'s template never reads
         // either (items render via the plain default <slot>; there is no
@@ -138,6 +175,9 @@ export class LyraMenu extends LyraElement {
         // after the last one, so "d" then "e" narrows to "de" instead of
         // restarting the search on every keystroke.
         this.typeAheadBuffer = '';
+        this.onRegionSlotChange = () => {
+            this.syncRegionState();
+        };
         this.onDocPointer = (e) => {
             if (!e.composedPath().includes(this))
                 this.hide();
@@ -151,7 +191,7 @@ export class LyraMenu extends LyraElement {
             // own Escape handling would otherwise never run.
             if (e.key === 'Escape' && this.open) {
                 e.preventDefault();
-                this.hide(true);
+                this.hide({ focusTrigger: true });
                 return;
             }
             if (this.open)
@@ -207,6 +247,7 @@ export class LyraMenu extends LyraElement {
             }
             this.activeIndex = previouslyActive ? this.items.indexOf(previouslyActive) : -1;
             this.applyRovingTabIndex();
+            this.syncRegionState();
             if (this.open) {
                 if (this.activeIndex === -1) {
                     // Nothing left to preserve: the active item is gone, or nothing had
@@ -246,7 +287,7 @@ export class LyraMenu extends LyraElement {
             if (!(item instanceof LyraMenuItem))
                 return;
             this.emit('lr-menu-select', { value: item.value });
-            this.hide(true);
+            this.hide({ focusTrigger: true });
         };
         /** Resyncs `activeIndex` (and the roving `tabindex`) to wherever real DOM
          *  focus actually lands, for any path that doesn't go through
@@ -276,7 +317,7 @@ export class LyraMenu extends LyraElement {
             // instanceof guard below exists to prevent).
             if (e.key === 'Escape' && (isItemTarget || this.closeOnEscapeAnywhere)) {
                 e.preventDefault();
-                this.hide(true);
+                this.hide({ focusTrigger: true });
                 return;
             }
             if (!isItemTarget)
@@ -315,11 +356,10 @@ export class LyraMenu extends LyraElement {
                     e.preventDefault();
                     current?.select();
                     break;
-                case 'Tab':
-                    // No preventDefault -- the browser's own default Tab navigation is
-                    // left to proceed untouched, only the (now-stale) open menu closes.
-                    this.hide();
-                    break;
+                // Tab is deliberately absent here: it is owned by onPopupKeyDown below,
+                // which sees keydowns from the header/footer regions too and so can tell
+                // "Tab moves within the popup" apart from "Tab leaves the popup". 'Tab'
+                // is longer than one character, so the type-ahead default arm ignores it.
                 default:
                     if (e.key.length === 1 && !e.altKey && !e.ctrlKey && !e.metaKey) {
                         this.typeAhead(e.key);
@@ -327,12 +367,61 @@ export class LyraMenu extends LyraElement {
                     return;
             }
         };
+        /**
+         * Bound to `[part='popup']` rather than `[part='list']` so it also sees keydowns from the
+         * `header`/`footer` regions, which sit outside the `role="menu"` list.
+         *
+         * Escape from those regions closes unconditionally, matching `<lr-popover>`'s own handling of
+         * arbitrary popup content. `closeOnEscapeAnywhere` keeps governing only the legacy case --
+         * non-item content still slotted into the *default* slot -- so Escape bubbling up from inside
+         * the list is left entirely to `onListKeyDown`.
+         */
+        this.onPopupKeyDown = (e) => {
+            const listEl = this.popupPart('list');
+            if (e.key === 'Escape') {
+                if (listEl && e.composedPath().includes(listEl))
+                    return;
+                e.preventDefault();
+                this.hide({ focusTrigger: true });
+                return;
+            }
+            // No preventDefault for Tab, in either branch -- the browser's own default
+            // navigation is left to proceed untouched, only the (now-stale) open menu
+            // closes, and only when Tab is actually leaving the popup.
+            if (e.key === 'Tab' && this.tabWouldLeavePopup(e))
+                this.hide();
+        };
     }
     static { this.styles = [LyraElement.styles, styles]; }
-    willUpdate() {
+    willUpdate(changed) {
+        super.willUpdate(changed);
         this._isFirstUpdate = !this.hasUpdated;
     }
+    firstUpdated() {
+        // `slotchange` only fires when a slot's assigned nodes actually *change*,
+        // so a slot that starts (and stays) empty never fires one at all. The
+        // header/footer wrappers and the divider borders are driven off these
+        // attributes, so seed them once from the real slots after the first render.
+        this.syncRegionState();
+    }
+    /**
+     * Reflects "is this slot filled?" onto the host so the stylesheet can collapse an unfilled
+     * header/footer wrapper to no box at all, and can skip the divider border next to an empty
+     * list. `:empty` cannot do this job: Chromium's `:empty` does not ignore the whitespace-only
+     * text nodes Lit leaves inside a part, so a `[part='header']:empty` rule never matches.
+     *
+     * The polarity is deliberate -- `data-has-header`/`data-has-footer` are *absent* for a menu
+     * with neither slot filled, and `data-list-empty` is absent for a menu that has items, so the
+     * overwhelmingly common shape gains no host attribute of any kind.
+     */
+    syncRegionState() {
+        const assigned = (selector) => this.renderRoot.querySelector(selector)?.assignedElements({ flatten: true }).length ?? 0;
+        this.toggleAttribute('data-has-header', assigned('slot[name="header"]') > 0);
+        this.toggleAttribute('data-has-footer', assigned('slot[name="footer"]') > 0);
+        this.toggleAttribute('data-list-empty', assigned('slot:not([name])') === 0);
+    }
     updated(changed) {
+        super.updated(changed);
         if (changed.has('open')) {
             this.cleanup?.();
             this.cleanup = undefined;
@@ -358,6 +447,15 @@ export class LyraMenu extends LyraElement {
             }
             else {
                 document.removeEventListener('pointerdown', this.onDocPointer);
+                // The roving state is reset here, not in hide(), for the same reason every other
+                // open-driven side effect lives here: `open` can become false through hide(), through a
+                // consumer writing `el.open = false` directly, or through disconnectedCallback()'s
+                // teardown reset -- and a closed menu must never leave a stale `tabindex="0"` tab stop on
+                // whichever item happened to be active. Focus restoration deliberately stays in hide()
+                // (see its doc): it is a user-intent-driven dismissal, and routing it through here would
+                // also fire it on the disconnectedCallback() path, stealing focus during teardown.
+                this.activeIndex = -1;
+                this.applyRovingTabIndex();
                 if (!this._isFirstUpdate)
                     this.emit('lr-hide');
             }
@@ -396,22 +494,38 @@ export class LyraMenu extends LyraElement {
         // no outside-click listener.
         this.open = false;
     }
+    /**
+     * Opens the menu, moving roving focus to the first (or, with `'last'`, the last) non-disabled
+     * item. A no-op when already open. Public so a consumer can open the menu from something other
+     * than the `trigger`-slotted element -- a keyboard shortcut, a context-menu gesture, a parent
+     * component restoring UI state -- without reproducing `pendingFocus`'s bookkeeping by hand.
+     * Deliberately thin: `updated()` remains the single owner of positioning, the outside-click
+     * listener, the `lr-show`/`lr-hide` events, and the initial focus move, so `el.open = true`
+     * behaves identically apart from the focus target.
+     */
     show(focus = 'first') {
         if (this.open)
             return;
         this.pendingFocus = focus;
         this.open = true;
     }
-    /** `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. */
-    hide(refocusTrigger = false) {
+    /**
+     * Closes the menu. A no-op when already closed.
+     *
+     * `options.focusTrigger` returns DOM focus to the `trigger`-slotted element, synchronously. Pass
+     * it for a dismissal with nowhere else for focus to land -- a slotted "Apply"/"Done" button
+     * inside the menu, a keyboard shortcut, Escape-like handling of your own. Leave it unset when
+     * the interaction that closed the menu has already put focus somewhere the user chose (an
+     * outside click, a Tab out) -- see the class doc's interaction contract.
+     *
+     * Deliberately thin, and deliberately *not* the owner of the roving-tabindex reset: that lives
+     * in `updated()` so a bare `el.open = false` gets it too.
+     */
+    hide(options) {
         if (!this.open)
             return;
         this.open = false;
-        this.activeIndex = -1;
-        this.applyRovingTabIndex();
-        if (refocusTrigger)
+        if (options?.focusTrigger)
             this.triggerEl?.focus();
     }
     /** `aria-haspopup`/`aria-expanded`/`aria-controls` belong on the actual
@@ -450,6 +564,53 @@ export class LyraMenu extends LyraElement {
         this.applyRovingTabIndex();
         item.focus();
     }
+    popupPart(name) {
+        return this.renderRoot.querySelector(`[part="${name}"]`);
+    }
+    /**
+     * Whether a Tab/Shift+Tab keypress would move focus out of `[part='popup']` altogether, rather
+     * than to another focusable inside it. The popup's Tab sequence is
+     * `[header focusables, the list, footer focusables]`, and the list contributes exactly one stop
+     * -- the roving `tabindex="0"` item.
+     *
+     * Non-item content slotted into the *default* slot is deliberately not part of that sequence
+     * from an item's point of view: Tab from an `<lr-menu-item>` closes the menu exactly as it
+     * always has unless there is a real region to move into. Tab *from* such content is still
+     * measured against its default-slot neighbors, so a legacy two-control filter row keeps
+     * working -- only tabbing past the last of them now closes the menu, which is the dismissal
+     * hole this seals (previously the item-target gate swallowed the keypress entirely and focus
+     * walked out of the popup while the menu stayed open).
+     */
+    tabWouldLeavePopup(e) {
+        const header = this.popupPart('header');
+        const footer = this.popupPart('footer');
+        const listEl = this.popupPart('list');
+        const backwards = e.shiftKey;
+        const active = deepActiveElement(this.ownerDocument);
+        const headerStops = header ? collectFocusableElements(header) : [];
+        const footerStops = footer ? collectFocusableElements(footer) : [];
+        const listStops = listEl ? collectFocusableElements(listEl) : [];
+        const hasNeighbor = (stops) => {
+            const index = active ? stops.indexOf(active) : -1;
+            if (index === -1)
+                return false;
+            return backwards ? index > 0 : index < stops.length - 1;
+        };
+        const path = e.composedPath();
+        if (footer && path.includes(footer)) {
+            if (hasNeighbor(footerStops))
+                return false;
+            return backwards ? listStops.length === 0 && headerStops.length === 0 : true;
+        }
+        if (header && path.includes(header)) {
+            if (hasNeighbor(headerStops))
+                return false;
+            return backwards ? true : listStops.length === 0 && footerStops.length === 0;
+        }
+        if (!(e.target instanceof LyraMenuItem) && hasNeighbor(listStops))
+            return false;
+        return backwards ? headerStops.length === 0 : footerStops.length === 0;
+    }
     /** 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
@@ -487,7 +648,10 @@ export class LyraMenu extends LyraElement {
       <div part="trigger" @click=${this.onTriggerClick} @keydown=${this.onTriggerKeyDown}>
         <slot name="trigger" @slotchange=${this.onTriggerSlotChange}></slot>
       </div>
-      <div part="popup">
+      <div part="popup" @keydown=${this.onPopupKeyDown}>
+        <div part="header">
+          <slot name="header" @slotchange=${this.onRegionSlotChange}></slot>
+        </div>
         <div
           part="list"
           id=${this.listId}
@@ -500,6 +664,9 @@ export class LyraMenu extends LyraElement {
         >
           <slot @slotchange=${this.onItemsSlotChange}></slot>
         </div>
+        <div part="footer">
+          <slot name="footer" @slotchange=${this.onRegionSlotChange}></slot>
+        </div>
       </div>
     `;
     }