fix: Restore keyboard focus for key triggers (#2634) (#2639)

- Closes #2634

src/card-controller/card-element-manager.ts

@@ -98,6 +98,10 @@ export class CardElementManager {
     this._element.toggleAttribute('panel', isCardInPanel(this._element));
     this._element.toggleAttribute('casted', isBeingCasted());
 
+    // The card must be focusable in its own right, so that it can receive
+    // keyboard events and be reached by tabbing.
+    this._element.setAttribute('tabindex', '0');
+
     this._api.getFullscreenManager().connect();
 
     this._element.addEventListener(

src/card-controller/keyboard-state-manager.ts

@@ -1,5 +1,6 @@
 import { isEqual } from 'lodash-es';
 
+import { isFocusWithin } from '../utils/focus';
 import type { CardKeyboardStateAPI, KeysState } from './types';
 
 export class KeyboardStateManager {
@@ -15,6 +16,12 @@ export class KeyboardStateManager {
     element.addEventListener('keydown', this._handleKeydown);
     element.addEventListener('keyup', this._handleKeyup);
     element.addEventListener('blur', this._handleBlur);
+
+    // Must capture, since elements within the card stop pointer events propagating
+    // (e.g. the zoom controller during a pan).
+    element.addEventListener('pointerdown', this._handlePointerdown, {
+      capture: true,
+    });
   }
 
   public uninitialize(): void {
@@ -22,6 +29,9 @@ export class KeyboardStateManager {
     element.removeEventListener('keydown', this._handleKeydown);
     element.removeEventListener('keyup', this._handleKeyup);
     element.removeEventListener('blur', this._handleBlur);
+    element.removeEventListener('pointerdown', this._handlePointerdown, {
+      capture: true,
+    });
 
     // Clear state on disconnect. Without listeners the card cannot know
     // whether a key was released while detached, and stale "down" state
@@ -54,7 +64,30 @@ export class KeyboardStateManager {
     }
   };
 
-  private _handleBlur = (): void => {
+  // Keys are only received when the card or something within it has focus, so
+  // focus is claimed on interaction. The card itself is focused rather than a
+  // child, as a child may be removed by the next render and take focus with it.
+  private _handlePointerdown = (): void => {
+    const element = this._api.getCardElementManager().getElement();
+
+    // Focus already inside the card is left where it is, as taking it would blur
+    // whatever the user is interacting with (e.g. a text field being typed in).
+    if (isFocusWithin(element)) {
+      return;
+    }
+
+    // Taking focus must not scroll the dashboard to bring the card into view.
+    element.focus({ preventScroll: true });
+  };
+
+  private _handleBlur = (ev: FocusEvent): void => {
+    // 'relatedTarget' would be the card element due to event retargeting --
+    // focus gained by another element within the card will be reported as to
+    // the card itself at this level.
+    if (ev.relatedTarget === this._api.getCardElementManager().getElement()) {
+      return;
+    }
+
     if (Object.keys(this._state).length) {
       // State is emptied if the element loses focus.
       this._state = {};

src/card.ts

@@ -454,7 +454,6 @@ class AdvancedCameraCard extends LitElement {
           @advanced-camera-card:media:pause=${
             () => this.requestUpdate() /* Refresh play/pause menu button */
           }
-          @advanced-camera-card:focus=${() => this.focus()}
           @advanced-camera-card:notification:dismiss=${() =>
             this._controller.getNotificationManager().reset()}
         >

src/components-lib/zoom/zoom-controller.ts

@@ -73,11 +73,6 @@ export class ZoomController {
     // handler in the viewer).
     if (!this._allowClick) {
       ev.stopPropagation();
-
-      // Even though the click is stopped,the card still needs to gain focus so
-      // that keyboard shortcuts will work immediately after the card is clicked
-      // upon.
-      fireAdvancedCameraCardEvent(this._element, 'focus');
     }
     this._allowClick = true;
   };

src/utils/focus.ts

@@ -0,0 +1,14 @@
+/**
+ * Determine whether focus currently rests on an element, or on any of its
+ * descendants (including those inside nested shadow roots).
+ */
+export const isFocusWithin = (element: Element): boolean => {
+  const root = element.getRootNode();
+
+  // Focus is reported per tree, with a shadow host standing in for whatever is
+  // focused inside it, so the element's own tree is the one that will name it.
+  const active =
+    root instanceof Document || root instanceof ShadowRoot ? root.activeElement : null;
+
+  return !!active && element.contains(active);
+};