ngwr 11.2.0 → 12.1.0

package/fesm2022/ngwr-context-menu.mjs

@@ -9,6 +9,71 @@ import { Directionality } from '@angular/cdk/bidi';
 import { coerceBooleanProperty } from '@angular/cdk/coercion';
 import { WrIcon } from 'ngwr/icon';
 
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/**
+ * Roving focus inside ONE context-menu pane.
+ *
+ * The APG menu pattern makes a menu a single tab stop and moves a focus cursor
+ * between its rows with the arrows — which is why every `<wr-context-menu-item>`
+ * carries `tabindex="-1"`. Shared by the root directive and by
+ * `WrContextMenuItem`'s submenu because a submenu is a SEPARATE overlay pane
+ * rather than nested DOM: each pane roves over its own rows, and CDK's keyboard
+ * dispatcher hands the key to the topmost one, which is the pane the user is in.
+ *
+ * @internal
+ */
+/**
+ * The rows of one pane the cursor may land on. Disabled rows are not stops —
+ * the same rule `WrDropdown` follows.
+ */
+function wrMenuItems(pane) {
+    return Array.from(pane.querySelectorAll('.wr-context-menu-item:not(.wr-context-menu-item--disabled)'));
+}
+/** Focus the row at `index`, wrapping at both ends. A pane with no rows is left alone. */
+function wrFocusMenuItemAt(pane, index) {
+    const items = wrMenuItems(pane);
+    if (items.length === 0)
+        return;
+    const clamped = ((index % items.length) + items.length) % items.length;
+    items[clamped]?.focus();
+}
+/**
+ * ArrowDown / ArrowUp / Home / End over one pane's rows. Returns `true` when the
+ * key was consumed, so a caller can leave every other key alone.
+ */
+function wrHandleMenuNavigation(pane, event) {
+    const items = wrMenuItems(pane);
+    if (items.length === 0)
+        return false;
+    const active = document.activeElement;
+    // -1 when the keyboard is not on a row yet, which makes ArrowDown open at the
+    // first row and ArrowUp at the last.
+    const index = active instanceof HTMLElement ? items.indexOf(active) : -1;
+    switch (event.key) {
+        case 'ArrowDown':
+            wrFocusMenuItemAt(pane, index + 1);
+            break;
+        case 'ArrowUp':
+            wrFocusMenuItemAt(pane, index <= 0 ? items.length - 1 : index - 1);
+            break;
+        case 'Home':
+            wrFocusMenuItemAt(pane, 0);
+            break;
+        case 'End':
+            wrFocusMenuItemAt(pane, items.length - 1);
+            break;
+        default:
+            return false;
+    }
+    event.preventDefault();
+    return true;
+}
+
 /**
  * @license
  *
@@ -67,9 +132,17 @@ class WrContextMenuItem {
     scrollStrategies = inject(ScrollStrategyOptions);
     destroyRef = inject(DestroyRef);
     submenuRef = null;
+    submenuKeys = null;
     openTimer = null;
     closeTimer = null;
     submenuOpen = false;
+    /**
+     * Whether the pending open was asked for by the keyboard (→ / Enter / Space)
+     * rather than by hover — only then does the submenu take focus, the same rule
+     * `wr-dropdown` applies to its own open. Sweeping the cursor across a row must
+     * show its submenu without yanking the caret out of it.
+     */
+    openedByKeyboard = false;
     /**
      * Id of the submenu's menu element while it is open, published on the item as
      * `aria-controls` — the same contract the root trigger keeps (see
@@ -128,6 +201,7 @@ class WrContextMenuItem {
             return;
         if (this.submenu()) {
             event.preventDefault();
+            this.openedByKeyboard = true;
             this.scheduleOpen(0);
             return;
         }
@@ -155,6 +229,7 @@ class WrContextMenuItem {
         if (this.disabled() || !this.submenu())
             return;
         event.preventDefault();
+        this.openedByKeyboard = true;
         this.scheduleOpen(0);
     }
     closeFromKey(event) {
@@ -168,6 +243,7 @@ class WrContextMenuItem {
         if (this.disabled() || !this.submenu())
             return;
         this.cancelClose();
+        this.openedByKeyboard = false;
         this.scheduleOpen(SUBMENU_OPEN_DELAY);
     }
     /** @internal Hover-out schedules a close with a grace window. */
@@ -257,9 +333,60 @@ class WrContextMenuItem {
         // when the cursor crosses the gap between item and submenu pane.
         pane.addEventListener('mouseenter', this.onSubmenuEnter);
         pane.addEventListener('mouseleave', this.onSubmenuLeave);
+        // While this pane is open it is the newest overlay that listens, so CDK's
+        // keyboard dispatcher hands it every keydown and the root menu's own handler
+        // stops seeing them. Which pane the keys then act on is decided in
+        // `onSubmenuKeydown`, not here: a hover open leaves the caret where it was.
+        this.submenuKeys = this.submenuRef.keydownEvents().subscribe(event => this.onSubmenuKeydown(event));
+        // A keyboard open walks INTO the submenu; a hover open only shows it.
+        if (this.openedByKeyboard)
+            wrFocusMenuItemAt(pane, 0);
         this.submenuOpen = true;
         WrContextMenuItem.openSubmenus.set(this.host.nativeElement, this);
     }
+    /**
+     * @internal Keys routed here while this submenu is the topmost overlay: the
+     * arrows walk the rows of the pane the caret is in, and Escape or the arrow
+     * pointing BACK the way the menu cascades steps out one level, returning the
+     * cursor to the row that owns the pane when the cursor was inside it.
+     *
+     * Escape closes this level only, not the whole chain — the APG's rule for a
+     * submenu. It reaches this handler rather than the root's because the
+     * dispatcher stops at the topmost overlay that listens, which is now this one.
+     *
+     * Which is also why the arrows are aimed at the pane holding the caret rather
+     * than at this one. The dispatcher routes by stacking order, not by focus, and
+     * a HOVER-opened submenu is topmost while focus is deliberately still on the
+     * root row the pointer swept off (see `openedByKeyboard`) — so ArrowDown used
+     * to jump into this pane's first row instead of moving down the menu the user
+     * is in. Same reason `wr-dropdown`'s menu handler checks ownership.
+     */
+    onSubmenuKeydown(event) {
+        const pane = this.submenuRef?.overlayElement;
+        if (!pane)
+            return;
+        // A row inside the pane already acted on this key — its own → into a deeper
+        // submenu, or Enter on a leaf. Re-handling it here would close the pane out
+        // from under the level it just opened.
+        if (event.defaultPrevented)
+            return;
+        const active = document.activeElement;
+        const focusedPane = active instanceof Element ? active.closest('.wr-context-menu-overlay') : null;
+        const back = this.isRtl() ? 'ArrowRight' : 'ArrowLeft';
+        if (event.key === 'Escape' || event.key === back) {
+            event.preventDefault();
+            this.disposeSubmenu(false);
+            // Onto the owning row only when the caret was in the pane just closed:
+            // dismissing a submenu the pointer opened must not drag it off the row the
+            // keyboard user is on.
+            if (focusedPane === pane)
+                this.host.nativeElement.focus();
+            return;
+        }
+        // Falls back to this pane when the caret is outside every menu — nothing
+        // else can answer, and the navigation opens at the first row from there.
+        wrHandleMenuNavigation(focusedPane ?? pane, event);
+    }
     /** Bound handlers (= preserves identity for removeEventListener). */
     onSubmenuEnter = () => {
         this.cancelClose();
@@ -336,6 +463,12 @@ class WrContextMenuItem {
         this.submenuRef = null;
         this.submenuOpen = false;
         this.submenuId.set(null);
+        // Now, not when the ref is finally disposed 220ms later: an overlay with a
+        // keydown subscriber is where CDK's dispatcher STOPS looking, so a pane
+        // still listening on its way out would swallow the arrows for the whole
+        // exit animation and the root menu would go dead for a quarter of a second.
+        this.submenuKeys?.unsubscribe();
+        this.submenuKeys = null;
         WrContextMenuItem.openSubmenus.delete(this.host.nativeElement);
         const pane = ref.overlayElement;
         pane.removeEventListener('mouseenter', this.onSubmenuEnter);
@@ -366,10 +499,10 @@ class WrContextMenuItem {
     isRtl() {
         return this.dir?.value === 'rtl';
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenuItem, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.1", type: WrContextMenuItem, isStandalone: true, selector: "wr-context-menu-item", inputs: { icon: { classPropertyName: "icon", publicName: "icon", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, submenu: { classPropertyName: "submenu", publicName: "submenu", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "role": "menuitem" }, listeners: { "mouseenter": "onMouseEnter()", "mouseleave": "onMouseLeave($event)", "click": "onClick()", "keydown.enter": "activate($event)", "keydown.space": "activate($event)", "keydown.arrowRight": "onArrowRight($event)", "keydown.arrowLeft": "onArrowLeft($event)" }, properties: { "class": "classes()", "attr.tabindex": "-1", "attr.aria-disabled": "disabled() ? true : null", "attr.aria-haspopup": "submenu() ? \"menu\" : null", "attr.aria-expanded": "submenu() ? (submenuOpen ? \"true\" : \"false\") : null", "attr.aria-controls": "submenuId()" } }, ngImport: i0, template: "@if (icon(); as name) {\n  <wr-icon class=\"wr-context-menu-item__icon\" [name]=\"name\" size=\"14\" />\n}\n<span class=\"wr-context-menu-item__label\"><ng-content /></span>\n@if (submenu()) {\n  <svg\n    class=\"wr-icon__svg wr-context-menu-item__chevron\"\n    xmlns=\"http://www.w3.org/2000/svg\"\n    viewBox=\"0 0 24 24\"\n    fill=\"none\"\n    stroke=\"currentColor\"\n    stroke-width=\"2\"\n    stroke-linecap=\"round\"\n    stroke-linejoin=\"round\"\n    aria-hidden=\"true\"\n  >\n    <path d=\"m9 18 6-6-6-6\" />\n  </svg>\n}\n", dependencies: [{ kind: "component", type: WrIcon, selector: "wr-icon", inputs: ["name"] }], encapsulation: i0.ViewEncapsulation.None });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenuItem, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.4", type: WrContextMenuItem, isStandalone: true, selector: "wr-context-menu-item", inputs: { icon: { classPropertyName: "icon", publicName: "icon", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, submenu: { classPropertyName: "submenu", publicName: "submenu", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "role": "menuitem" }, listeners: { "mouseenter": "onMouseEnter()", "mouseleave": "onMouseLeave($event)", "click": "onClick()", "keydown.enter": "activate($event)", "keydown.space": "activate($event)", "keydown.arrowRight": "onArrowRight($event)", "keydown.arrowLeft": "onArrowLeft($event)" }, properties: { "class": "classes()", "attr.tabindex": "-1", "attr.aria-disabled": "disabled() ? true : null", "attr.aria-haspopup": "submenu() ? \"menu\" : null", "attr.aria-expanded": "submenu() ? (submenuOpen ? \"true\" : \"false\") : null", "attr.aria-controls": "submenuId()" } }, ngImport: i0, template: "@if (icon(); as name) {\n  <wr-icon class=\"wr-context-menu-item__icon\" [name]=\"name\" size=\"14\" />\n}\n<span class=\"wr-context-menu-item__label\"><ng-content /></span>\n@if (submenu()) {\n  <svg\n    class=\"wr-icon__svg wr-context-menu-item__chevron\"\n    xmlns=\"http://www.w3.org/2000/svg\"\n    viewBox=\"0 0 24 24\"\n    fill=\"none\"\n    stroke=\"currentColor\"\n    stroke-width=\"2\"\n    stroke-linecap=\"round\"\n    stroke-linejoin=\"round\"\n    aria-hidden=\"true\"\n  >\n    <path d=\"m9 18 6-6-6-6\" />\n  </svg>\n}\n", dependencies: [{ kind: "component", type: WrIcon, selector: "wr-icon", inputs: ["name"] }], encapsulation: i0.ViewEncapsulation.None });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenuItem, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenuItem, decorators: [{
             type: Component,
             args: [{ selector: 'wr-context-menu-item', encapsulation: ViewEncapsulation.None, host: {
                         role: 'menuitem',
@@ -395,6 +528,45 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImpor
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
  */
+/**
+ * Where the menu may hang off the pointer, best first: down-and-inline-start of
+ * the cursor (what a native context menu does), then flipped up, then across,
+ * then both.
+ *
+ * The origin is a zero-size POINT, so every `originX` / `originY` resolves to
+ * the same coordinate and only the overlay's own corner varies. `overlayX:
+ * 'start'` is the logical corner: CDK resolves it against the ambient reading
+ * direction, so an RTL page opens the menu to the LEFT of the cursor without a
+ * second table.
+ */
+const POINTER_POSITIONS = [
+    { originX: 'start', originY: 'top', overlayX: 'start', overlayY: 'top' },
+    { originX: 'start', originY: 'top', overlayX: 'start', overlayY: 'bottom' },
+    { originX: 'start', originY: 'top', overlayX: 'end', overlayY: 'top' },
+    { originX: 'start', originY: 'top', overlayX: 'end', overlayY: 'bottom' },
+];
+/**
+ * The pointer as a CDK origin: a zero-size rect at the click, in VIEWPORT
+ * coordinates.
+ *
+ * Live getters rather than a snapshot, and that is the whole trick. The menu is
+ * anchored to the DOCUMENT — as the page scrolls it travels with the content it
+ * was opened over (native + PrimeNG behaviour) — while CDK positions against
+ * the viewport. Reading the scroll offset at `apply()` time is what converts one
+ * into the other, so a re-anchor is nothing but a request to re-apply.
+ */
+function pointerOrigin(pageX, pageY) {
+    return {
+        width: 0,
+        height: 0,
+        get x() {
+            return pageX - window.scrollX;
+        },
+        get y() {
+            return pageY - window.scrollY;
+        },
+    };
+}
 /**
  * Attach to any element to show a `<wr-context-menu>` at the pointer
  * position when the user right-clicks or otherwise sends a `contextmenu`
@@ -440,6 +612,18 @@ class WrContextMenu {
     openMenuId = signal(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "openMenuId" }] : /* istanbul ignore next */ []));
     overlayRef = null;
+    /**
+     * The open menu's subscription to CDK's keyboard dispatcher, held so that
+     * `closeOverlay()` can drop it — see the unsubscribe there for why the pane's
+     * own disposal is 220 ms too late.
+     */
+    rootKeys = null;
+    /**
+     * Where the keyboard was at the moment this menu took it, so a close can put
+     * it back there. Null when it was nowhere in particular (`<body>`) or already
+     * inside a menu pane, neither of which is a place to return to.
+     */
+    restoreFocusTo = null;
     /**
      * Panes waiting out their exit animation, keyed by the timer that disposes
      * them.
@@ -590,37 +774,47 @@ class WrContextMenu {
     }
     // Overlay
     openOverlay(x, y) {
-        // GlobalPositionStrategy uses margins, which led to flaky positioning
-        // (`position: static` inline overridden by our `!important`, etc.).
-        // Use it just to create the overlay, then write the coords directly to
-        // the pane element via `top`/`left` so the menu sits exactly where the
-        // user clicked and never moves until we close it.
+        // Read before `wrFocusMenuItemAt` below takes the keyboard: this is the
+        // element the close hands it back to. A pane row is not a candidate — a
+        // previous menu may still be fading out — and neither is `<body>`, which is
+        // where focus already is when nobody has it.
+        const active = document.activeElement;
+        this.restoreFocusTo =
+            active instanceof HTMLElement && active !== document.body && !active.closest('.wr-context-menu-overlay')
+                ? active
+                : null;
+        // Anchored to the POINTER, which is not an element — CDK takes a virtual
+        // origin for exactly that, and a FLEXIBLE strategy is what makes the menu
+        // flip up (or across) instead of hanging off the edge of the screen. It used
+        // to be a bare `GlobalPositionStrategy` with the raw coordinates written
+        // onto the pane, which never measured the menu against the viewport: a
+        // right-click 6px above the bottom of the window put two of the three rows
+        // below the fold and clipped the third, since the pane is `position: fixed`
+        // and cannot be scrolled to. Submenus have used the flexible strategy from
+        // the start (`context-menu-item.ts`); only the root skipped it.
+        const positionStrategy = this.overlay
+            .position()
+            .flexibleConnectedTo(pointerOrigin(x, y))
+            // The menu sizes itself; the fallbacks below are the whole answer to a
+            // cramped viewport, and `withPush` clamps whatever is left over.
+            .withFlexibleDimensions(false)
+            .withPush(true)
+            .withPositions(POINTER_POSITIONS);
         this.overlayRef = this.overlay.create({
-            positionStrategy: this.overlay.position().global(),
-            // `noop` so scroll doesn't dismiss the menu. With absolute coords
-            // pinned to viewport (`position: fixed` in the panel CSS), the menu
-            // visually stays put as the page scrolls underneath.
+            positionStrategy,
+            // `noop` so scroll doesn't dismiss the menu — `sync()` below re-anchors it
+            // instead.
             scrollStrategy: this.scrollStrategies.noop(),
             panelClass: ['wr-context-menu-overlay'],
         });
         const portal = new TemplatePortal(this.menu().contentTpl(), this.vcr);
         this.overlayRef.attach(portal);
-        // Position model: the pane uses `position: fixed` (panel CSS) but we
-        // want the menu to anchor to the DOCUMENT — when the user scrolls,
-        // the menu should travel with the content it was opened over (native
-        // browser + PrimeNG behavior). Strategy:
-        //
-        //   - Record the page coords (pageX/pageY = document-relative).
-        //   - Each frame the user scrolls, set top/left to (pageX/Y minus the
-        //     current scroll offset). At scroll 0 this matches clientX/Y; as
-        //     scroll grows the menu shifts up/left visually, which is exactly
-        //     what `position: absolute` inside an un-fixed container would do
-        //     naturally — we just have to emulate it manually because CDK's
-        //     overlay container is `position: fixed`.
+        // `attach()` defers CDK's first placement into `afterNextRender`. Place it
+        // now: until then the pane sits at the container's top-left corner, and the
+        // rows are already in the DOM (see `wrFocusMenuItemAt` below), so the
+        // measurement the flip depends on is available.
+        this.overlayRef.updatePosition();
         const pane = this.overlayRef.overlayElement;
-        pane.style.right = 'auto';
-        pane.style.bottom = 'auto';
-        pane.style.margin = '0';
         // Name the menu we just opened so the host can point at it. The id is
         // minted per OPEN rather than living on the panel: `closeOverlay()` keeps
         // the previous pane in the DOM for its exit animation, so a re-open would
@@ -631,11 +825,31 @@ class WrContextMenu {
             menuEl.id = randomId('wr-context-menu');
             this.openMenuId.set(menuEl.id);
         }
-        const sync = () => {
-            pane.style.top = `${y - window.scrollY}px`;
-            pane.style.left = `${x - window.scrollX}px`;
-        };
-        sync();
+        // Re-anchor. `pointerOrigin` reads the scroll offset afresh, so this is all
+        // it takes for the menu to travel with the content it was opened over.
+        //
+        // `reapplyLastPosition()` rather than `updatePosition()`: the flip is
+        // decided once, when the menu opens. Re-running the fallback list on every
+        // scroll event would let the menu hop from above the cursor to below it and
+        // back while the page moves under it, which is a worse reading of "the menu
+        // stays where you put it" than a menu that simply slides with the page.
+        const sync = () => positionStrategy.reapplyLastPosition();
+        // Move the keyboard INTO the menu. Without this the pane painted a
+        // `role="menu"` that could be seen and never entered: rows are
+        // `tabindex="-1"` (the roving-focus contract) and the pane is not a tab
+        // stop, so ArrowDown / Enter / ArrowRight all went to whatever still held
+        // focus behind the menu and only Escape worked — the dispatcher routes that
+        // one regardless of focus.
+        //
+        // Unconditional, unlike `wr-dropdown`'s `openedByPointer` gate: there is no
+        // hover open here. Every path into this method is a deliberate request for
+        // the menu (right-click, Shift+F10, the Menu key, a long-press), which is
+        // also when a native context menu takes the keyboard.
+        //
+        // Synchronous, and it can be: `attach()` above runs the embedded view's
+        // first change detection itself (CDK's `attachTemplatePortal`), so the rows
+        // and their `[class]` host binding are already in the DOM.
+        wrFocusMenuItemAt(pane, 0);
         // Trigger the open transition on the next frame — adding the class
         // synchronously with attach would skip the initial 0→1 frame and
         // the menu would just appear without animating.
@@ -696,20 +910,39 @@ class WrContextMenu {
                 return;
             this.closeOverlay();
         });
-        this.overlayRef
+        this.rootKeys = this.overlayRef
             .keydownEvents()
             .pipe(takeUntilDestroyed(this.destroyRef))
             .subscribe(event => {
             if (event.key === 'Escape') {
                 event.preventDefault();
                 this.closeOverlay();
-                this.host.nativeElement.focus();
+                return;
+            }
+            if (event.key === 'Tab') {
+                // Let focus leave naturally — `closeOverlay()` hands it back to the
+                // trigger first, so Tab continues from there instead of from a pane
+                // that is about to be removed.
+                this.closeOverlay();
+                return;
             }
+            // A row's own handler already acted on this key (ArrowRight into a
+            // submenu, Enter on an item): `preventDefault()` is how it says so, and
+            // moving the cursor on top of that would undo it.
+            if (event.defaultPrevented)
+                return;
+            wrHandleMenuNavigation(pane, event);
         });
     }
     closeOverlay() {
         if (!this.overlayRef)
             return;
+        // Read up front, before the teardown below starts on the panes: the answer
+        // wanted is where the keyboard was at the moment of dismissal.
+        const active = document.activeElement;
+        const focusWasInside = active instanceof Element && active.closest('.wr-context-menu-overlay') !== null;
+        const restoreTo = this.restoreFocusTo;
+        this.restoreFocusTo = null;
         this.cancelLeaveTimer();
         // Drop the reference immediately: the pane below stays in the DOM until the
         // exit animation has played, and a trigger still pointing at a menu on its
@@ -728,6 +961,25 @@ class WrContextMenu {
         // class first so the SCSS transition runs back to the default
         // (faded + scaled-down) state, then dispose after the transition.
         pane.classList.remove('wr-context-menu-overlay--open');
+        // …and stop it hit-testing on the way out. Fading to `opacity: 0` does not
+        // stop a pane receiving pointer events — `.cdk-overlay-pane` sets
+        // `pointer-events: auto` — so for the whole 220 ms an invisible menu kept
+        // swallowing clicks meant for the page underneath, and a second click on
+        // the item just picked (a double-click, or Escape then click) re-ran the
+        // consumer's action. Written inline rather than in `styles/_index.scss`
+        // because the closing state has no class of its own, and inline beats the
+        // CDK's own sheet without an `!important`.
+        pane.style.pointerEvents = 'none';
+        // …and stop it taking the page's KEYS on the way out, for the same reason
+        // and with the same timing. An overlay with a keydown subscriber is where
+        // CDK's dispatcher stops looking, and it is removed from the dispatcher only
+        // by `detach()` / `dispose()` — which is 220 ms away — so a dismissed menu
+        // went on swallowing every keydown on the page: ArrowDown pulled real focus
+        // back onto a row of the invisible pane, and a second Escape meant for the
+        // dialog underneath was `preventDefault`ed and did nothing.
+        // `WrContextMenuItem.disposeSubmenu()` does exactly this; the root had not.
+        this.rootKeys?.unsubscribe();
+        this.rootKeys = null;
         const timer = setTimeout(() => {
             this.closingPanes.delete(timer);
             ref.dispose();
@@ -736,6 +988,44 @@ class WrContextMenu {
         // Mark immediately so a subsequent right-click opens a fresh menu
         // rather than landing on the disposing one.
         this.overlayRef = null;
+        // Hand the keyboard back. The menu takes focus on open, so a dismissal that
+        // left it in the pane would strand it on `<body>` once the pane is disposed
+        // and the next Tab would restart at the top of the document. Only when the
+        // caret was actually in the chain: Escape reaches this overlay from anywhere
+        // on the page (CDK's dispatcher routes it by stacking order, not by focus),
+        // and a menu nobody was in must not steal the caret from a field they are.
+        if (focusWasInside)
+            this.handBackFocus(restoreTo);
+    }
+    /**
+     * Put the keyboard back where it came from.
+     *
+     * The element that had it when the menu opened comes first: a context menu
+     * hangs on a REGION — a card, a table row — and Shift+F10 / the Menu key fires
+     * `contextmenu` at whatever control inside it the user was actually on, which
+     * is their place in the page.
+     *
+     * The trigger is the fallback, and it needs help to be one. `[wrContextMenu]`
+     * adds no `tabindex` and every shape the docs ship is a plain `<div>`, so
+     * `focus()` on it does nothing at all — the handback silently missed, leaving
+     * the caret in the disposing pane and then on `<body>`, which is the outcome
+     * the call is there to prevent. Lending it `tabindex="-1"` for the call and
+     * taking that back on blur keeps the consumer's DOM as they wrote it; a
+     * permanent `tabindex="0"` would make every right-clickable region a tab stop,
+     * which is their decision and not the library's.
+     */
+    handBackFocus(previous) {
+        const target = previous?.isConnected && !previous.closest('.wr-context-menu-overlay') ? previous : this.host.nativeElement;
+        target.focus();
+        // Asking whether it took, rather than deciding up front whether it can: the
+        // focusability rules are wide (an `<a>` needs an href, a `<div>` needs a
+        // tabindex, `inert`/`disabled` opt out) and `document.activeElement` answers
+        // all of them at once.
+        if (document.activeElement === target)
+            return;
+        target.setAttribute('tabindex', '-1');
+        target.focus();
+        target.addEventListener('blur', () => target.removeAttribute('tabindex'), { once: true });
     }
     cancelLeaveTimer() {
         if (this.leaveTimer !== null) {
@@ -750,10 +1040,10 @@ class WrContextMenu {
             this.closeOverlay();
         }, WrContextMenu.LEAVE_DELAY);
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenu, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.1", type: WrContextMenu, isStandalone: true, selector: "[wrContextMenu]", inputs: { menu: { classPropertyName: "menu", publicName: "wrContextMenu", isSignal: true, isRequired: true, transformFunction: null } }, host: { listeners: { "contextmenu": "onContextMenu($event)", "pointerdown": "onPointerDown($event)", "pointermove": "onPointerMove($event)", "pointerup": "onPointerUp()", "pointercancel": "onPointerUp()" }, properties: { "attr.aria-controls": "openMenuId()" }, classAttribute: "wr-context-menu-host" }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenu, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.4", type: WrContextMenu, isStandalone: true, selector: "[wrContextMenu]", inputs: { menu: { classPropertyName: "menu", publicName: "wrContextMenu", isSignal: true, isRequired: true, transformFunction: null } }, host: { listeners: { "contextmenu": "onContextMenu($event)", "pointerdown": "onPointerDown($event)", "pointermove": "onPointerMove($event)", "pointerup": "onPointerUp()", "pointercancel": "onPointerUp()" }, properties: { "attr.aria-controls": "openMenuId()" }, classAttribute: "wr-context-menu-host" }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenu, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenu, decorators: [{
             type: Directive,
             args: [{
                     selector: '[wrContextMenu]',
@@ -793,10 +1083,10 @@ class WrContextMenuPanel {
     /** The internal template the directive portals into the overlay. @internal */
     contentTpl = viewChild.required(TemplateRef, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "contentTpl" }] : /* istanbul ignore next */ []));
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenuPanel, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "22.1.1", type: WrContextMenuPanel, isStandalone: true, selector: "wr-context-menu", host: { styleAttribute: "display:none" }, viewQueries: [{ propertyName: "contentTpl", first: true, predicate: TemplateRef, descendants: true, isSignal: true }], exportAs: ["wrContextMenu"], ngImport: i0, template: '<ng-template><div class="wr-context-menu" role="menu"><ng-content /></div></ng-template>', isInline: true, encapsulation: i0.ViewEncapsulation.None });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenuPanel, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "22.1.4", type: WrContextMenuPanel, isStandalone: true, selector: "wr-context-menu", host: { styleAttribute: "display:none" }, viewQueries: [{ propertyName: "contentTpl", first: true, predicate: TemplateRef, descendants: true, isSignal: true }], exportAs: ["wrContextMenu"], ngImport: i0, template: '<ng-template><div class="wr-context-menu" role="menu"><ng-content /></div></ng-template>', isInline: true, encapsulation: i0.ViewEncapsulation.None });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenuPanel, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenuPanel, decorators: [{
             type: Component,
             args: [{
                     selector: 'wr-context-menu',
@@ -829,10 +1119,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImpor
  * ```
  */
 class WrContextMenuDivider {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenuDivider, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.1.1", type: WrContextMenuDivider, isStandalone: true, selector: "wr-context-menu-divider", host: { attributes: { "role": "separator", "aria-orientation": "horizontal" }, classAttribute: "wr-context-menu-divider" }, ngImport: i0, template: '', isInline: true, encapsulation: i0.ViewEncapsulation.None });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenuDivider, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.1.4", type: WrContextMenuDivider, isStandalone: true, selector: "wr-context-menu-divider", host: { attributes: { "role": "separator", "aria-orientation": "horizontal" }, classAttribute: "wr-context-menu-divider" }, ngImport: i0, template: '', isInline: true, encapsulation: i0.ViewEncapsulation.None });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.1", ngImport: i0, type: WrContextMenuDivider, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: WrContextMenuDivider, decorators: [{
             type: Component,
             args: [{
                     selector: 'wr-context-menu-divider',