@adobe/spectrum-wc-core 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/components/popover/Popover.base.js

@@ -1,11 +1,11 @@
 import { __decorate as e } from "../../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { POPOVER_VALID_PLACEMENTS as t, POPOVER_VALID_SIZES as n } from "./Popover.types.js";
 import { property as r } from "lit/decorators.js";
-import { PageScrollLockController as i, PlacementController as a } from "@adobe/spectrum-wc-core/controllers/index.js";
-import { SpectrumElement as o } from "@adobe/spectrum-wc-core/element/index.js";
-import { deepContains as s, getActiveElement as c, isTopDismissible as l, physicalSide as u, registerDismissible as d, resolveTrigger as f, runAfterTransition as p, unregisterDismissible as m } from "@adobe/spectrum-wc-core/utils/index.js";
+import { PageScrollLockController as i, PlacementController as a, TriggerPressController as o } from "@adobe/spectrum-wc-core/controllers/index.js";
+import { SpectrumElement as s } from "@adobe/spectrum-wc-core/element/index.js";
+import { deepContains as c, getActiveElement as l, isTopDismissible as u, physicalSide as d, registerDismissible as f, resolveTrigger as p, runAfterTransition as m, unregisterDismissible as h, validateEnum as g, warnIf as _ } from "@adobe/spectrum-wc-core/utils/index.js";
 //#region components/popover/Popover.base.ts
-var h, g = [
+var v, y = [
 	"placement",
 	"offset",
 	"crossOffset",
@@ -14,40 +14,22 @@ var h, g = [
 	"hideArrow",
 	"tipPadding",
 	"size"
-], _ = class extends o {
+], b = class extends s {
 	constructor(...e) {
-		super(...e), this.open = !1, this.modal = !1, this.accessibleLabel = "", this.placement = "bottom", this.hideArrow = !1, this.offset = 8, this.crossOffset = 0, this.containerPadding = 8, this.shouldFlip = !0, this.tipPadding = 8, this.triggerElement = null, this.manual = !1, this._placementController = new a(this), this._scrollLock = new i(this), this._interactiveElement = null, this._anchor = null, this._clickTrigger = null, this._triggerPointerActive = !1, this._pressEndAbort = null, this._dismissedByTriggerPress = !1, this._closeSource = null, this._syncingOpen = !1, this._suppressOpenEvent = !1, this._hasCompletedFirstUpdate = !1, this._pendingFocusOnOpen = !1, this._onTriggerPressStart = () => {
-			this._triggerPointerActive = !0, this._pressEndAbort = new AbortController();
-			let { signal: e } = this._pressEndAbort;
-			document.addEventListener("pointerup", this._onTriggerPressEnd, {
-				capture: !0,
-				once: !0,
-				signal: e
-			}), document.addEventListener("pointercancel", this._onTriggerPressEnd, {
-				capture: !0,
-				once: !0,
-				signal: e
-			});
-		}, this._onTriggerPressEnd = (e) => {
-			var t;
-			(t = this._pressEndAbort) == null || t.abort(), !(e.type === "pointerup" && e.composedPath().includes(this._clickTrigger)) && (this._triggerPointerActive = !1);
-		}, this._onTriggerClick = () => {
-			let e = this._dismissedByTriggerPress;
-			this._triggerPointerActive = !1, this._dismissedByTriggerPress = !1, !e && (this.open = !this.open);
-		}, this._onBeforeToggle = (e) => {
+		super(...e), this.open = !1, this.modal = !1, this.accessibleLabel = "", this.placement = "bottom", this.hideArrow = !1, this.offset = 8, this.crossOffset = 0, this.containerPadding = 8, this.shouldFlip = !0, this.tipPadding = 8, this.triggerElement = null, this.manual = !1, this._placementController = new a(this), this._scrollLock = new i(this), this._interactiveElement = null, this._anchor = null, this._pressGuard = new o(this), this._closeSource = null, this._syncingOpen = !1, this._suppressOpenEvent = !1, this._hasCompletedFirstUpdate = !1, this._pendingFocusOnOpen = !1, this._onBeforeToggle = (e) => {
 			if (e.newState === "open") this._dispatchOpen();
 			else {
 				var t;
 				let e = (t = this._closeSource) == null ? "outside" : t;
-				e === "outside" && this._triggerPointerActive && (this._dismissedByTriggerPress = !0);
+				e === "outside" && this._pressGuard.noteNativeDismiss();
 				let r = this._isFocusWithin();
 				if (this._syncOpen(!1), this._dispatchClose(e), this._closeTeardown(), r) {
 					var n;
-					(n = this._interactiveElement) == null || n.focus();
+					(n = this._interactiveElement) == null || n.focus({ preventScroll: !0 });
 				}
 			}
 		}, this._onCancel = (e) => {
-			if (!l(this)) {
+			if (!u(this)) {
 				e.preventDefault();
 				return;
 			}
@@ -71,15 +53,21 @@ var h, g = [
 	}
 	disconnectedCallback() {
 		var e;
-		super.disconnectedCallback(), this._placementController.stop(), (e = this._cancelAfterTransition) == null || e.call(this), m(this), this._removeEscapeListener(), this._scrollLock.unlock(), this._removeTriggerListeners(), this._clearTriggerAria(), this._interactiveElement = null, this._anchor = null;
+		super.disconnectedCallback(), this._placementController.stop(), (e = this._cancelAfterTransition) == null || e.call(this), h(this), this._removeEscapeListener(), this._scrollLock.unlock(), this._clearTriggerAria(), this._interactiveElement = null, this._anchor = null;
 	}
 	update(e) {
-		var t;
-		if ((t = window.__swc) != null && t.DEBUG) {
-			let e = this.constructor;
-			e.VALID_PLACEMENTS.includes(this.placement) || window.__swc.warn(this, `<${this.localName}> element expects the "placement" attribute to be one of the following:`, "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs", { issues: [...e.VALID_PLACEMENTS] });
-		}
-		super.update(e);
+		let t = this.constructor;
+		g(this, {
+			prop: "placement",
+			value: this.placement,
+			valid: t.VALID_PLACEMENTS,
+			url: "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs"
+		}), this.size !== void 0 && g(this, {
+			prop: "size",
+			value: this.size,
+			valid: t.VALID_SIZES,
+			url: "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs"
+		}), super.update(e);
 	}
 	updated(e) {
 		if (super.updated(e), (e.has("for") || e.has("triggerElement") || e.has("modal") || e.has("manual")) && this._wireTrigger(), e.has("open")) {
@@ -89,28 +77,21 @@ var h, g = [
 		this._hasCompletedFirstUpdate = !0;
 	}
 	_positioningChanged(e) {
-		return g.some((t) => e.has(t));
+		return y.some((t) => e.has(t));
 	}
 	_wireTrigger() {
-		var e;
-		let { trigger: t, interactiveElement: n } = f(this, {
+		let { trigger: e, interactiveElement: t } = p(this, {
 			for: this.for,
 			triggerElement: this.triggerElement instanceof HTMLElement ? this.triggerElement : null
 		});
-		!t && this.for && (e = window.__swc) != null && e.DEBUG && window.__swc.warn(this, `<${this.localName}> for="${this.for}" did not resolve to an element in the current tree root. Check that the referenced id exists in the same document tree root.`, "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs", { level: "high" }), this._interactiveElement && this._interactiveElement !== n && this._clearTriggerAria(), this._interactiveElement = n, this._anchor = this.triggerElement && !(this.triggerElement instanceof HTMLElement) ? this.triggerElement : t, n && (n.ariaControlsElements = [this], n.setAttribute("aria-expanded", String(this.open)), n.setAttribute("aria-haspopup", "dialog"));
-		let r = this.manual ? null : t;
-		r !== this._clickTrigger && (this._removeTriggerListeners(), r && (r.addEventListener("pointerdown", this._onTriggerPressStart, { capture: !0 }), r.addEventListener("touchstart", this._onTriggerPressStart, { capture: !0 }), r.addEventListener("click", this._onTriggerClick), this._clickTrigger = r));
-	}
-	_removeTriggerListeners() {
-		var e, t, n;
-		(e = this._clickTrigger) == null || e.removeEventListener("pointerdown", this._onTriggerPressStart, { capture: !0 }), (t = this._clickTrigger) == null || t.removeEventListener("touchstart", this._onTriggerPressStart, { capture: !0 }), (n = this._clickTrigger) == null || n.removeEventListener("click", this._onTriggerClick), this._clickTrigger = null;
+		_(this, !e && !!this.for, `<${this.localName}> for="${this.for}" did not resolve to an element in the current tree root. Check that the referenced id exists in the same document tree root.`, "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs", { level: "high" }), this._interactiveElement && this._interactiveElement !== t && this._clearTriggerAria(), this._interactiveElement = t, this._anchor = this.triggerElement && !(this.triggerElement instanceof HTMLElement) ? this.triggerElement : e, t && (t.ariaControlsElements = [this], t.setAttribute("aria-expanded", String(this.open)), t.setAttribute("aria-haspopup", "dialog")), this._pressGuard.attach(this.manual ? null : e, { onToggle: () => this.open = !this.open });
 	}
 	_clearTriggerAria() {
 		let e = this._interactiveElement;
 		e && (e.ariaControlsElements = null, e.removeAttribute("aria-expanded"), e.removeAttribute("aria-haspopup"));
 	}
 	_isFocusWithin() {
-		return s(this, c());
+		return c(this, l());
 	}
 	_startPositioning() {
 		var e;
@@ -129,39 +110,38 @@ var h, g = [
 			tipElement: n ? (e = this.tipElement) == null ? void 0 : e : void 0,
 			tipPadding: this.tipPadding,
 			onPlacementChange: (e) => {
-				this.setAttribute("actual-placement", u(e)), this._pendingFocusOnOpen && (this._pendingFocusOnOpen = !1, this._focusSurface());
+				this.setAttribute("actual-placement", d(e)), this._pendingFocusOnOpen && (this._pendingFocusOnOpen = !1, this._focusSurface());
 			}
 		});
 	}
 	_show(e = !1) {
-		var t;
-		let n = this.internalElement;
-		if (n) {
-			if ((t = window.__swc) != null && t.DEBUG && !this.accessibleLabel.trim() && window.__swc.warn(this, `<${this.localName}> must have an "accessible-label" attribute to name the dialog for assistive technology.`, "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs", { issues: ["accessible-label"] }), this.modal) {
-				let t = n, r = t.open;
+		let t = this.internalElement;
+		if (t) {
+			if (_(this, !this.accessibleLabel.trim(), `<${this.localName}> must have an "accessible-label" attribute to name the dialog for assistive technology.`, "https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs", { issues: ["accessible-label"] }), this.modal) {
+				let n = t, r = n.open;
 				if (!r) {
-					let { scrollX: e, scrollY: n } = window;
+					let { scrollX: e, scrollY: t } = window;
 					try {
-						t.showModal(), r = !0;
+						n.showModal(), r = !0;
 					} catch (e) {
 						r = !1;
 					}
-					window.scrollTo(e, n);
+					window.scrollTo(e, t);
 				}
 				if (!r) return;
-				this._removeEscapeListener(), this._scrollLock.lock(), d(this), e || this._dispatchOpen();
+				this._removeEscapeListener(), this._scrollLock.lock(), f(this), e || this._dispatchOpen();
 			} else {
-				let t = n.matches(":popover-open");
-				if (!t) {
+				let n = t.matches(":popover-open");
+				if (!n) {
 					this._suppressOpenEvent = e;
 					try {
-						n.showPopover(), t = !0;
+						t.showPopover(), n = !0;
 					} catch (e) {
-						this._suppressOpenEvent = !1, t = !1;
+						this._suppressOpenEvent = !1, n = !1;
 					}
 				}
-				if (!t) return;
-				this._scrollLock.unlock(), d(this), this._addEscapeListener(), this._pendingFocusOnOpen = this._hasCompletedFirstUpdate;
+				if (!n) return;
+				this._scrollLock.unlock(), f(this), this._addEscapeListener(), this._pendingFocusOnOpen = this._hasCompletedFirstUpdate;
 			}
 			this._startPositioning();
 		}
@@ -185,7 +165,7 @@ var h, g = [
 		}
 	}
 	_closeTeardown() {
-		m(this), this._removeEscapeListener(), this._scrollLock.unlock();
+		h(this), this._removeEscapeListener(), this._scrollLock.unlock();
 	}
 	_stopPositioningWhenClosed() {
 		this.open || (this._placementController.stop(), this.removeAttribute("actual-placement"));
@@ -195,7 +175,7 @@ var h, g = [
 	}
 	_addEscapeListener() {
 		this._escapeListener || (this._escapeListener = (e) => {
-			e.key === "Escape" && l(this) && (this._closeSource = "escape");
+			e.key === "Escape" && u(this) && (this._closeSource = "escape");
 		}, document.addEventListener("keydown", this._escapeListener, { capture: !0 }));
 	}
 	_removeEscapeListener() {
@@ -236,48 +216,48 @@ var h, g = [
 			e();
 			return;
 		}
-		this._cancelAfterTransition = p(r, () => {
+		this._cancelAfterTransition = m(r, () => {
 			this._cancelAfterTransition = void 0, e();
 		}, { fallback: t });
 	}
 };
-h = _, h.VALID_PLACEMENTS = t, h.VALID_SIZES = n, e([r({
+v = b, v.VALID_PLACEMENTS = t, v.VALID_SIZES = n, e([r({
 	type: Boolean,
 	reflect: !0
-})], _.prototype, "open", void 0), e([r({
+})], b.prototype, "open", void 0), e([r({
 	type: Boolean,
 	reflect: !0
-})], _.prototype, "modal", void 0), e([r({
+})], b.prototype, "modal", void 0), e([r({
 	type: String,
 	attribute: "accessible-label"
-})], _.prototype, "accessibleLabel", void 0), e([r({
+})], b.prototype, "accessibleLabel", void 0), e([r({
 	type: String,
 	reflect: !0
-})], _.prototype, "placement", void 0), e([r({
+})], b.prototype, "placement", void 0), e([r({
 	type: String,
 	reflect: !0
-})], _.prototype, "size", void 0), e([r({
+})], b.prototype, "size", void 0), e([r({
 	type: Boolean,
 	reflect: !0,
 	attribute: "hide-arrow"
-})], _.prototype, "hideArrow", void 0), e([r({ type: Number })], _.prototype, "offset", void 0), e([r({
+})], b.prototype, "hideArrow", void 0), e([r({ type: Number })], b.prototype, "offset", void 0), e([r({
 	type: Number,
 	attribute: "cross-offset"
-})], _.prototype, "crossOffset", void 0), e([r({
+})], b.prototype, "crossOffset", void 0), e([r({
 	type: Number,
 	attribute: "container-padding"
-})], _.prototype, "containerPadding", void 0), e([r({
+})], b.prototype, "containerPadding", void 0), e([r({
 	type: Boolean,
 	reflect: !0,
 	attribute: "should-flip"
-})], _.prototype, "shouldFlip", void 0), e([r({
+})], b.prototype, "shouldFlip", void 0), e([r({
 	type: Number,
 	attribute: "tip-padding"
-})], _.prototype, "tipPadding", void 0), e([r({ type: String })], _.prototype, "for", void 0), e([r({ attribute: !1 })], _.prototype, "triggerElement", void 0), e([r({
+})], b.prototype, "tipPadding", void 0), e([r({ type: String })], b.prototype, "for", void 0), e([r({ attribute: !1 })], b.prototype, "triggerElement", void 0), e([r({
 	type: Boolean,
 	reflect: !0
-})], _.prototype, "manual", void 0);
+})], b.prototype, "manual", void 0);
 //#endregion
-export { _ as PopoverBase };
+export { b as PopoverBase };
 
 //# sourceMappingURL=Popover.base.js.map

package/dist/components/popover/Popover.base.js.map

@@ -1 +1 @@
-{"version":3,"file":"Popover.base.js","names":[],"sources":["../../../components/popover/Popover.base.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { PropertyValues } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nimport {\n  PageScrollLockController,\n  PlacementController,\n  type VirtualTrigger,\n} from '@adobe/spectrum-wc-core/controllers/index.js';\nimport { SpectrumElement } from '@adobe/spectrum-wc-core/element/index.js';\nimport {\n  deepContains,\n  getActiveElement,\n  isTopDismissible,\n  physicalSide,\n  registerDismissible,\n  resolveTrigger,\n  runAfterTransition,\n  unregisterDismissible,\n} from '@adobe/spectrum-wc-core/utils/index.js';\n\nimport {\n  type Placement,\n  POPOVER_VALID_PLACEMENTS,\n  POPOVER_VALID_SIZES,\n  type PopoverCloseSource,\n  type PopoverSize,\n} from './Popover.types.js';\n\n/**\n * The `aria-controls` relationship is wired via the element-reference IDL\n * (`ariaControlsElements`) so it works across shadow boundaries. The property\n * is Baseline but not yet in every TypeScript DOM lib, so it is declared here.\n */\ninterface ARIAControlsElements {\n  ariaControlsElements?: readonly Element[] | null;\n}\n\n/** Properties whose change re-anchors the surface while open. */\nconst POSITIONING_PROPERTIES = [\n  'placement',\n  'offset',\n  'crossOffset',\n  'containerPadding',\n  'shouldFlip',\n  'hideArrow',\n  'tipPadding',\n  'size',\n] as const;\n\n/**\n * Abstract base for the popover component. Owns the popover's behavior: the\n * dual-mode dialog lifecycle (`showPopover()` / `showModal()`), trigger and ARIA\n * wiring, positioning through the `PlacementController`, dismissal coordination,\n * and `swc-*` event dispatch. The concrete SWC subclass adds only the styles, the\n * render template, and the shadow-DOM element getters (`internalElement`,\n * `tipElement`) it overrides.\n *\n * @slot - Popover content. Free-form; consumers slot whatever pattern they build.\n */\nexport abstract class PopoverBase extends SpectrumElement {\n  /**\n   * @internal\n   *\n   * The valid placement values for the popover. Narrowed in downstream\n   * first-party subclasses per the proxy pattern.\n   */\n  static readonly VALID_PLACEMENTS: readonly Placement[] =\n    POPOVER_VALID_PLACEMENTS;\n\n  /**\n   * @internal\n   *\n   * The valid fixed sizes for the popover.\n   */\n  static readonly VALID_SIZES: readonly PopoverSize[] = POPOVER_VALID_SIZES;\n\n  /**\n   * Whether the popover is open.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true })\n  public open = false;\n\n  /**\n   * Opt in to blocking modal behavior (`<dialog>.showModal()`): focus trap,\n   * background inert, native `role=\"dialog\"`. When unset, the popover uses\n   * `popover=\"auto\"` light-dismiss behavior.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true })\n  public modal = false;\n\n  /**\n   * Accessible name for the popover's dialog surface, forwarded as `aria-label`\n   * to the internal element. Required in both modes (the surface is a dialog);\n   * the component dev-warns when opened without one.\n   */\n  @property({ type: String, attribute: 'accessible-label' })\n  public accessibleLabel = '';\n\n  /**\n   * The placement of the popover relative to its trigger.\n   *\n   * @default 'bottom'\n   */\n  @property({ type: String, reflect: true })\n  public placement: Placement = 'bottom';\n\n  /**\n   * Optional fixed size. When set, the popover uses a fixed inline size\n   * (`s` → 336px, `m` → 416px, `l` → 576px); when unset, it fits its contents.\n   */\n  @property({ type: String, reflect: true })\n  public size?: PopoverSize;\n\n  // The flipped placement is kept off the public property surface (a readonly\n  // property is still writable at runtime and could desync from the controller).\n  // It is reflected as the internal `actual-placement` host attribute for CSS\n  // only, mirroring Tooltip; consumers read the requested side via `placement`.\n\n  /**\n   * Hide the popover's arrow (tip). The arrow is shown by default.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true, attribute: 'hide-arrow' })\n  public hideArrow = false;\n\n  /**\n   * Main-axis offset in pixels from the trigger.\n   *\n   * @default 8\n   */\n  @property({ type: Number })\n  public offset = 8;\n\n  /**\n   * Cross-axis offset in pixels from the trigger.\n   *\n   * @default 0\n   */\n  @property({ type: Number, attribute: 'cross-offset' })\n  public crossOffset = 0;\n\n  /**\n   * Distance from the viewport edge for the `flip` and `shift` middleware.\n   *\n   * Positioning implementation detail. Set by first-party components; excluded\n   * from the public API. Users are not expected to set it.\n   *\n   * @internal\n   * @default 8\n   */\n  @property({ type: Number, attribute: 'container-padding' })\n  public containerPadding = 8;\n\n  /**\n   * Allow the popover to flip to the opposite side when constrained. When\n   * `false`, the popover stays in the requested placement.\n   *\n   * @default true\n   */\n  @property({ type: Boolean, reflect: true, attribute: 'should-flip' })\n  public shouldFlip = true;\n\n  /**\n   * Minimum inset of the tip from the popover's corners, passed to the\n   * `PlacementController`'s `arrow` middleware as its `padding`.\n   *\n   * Positioning implementation detail. Set by first-party components; excluded\n   * from the public API. Users are not expected to set it.\n   *\n   * @internal\n   * @default 8\n   */\n  @property({ type: Number, attribute: 'tip-padding' })\n  public tipPadding = 8;\n\n  /**\n   * ID of the trigger element in the same document tree root.\n   */\n  @property({ type: String })\n  public for?: string;\n\n  /**\n   * Direct trigger reference. Overrides `for` when both are set. Use for\n   * cross-shadow-root triggers or programmatic wiring.\n   */\n  @property({ attribute: false })\n  public triggerElement: HTMLElement | VirtualTrigger | null = null;\n\n  /**\n   * Suppress the automatic click-to-toggle wiring on the resolved trigger. When\n   * set, control visibility through the `open` property instead. ARIA\n   * relationship wiring still applies.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true })\n  public manual = false;\n\n  // ──────────────────────────────\n  //     RENDERING-LAYER HANDLES\n  // ──────────────────────────────\n\n  /**\n   * The internal top-layer element (a `<div popover>` or a `<dialog>`) the\n   * lifecycle drives. Mandatory: the SWC rendering layer must implement this to\n   * return the rendered `.swc-Popover` element from the shadow DOM (it may still\n   * return `null` before the first render, which the lifecycle guards against).\n   */\n  protected abstract get internalElement(): HTMLElement | null;\n\n  /**\n   * The arrow tip element passed to the `PlacementController`. Optional: returns\n   * `null` in the base class (no arrow), and the SWC rendering layer overrides it\n   * to return the rendered `.swc-Popover-tip` element when an arrow is shown.\n   */\n  protected get tipElement(): HTMLElement | null {\n    return null;\n  }\n\n  /**\n   * The arrow's height in pixels, added to the trigger gap when the arrow is\n   * shown. Returns `0` in the base class; the SWC rendering layer overrides it\n   * with the token-derived value so the gap stays in sync with the tip, keeping\n   * the base free of any coupling to the surface's CSS.\n   */\n  protected get arrowHeight(): number {\n    return 0;\n  }\n\n  // ──────────────────\n  //     STATE\n  // ──────────────────\n\n  private _placementController = new PlacementController(this);\n\n  /**\n   * Page-scroll lock for modal mode. Reference-counted at module scope so stacked\n   * modal surfaces coordinate a single lock and restore the original overflow\n   * exactly once. See {@link PageScrollLockController}.\n   */\n  private _scrollLock = new PageScrollLockController(this);\n\n  /** The trigger's AT-facing element that receives ARIA wiring. */\n  private _interactiveElement: (HTMLElement & ARIAControlsElements) | null =\n    null;\n\n  /** The positioning anchor (an element or a `VirtualTrigger`). */\n  private _anchor: HTMLElement | VirtualTrigger | null = null;\n\n  /** The element the click-to-toggle listeners are currently attached to. */\n  private _clickTrigger: HTMLElement | null = null;\n\n  /**\n   * True between a trigger press start (`pointerdown`/`touchstart`) and its\n   * `click`, so a light-dismiss inside that window is attributed to the press.\n   * Both events open it, covering touch (where the dismiss can fire off\n   * `touchstart` before `pointerdown`).\n   */\n  private _triggerPointerActive = false;\n\n  /** Cancels the pending press-end listeners armed in `_onTriggerPressStart`. */\n  private _pressEndAbort: AbortController | null = null;\n\n  /**\n   * Set when the trigger press light-dismissed an open popover (an `'outside'`\n   * close observed while `_triggerPointerActive`), so the trailing `click` of\n   * that same gesture is read as the close rather than a reopen.\n   */\n  private _dismissedByTriggerPress = false;\n\n  /** Cause of the in-progress close, read when dispatching `swc-close`. */\n  private _closeSource: PopoverCloseSource | null = null;\n\n  /** Suppresses the open/close effect when `open` is synced from a native event. */\n  private _syncingOpen = false;\n\n  /**\n   * Suppresses the next `swc-open` dispatch. Set when re-showing an\n   * already-open popover (a `modal` toggle swaps the internal element), so the\n   * mode swap does not emit a second `swc-open` with no intervening close.\n   */\n  private _suppressOpenEvent = false;\n\n  /** Document Escape listener (default mode) used to label the close source. */\n  private _escapeListener?: (event: KeyboardEvent) => void;\n\n  /** Tears down the in-flight `_afterTransition` wiring (listener + fallback timer). */\n  private _cancelAfterTransition?: () => void;\n\n  /**\n   * Set after the first render. Auto-focus on open is suppressed until then so an\n   * initially-`open` popover (server-rendered or a static demo) does not steal\n   * focus on mount; only an open triggered after the element is live moves focus.\n   */\n  private _hasCompletedFirstUpdate = false;\n\n  /**\n   * Set when a default-mode open should move focus into the dialog surface;\n   * consumed by the first placement compute so focus lands after the surface is\n   * anchored on screen (focusing it at its 0,0 reset origin would shift layout).\n   * Modal mode moves focus natively via `showModal()`.\n   */\n  private _pendingFocusOnOpen = false;\n\n  // ──────────────────\n  //     LIFECYCLE\n  // ──────────────────\n\n  public override disconnectedCallback(): void {\n    super.disconnectedCallback();\n    this._placementController.stop();\n    this._cancelAfterTransition?.();\n    unregisterDismissible(this);\n    this._removeEscapeListener();\n    this._scrollLock.unlock();\n    this._removeTriggerListeners();\n    this._clearTriggerAria();\n    this._interactiveElement = null;\n    this._anchor = null;\n    // Focus restoration on close is handled elsewhere (default mode in\n    // `_onBeforeToggle`, modal mode natively). Removing an open popover from the\n    // DOM is not: the browser has already moved focus to `<body>` before this\n    // runs, so there is no trigger to restore to.\n  }\n\n  protected override update(changedProperties: PropertyValues): void {\n    if (window.__swc?.DEBUG) {\n      // Validate against the static so subclasses that narrow the placement set\n      // (the proxy pattern) get their own valid values checked at runtime.\n      const constructor = this.constructor as typeof PopoverBase;\n      if (!constructor.VALID_PLACEMENTS.includes(this.placement)) {\n        window.__swc.warn(\n          this,\n          `<${this.localName}> element expects the \"placement\" attribute to be one of the following:`,\n          'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n          {\n            issues: [...constructor.VALID_PLACEMENTS],\n          }\n        );\n      }\n    }\n    super.update(changedProperties);\n  }\n\n  protected override updated(changedProperties: PropertyValues): void {\n    super.updated(changedProperties);\n\n    if (\n      changedProperties.has('for') ||\n      changedProperties.has('triggerElement') ||\n      changedProperties.has('modal') ||\n      changedProperties.has('manual')\n    ) {\n      this._wireTrigger();\n    }\n\n    if (changedProperties.has('open')) {\n      if (this._syncingOpen) {\n        // The change came from a native event; the element is already in the\n        // right state. Just consume the guard.\n        this._syncingOpen = false;\n      } else if (this.open) {\n        this._show();\n      } else {\n        this._hide();\n      }\n      this._interactiveElement?.setAttribute(\n        'aria-expanded',\n        String(this.open)\n      );\n    } else if (this.open && changedProperties.has('modal')) {\n      // `modal` toggled while open: the render swapped the internal element\n      // between a `<div popover=\"auto\">` and a `<dialog>`. Lit removed the old\n      // element (the browser closes a disconnected top-layer element), so the\n      // newly rendered element is present but never went through its show API.\n      // Re-show so the correct mode engages (e.g. `showModal()` traps focus),\n      // without re-emitting `swc-open` for a popover that never closed.\n      this._show(true);\n    } else if (\n      this.open &&\n      (this._positioningChanged(changedProperties) ||\n        changedProperties.has('for') ||\n        changedProperties.has('triggerElement'))\n    ) {\n      // Re-anchor while open when a positioning input or the trigger changes.\n      this._startPositioning();\n    }\n\n    // First render is done: subsequent opens may move focus into the surface.\n    this._hasCompletedFirstUpdate = true;\n  }\n\n  private _positioningChanged(changedProperties: PropertyValues): boolean {\n    return POSITIONING_PROPERTIES.some((prop) => changedProperties.has(prop));\n  }\n\n  // ──────────────────────────\n  //     TRIGGER + ARIA\n  // ──────────────────────────\n\n  private _wireTrigger(): void {\n    const { trigger, interactiveElement } = resolveTrigger(this, {\n      for: this.for,\n      triggerElement:\n        this.triggerElement instanceof HTMLElement ? this.triggerElement : null,\n    });\n\n    if (!trigger && this.for && window.__swc?.DEBUG) {\n      window.__swc.warn(\n        this,\n        `<${this.localName}> for=\"${this.for}\" did not resolve to an element in the current tree root. Check that the referenced id exists in the same document tree root.`,\n        'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n        { level: 'high' }\n      );\n    }\n\n    if (\n      this._interactiveElement &&\n      this._interactiveElement !== interactiveElement\n    ) {\n      this._clearTriggerAria();\n    }\n\n    this._interactiveElement = interactiveElement;\n    // A `VirtualTrigger` (non-element) anchors positioning only; an element\n    // trigger anchors positioning and carries ARIA.\n    this._anchor =\n      this.triggerElement && !(this.triggerElement instanceof HTMLElement)\n        ? this.triggerElement\n        : trigger;\n\n    if (interactiveElement) {\n      // Durable across open/close cycles; visibility is conveyed by aria-expanded.\n      interactiveElement.ariaControlsElements = [this];\n      interactiveElement.setAttribute('aria-expanded', String(this.open));\n      // The surface is a dialog in both modes, so the trigger always signals it.\n      interactiveElement.setAttribute('aria-haspopup', 'dialog');\n    }\n\n    // Click-to-toggle on the trigger host, unless the consumer drives `open`\n    // themselves (`manual`). Listens on the host so clicks bubbling from an inner\n    // button are caught. The capturing `pointerdown`/`touchstart` listeners open\n    // the reopen-guard gesture window (see `_onTriggerPressStart`).\n    const clickTrigger = this.manual ? null : trigger;\n    if (clickTrigger !== this._clickTrigger) {\n      this._removeTriggerListeners();\n      if (clickTrigger) {\n        clickTrigger.addEventListener(\n          'pointerdown',\n          this._onTriggerPressStart,\n          {\n            capture: true,\n          }\n        );\n        clickTrigger.addEventListener('touchstart', this._onTriggerPressStart, {\n          capture: true,\n        });\n        clickTrigger.addEventListener('click', this._onTriggerClick);\n        this._clickTrigger = clickTrigger;\n      }\n    }\n    // Re-anchoring while open (trigger or positioning input changed) is driven\n    // from `updated()`, so this method only wires the trigger and ARIA. Doing it\n    // here too would double-start the controller when `updated()` also re-shows\n    // or re-anchors in the same cycle (e.g. a `modal` toggle while open).\n  }\n\n  private _removeTriggerListeners(): void {\n    this._clickTrigger?.removeEventListener(\n      'pointerdown',\n      this._onTriggerPressStart,\n      { capture: true }\n    );\n    this._clickTrigger?.removeEventListener(\n      'touchstart',\n      this._onTriggerPressStart,\n      { capture: true }\n    );\n    this._clickTrigger?.removeEventListener('click', this._onTriggerClick);\n    this._clickTrigger = null;\n  }\n\n  // In the default mode, pressing the (outside) trigger while open is a native\n  // light-dismiss: the browser hides the popover before the click fires. Opening\n  // the gesture window at press start (capture, before the dismiss) lets\n  // `_onBeforeToggle` attribute that close to the press, so `_onTriggerClick`\n  // reads the trailing click as a close, not a reopen. Only sets the flag, never\n  // clears `_dismissedByTriggerPress`: on touch both `pointerdown` and\n  // `touchstart` fire for one press, and the second must not reset a dismissal\n  // already recorded (`_onTriggerClick` clears it per gesture).\n  private _onTriggerPressStart = (): void => {\n    this._triggerPointerActive = true;\n    // Catches a press that ends without a click (drag off the trigger, or a\n    // cancelled gesture), which would otherwise leave the flag stuck true.\n    this._pressEndAbort = new AbortController();\n    const { signal } = this._pressEndAbort;\n    document.addEventListener('pointerup', this._onTriggerPressEnd, {\n      capture: true,\n      once: true,\n      signal,\n    });\n    document.addEventListener('pointercancel', this._onTriggerPressEnd, {\n      capture: true,\n      once: true,\n      signal,\n    });\n  };\n\n  private _onTriggerPressEnd = (event: PointerEvent): void => {\n    this._pressEndAbort?.abort();\n    // A same-target pointerup still gets its own click, which resets the flag\n    // itself; resetting it here too would race that click's read of\n    // `_dismissedByTriggerPress`. pointercancel never gets a click, so it\n    // always resets.\n    if (\n      event.type === 'pointerup' &&\n      event.composedPath().includes(this._clickTrigger as EventTarget)\n    ) {\n      return;\n    }\n    this._triggerPointerActive = false;\n  };\n\n  // If the press light-dismissed the popover (recorded in `_onBeforeToggle`),\n  // consume this click so it does not toggle back open; otherwise toggle from the\n  // live state. Keying off the real close event makes this correct with or without\n  // a native dismiss (e.g. keyboard activation) and needs no timer. (`popovertarget`\n  // can't reach the shadow-DOM surface across roots, so the correlation is manual.)\n  private _onTriggerClick = (): void => {\n    const dismissedByThisGesture = this._dismissedByTriggerPress;\n    this._triggerPointerActive = false;\n    this._dismissedByTriggerPress = false;\n    if (dismissedByThisGesture) {\n      return;\n    }\n    this.open = !this.open;\n  };\n\n  private _clearTriggerAria(): void {\n    const element = this._interactiveElement;\n    if (!element) {\n      return;\n    }\n    element.ariaControlsElements = null;\n    element.removeAttribute('aria-expanded');\n    element.removeAttribute('aria-haspopup');\n  }\n\n  // Whether focus is currently within the popover's content. `deepContains`\n  // crosses shadow boundaries, so focus inside a slotted custom element (e.g. a\n  // button's inner control) is detected; the content is slotted, so its DOM\n  // ancestors lead back to this host.\n  private _isFocusWithin(): boolean {\n    return deepContains(this, getActiveElement());\n  }\n\n  // ──────────────────────────\n  //     POSITIONING\n  // ──────────────────────────\n\n  private _startPositioning(): void {\n    const floating = this.internalElement;\n    if (!floating || !this._anchor) {\n      // No element or no anchor to position against (e.g. the trigger was\n      // changed to an unresolved id while open). Tear down any prior session so\n      // the surface is not left anchored to stale geometry; clearing\n      // `actual-placement` also re-gates it hidden until a valid anchor returns.\n      this._placementController.stop();\n      this.removeAttribute('actual-placement');\n      return;\n    }\n    const showArrow = !this.hideArrow;\n    // Clear `actual-placement` to re-gate the surface and tip for this session:\n    // `start()` calls `stop()`, which resets the inline `translate` to the 0,0\n    // origin until the async first compute re-anchors. The stylesheet reveals the\n    // surface and tip only once `actual-placement` is present, so they stay hidden\n    // through that window (and a rapid reopen during the close fade) instead of\n    // painting at 0,0. Re-set by `onPlacementChange` once the session anchors.\n    this.removeAttribute('actual-placement');\n    // Add the arrow height to the trigger gap so the surface clears the tip on\n    // every side. Applied through the controller's direction-aware main-axis\n    // offset, not a CSS margin (a margin only shifts the absolutely-positioned\n    // surface on its block-/inline-start sides). `arrowHeight` comes from the\n    // rendering layer.\n    this._placementController.start(this._anchor, floating, {\n      placement: this.placement,\n      offset: this.offset + (showArrow ? this.arrowHeight : 0),\n      crossOffset: this.crossOffset,\n      containerPadding: this.containerPadding,\n      shouldFlip: this.shouldFlip,\n      tipElement: showArrow ? (this.tipElement ?? undefined) : undefined,\n      tipPadding: this.tipPadding,\n      onPlacementChange: (next) => {\n        // Expose the computed physical side as the `actual-placement` host\n        // attribute for CSS: it orients the tip and, by its presence, reveals the\n        // surface and tip (gated off until now so the entry fade runs from the\n        // anchored position, not the 0,0 origin). The first compute of a session\n        // always fires this (`stop()` resets the last-notified placement). The\n        // controller skips the compute only for a 0x0 element, but the surface\n        // always has border and padded chrome, so it is never zero-sized while\n        // open. Not a public property; removed in `_stopPositioningWhenClosed`.\n        this.setAttribute('actual-placement', physicalSide(next));\n        // Now anchored and revealed: move focus in for a pending default-mode\n        // open. Focusing earlier, at the 0,0 origin, would shift layout/scroll.\n        if (this._pendingFocusOnOpen) {\n          this._pendingFocusOnOpen = false;\n          this._focusSurface();\n        }\n      },\n    });\n  }\n\n  // ──────────────────\n  //     OPEN/CLOSE\n  // ──────────────────\n\n  // `reShow` is true when re-engaging the show API for a popover that is already\n  // open (a `modal` toggle swaps the internal element). It suppresses a second\n  // `swc-open` for a popover that never closed.\n  private _show(reShow = false): void {\n    const element = this.internalElement;\n    if (!element) {\n      return;\n    }\n    // The surface is a dialog in both modes, so it must have an accessible name.\n    if (window.__swc?.DEBUG && !this.accessibleLabel.trim()) {\n      window.__swc.warn(\n        this,\n        `<${this.localName}> must have an \"accessible-label\" attribute to name the dialog for assistive technology.`,\n        'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n        { issues: ['accessible-label'] }\n      );\n    }\n    // Enter the top layer first; only register listeners, the dismissible stack,\n    // and positioning once the native show actually succeeds, so a failed\n    // `showPopover()`/`showModal()` does not leave the component wired up for a\n    // popover that never opened.\n    if (this.modal) {\n      const dialog = element as HTMLDialogElement;\n      let shown = dialog.open;\n      if (!shown) {\n        // `showModal()` synchronously moves focus into the dialog, scrolling the\n        // page to it, and has no `preventScroll` option. Positioning is async, so\n        // the surface is still at its 0,0 origin when focus lands. Capture and\n        // restore the scroll position around the call; it is synchronous, so the\n        // restore is seamless (no paint between).\n        const { scrollX, scrollY } = window;\n        try {\n          dialog.showModal();\n          shown = true;\n        } catch {\n          shown = false;\n        }\n        window.scrollTo(scrollX, scrollY);\n      }\n      if (!shown) {\n        return;\n      }\n      // Modal mode uses the native `<dialog>` Escape (`cancel`); drop any\n      // default-mode document listener left over from a prior mode.\n      this._removeEscapeListener();\n      this._scrollLock.lock();\n      registerDismissible(this);\n      // `<dialog>` modal-mode has no native open event, so dispatch here (unless\n      // this is a re-show of an already-open popover).\n      if (!reShow) {\n        this._dispatchOpen();\n      }\n    } else {\n      let shown = element.matches(':popover-open');\n      if (!shown) {\n        // `showPopover()` fires `beforetoggle` synchronously, which dispatches\n        // `swc-open`; suppress that one dispatch on a re-show.\n        this._suppressOpenEvent = reShow;\n        try {\n          element.showPopover();\n          shown = true;\n        } catch {\n          this._suppressOpenEvent = false;\n          shown = false;\n        }\n      }\n      if (!shown) {\n        return;\n      }\n      // Default mode never locks scroll; release a lock left from a prior modal\n      // mode (e.g. `modal` toggled false while open).\n      this._scrollLock.unlock();\n      registerDismissible(this);\n      this._addEscapeListener();\n      // Move focus into the dialog surface so assistive technology lands inside\n      // it (modal mode does this natively via `showModal()`). Deferred to the\n      // first placement compute so focus lands once the surface is anchored on\n      // screen, not at its 0,0 reset origin. Suppressed on the initial render so\n      // an initially-`open` popover does not steal focus.\n      this._pendingFocusOnOpen = this._hasCompletedFirstUpdate;\n      // `swc-open` is dispatched from the `beforetoggle` listener.\n    }\n    this._startPositioning();\n  }\n\n  // Move focus into the open default-mode dialog surface. The surface is a named\n  // `role=\"dialog\"` element, so focusing it announces the dialog and seats the\n  // user inside it; `preventScroll` because it is already anchored in the top\n  // layer. Focus restoration on close is handled by `_onBeforeToggle`.\n  private _focusSurface(): void {\n    this.internalElement?.focus({ preventScroll: true });\n  }\n\n  private _hide(): void {\n    const element = this.internalElement;\n    if (!element) {\n      return;\n    }\n    // Attribute a close source only when actually hiding an open element. Setting\n    // it unconditionally would poison the next real close: the initial render\n    // calls `_hide()` for the default `open = false`, and a stale `'programmatic'`\n    // source would survive (no `beforetoggle` clears it), making the first genuine\n    // light-dismiss read as non-`outside` and defeating the reopen guard.\n    if (this.modal) {\n      const dialog = element as HTMLDialogElement;\n      if (dialog.open) {\n        this._closeSource ??= 'programmatic';\n        dialog.close();\n      }\n    } else if (element.matches(':popover-open')) {\n      this._closeSource ??= 'programmatic';\n      try {\n        element.hidePopover();\n      } catch {\n        /* already hidden */\n      }\n    }\n  }\n\n  private _closeTeardown(): void {\n    unregisterDismissible(this);\n    this._removeEscapeListener();\n    this._scrollLock.unlock();\n    // `aria-expanded` is written by `updated()` on every `open` change, so it is\n    // not set here. Positioning is frozen at close start (autoUpdate stopped in\n    // `_dispatchClose`) and fully torn down only after the close transition (see\n    // `_stopPositioningWhenClosed`), so the surface and arrow keep their position\n    // and offset during the fade.\n  }\n\n  // Tear down positioning once the close animation has completed. Guarded by\n  // `!this.open` so a rapid re-open during the fade keeps its positioning.\n  private _stopPositioningWhenClosed(): void {\n    if (this.open) {\n      return;\n    }\n    this._placementController.stop();\n    this.removeAttribute('actual-placement');\n  }\n\n  /** Set `open` without re-triggering the show/hide effect. */\n  private _syncOpen(value: boolean): void {\n    if (this.open === value) {\n      return;\n    }\n    this._syncingOpen = true;\n    this.open = value;\n  }\n\n  // ──────────────────────────────\n  //     NATIVE EVENT HANDLERS\n  //   (bound by the SWC render template)\n  // ──────────────────────────────\n\n  // Default mode: the popover-API lifecycle on the internal `<div>`.\n  protected _onBeforeToggle = (event: ToggleEvent): void => {\n    if (event.newState === 'open') {\n      this._dispatchOpen();\n    } else {\n      const source = this._closeSource ?? 'outside';\n      // Attribute an outside light-dismiss that lands during a trigger press to\n      // that press, so `_onTriggerClick` reads the trailing click as the close\n      // rather than a reopen.\n      if (source === 'outside' && this._triggerPointerActive) {\n        this._dismissedByTriggerPress = true;\n      }\n      // `beforetoggle` fires before the popover hides, so focus is still inside if\n      // it was there. Unlike modal `<dialog>` (which restores focus natively), the\n      // popover API drops focus to `<body>` when the focused content is hidden, so\n      // restore it to the trigger. Gated on focus actually being inside our content\n      // so an outside click that moved focus elsewhere is left alone.\n      const restoreFocusToTrigger = this._isFocusWithin();\n      this._syncOpen(false);\n      this._dispatchClose(source);\n      this._closeTeardown();\n      if (restoreFocusToTrigger) {\n        this._interactiveElement?.focus();\n      }\n    }\n  };\n\n  // Modal mode: Escape routes through the native `cancel` event. Honor the\n  // dismissible stack so Escape dismisses the topmost layer first: if something\n  // opened on top of this dialog, cancel the close and let that layer handle the\n  // key. The next Escape, once this dialog is topmost, closes it.\n  protected _onCancel = (event: Event): void => {\n    if (!isTopDismissible(this)) {\n      event.preventDefault();\n      return;\n    }\n    this._closeSource = 'escape';\n  };\n\n  // Modal mode: `close` fires for Escape, backdrop-click, and programmatic close.\n  protected _onClose = (): void => {\n    const source = this._closeSource ?? 'programmatic';\n    this._syncOpen(false);\n    this._dispatchClose(source);\n    this._closeTeardown();\n  };\n\n  // Modal mode: a pointerdown on the dialog's backdrop is an outside dismiss. The\n  // backdrop targets the dialog element itself, as does its own border, so confirm\n  // the point is outside the dialog box before closing; otherwise a press on the\n  // 1px border would dismiss like a backdrop click.\n  protected _onPointerDown = (event: PointerEvent): void => {\n    const dialog = this.internalElement;\n    if (!dialog || event.target !== dialog) {\n      return;\n    }\n    const rect = dialog.getBoundingClientRect();\n    const outsideDialogBox =\n      event.clientX < rect.left ||\n      event.clientX > rect.right ||\n      event.clientY < rect.top ||\n      event.clientY > rect.bottom;\n    if (!outsideDialogBox) {\n      return;\n    }\n    this._closeSource = 'outside';\n    (dialog as HTMLDialogElement).close();\n  };\n\n  private _addEscapeListener(): void {\n    if (this._escapeListener) {\n      return;\n    }\n    this._escapeListener = (event: KeyboardEvent): void => {\n      if (event.key === 'Escape' && isTopDismissible(this)) {\n        this._closeSource = 'escape';\n      }\n    };\n    document.addEventListener('keydown', this._escapeListener, {\n      capture: true,\n    });\n  }\n\n  private _removeEscapeListener(): void {\n    if (!this._escapeListener) {\n      return;\n    }\n    document.removeEventListener('keydown', this._escapeListener, {\n      capture: true,\n    });\n    this._escapeListener = undefined;\n  }\n\n  // ──────────────────\n  //     EVENTS\n  // ──────────────────\n\n  private _dispatchOpen(): void {\n    // A re-show of an already-open popover (modal toggle) must not emit a second\n    // `swc-open`; consume the one-shot suppression set in `_show`.\n    if (this._suppressOpenEvent) {\n      this._suppressOpenEvent = false;\n      return;\n    }\n    this.dispatchEvent(\n      new CustomEvent('swc-open', { bubbles: true, composed: true })\n    );\n    // No fallback timer on open: nothing is gated on `swc-after-open`, so a\n    // delayed (janky) `transitionend` must not be pre-empted by the timer.\n    this._afterTransition(() => {\n      this.dispatchEvent(\n        new CustomEvent('swc-after-open', { bubbles: true, composed: true })\n      );\n    }, false);\n  }\n\n  private _dispatchClose(source: PopoverCloseSource): void {\n    // Freeze positioning at the current location the moment the close begins.\n    // `stop()` tears down the `autoUpdate` loop but leaves the inline `translate`\n    // and `actual-placement` in place, so the surface fades out from where it is.\n    // `beforetoggle` fires before the surface hides, so this runs before the fade.\n    // Without it, a nested popover keeps auto-updating during its fade: when an\n    // ancestor popover closes and its content collapses, the nested popover's\n    // anchor shifts, `autoUpdate` recomputes, and it flashes to a new position\n    // before disappearing. The attribute and remaining inline styles are cleared\n    // after the transition in `_stopPositioningWhenClosed`.\n    this._placementController.stop();\n    this.dispatchEvent(\n      new CustomEvent('swc-close', {\n        detail: { source },\n        bubbles: true,\n        composed: true,\n      })\n    );\n    this._afterTransition(() => {\n      this.dispatchEvent(\n        new CustomEvent('swc-after-close', { bubbles: true, composed: true })\n      );\n      // Positioning autoUpdate was already frozen at close start; this clears the\n      // now-stale `actual-placement` attribute once the exit transition finishes.\n      this._stopPositioningWhenClosed();\n    });\n    this._closeSource = null;\n  }\n\n  // Run `callback` once the internal element's transition settles (or\n  // immediately when none will run). Each call supersedes the previous\n  // open/close cycle's pending run, so a rapid close-then-reopen never\n  // dispatches a spurious `swc-after-close` after reopening. `fallback` arms the\n  // allow-discrete safety timer (default true; the close path relies on it to\n  // always tear down positioning). Shared with Tooltip via `core/utils`.\n  private _afterTransition(callback: () => void, fallback = true): void {\n    this._cancelAfterTransition?.();\n    const element = this.internalElement;\n    if (!element) {\n      callback();\n      return;\n    }\n    this._cancelAfterTransition = runAfterTransition(\n      element,\n      () => {\n        this._cancelAfterTransition = undefined;\n        callback();\n      },\n      { fallback }\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"Popover.base.js","names":[],"sources":["../../../components/popover/Popover.base.ts"],"sourcesContent":["/**\n * Copyright 2026 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { PropertyValues } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nimport {\n  PageScrollLockController,\n  PlacementController,\n  TriggerPressController,\n  type VirtualTrigger,\n} from '@adobe/spectrum-wc-core/controllers/index.js';\nimport { SpectrumElement } from '@adobe/spectrum-wc-core/element/index.js';\nimport {\n  deepContains,\n  getActiveElement,\n  isTopDismissible,\n  physicalSide,\n  registerDismissible,\n  resolveTrigger,\n  runAfterTransition,\n  unregisterDismissible,\n  validateEnum,\n  warnIf,\n} from '@adobe/spectrum-wc-core/utils/index.js';\n\nimport {\n  type Placement,\n  POPOVER_VALID_PLACEMENTS,\n  POPOVER_VALID_SIZES,\n  type PopoverCloseSource,\n  type PopoverSize,\n} from './Popover.types.js';\n\n/**\n * The `aria-controls` relationship is wired via the element-reference IDL\n * (`ariaControlsElements`) so it works across shadow boundaries. The property\n * is Baseline but not yet in every TypeScript DOM lib, so it is declared here.\n */\ninterface ARIAControlsElements {\n  ariaControlsElements?: readonly Element[] | null;\n}\n\n/** Properties whose change re-anchors the surface while open. */\nconst POSITIONING_PROPERTIES = [\n  'placement',\n  'offset',\n  'crossOffset',\n  'containerPadding',\n  'shouldFlip',\n  'hideArrow',\n  'tipPadding',\n  'size',\n] as const;\n\n/**\n * Abstract base for the popover component. Owns the popover's behavior: the\n * dual-mode dialog lifecycle (`showPopover()` / `showModal()`), trigger and ARIA\n * wiring, positioning through the `PlacementController`, dismissal coordination,\n * and `swc-*` event dispatch. The concrete SWC subclass adds only the styles, the\n * render template, and the shadow-DOM element getters (`internalElement`,\n * `tipElement`) it overrides.\n *\n * @slot - Popover content. Free-form; consumers slot whatever pattern they build.\n */\nexport abstract class PopoverBase extends SpectrumElement {\n  /**\n   * @internal\n   *\n   * The valid placement values for the popover. Narrowed in downstream\n   * first-party subclasses per the proxy pattern.\n   */\n  static readonly VALID_PLACEMENTS: readonly Placement[] =\n    POPOVER_VALID_PLACEMENTS;\n\n  /**\n   * @internal\n   *\n   * The valid fixed sizes for the popover.\n   */\n  static readonly VALID_SIZES: readonly PopoverSize[] = POPOVER_VALID_SIZES;\n\n  /**\n   * Whether the popover is open.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true })\n  public open = false;\n\n  /**\n   * Opt in to blocking modal behavior (`<dialog>.showModal()`): focus trap,\n   * background inert, native `role=\"dialog\"`. When unset, the popover uses\n   * `popover=\"auto\"` light-dismiss behavior.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true })\n  public modal = false;\n\n  /**\n   * Accessible name for the popover's dialog surface, forwarded as `aria-label`\n   * to the internal element. Required in both modes (the surface is a dialog);\n   * the component dev-warns when opened without one.\n   */\n  @property({ type: String, attribute: 'accessible-label' })\n  public accessibleLabel = '';\n\n  /**\n   * The placement of the popover relative to its trigger.\n   *\n   * @default 'bottom'\n   */\n  @property({ type: String, reflect: true })\n  public placement: Placement = 'bottom';\n\n  /**\n   * Optional fixed size. When set, the popover uses a fixed inline size\n   * (`s` → 336px, `m` → 416px, `l` → 576px); when unset, it fits its contents.\n   */\n  @property({ type: String, reflect: true })\n  public size?: PopoverSize;\n\n  // The flipped placement is kept off the public property surface (a readonly\n  // property is still writable at runtime and could desync from the controller).\n  // It is reflected as the internal `actual-placement` host attribute for CSS\n  // only, mirroring Tooltip; consumers read the requested side via `placement`.\n\n  /**\n   * Hide the popover's arrow (tip). The arrow is shown by default.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true, attribute: 'hide-arrow' })\n  public hideArrow = false;\n\n  /**\n   * Main-axis offset in pixels from the trigger.\n   *\n   * @default 8\n   */\n  @property({ type: Number })\n  public offset = 8;\n\n  /**\n   * Cross-axis offset in pixels from the trigger.\n   *\n   * @default 0\n   */\n  @property({ type: Number, attribute: 'cross-offset' })\n  public crossOffset = 0;\n\n  /**\n   * Distance from the viewport edge for the `flip` and `shift` middleware.\n   *\n   * Positioning implementation detail. Set by first-party components; excluded\n   * from the public API. Users are not expected to set it.\n   *\n   * @internal\n   * @default 8\n   */\n  @property({ type: Number, attribute: 'container-padding' })\n  public containerPadding = 8;\n\n  /**\n   * Allow the popover to flip to the opposite side when constrained. When\n   * `false`, the popover stays in the requested placement.\n   *\n   * @default true\n   */\n  @property({ type: Boolean, reflect: true, attribute: 'should-flip' })\n  public shouldFlip = true;\n\n  /**\n   * Minimum inset of the tip from the popover's corners, passed to the\n   * `PlacementController`'s `arrow` middleware as its `padding`.\n   *\n   * Positioning implementation detail. Set by first-party components; excluded\n   * from the public API. Users are not expected to set it.\n   *\n   * @internal\n   * @default 8\n   */\n  @property({ type: Number, attribute: 'tip-padding' })\n  public tipPadding = 8;\n\n  /**\n   * ID of the trigger element in the same document tree root.\n   */\n  @property({ type: String })\n  public for?: string;\n\n  /**\n   * Direct trigger reference. Overrides `for` when both are set. Use for\n   * cross-shadow-root triggers or programmatic wiring.\n   */\n  @property({ attribute: false })\n  public triggerElement: HTMLElement | VirtualTrigger | null = null;\n\n  /**\n   * Suppress the automatic click-to-toggle wiring on the resolved trigger. When\n   * set, control visibility through the `open` property instead. ARIA\n   * relationship wiring still applies.\n   *\n   * @default false\n   */\n  @property({ type: Boolean, reflect: true })\n  public manual = false;\n\n  // ──────────────────────────────\n  //     RENDERING-LAYER HANDLES\n  // ──────────────────────────────\n\n  /**\n   * The internal top-layer element (a `<div popover>` or a `<dialog>`) the\n   * lifecycle drives. Mandatory: the SWC rendering layer must implement this to\n   * return the rendered `.swc-Popover` element from the shadow DOM (it may still\n   * return `null` before the first render, which the lifecycle guards against).\n   */\n  protected abstract get internalElement(): HTMLElement | null;\n\n  /**\n   * The arrow tip element passed to the `PlacementController`. Optional: returns\n   * `null` in the base class (no arrow), and the SWC rendering layer overrides it\n   * to return the rendered `.swc-Popover-tip` element when an arrow is shown.\n   */\n  protected get tipElement(): HTMLElement | null {\n    return null;\n  }\n\n  /**\n   * The arrow's height in pixels, added to the trigger gap when the arrow is\n   * shown. Returns `0` in the base class; the SWC rendering layer overrides it\n   * with the token-derived value so the gap stays in sync with the tip, keeping\n   * the base free of any coupling to the surface's CSS.\n   */\n  protected get arrowHeight(): number {\n    return 0;\n  }\n\n  // ──────────────────\n  //     STATE\n  // ──────────────────\n\n  private _placementController = new PlacementController(this);\n\n  /**\n   * Page-scroll lock for modal mode. Reference-counted at module scope so stacked\n   * modal surfaces coordinate a single lock and restore the original overflow\n   * exactly once. See {@link PageScrollLockController}.\n   */\n  private _scrollLock = new PageScrollLockController(this);\n\n  /** The trigger's AT-facing element that receives ARIA wiring. */\n  private _interactiveElement: (HTMLElement & ARIAControlsElements) | null =\n    null;\n\n  /** The positioning anchor (an element or a `VirtualTrigger`). */\n  private _anchor: HTMLElement | VirtualTrigger | null = null;\n\n  // Click-to-toggle on the resolved trigger, without the surface reopening on\n  // the same click that light-dismissed it (see the controller's own doc for\n  // why that needs dedicated gesture tracking, not just a naive toggle).\n  private readonly _pressGuard = new TriggerPressController(this);\n\n  /** Cause of the in-progress close, read when dispatching `swc-close`. */\n  private _closeSource: PopoverCloseSource | null = null;\n\n  /** Suppresses the open/close effect when `open` is synced from a native event. */\n  private _syncingOpen = false;\n\n  /**\n   * Suppresses the next `swc-open` dispatch. Set when re-showing an\n   * already-open popover (a `modal` toggle swaps the internal element), so the\n   * mode swap does not emit a second `swc-open` with no intervening close.\n   */\n  private _suppressOpenEvent = false;\n\n  /** Document Escape listener (default mode) used to label the close source. */\n  private _escapeListener?: (event: KeyboardEvent) => void;\n\n  /** Tears down the in-flight `_afterTransition` wiring (listener + fallback timer). */\n  private _cancelAfterTransition?: () => void;\n\n  /**\n   * Set after the first render. Auto-focus on open is suppressed until then so an\n   * initially-`open` popover (server-rendered or a static demo) does not steal\n   * focus on mount; only an open triggered after the element is live moves focus.\n   */\n  private _hasCompletedFirstUpdate = false;\n\n  /**\n   * Set when a default-mode open should move focus into the dialog surface;\n   * consumed by the first placement compute so focus lands after the surface is\n   * anchored on screen (focusing it at its 0,0 reset origin would shift layout).\n   * Modal mode moves focus natively via `showModal()`.\n   */\n  private _pendingFocusOnOpen = false;\n\n  // ──────────────────\n  //     LIFECYCLE\n  // ──────────────────\n\n  public override disconnectedCallback(): void {\n    super.disconnectedCallback();\n    this._placementController.stop();\n    this._cancelAfterTransition?.();\n    unregisterDismissible(this);\n    this._removeEscapeListener();\n    this._scrollLock.unlock();\n    this._clearTriggerAria();\n    this._interactiveElement = null;\n    this._anchor = null;\n    // Focus restoration on close is handled elsewhere (default mode in\n    // `_onBeforeToggle`, modal mode natively). Removing an open popover from the\n    // DOM is not: the browser has already moved focus to `<body>` before this\n    // runs, so there is no trigger to restore to.\n  }\n\n  protected override update(changedProperties: PropertyValues): void {\n    // Validate against the static so subclasses that narrow the placement set\n    // (the proxy pattern) get their own valid values checked at runtime.\n    const constructor = this.constructor as typeof PopoverBase;\n    validateEnum(this, {\n      prop: 'placement',\n      value: this.placement,\n      valid: constructor.VALID_PLACEMENTS,\n      url: 'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n    });\n    if (this.size !== undefined) {\n      validateEnum(this, {\n        prop: 'size',\n        value: this.size,\n        valid: constructor.VALID_SIZES,\n        url: 'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n      });\n    }\n    super.update(changedProperties);\n  }\n\n  protected override updated(changedProperties: PropertyValues): void {\n    super.updated(changedProperties);\n\n    if (\n      changedProperties.has('for') ||\n      changedProperties.has('triggerElement') ||\n      changedProperties.has('modal') ||\n      changedProperties.has('manual')\n    ) {\n      this._wireTrigger();\n    }\n\n    if (changedProperties.has('open')) {\n      if (this._syncingOpen) {\n        // The change came from a native event; the element is already in the\n        // right state. Just consume the guard.\n        this._syncingOpen = false;\n      } else if (this.open) {\n        this._show();\n      } else {\n        this._hide();\n      }\n      this._interactiveElement?.setAttribute(\n        'aria-expanded',\n        String(this.open)\n      );\n    } else if (this.open && changedProperties.has('modal')) {\n      // `modal` toggled while open: the render swapped the internal element\n      // between a `<div popover=\"auto\">` and a `<dialog>`. Lit removed the old\n      // element (the browser closes a disconnected top-layer element), so the\n      // newly rendered element is present but never went through its show API.\n      // Re-show so the correct mode engages (e.g. `showModal()` traps focus),\n      // without re-emitting `swc-open` for a popover that never closed.\n      this._show(true);\n    } else if (\n      this.open &&\n      (this._positioningChanged(changedProperties) ||\n        changedProperties.has('for') ||\n        changedProperties.has('triggerElement'))\n    ) {\n      // Re-anchor while open when a positioning input or the trigger changes.\n      this._startPositioning();\n    }\n\n    // First render is done: subsequent opens may move focus into the surface.\n    this._hasCompletedFirstUpdate = true;\n  }\n\n  private _positioningChanged(changedProperties: PropertyValues): boolean {\n    return POSITIONING_PROPERTIES.some((prop) => changedProperties.has(prop));\n  }\n\n  // ──────────────────────────\n  //     TRIGGER + ARIA\n  // ──────────────────────────\n\n  private _wireTrigger(): void {\n    const { trigger, interactiveElement } = resolveTrigger(this, {\n      for: this.for,\n      triggerElement:\n        this.triggerElement instanceof HTMLElement ? this.triggerElement : null,\n    });\n\n    warnIf(\n      this,\n      !trigger && Boolean(this.for),\n      `<${this.localName}> for=\"${this.for}\" did not resolve to an element in the current tree root. Check that the referenced id exists in the same document tree root.`,\n      'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n      { level: 'high' }\n    );\n\n    if (\n      this._interactiveElement &&\n      this._interactiveElement !== interactiveElement\n    ) {\n      this._clearTriggerAria();\n    }\n\n    this._interactiveElement = interactiveElement;\n    // A `VirtualTrigger` (non-element) anchors positioning only; an element\n    // trigger anchors positioning and carries ARIA.\n    this._anchor =\n      this.triggerElement && !(this.triggerElement instanceof HTMLElement)\n        ? this.triggerElement\n        : trigger;\n\n    if (interactiveElement) {\n      // Durable across open/close cycles; visibility is conveyed by aria-expanded.\n      interactiveElement.ariaControlsElements = [this];\n      interactiveElement.setAttribute('aria-expanded', String(this.open));\n      // The surface is a dialog in both modes, so the trigger always signals it.\n      interactiveElement.setAttribute('aria-haspopup', 'dialog');\n    }\n\n    // Click-to-toggle on the trigger host, unless the consumer drives `open`\n    // themselves (`manual`). Listens on the host so clicks bubbling from an\n    // inner button are caught. `attach` is a no-op for an unchanged trigger.\n    this._pressGuard.attach(this.manual ? null : trigger, {\n      onToggle: () => (this.open = !this.open),\n    });\n    // Re-anchoring while open (trigger or positioning input changed) is driven\n    // from `updated()`, so this method only wires the trigger and ARIA. Doing it\n    // here too would double-start the controller when `updated()` also re-shows\n    // or re-anchors in the same cycle (e.g. a `modal` toggle while open).\n  }\n\n  private _clearTriggerAria(): void {\n    const element = this._interactiveElement;\n    if (!element) {\n      return;\n    }\n    element.ariaControlsElements = null;\n    element.removeAttribute('aria-expanded');\n    element.removeAttribute('aria-haspopup');\n  }\n\n  // Whether focus is currently within the popover's content. `deepContains`\n  // crosses shadow boundaries, so focus inside a slotted custom element (e.g. a\n  // button's inner control) is detected; the content is slotted, so its DOM\n  // ancestors lead back to this host.\n  private _isFocusWithin(): boolean {\n    return deepContains(this, getActiveElement());\n  }\n\n  // ──────────────────────────\n  //     POSITIONING\n  // ──────────────────────────\n\n  private _startPositioning(): void {\n    const floating = this.internalElement;\n    if (!floating || !this._anchor) {\n      // No element or no anchor to position against (e.g. the trigger was\n      // changed to an unresolved id while open). Tear down any prior session so\n      // the surface is not left anchored to stale geometry; clearing\n      // `actual-placement` also re-gates it hidden until a valid anchor returns.\n      this._placementController.stop();\n      this.removeAttribute('actual-placement');\n      return;\n    }\n    const showArrow = !this.hideArrow;\n    // Clear `actual-placement` to re-gate the surface and tip for this session:\n    // `start()` calls `stop()`, which resets the inline `translate` to the 0,0\n    // origin until the async first compute re-anchors. The stylesheet reveals the\n    // surface and tip only once `actual-placement` is present, so they stay hidden\n    // through that window (and a rapid reopen during the close fade) instead of\n    // painting at 0,0. Re-set by `onPlacementChange` once the session anchors.\n    this.removeAttribute('actual-placement');\n    // Add the arrow height to the trigger gap so the surface clears the tip on\n    // every side. Applied through the controller's direction-aware main-axis\n    // offset, not a CSS margin (a margin only shifts the absolutely-positioned\n    // surface on its block-/inline-start sides). `arrowHeight` comes from the\n    // rendering layer.\n    this._placementController.start(this._anchor, floating, {\n      placement: this.placement,\n      offset: this.offset + (showArrow ? this.arrowHeight : 0),\n      crossOffset: this.crossOffset,\n      containerPadding: this.containerPadding,\n      shouldFlip: this.shouldFlip,\n      tipElement: showArrow ? (this.tipElement ?? undefined) : undefined,\n      tipPadding: this.tipPadding,\n      onPlacementChange: (next) => {\n        // Expose the computed physical side as the `actual-placement` host\n        // attribute for CSS: it orients the tip and, by its presence, reveals the\n        // surface and tip (gated off until now so the entry fade runs from the\n        // anchored position, not the 0,0 origin). The first compute of a session\n        // always fires this (`stop()` resets the last-notified placement). The\n        // controller skips the compute only for a 0x0 element, but the surface\n        // always has border and padded chrome, so it is never zero-sized while\n        // open. Not a public property; removed in `_stopPositioningWhenClosed`.\n        this.setAttribute('actual-placement', physicalSide(next));\n        // Now anchored and revealed: move focus in for a pending default-mode\n        // open. Focusing earlier, at the 0,0 origin, would shift layout/scroll.\n        if (this._pendingFocusOnOpen) {\n          this._pendingFocusOnOpen = false;\n          this._focusSurface();\n        }\n      },\n    });\n  }\n\n  // ──────────────────\n  //     OPEN/CLOSE\n  // ──────────────────\n\n  // `reShow` is true when re-engaging the show API for a popover that is already\n  // open (a `modal` toggle swaps the internal element). It suppresses a second\n  // `swc-open` for a popover that never closed.\n  private _show(reShow = false): void {\n    const element = this.internalElement;\n    if (!element) {\n      return;\n    }\n    // The surface is a dialog in both modes, so it must have an accessible name.\n    warnIf(\n      this,\n      !this.accessibleLabel.trim(),\n      `<${this.localName}> must have an \"accessible-label\" attribute to name the dialog for assistive technology.`,\n      'https://spectrum-web-components.adobe.com/?path=/docs/components-popover--docs',\n      { issues: ['accessible-label'] }\n    );\n    // Enter the top layer first; only register listeners, the dismissible stack,\n    // and positioning once the native show actually succeeds, so a failed\n    // `showPopover()`/`showModal()` does not leave the component wired up for a\n    // popover that never opened.\n    if (this.modal) {\n      const dialog = element as HTMLDialogElement;\n      let shown = dialog.open;\n      if (!shown) {\n        // `showModal()` synchronously moves focus into the dialog, scrolling the\n        // page to it, and has no `preventScroll` option. Positioning is async, so\n        // the surface is still at its 0,0 origin when focus lands. Capture and\n        // restore the scroll position around the call; it is synchronous, so the\n        // restore is seamless (no paint between).\n        const { scrollX, scrollY } = window;\n        try {\n          dialog.showModal();\n          shown = true;\n        } catch {\n          shown = false;\n        }\n        window.scrollTo(scrollX, scrollY);\n      }\n      if (!shown) {\n        return;\n      }\n      // Modal mode uses the native `<dialog>` Escape (`cancel`); drop any\n      // default-mode document listener left over from a prior mode.\n      this._removeEscapeListener();\n      this._scrollLock.lock();\n      registerDismissible(this);\n      // `<dialog>` modal-mode has no native open event, so dispatch here (unless\n      // this is a re-show of an already-open popover).\n      if (!reShow) {\n        this._dispatchOpen();\n      }\n    } else {\n      let shown = element.matches(':popover-open');\n      if (!shown) {\n        // `showPopover()` fires `beforetoggle` synchronously, which dispatches\n        // `swc-open`; suppress that one dispatch on a re-show.\n        this._suppressOpenEvent = reShow;\n        try {\n          element.showPopover();\n          shown = true;\n        } catch {\n          this._suppressOpenEvent = false;\n          shown = false;\n        }\n      }\n      if (!shown) {\n        return;\n      }\n      // Default mode never locks scroll; release a lock left from a prior modal\n      // mode (e.g. `modal` toggled false while open).\n      this._scrollLock.unlock();\n      registerDismissible(this);\n      this._addEscapeListener();\n      // Move focus into the dialog surface so assistive technology lands inside\n      // it (modal mode does this natively via `showModal()`). Deferred to the\n      // first placement compute so focus lands once the surface is anchored on\n      // screen, not at its 0,0 reset origin. Suppressed on the initial render so\n      // an initially-`open` popover does not steal focus.\n      this._pendingFocusOnOpen = this._hasCompletedFirstUpdate;\n      // `swc-open` is dispatched from the `beforetoggle` listener.\n    }\n    this._startPositioning();\n  }\n\n  // Move focus into the open default-mode dialog surface. The surface is a named\n  // `role=\"dialog\"` element, so focusing it announces the dialog and seats the\n  // user inside it; `preventScroll` because it is already anchored in the top\n  // layer. Focus restoration on close is handled by `_onBeforeToggle`.\n  private _focusSurface(): void {\n    this.internalElement?.focus({ preventScroll: true });\n  }\n\n  private _hide(): void {\n    const element = this.internalElement;\n    if (!element) {\n      return;\n    }\n    // Attribute a close source only when actually hiding an open element. Setting\n    // it unconditionally would poison the next real close: the initial render\n    // calls `_hide()` for the default `open = false`, and a stale `'programmatic'`\n    // source would survive (no `beforetoggle` clears it), making the first genuine\n    // light-dismiss read as non-`outside` and defeating the reopen guard.\n    if (this.modal) {\n      const dialog = element as HTMLDialogElement;\n      if (dialog.open) {\n        this._closeSource ??= 'programmatic';\n        dialog.close();\n      }\n    } else if (element.matches(':popover-open')) {\n      this._closeSource ??= 'programmatic';\n      try {\n        element.hidePopover();\n      } catch {\n        /* already hidden */\n      }\n    }\n  }\n\n  private _closeTeardown(): void {\n    unregisterDismissible(this);\n    this._removeEscapeListener();\n    this._scrollLock.unlock();\n    // `aria-expanded` is written by `updated()` on every `open` change, so it is\n    // not set here. Positioning is frozen at close start (autoUpdate stopped in\n    // `_dispatchClose`) and fully torn down only after the close transition (see\n    // `_stopPositioningWhenClosed`), so the surface and arrow keep their position\n    // and offset during the fade.\n  }\n\n  // Tear down positioning once the close animation has completed. Guarded by\n  // `!this.open` so a rapid re-open during the fade keeps its positioning.\n  private _stopPositioningWhenClosed(): void {\n    if (this.open) {\n      return;\n    }\n    this._placementController.stop();\n    this.removeAttribute('actual-placement');\n  }\n\n  /** Set `open` without re-triggering the show/hide effect. */\n  private _syncOpen(value: boolean): void {\n    if (this.open === value) {\n      return;\n    }\n    this._syncingOpen = true;\n    this.open = value;\n  }\n\n  // ──────────────────────────────\n  //     NATIVE EVENT HANDLERS\n  //   (bound by the SWC render template)\n  // ──────────────────────────────\n\n  // Default mode: the popover-API lifecycle on the internal `<div>`.\n  protected _onBeforeToggle = (event: ToggleEvent): void => {\n    if (event.newState === 'open') {\n      this._dispatchOpen();\n    } else {\n      const source = this._closeSource ?? 'outside';\n      // Attribute an outside light-dismiss that lands during a trigger press\n      // to that press, so the trailing click is read as the close rather\n      // than a reopen (see `TriggerPressController`).\n      if (source === 'outside') {\n        this._pressGuard.noteNativeDismiss();\n      }\n      // `beforetoggle` fires before the popover hides, so focus is still inside if\n      // it was there. Unlike modal `<dialog>` (which restores focus natively), the\n      // popover API drops focus to `<body>` when the focused content is hidden, so\n      // restore it to the trigger. Gated on focus actually being inside our content\n      // so an outside click that moved focus elsewhere is left alone.\n      const restoreFocusToTrigger = this._isFocusWithin();\n      this._syncOpen(false);\n      this._dispatchClose(source);\n      this._closeTeardown();\n      if (restoreFocusToTrigger) {\n        // `preventScroll` so restoring focus does not scroll a trigger that the\n        // user scrolled out of view back into it (matches `_focusSurface`).\n        this._interactiveElement?.focus({ preventScroll: true });\n      }\n    }\n  };\n\n  // Modal mode: Escape routes through the native `cancel` event. Honor the\n  // dismissible stack so Escape dismisses the topmost layer first: if something\n  // opened on top of this dialog, cancel the close and let that layer handle the\n  // key. The next Escape, once this dialog is topmost, closes it.\n  protected _onCancel = (event: Event): void => {\n    if (!isTopDismissible(this)) {\n      event.preventDefault();\n      return;\n    }\n    this._closeSource = 'escape';\n  };\n\n  // Modal mode: `close` fires for Escape, backdrop-click, and programmatic close.\n  protected _onClose = (): void => {\n    const source = this._closeSource ?? 'programmatic';\n    this._syncOpen(false);\n    this._dispatchClose(source);\n    this._closeTeardown();\n  };\n\n  // Modal mode: a pointerdown on the dialog's backdrop is an outside dismiss. The\n  // backdrop targets the dialog element itself, as does its own border, so confirm\n  // the point is outside the dialog box before closing; otherwise a press on the\n  // 1px border would dismiss like a backdrop click.\n  protected _onPointerDown = (event: PointerEvent): void => {\n    const dialog = this.internalElement;\n    if (!dialog || event.target !== dialog) {\n      return;\n    }\n    const rect = dialog.getBoundingClientRect();\n    const outsideDialogBox =\n      event.clientX < rect.left ||\n      event.clientX > rect.right ||\n      event.clientY < rect.top ||\n      event.clientY > rect.bottom;\n    if (!outsideDialogBox) {\n      return;\n    }\n    this._closeSource = 'outside';\n    (dialog as HTMLDialogElement).close();\n  };\n\n  private _addEscapeListener(): void {\n    if (this._escapeListener) {\n      return;\n    }\n    this._escapeListener = (event: KeyboardEvent): void => {\n      if (event.key === 'Escape' && isTopDismissible(this)) {\n        this._closeSource = 'escape';\n      }\n    };\n    document.addEventListener('keydown', this._escapeListener, {\n      capture: true,\n    });\n  }\n\n  private _removeEscapeListener(): void {\n    if (!this._escapeListener) {\n      return;\n    }\n    document.removeEventListener('keydown', this._escapeListener, {\n      capture: true,\n    });\n    this._escapeListener = undefined;\n  }\n\n  // ──────────────────\n  //     EVENTS\n  // ──────────────────\n\n  private _dispatchOpen(): void {\n    // A re-show of an already-open popover (modal toggle) must not emit a second\n    // `swc-open`; consume the one-shot suppression set in `_show`.\n    if (this._suppressOpenEvent) {\n      this._suppressOpenEvent = false;\n      return;\n    }\n    this.dispatchEvent(\n      new CustomEvent('swc-open', { bubbles: true, composed: true })\n    );\n    // No fallback timer on open: nothing is gated on `swc-after-open`, so a\n    // delayed (janky) `transitionend` must not be pre-empted by the timer.\n    this._afterTransition(() => {\n      this.dispatchEvent(\n        new CustomEvent('swc-after-open', { bubbles: true, composed: true })\n      );\n    }, false);\n  }\n\n  private _dispatchClose(source: PopoverCloseSource): void {\n    // Freeze positioning at the current location the moment the close begins.\n    // `stop()` tears down the `autoUpdate` loop but leaves the inline `translate`\n    // and `actual-placement` in place, so the surface fades out from where it is.\n    // `beforetoggle` fires before the surface hides, so this runs before the fade.\n    // Without it, a nested popover keeps auto-updating during its fade: when an\n    // ancestor popover closes and its content collapses, the nested popover's\n    // anchor shifts, `autoUpdate` recomputes, and it flashes to a new position\n    // before disappearing. The attribute and remaining inline styles are cleared\n    // after the transition in `_stopPositioningWhenClosed`.\n    this._placementController.stop();\n    this.dispatchEvent(\n      new CustomEvent('swc-close', {\n        detail: { source },\n        bubbles: true,\n        composed: true,\n      })\n    );\n    this._afterTransition(() => {\n      this.dispatchEvent(\n        new CustomEvent('swc-after-close', { bubbles: true, composed: true })\n      );\n      // Positioning autoUpdate was already frozen at close start; this clears the\n      // now-stale `actual-placement` attribute once the exit transition finishes.\n      this._stopPositioningWhenClosed();\n    });\n    this._closeSource = null;\n  }\n\n  // Run `callback` once the internal element's transition settles (or\n  // immediately when none will run). Each call supersedes the previous\n  // open/close cycle's pending run, so a rapid close-then-reopen never\n  // dispatches a spurious `swc-after-close` after reopening. `fallback` arms the\n  // allow-discrete safety timer (default true; the close path relies on it to\n  // always tear down positioning). Shared with Tooltip via `core/utils`.\n  private _afterTransition(callback: () => void, fallback = true): void {\n    this._cancelAfterTransition?.();\n    const element = this.internalElement;\n    if (!element) {\n      callback();\n      return;\n    }\n    this._cancelAfterTransition = runAfterTransition(\n      element,\n      () => {\n        this._cancelAfterTransition = undefined;\n        callback();\n      },\n      { fallback }\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/components/progress-circle/ProgressCircle.base.d.ts

@@ -76,7 +76,6 @@ export declare abstract class ProgressCircleBase extends ProgressCircleBase_base
     private static clampProgress;
     private formatProgress;
     private warnDeprecatedLightDomChildren;
-    private warnMissingAccessibleName;
     protected willUpdate(changes: PropertyValues): void;
     protected firstUpdated(changes: PropertyValues): void;
     protected updated(changes: PropertyValues): void;

package/dist/components/progress-circle/ProgressCircle.base.js

@@ -3,11 +3,12 @@ import { PROGRESS_CIRCLE_VALID_SIZES as t } from "./ProgressCircle.types.js";
 import { property as n } from "lit/decorators.js";
 import { SpectrumElement as r } from "@adobe/spectrum-wc-core/element/index.js";
 import { SizedMixin as i } from "@adobe/spectrum-wc-core/mixins/index.js";
-import { LanguageResolutionController as a, languageResolverUpdatedSymbol as o } from "@adobe/spectrum-wc-core/controllers/language-resolution.js";
+import { isDebug as a, validateEnum as o, warnIf as s } from "@adobe/spectrum-wc-core/utils/index.js";
+import { LanguageResolutionController as c, languageResolverUpdatedSymbol as l } from "@adobe/spectrum-wc-core/controllers/language-resolution.js";
 //#region components/progress-circle/ProgressCircle.base.ts
-var s, c = class e extends i(r, { validSizes: t }) {
+var u, d = class e extends i(r, { validSizes: t }) {
 	constructor(...e) {
-		super(...e), this.label = "", this.progress = null, this.languageResolver = new a(this);
+		super(...e), this.label = "", this.progress = null, this.languageResolver = new c(this);
 	}
 	static hasMeaningfulLightDomChildren(e) {
 		for (let n of e.childNodes) {
@@ -30,19 +31,7 @@ var s, c = class e extends i(r, { validSizes: t }) {
 		}).format(((e = this.progress) == null ? 0 : e) / 100);
 	}
 	warnDeprecatedLightDomChildren() {
-		var t;
-		(t = window.__swc) != null && t.DEBUG && e.hasMeaningfulLightDomChildren(this) && window.__swc.warn(this, `<${this.localName}> no longer has a default slot. Light DOM children are not rendered and are not used for an accessible name. Use the "label" attribute or property, or "aria-label" / "aria-labelledby" on the host instead.`, "https://opensource.adobe.com/spectrum-web-components/second-gen/?path=/docs/components-progress-circle--docs", { level: "deprecation" });
-	}
-	warnMissingAccessibleName() {
-		var t, n;
-		(t = window.__swc) != null && t.DEBUG && ((n = window.__swc) == null || n.warn(this, `<${this.localName}> requires an accessible name. A default label of "${e.DEFAULT_LABEL}" has been applied, but a more specific label should be provided via:`, "https://opensource.adobe.com/spectrum-web-components/second-gen/?path=/docs/components-progress-circle--docs", {
-			type: "accessibility",
-			issues: [
-				"value supplied to the \"label\" attribute, which will be displayed visually as part of the element, or",
-				"value supplied to the \"aria-label\" attribute, which will only be provided to screen readers, or",
-				"an element ID reference supplied to the \"aria-labelledby\" attribute, which will be provided by screen readers and will need to be managed manually by the parent application."
-			]
-		}));
+		s(this, e.hasMeaningfulLightDomChildren(this), `<${this.localName}> no longer has a default slot. Light DOM children are not rendered and are not used for an accessible name. Use the "label" attribute or property, or "aria-label" / "aria-labelledby" on the host instead.`, "https://spectrum-web-components.adobe.com/?path=/docs/components-progress-circle--docs", { level: "deprecation" });
 	}
 	willUpdate(t) {
 		if (t.has("progress") && this.progress !== null) {
@@ -55,19 +44,34 @@ var s, c = class e extends i(r, { validSizes: t }) {
 		super.firstUpdated(e), this.setAttribute("role", "progressbar");
 	}
 	updated(t) {
-		var n;
-		super.updated(t), t.has("progress") && (this.progress !== null && this.progress >= 0 ? (this.setAttribute("aria-valuemin", "0"), this.setAttribute("aria-valuemax", "100"), this.setAttribute("aria-valuenow", String(this.progress)), this.setAttribute("aria-valuetext", this.formatProgress())) : (this.removeAttribute("aria-valuemin"), this.removeAttribute("aria-valuemax"), this.removeAttribute("aria-valuenow"), this.removeAttribute("aria-valuetext"))), this.progress !== null && t.has(o) && this.setAttribute("aria-valuetext", this.formatProgress()), t.has("label") && (this.label.length ? this.setAttribute("aria-label", this.label) : t.get("label") === this.getAttribute("aria-label") && this.removeAttribute("aria-label")), t.has("label") && !this.hasAccessibleName() && (this.setAttribute("aria-label", e.DEFAULT_LABEL), this.warnMissingAccessibleName()), (n = window.__swc) != null && n.DEBUG && this.warnDeprecatedLightDomChildren();
+		if (super.updated(t), t.has("progress") && (this.progress !== null && this.progress >= 0 ? (this.setAttribute("aria-valuemin", "0"), this.setAttribute("aria-valuemax", "100"), this.setAttribute("aria-valuenow", String(this.progress)), this.setAttribute("aria-valuetext", this.formatProgress())) : (this.removeAttribute("aria-valuemin"), this.removeAttribute("aria-valuemax"), this.removeAttribute("aria-valuenow"), this.removeAttribute("aria-valuetext"))), this.progress !== null && t.has(l) && this.setAttribute("aria-valuetext", this.formatProgress()), t.has("label") && (this.label.length ? this.setAttribute("aria-label", this.label) : t.get("label") === this.getAttribute("aria-label") && this.removeAttribute("aria-label")), t.has("label") && !this.hasAccessibleName() && (this.setAttribute("aria-label", e.DEFAULT_LABEL), s(this, !0, `<${this.localName}> requires an accessible name. A default label of "${e.DEFAULT_LABEL}" has been applied, but a more specific label should be provided via:`, "https://spectrum-web-components.adobe.com/?path=/docs/components-progress-circle--docs", {
+			type: "accessibility",
+			issues: [
+				"value supplied to the \"label\" attribute, which will be displayed visually as part of the element, or",
+				"value supplied to the \"aria-label\" attribute, which will only be provided to screen readers, or",
+				"an element ID reference supplied to the \"aria-labelledby\" attribute, which will be provided by screen readers and will need to be managed manually by the parent application."
+			]
+		})), t.has("staticColor") && this.staticColor !== void 0) {
+			let e = this.constructor;
+			o(this, {
+				prop: "static-color",
+				value: this.staticColor,
+				valid: e.STATIC_COLORS,
+				url: "https://spectrum-web-components.adobe.com/?path=/docs/components-progress-circle--docs"
+			});
+		}
+		a() && this.warnDeprecatedLightDomChildren();
 	}
 };
-s = c, s.DEFAULT_LABEL = "Loading", e([n({
+u = d, u.DEFAULT_LABEL = "Loading", e([n({
 	type: String,
 	reflect: !0,
 	attribute: "static-color"
-})], c.prototype, "staticColor", void 0), e([n({ type: String })], c.prototype, "label", void 0), e([n({
+})], d.prototype, "staticColor", void 0), e([n({ type: String })], d.prototype, "label", void 0), e([n({
 	type: Number,
 	reflect: !0
-})], c.prototype, "progress", void 0);
+})], d.prototype, "progress", void 0);
 //#endregion
-export { c as ProgressCircleBase };
+export { d as ProgressCircleBase };
 
 //# sourceMappingURL=ProgressCircle.base.js.map