fix(ui): add keyboard-resizable drawers with Escape handling and focus restoration.

CHANGELOG.md

@@ -22,3 +22,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - feat(tests): add unit tests for panel snapshots and enhance existing test coverage.
 - feat(ui): share User guest and RBAC section rendering and support selecting filtered tabs.
 - feat(ui): add sensitive queue-payload redaction and recognize Yii3 queue producers for Dump, Mail, and Queue parity.
+- fix(ui): add keyboard-resizable drawers with Escape handling and focus restoration.

README.md

@@ -55,6 +55,9 @@ npm run test:js
 npm run build
 ```
 
+The toolbar drawer moves focus to its close control, restores the activating chip on close, closes with `Escape`, and
+supports `ArrowUp`, `ArrowDown`, `Home`, and `End` on its resize separator.
+
 ## License
 
 The package is released under the BSD-3-Clause license. See `LICENSE`.

resources/src/core/debug.js

@@ -12,6 +12,7 @@ import {
   THEME_PARAM,
   writeTheme,
 } from "./theme.js";
+import { requestParentToolbarDrawerClose } from "../toolbar/focus.js";
 
 (function () {
   "use strict";
@@ -295,7 +296,15 @@ import {
     }
 
     if (event.key === "Escape") {
+      var dropdownWasOpen = Boolean(
+        document.querySelector(".yii-debug-dropdown.is-open"),
+      );
+
       hideDropdowns(null);
+
+      window.setTimeout(function () {
+        requestParentToolbarDrawerClose(event, window, dropdownWasOpen);
+      }, 0);
     }
   });
 

resources/src/toolbar/element.js

@@ -22,6 +22,12 @@ import {
   writeThemeCookie,
 } from "./theme.js";
 import { builtinIconUrl } from "./icons.js";
+import {
+  focusToolbarElement,
+  focusToolbarTrigger,
+  isToolbarDrawerCloseMessage,
+  shouldCloseToolbarDrawer,
+} from "./focus.js";
 import {
   isToolbarLoadCurrent,
   resolveToolbarLoadGeneration,
@@ -37,7 +43,11 @@ import {
   toolbarItemTag,
   toolbarPanelContainerTag,
 } from "./panel.js";
-import { normalizeToolbarPosition, toolbarDrawerHeight } from "./position.js";
+import {
+  normalizeToolbarPosition,
+  toolbarDrawerHeight,
+  toolbarDrawerHeightForKey,
+} from "./position.js";
 
 /**
  * Styles injected into the toolbar's open shadow DOM. Authored in
@@ -55,6 +65,7 @@ export function YiiDebugToolbar() {
   self.activeUrl = "";
   self.expanded = readStorageItem(storageKey) === "1";
   self.drawerOpen = false;
+  self.restoreFocusUrl = null;
   self.resizing = false;
   self.currentTag = null;
   self.lastLoadedTag = null;
@@ -135,6 +146,10 @@ YiiDebugToolbar.prototype.disconnectedCallback = function () {
     window.removeEventListener("message", this.boundThemeMessage, false);
     this.boundThemeMessage = null;
   }
+
+  this.resizing = false;
+  document.removeEventListener("pointermove", this.boundPointerMove, false);
+  document.removeEventListener("pointerup", this.boundPointerUp, false);
 };
 
 YiiDebugToolbar.prototype.setAjaxRequests = function (requests) {
@@ -183,6 +198,7 @@ YiiDebugToolbar.prototype.toggleTheme = function () {
 
   if (delegateThemeToHost(next, this.detectTheme())) {
     this.refreshTheme();
+    focusToolbarElement(this.shadowRoot, ".toggle-theme");
 
     return;
   }
@@ -208,6 +224,7 @@ YiiDebugToolbar.prototype.toggleTheme = function () {
    */
   this.propagateThemeToHost(next);
   this.render();
+  focusToolbarElement(this.shadowRoot, ".toggle-theme");
 };
 
 /**
@@ -326,6 +343,19 @@ YiiDebugToolbar.prototype.watchTheme = function () {
       }
 
       var data = event.data;
+      var drawerFrame = self.shadowRoot.querySelector(".drawer iframe");
+
+      if (
+        isToolbarDrawerCloseMessage(
+          event,
+          window.location.origin,
+          drawerFrame ? drawerFrame.contentWindow : null,
+        )
+      ) {
+        self.closeDrawer();
+
+        return;
+      }
 
       if (
         !data ||
@@ -981,9 +1011,9 @@ YiiDebugToolbar.prototype.renderDrawer = function (position) {
   }
 
   var handle =
-    '<div class="resize-handle" title="Resize debug panel" aria-label="Resize debug panel"></div>';
+    '<div class="resize-handle" role="separator" aria-label="Resize debug panel" aria-orientation="horizontal" tabindex="0"></div>';
   var drawer =
-    '<div class="drawer"><iframe src="' +
+    '<div class="drawer" role="region" aria-label="Yii debug panel"><iframe src="' +
     escapeHtml(this.withTheme(this.activeUrl)) +
     '" title="Yii debug panel"></iframe></div>';
 
@@ -1006,6 +1036,16 @@ YiiDebugToolbar.prototype.bindDelegatedEvents = function () {
     event.stopPropagation();
     self.openPanel(url);
   });
+
+  root.addEventListener("keydown", function (event) {
+    if (!shouldCloseToolbarDrawer(event, self.drawerOpen)) {
+      return;
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    self.closeDrawer();
+  });
 };
 
 YiiDebugToolbar.prototype.bindEvents = function () {
@@ -1035,6 +1075,9 @@ YiiDebugToolbar.prototype.bindEvents = function () {
   }
 
   if (resizeHandle) {
+    resizeHandle.addEventListener("keydown", function (event) {
+      self.onResizeKeyDown(event);
+    });
     resizeHandle.addEventListener(
       "pointerdown",
       function (event) {
@@ -1055,6 +1098,7 @@ YiiDebugToolbar.prototype.toggleExpanded = function () {
     this.drawerOpen = false;
   }
   this.render();
+  focusToolbarElement(this.shadowRoot, ".toggle-toolbar");
 };
 
 YiiDebugToolbar.prototype.openPanel = function (url) {
@@ -1065,13 +1109,22 @@ YiiDebugToolbar.prototype.openPanel = function (url) {
   this.expanded = true;
   this.drawerOpen = true;
   this.activeUrl = url;
+  this.restoreFocusUrl = url;
   writeStorageItem(storageKey, "1");
   this.render();
+  focusToolbarElement(this.shadowRoot, ".close-drawer");
 };
 
 YiiDebugToolbar.prototype.closeDrawer = function () {
+  var restoreFocusUrl = this.restoreFocusUrl;
+
   this.drawerOpen = false;
+  this.restoreFocusUrl = null;
   this.render();
+
+  if (!focusToolbarTrigger(this.shadowRoot, restoreFocusUrl)) {
+    focusToolbarElement(this.shadowRoot, ".toggle-toolbar");
+  }
 };
 
 YiiDebugToolbar.prototype.applyDrawerHeight = function () {
@@ -1091,6 +1144,8 @@ YiiDebugToolbar.prototype.applyDrawerHeight = function () {
       Math.max(20, Math.min(90, height)) + "vh",
     );
   }
+
+  this.updateResizeHandleAccessibility();
 };
 
 YiiDebugToolbar.prototype.onPointerMove = function (event) {
@@ -1114,6 +1169,54 @@ YiiDebugToolbar.prototype.onPointerMove = function (event) {
     "--yii-debug-toolbar-drawer-height",
     Math.max(120, Math.min(viewportHeight - 48, height)) + "px",
   );
+  this.updateResizeHandleAccessibility();
+};
+
+YiiDebugToolbar.prototype.onResizeKeyDown = function (event) {
+  var drawer = this.shadowRoot.querySelector(".drawer");
+
+  if (!drawer) {
+    return;
+  }
+
+  var viewportHeight =
+    window.innerHeight || document.documentElement.clientHeight;
+  var height = toolbarDrawerHeightForKey(
+    this.getPosition(),
+    event.key,
+    drawer.getBoundingClientRect().height,
+    viewportHeight,
+  );
+
+  if (height === null) {
+    return;
+  }
+
+  event.preventDefault();
+  this.style.setProperty("--yii-debug-toolbar-drawer-height", height + "px");
+  this.updateResizeHandleAccessibility();
+};
+
+YiiDebugToolbar.prototype.updateResizeHandleAccessibility = function () {
+  var drawer = this.shadowRoot.querySelector(".drawer");
+  var handle = this.shadowRoot.querySelector(".resize-handle");
+
+  if (!drawer || !handle) {
+    return;
+  }
+
+  var viewportHeight =
+    window.innerHeight || document.documentElement.clientHeight;
+  var minimum = 120;
+  var maximum = Math.max(minimum, viewportHeight - 48);
+  var current = Math.max(
+    minimum,
+    Math.min(maximum, Math.round(drawer.getBoundingClientRect().height)),
+  );
+
+  handle.setAttribute("aria-valuemin", String(minimum));
+  handle.setAttribute("aria-valuemax", String(maximum));
+  handle.setAttribute("aria-valuenow", String(current));
 };
 
 YiiDebugToolbar.prototype.onPointerUp = function () {

resources/src/toolbar/focus.js

@@ -0,0 +1,78 @@
+export function focusToolbarElement(root, selector) {
+  if (!root) {
+    return false;
+  }
+
+  var element = root.querySelector(selector);
+
+  if (!element || typeof element.focus !== "function") {
+    return false;
+  }
+
+  element.focus();
+
+  return true;
+}
+
+export function focusToolbarTrigger(root, url) {
+  if (!root || !url) {
+    return false;
+  }
+
+  var triggers = root.querySelectorAll("[data-debug-url]");
+
+  for (var i = 0; i < triggers.length; i++) {
+    if (triggers[i].getAttribute("data-debug-url") === url) {
+      triggers[i].focus();
+
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function isToolbarDrawerCloseMessage(event, origin, frameWindow) {
+  var data = event && event.data;
+
+  return Boolean(
+    event &&
+    event.origin === origin &&
+    frameWindow &&
+    event.source === frameWindow &&
+    data &&
+    typeof data === "object" &&
+    data.source === "yii-debug-toolbar" &&
+    data.type === "close-drawer",
+  );
+}
+
+export function requestParentToolbarDrawerClose(
+  event,
+  browserWindow,
+  dropdownWasOpen,
+) {
+  if (
+    !event ||
+    event.key !== "Escape" ||
+    event.defaultPrevented ||
+    dropdownWasOpen ||
+    !browserWindow.parent ||
+    browserWindow.parent === browserWindow
+  ) {
+    return false;
+  }
+
+  browserWindow.parent.postMessage(
+    { source: "yii-debug-toolbar", type: "close-drawer" },
+    browserWindow.location.origin,
+  );
+
+  return true;
+}
+
+export function shouldCloseToolbarDrawer(event, drawerOpen) {
+  return Boolean(
+    drawerOpen && event && event.key === "Escape" && !event.defaultPrevented,
+  );
+}

resources/src/toolbar/position.js

@@ -16,3 +16,32 @@ export function toolbarDrawerHeight(
 
   return top ? clientY - drawerRect.top : drawerRect.bottom - clientY;
 }
+
+export function toolbarDrawerHeightForKey(
+  position,
+  key,
+  currentHeight,
+  viewportHeight,
+  step = 24,
+) {
+  var minimum = 120;
+  var maximum = Math.max(minimum, viewportHeight - 48);
+
+  if (key === "Home") {
+    return minimum;
+  }
+
+  if (key === "End") {
+    return maximum;
+  }
+
+  if (key !== "ArrowUp" && key !== "ArrowDown") {
+    return null;
+  }
+
+  var top = normalizeToolbarPosition(position) === "top";
+  var grows = (top && key === "ArrowDown") || (!top && key === "ArrowUp");
+  var height = currentHeight + (grows ? step : -step);
+
+  return Math.max(minimum, Math.min(maximum, height));
+}

resources/src/toolbar/toolbar-shadow.css

@@ -648,8 +648,12 @@
 
 /* The tick-rail: the resize handle doubles as the cluster's trace line. */
 .resize-handle {
+  display: block;
+  width: auto;
   height: 6px;
   margin: 0 18px -3px;
+  padding: 0;
+  border: 0;
   border-radius: 999px;
   background: linear-gradient(
     90deg,
@@ -664,6 +668,12 @@
   z-index: 1;
 }
 
+.resize-handle:focus-visible {
+  outline: 3px solid var(--yii-debug-panel-primary);
+  outline-offset: 3px;
+  opacity: 1;
+}
+
 .position-top .resize-handle {
   margin: -3px 18px 0;
 }