@fabric-msft/fabric-web 4.0.0-beta.1 → 5.0.0

package/dist/esm/components/teaching-bubble/teaching-bubble.js

@@ -1,21 +1,23 @@
-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 { autoUpdate, arrow, offset, autoPlacement, computePosition } from '@floating-ui/dom';
+import { attr, FASTElement, Updates } from '@microsoft/fast-element';
+import { keyEscape, keyTab } from '@microsoft/fast-web-utilities';
+import { isTabbable } from 'tabbable';
+import { TeachingBubbleEventNames } from './teaching-bubble.options.js';
+
+var __decorate = globalThis && globalThis.__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 { arrow, autoPlacement, autoUpdate, computePosition, offset } from "@floating-ui/dom";
-import { FASTElement, Updates, attr, observable } from "@microsoft/fast-element";
-import { keyEscape, keyTab } from "@microsoft/fast-web-utilities";
-import { isTabbable } from "tabbable";
-import { TeachingBubbleEventNames } from "./teaching-bubble.options";
 /**
  * TeachingBubble
  * @summary A customizable teaching bubble component for providing contextual help or instruction.
  *
  * @example
  * ```html
- * <fabric-teaching-bubble target="selector" open placement="top" size="medium">
+ * <fabric-teaching-bubble target="help-button" open placement="top" size="medium">
  *   <span slot="image">Image content</span>
  *   <span slot="close">Close button</span>
  *   <span slot="heading">Heading content</span>
@@ -24,22 +26,18 @@ import { TeachingBubbleEventNames } from "./teaching-bubble.options";
  * </fabric-teaching-bubble>
  * ```
  *
- * @attr {string} target - The target element selector for the teaching bubble.
- * @attr {TeachingBubblePlacement} placement - The placement of the teaching bubble.
- * @attr {boolean} open - Indicates whether the teaching bubble is open.
- * @attr {boolean} disable-trap-focus - Indicates whether trap focus is disabled.
+ * @attr {string} target - The ID of the target element for the teaching bubble.
+ * @attr {TeachingBubblePlacements} placement - The placement of the teaching bubble.
+ * @attr {boolean} open - Controls whether the teaching bubble is open.
+ * @attr {boolean} disable-trap-focus - Controls whether trap focus is disabled.
  * @attr {TeachingBubbleSize} size - The size of the teaching bubble.
  *
- * @prop {HTMLElement | null} targetEl - The target element for the teaching bubble.
- * @prop {HTMLElement | null} currentEl - The current element of the teaching bubble.
- * @prop {HTMLElement | null} arrowEl - The arrow element of the teaching bubble.
- * @prop {boolean} isTrappingFocus - Indicates whether the teaching bubble is trapping focus.
- * @prop {boolean} trapFocus - Indicates whether the teaching bubble should trap focus.
+ * @prop {ElementInternals} elementInternals - The internal ElementInternals instance for the component.
  *
  * @slot image - Slot for adding an image inside the teaching bubble.
  * @slot close - Slot for adding a close button inside the teaching bubble.
  * @slot heading - Slot for adding a heading inside the teaching bubble.
- * @slot - Default slot for adding content inside the teaching bubble.
+ * @slot default - Default slot for adding content inside the teaching bubble.
  * @slot footer - Slot for adding a footer inside the teaching bubble.
  *
  * @csspart image - Style part for the image inside the teaching bubble.
@@ -52,11 +50,6 @@ import { TeachingBubbleEventNames } from "./teaching-bubble.options";
  * @method show() - Shows the teaching bubble.
  * @method hide(dismiss: boolean) - Hides the teaching bubble, optionally dismissing it.
  * @method openChanged() - Handles changes to the open attribute.
- * @method reduceTabbableItems(elements: HTMLElement[], element: FASTElement): HTMLElement[] - Reduces tabbable items to a list of elements.
- * @method isFocusableFastElement(element: FASTElement): boolean - Determines if a FAST element is focusable.
- * @method hasTabbableShadow(element: FASTElement): boolean - Determines if a FAST element has a tabbable shadow root.
- * @method disableTrapFocusHandler() - Handles the trap focus disable state.
- * @method initializePosition() - Initializes the position of the teaching bubble.
  *
  * @fires open-change - Fires when the 'open' attribute changes.
  * @fires dismiss - Fires when the teaching bubble is dismissed.
@@ -65,427 +58,457 @@ import { TeachingBubbleEventNames } from "./teaching-bubble.options";
  * @tagname fabric-teaching-bubble
  * @public
  */
-export class TeachingBubble extends FASTElement {
-    constructor() {
-        super(...arguments);
-        /**
-         * The target element selector for the teaching bubble.
-         * @public
-         * @attr target
-         * @type {string}
-         */
-        this.target = "";
-        /**
-         * Indicates whether trap focus is disabled.
-         * @public
-         * @attr disable-trap-focus
-         * @type {boolean}
-         * @default false
-         */
-        this.disableTrapFocus = false;
-        /**
-         * Indicates whether the teaching bubble is trapping focus.
-         * @private
-         * @observable
-         * @type {boolean}
-         * @default false
-         */
-        this.isTrappingFocus = false;
-        /**
-         * Indicates whether the teaching bubble should trap focus.
-         * @private
-         * @observable
-         * @type {boolean}
-         * @default false
-         */
-        this.trapFocus = false;
-        /**
-         * Function to clean up auto updates.
-         * @private
-         * @observable
-         * @type {() => void | null}
-         */
-        this.cleanAutoUpdate = null;
-        /**
-         * Shows the teaching bubble.
-         * @public
-         */
-        this.show = () => {
-            this.updatePosition();
-            this.cleanAutoUpdate = autoUpdate(this.targetEl, this.currentEl, this.updatePosition);
-            this.open = true;
-            this.trapFocus = true;
-            this.updateTrapFocus(true);
-        };
-        /**
-         * Hides the teaching bubble.
-         * @public
-         * @param {boolean} - Indicates whether the bubble should be dismissed.
-         * @fires dismiss - Emitted when the open attribute changes.
-         */
-        this.hide = (dismiss = false) => {
-            var _a;
-            this.open = false;
-            (_a = this.currentEl) === null || _a === void 0 ? void 0 : _a.setAttribute("hidden", "");
-            if (dismiss) {
-                this.dispatchEvent(new CustomEvent(TeachingBubbleEventNames.dismiss, {
-                    detail: { dismiss: true }
-                }));
-            }
-        };
-        /**
-         * Resolver function for the render promise.
-         * @private
-         * @type {() => undefined | null}
-         */
-        this.renderResolver = () => undefined;
-        /**
-         * Promise that resolves when the teaching bubble is rendered.
-         * @private
-         * @type {Promise<void>}
-         */
-        this.renderPromise = new Promise((resolve) => {
-            this.renderResolver = resolve;
-        });
-        /**
-         * Sets the target, current, and arrow elements.
-         * @private
-         */
-        this.setElements = () => {
-            var _a;
-            this.targetEl = document.getElementById(this.target);
-            this.currentEl = this;
-            this.arrowEl = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.getElementById("arrow");
-        };
-        /**
-         * Updates the position of the teaching bubble.
-         * @private
-         */
-        this.updatePosition = () => {
-            this.setElements();
-            const computeObj = this.placement
-                ? {
-                    placement: this.placement,
-                    middleware: [
-                        offset(10),
-                        arrow({
-                            element: this.arrowEl,
-                            padding: 4
-                        })
-                    ]
-                }
-                : {
-                    middleware: [
-                        autoPlacement({ autoAlignment: true }),
-                        offset(10),
-                        arrow({
-                            element: this.arrowEl,
-                            padding: 4
-                        })
-                    ]
-                };
-            if (this.targetEl && this.currentEl) {
-                computePosition(this.targetEl, this.currentEl, computeObj).then(({ x, y, placement, middlewareData }) => {
-                    var _a;
-                    if (!(this.currentEl instanceof HTMLElement)) {
-                        return;
-                    }
-                    Object.assign(this.currentEl.style, {
-                        left: `${x}px`,
-                        top: `${y}px`
-                    });
-                    const { x: arrowX, y: arrowY } = ((_a = middlewareData.arrow) !== null && _a !== void 0 ? _a : {});
-                    const staticSide = {
-                        top: "bottom",
-                        right: "left",
-                        bottom: "top",
-                        left: "right"
-                    }[placement.split("-")[0]];
-                    Object.assign(this.arrowEl.style, {
-                        left: arrowX != null ? `${arrowX}px` : "",
-                        top: arrowY != null ? `${arrowY}px` : "",
-                        right: "",
-                        bottom: "",
-                        [staticSide]: "-8px"
-                    });
-                });
-            }
-        };
-        /**
-         * Handles keydown events on the document.
-         * @private
-         * @param {KeyboardEvent} e - The keyboard event.
-         * @returns {boolean | void}
-         */
-        this.handleDocumentKeydown = (e) => {
-            if (!e.defaultPrevented && this.open) {
-                switch (e.key) {
-                    case keyTab:
-                        this.handleTabKeyDown(e);
-                        break;
-                    case keyEscape:
-                        this.hide(true);
-                        break;
-                    default:
-                        return true;
-                }
-            }
-        };
-        /**
-         * Handles the tab keydown event.
-         * @private
-         * @param {KeyboardEvent} e - The keyboard event.
-         */
-        this.handleTabKeyDown = (e) => {
-            if (!this.trapFocus || !this.open) {
-                return;
-            }
-            const bounds = this.getTabQueueBounds();
-            if (bounds.length === 1) {
-                bounds[0].focus();
-                e.preventDefault();
-                return;
-            }
-            if (e.shiftKey && e.target === bounds[0]) {
-                bounds[bounds.length - 1].focus();
-                e.preventDefault();
-            }
-            else if (!e.shiftKey && e.target === bounds[bounds.length - 1]) {
-                bounds[0].focus();
-                e.preventDefault();
-            }
-            return;
-        };
-        /**
-         * Gets the bounds of the tab queue.
-         * @private
-         * @returns {(HTMLElement | SVGElement)[]}
-         */
-        this.getTabQueueBounds = () => {
-            const bounds = [];
-            return TeachingBubble.reduceTabbableItems(bounds, this);
-        };
-        /**
-         * Updates the focus trap state.
-         * @private
-         * @param {boolean} [shouldTrapFocusOverride] - Optional override for whether to trap focus.
-         */
-        this.updateTrapFocus = (shouldTrapFocusOverride) => {
-            const shouldTrapFocus = shouldTrapFocusOverride === undefined
-                ? this.shouldTrapFocus()
-                : shouldTrapFocusOverride;
-            if (shouldTrapFocus && !this.isTrappingFocus) {
-                this.isTrappingFocus = true;
-                document.addEventListener("focusin", this.handleDocumentFocus);
-                Updates.enqueue(() => {
-                    if (this.shouldForceFocus(document.activeElement)) {
-                        this.focusFirstElement();
-                    }
-                });
-            }
-            else if (!shouldTrapFocus && this.isTrappingFocus) {
-                this.isTrappingFocus = false;
-                document.removeEventListener("focusin", this.handleDocumentFocus);
-            }
-        };
-        /**
-         * Handles focus events on the document.
-         * @private
-         * @param {Event} e - The focus event.
-         */
-        this.handleDocumentFocus = (e) => {
-            if (!e.defaultPrevented && this.shouldForceFocus(e.target)) {
-                this.focusFirstElement();
-                e.preventDefault();
-            }
-        };
-        /**
-         * Focuses the first element in the tab queue.
-         * @private
-         */
-        this.focusFirstElement = () => {
-            const bounds = this.getTabQueueBounds();
-            const teachingBubbleAllEls = document.getElementsByTagName("fabric-teaching-bubble");
-            let disableFocus = 0;
-            Array.from(teachingBubbleAllEls).forEach((el) => {
-                if (true === el.hasAttribute("open")) {
-                    disableFocus++;
-                }
-            });
-            if (disableFocus > 1) {
-                return;
-            }
-            if (bounds.length > 0) {
-                bounds[0].focus();
-            }
-            else {
-                if (this.currentEl instanceof HTMLElement) {
-                    this.currentEl.focus();
-                }
-            }
-        };
-        /**
-         * Determines if the focus should be forced to the teaching bubble.
-         * @private
-         * @param {Element | null} currentFocusElement - The current focused element.
-         * @returns {boolean}
-         */
-        this.shouldForceFocus = (currentFocusElement) => {
-            return this.isTrappingFocus && !this.contains(currentFocusElement);
-        };
-        /**
-         * Determines if the teaching bubble should trap focus.
-         * @private
-         * @returns {boolean}
-         */
-        this.shouldTrapFocus = () => {
-            return this.trapFocus && this.open;
-        };
-    }
+class TeachingBubble extends FASTElement {
+  constructor() {
+    super(...arguments);
     /**
-     * Called when the element is connected to the DOM.
+     * The ID of the target element for the teaching bubble.
      * @public
+     * @attr target
+     * @type {string}
      */
-    connectedCallback() {
-        super.connectedCallback();
-        this.renderPromise.then(() => {
-            this.setElements();
-            this.initializePosition();
-            document.addEventListener("keydown", this.handleDocumentKeydown);
-            Updates.enqueue(() => {
-                this.updateTrapFocus();
-                this.disableTrapFocusHandler();
-            });
-        });
-        this.renderResolver();
-    }
+    this.target = "";
+    /**
+     * Indicates whether trap focus is disabled.
+     * @public
+     * @attr disable-trap-focus
+     * @type {boolean}
+     * @default false
+     */
+    this.disableTrapFocus = false;
+    /**
+     * The internal ElementInternals instance for the component.
+     * @public
+     */
+    this.elementInternals = this.attachInternals();
+    /**
+     * Indicates whether the teaching bubble is trapping focus.
+     * @private
+     * @type {boolean}
+     * @default false
+     */
+    this.isTrappingFocus = false;
     /**
-     * Called when the element is disconnected from the DOM.
+     * Indicates whether a focus operation is currently in progress.
+     * Used to prevent infinite recursion in focus handling.
+     * @private
+     * @type {boolean}
+     * @default false
+     */
+    this.focusInProgress = false;
+    /**
+     * Indicates whether the teaching bubble should trap focus.
+     * @private
+     * @type {boolean}
+     * @default false
+     */
+    this.trapFocus = false;
+    /**
+     * Function to clean up auto updates.
+     * @private
+     * @type {() => void | null}
+     */
+    this.cleanAutoUpdate = null;
+    /**
+     * Shows the teaching bubble.
      * @public
      */
-    disconnectedCallback() {
-        super.disconnectedCallback();
-        document.removeEventListener("keydown", this.handleDocumentKeydown);
-        document.removeEventListener("focusin", this.handleDocumentFocus);
-        this.updateTrapFocus(false);
-        if (this.cleanAutoUpdate) {
-            this.cleanAutoUpdate();
+    this.show = () => {
+      var _a, _b;
+      // Set elements first to ensure we have the latest state
+      this.setElements();
+      // Check for required elements
+      if (!this.targetEl) {
+        // Assert in development to catch configuration issues early
+        if (typeof console !== "undefined" && console.assert) {
+          const targetTrimmed = (_b = (_a = this.target) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "";
+          if (targetTrimmed === "") {
+            console.assert(false, `TeachingBubble.show(): target attribute is empty or missing. Expected a valid element ID.`);
+          } else {
+            console.assert(false, `TeachingBubble.show(): target element with ID "${this.target}" not found in DOM. ` + `Ensure the target element exists before calling show().`);
+          }
         }
-        this.targetEl = null;
-        this.currentEl = null;
-        this.arrowEl = null;
-    }
+        // Required elements not yet available; bail quietly
+        return;
+      }
+      // Ensure visibility if previously hidden
+      this.removeAttribute("hidden");
+      this.updatePosition();
+      if (!this.cleanAutoUpdate) {
+        this.cleanAutoUpdate = autoUpdate(this.targetEl, this, this.updatePosition);
+      }
+      if (!this.open) this.open = true;
+      TeachingBubble.openInstances.add(this);
+      // Respect disable-trap-focus attribute
+      const shouldTrap = !this.disableTrapFocus;
+      this.trapFocus = shouldTrap;
+      this.updateTrapFocus(shouldTrap);
+    };
     /**
-     * Handles changes to the open attribute.
+     * Hides the teaching bubble.
      * @public
-     * @fires openchange - Emitted when the open attribute changes.
+     * @param {boolean} - Indicates whether the bubble should be dismissed.
+     * @fires dismiss - Fires when the teaching bubble is dismissed.
      */
-    openChanged() {
-        this.initializePosition();
-        Updates.enqueue(() => {
-            this.updateTrapFocus();
-            this.disableTrapFocusHandler();
-        });
-        this.dispatchEvent(new CustomEvent(TeachingBubbleEventNames.openChange, {
-            detail: { open: this.open }
+    this.hide = (dismiss = false) => {
+      this.open = false;
+      // Stop auto updates when hidden
+      if (this.cleanAutoUpdate) {
+        this.cleanAutoUpdate();
+        this.cleanAutoUpdate = null;
+      }
+      // Disable trapping while hidden
+      // Remove from registry first so next topmost bubble (if any) can trap
+      TeachingBubble.openInstances.delete(this);
+      this.updateTrapFocus(false);
+      // Hide element
+      this.setAttribute("hidden", "");
+      if (dismiss) {
+        this.dispatchEvent(new CustomEvent(TeachingBubbleEventNames.dismiss, {
+          bubbles: true,
+          composed: true
         }));
-    }
+      }
+    };
     /**
-     * Reduces tabbable items to a list of elements.
+     * Sets the target, current, and arrow elements.
      * @private
-     * @static
-     * @param {HTMLElement[]} elements - The current list of elements.
-     * @param {FASTElement} element - The current element to check.
-     * @returns {HTMLElement[]}
      */
-    static reduceTabbableItems(elements, element) {
-        if (element.getAttribute("tabindex") === "-1") {
-            return elements;
-        }
-        if (isTabbable(element) ||
-            (TeachingBubble.isFocusableFastElement(element) &&
-                TeachingBubble.hasTabbableShadow(element))) {
-            elements.push(element);
-            return elements;
+    this.setElements = () => {
+      var _a;
+      const id = ((_a = this.target) !== null && _a !== void 0 ? _a : "").trim();
+      this.targetEl = id ? document.getElementById(id) : null;
+    };
+    /**
+     * Updates the position of the teaching bubble.
+     * @private
+     */
+    this.updatePosition = () => {
+      this.setElements();
+      const arrowMw = this.arrowEl ? [arrow({
+        element: this.arrowEl,
+        padding: 4
+      })] : [];
+      const computeObj = this.placement ? {
+        placement: this.placement,
+        middleware: [offset(10), ...arrowMw]
+      } : {
+        middleware: [autoPlacement({
+          autoAlignment: true
+        }), offset(10), ...arrowMw]
+      };
+      if (this.targetEl) {
+        computePosition(this.targetEl, this, computeObj).then(({
+          x,
+          y,
+          placement,
+          middlewareData
+        }) => {
+          var _a;
+          Object.assign(this.style, {
+            left: `${x}px`,
+            top: `${y}px`
+          });
+          const arrowData = (_a = middlewareData.arrow) !== null && _a !== void 0 ? _a : undefined;
+          if (this.arrowEl && arrowData) {
+            const {
+              x: arrowX,
+              y: arrowY
+            } = arrowData;
+            const staticSide = {
+              top: "bottom",
+              right: "left",
+              bottom: "top",
+              left: "right"
+            }[placement.split("-")[0]];
+            Object.assign(this.arrowEl.style, {
+              left: arrowX != null ? `${arrowX}px` : "",
+              top: arrowY != null ? `${arrowY}px` : "",
+              right: "",
+              bottom: "",
+              [staticSide]: "-8px"
+            });
+          }
+        });
+      }
+    };
+    /**
+     * Handles keydown events on the document.
+     * @private
+     * @param {KeyboardEvent} e - The keyboard event.
+     */
+    this.handleDocumentKeydown = e => {
+      if (!e.defaultPrevented && this.open) {
+        switch (e.key) {
+          case keyTab:
+            this.handleTabKeyDown(e);
+            break;
+          case keyEscape:
+            this.hide(true);
+            break;
         }
-        return Array.from(element.children).reduce((elements, currentElement) => TeachingBubble.reduceTabbableItems(elements, currentElement), elements);
-    }
+      }
+    };
     /**
-     * Determines if a FAST element is focusable.
+     * Handles the tab keydown event.
      * @private
-     * @static
-     * @param {FASTElement} element - The element to check.
-     * @returns {boolean}
+     * @param {KeyboardEvent} e - The keyboard event.
      */
-    static isFocusableFastElement(element) {
-        var _a, _b;
-        return !!((_b = (_a = element.$fastController) === null || _a === void 0 ? void 0 : _a.definition.shadowOptions) === null || _b === void 0 ? void 0 : _b.delegatesFocus);
-    }
+    this.handleTabKeyDown = e => {
+      if (!this.trapFocus || !this.open) {
+        return;
+      }
+      const bounds = this.getTabQueueBounds();
+      if (bounds.length === 1) {
+        bounds[0].focus();
+        e.preventDefault();
+        return;
+      }
+      if (e.shiftKey && e.target === bounds[0]) {
+        bounds[bounds.length - 1].focus();
+        e.preventDefault();
+      } else if (!e.shiftKey && e.target === bounds[bounds.length - 1]) {
+        bounds[0].focus();
+        e.preventDefault();
+      }
+      return;
+    };
     /**
-     * Determines if a FAST element has a tabbable shadow root.
+     * Gets the bounds of the tab queue.
      * @private
-     * @static
-     * @param {FASTElement} element - The element to check.
-     * @returns {boolean}
+     * @returns {(HTMLElement | SVGElement)[]}
+     */
+    this.getTabQueueBounds = () => {
+      const bounds = [];
+      return this.reduceTabbableItems(bounds, this);
+    };
+    /**
+     * Updates the focus trap state.
+     * @private
+     * @param {boolean} [shouldTrapFocusOverride] - Optional override for whether to trap focus.
      */
-    static hasTabbableShadow(element) {
-        var _a, _b;
-        return Array.from((_b = (_a = element.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelectorAll("*")) !== null && _b !== void 0 ? _b : []).some((x) => {
-            return isTabbable(x);
+    this.updateTrapFocus = shouldTrapFocusOverride => {
+      const shouldTrapFocusBase = shouldTrapFocusOverride === undefined ? this.shouldTrapFocus() : shouldTrapFocusOverride;
+      // Only the topmost/sole open bubble should trap to avoid jitter
+      const isTopmost = TeachingBubble.openInstances.size === 1;
+      const shouldTrapFocus = shouldTrapFocusBase && isTopmost;
+      if (shouldTrapFocus && !this.isTrappingFocus) {
+        this.isTrappingFocus = true;
+        // Use host-scoped focusout to detect leaving the component
+        this.addEventListener("focusout", this.handleFocusOut, true);
+        Updates.enqueue(() => {
+          const root = this.getRootNode() || document;
+          const activeEl = "activeElement" in root ? root.activeElement : null;
+          const active = activeEl !== null && activeEl !== void 0 ? activeEl : document.activeElement;
+          if (this.shouldForceFocus(active)) {
+            this.focusFirstElement();
+          }
         });
-    }
+      } else if (!shouldTrapFocus && this.isTrappingFocus) {
+        this.isTrappingFocus = false;
+        this.removeEventListener("focusout", this.handleFocusOut, true);
+      }
+    };
+    /**
+     * Handles focus moving out of the component; re-focus inside when trapping.
+     * @private
+     */
+    this.handleFocusOut = e => {
+      if (!this.isTrappingFocus) return;
+      const next = e.relatedTarget;
+      if (!next || !this.contains(next)) {
+        queueMicrotask(() => {
+          this.focusFirstElement();
+        });
+      }
+    };
     /**
-     * Handles the trap focus disable state.
+     * Focuses the first element in the tab queue.
      * @private
      */
-    disableTrapFocusHandler() {
-        if (this.disableTrapFocus) {
-            this.trapFocus = false;
+    this.focusFirstElement = () => {
+      if (this.focusInProgress) {
+        return false;
+      }
+      this.focusInProgress = true;
+      try {
+        const bounds = this.getTabQueueBounds();
+        // If multiple bubbles are open, do not intercept focus
+        const openCount = TeachingBubble.openInstances.size;
+        if (openCount > 1) {
+          return false;
         }
-        else {
-            this.trapFocus = true;
+        if (bounds.length > 0) {
+          bounds[0].focus();
+          return true;
         }
-    }
+        // TeachingBubble extends FASTElement which extends HTMLElement
+        this.focus();
+        return true;
+      } finally {
+        this.focusInProgress = false;
+      }
+    };
     /**
-     * Initializes the position of the teaching bubble.
+     * Determines if the focus should be forced to the teaching bubble.
      * @private
+     * @param {Element | null} currentFocusElement - The current focused element.
+     * @returns {boolean}
+     */
+    this.shouldForceFocus = currentFocusElement => {
+      return this.isTrappingFocus && !this.contains(currentFocusElement);
+    };
+    /**
+     * Determines if the teaching bubble should trap focus.
+     * @private
+     * @returns {boolean}
      */
-    initializePosition() {
-        this.open && this.targetEl && this.currentEl && this.arrowEl && this.show();
-        this.open || this.hide();
+    this.shouldTrapFocus = () => {
+      return this.trapFocus && this.open;
+    };
+  }
+  /**
+   * Called when the element is connected to the DOM.
+   * @public
+   */
+  connectedCallback() {
+    super.connectedCallback();
+    // Ensure host can be programmatically focused as a last resort
+    if (!this.hasAttribute("tabindex")) {
+      this.setAttribute("tabindex", "-1");
     }
+    // Ensure dialog semantics are on the host (not shadow template)
+    if (!this.hasAttribute("role")) {
+      this.elementInternals.role = "dialog";
+    }
+    // Inline setup: elements, positioning, listeners
+    this.setElements();
+    this.initializePosition();
+    // Scope keyboard handling to the host
+    this.addEventListener("keydown", this.handleDocumentKeydown);
+    Updates.enqueue(() => {
+      // Compute trap state after applying disableTrapFocus
+      this.disableTrapFocusHandler();
+      this.updateTrapFocus();
+    });
+  }
+  /**
+   * Called when the element is disconnected from the DOM.
+   * @public
+   */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener("keydown", this.handleDocumentKeydown);
+    // Ensure focus trap listeners are removed
+    this.removeEventListener("focusout", this.handleFocusOut, true);
+    this.updateTrapFocus(false);
+    if (this.cleanAutoUpdate) {
+      this.cleanAutoUpdate();
+    }
+    // Remove from registry if present
+    TeachingBubble.openInstances.delete(this);
+  }
+  /**
+   * Handles changes to the open attribute.
+   * @public
+   * @fires open-change - Emitted when the open attribute changes.
+   */
+  openChanged() {
+    this.initializePosition();
+    Updates.enqueue(() => {
+      // Apply disable-trap-focus, then compute trapping & listeners
+      this.disableTrapFocusHandler();
+      this.updateTrapFocus();
+    });
+    this.dispatchEvent(new CustomEvent(TeachingBubbleEventNames.openChange, {
+      detail: {
+        open: this.open
+      },
+      bubbles: true,
+      composed: true
+    }));
+    // Reflect dialog modality for SRs even when toggled via attribute
+    this.elementInternals.ariaModal = this.open ? "true" : "false";
+    // Registry is managed by show()/hide() only
+  }
+  /**
+   * Reduces tabbable items to a list of elements.
+   * @private
+   * @param {HTMLElement[]} elements - The current list of elements.
+   * @param {FASTElement} element - The current element to check.
+   * @returns {HTMLElement[]}
+   */
+  reduceTabbableItems(elements, element) {
+    const host = element;
+    // Include direct focusables or hosts with tabbables in shadow
+    const shouldPush = isTabbable(host) || TeachingBubble.isFocusableFastElement(element);
+    if (shouldPush) {
+      elements.push(host);
+    }
+    // Traverse light DOM children
+    elements = Array.from(element.children).reduce((acc, child) => this.reduceTabbableItems(acc, child), elements);
+    // Traverse shadow DOM children if present
+    const sr = host.shadowRoot;
+    if (sr) {
+      elements = Array.from(sr.children).reduce((acc, child) => this.reduceTabbableItems(acc, child), elements);
+    }
+    return elements;
+  }
+  /**
+   * Determines if a FAST element is focusable.
+   * @private
+   * @static
+   * @param {FASTElement} element - The element to check.
+   * @returns {boolean}
+   */
+  static isFocusableFastElement(element) {
+    var _a, _b;
+    return !!((_b = (_a = element.$fastController) === null || _a === void 0 ? void 0 : _a.definition.shadowOptions) === null || _b === void 0 ? void 0 : _b.delegatesFocus);
+  }
+  /**
+   * Handles the trap focus disable state.
+   * @private
+   */
+  disableTrapFocusHandler() {
+    if (this.disableTrapFocus) {
+      this.trapFocus = false;
+    } else {
+      this.trapFocus = true;
+    }
+  }
+  /**
+   * Initializes the position of the teaching bubble.
+   * @private
+   */
+  initializePosition() {
+    this.setElements();
+    if (this.open) {
+      // Let show() handle missing refs gracefully; don't force-close
+      this.show();
+    } else {
+      this.hide();
+    }
+  }
 }
-__decorate([
-    attr({ mode: "fromView" })
-], TeachingBubble.prototype, "target", void 0);
-__decorate([
-    attr({ mode: "fromView" })
-], TeachingBubble.prototype, "placement", void 0);
-__decorate([
-    attr({ mode: "boolean" })
-], TeachingBubble.prototype, "open", void 0);
-__decorate([
-    attr({ mode: "boolean", attribute: "disable-trap-focus" })
-], TeachingBubble.prototype, "disableTrapFocus", void 0);
-__decorate([
-    attr({ mode: "fromView" })
-], TeachingBubble.prototype, "size", void 0);
-__decorate([
-    observable
-], TeachingBubble.prototype, "targetEl", void 0);
-__decorate([
-    observable
-], TeachingBubble.prototype, "currentEl", void 0);
-__decorate([
-    observable
-], TeachingBubble.prototype, "arrowEl", void 0);
-__decorate([
-    observable
-], TeachingBubble.prototype, "isTrappingFocus", void 0);
-__decorate([
-    observable
-], TeachingBubble.prototype, "trapFocus", void 0);
-__decorate([
-    observable
-], TeachingBubble.prototype, "cleanAutoUpdate", void 0);
-//# sourceMappingURL=teaching-bubble.js.map
+/**
+ * Static registry of open TeachingBubble instances.
+ */
+TeachingBubble.openInstances = new Set();
+__decorate([attr({
+  mode: "fromView"
+})], TeachingBubble.prototype, "target", void 0);
+__decorate([attr({
+  mode: "reflect"
+})], TeachingBubble.prototype, "placement", void 0);
+__decorate([attr({
+  mode: "boolean"
+})], TeachingBubble.prototype, "open", void 0);
+__decorate([attr({
+  mode: "boolean",
+  attribute: "disable-trap-focus"
+})], TeachingBubble.prototype, "disableTrapFocus", void 0);
+__decorate([attr({
+  mode: "reflect"
+})], TeachingBubble.prototype, "size", void 0);
+
+export { TeachingBubble };