@adobe/spectrum-wc-core 0.0.0-snapshot.20260922095923

package/dist/controllers/focusgroup-navigation-controller/src/focusgroup-navigation-controller.js

@@ -0,0 +1,345 @@
+//#region controllers/focusgroup-navigation-controller/src/focusgroup-navigation-controller.ts
+var e = {
+	wrap: !1,
+	memory: !0,
+	skipDisabled: !1
+}, t = 6, n = "swc-focusgroup-navigation-active-change", r = class {
+	constructor(t, n) {
+		this.boundKeydown = this.handleKeydown.bind(this), this.boundFocusin = this.handleFocusin.bind(this), this.boundFocusout = this.handleFocusout.bind(this), this.lastFocused = null, this.previousActive = null, this.isNavigating = !1, this.cachedEligibleItems = null, this.cachedRows = null, this.host = t, this.options = {
+			...e,
+			...n
+		}, t.addController(this);
+	}
+	setOptions(e) {
+		this.options = {
+			...this.options,
+			...e
+		}, this.refresh();
+	}
+	getActiveItem() {
+		for (let e of this.getEligibleItems()) if (e.tabIndex === 0) return e;
+		return null;
+	}
+	refresh() {
+		var e, t;
+		this.cachedEligibleItems = null, this.cachedRows = null;
+		let n = this.getEligibleItems();
+		if (n.length === 0) {
+			for (let e of this.getRawItems()) e.tabIndex = -1;
+			if (this.lastFocused = null, this.previousActive !== null) {
+				var r, i;
+				this.previousActive = null, this.dispatchActiveChange(null, "refresh"), (r = (i = this.options).onActiveItemChange) == null || r.call(i, null);
+			}
+			return;
+		}
+		let a = (e = (t = this.options.memory && this.lastFocused && n.includes(this.lastFocused) ? this.lastFocused : null) == null ? this.getActiveItem() : t) == null ? n[0] : e;
+		this.applyRovingTabindex(a, "refresh");
+	}
+	setActiveItem(e) {
+		return this.getEligibleItems().includes(e) ? (this.applyRovingTabindex(e, "programmatic"), this.options.memory && (this.lastFocused = e), !0) : !1;
+	}
+	focusFirstItemByTextPrefix(e) {
+		let t = e.trim();
+		if (t === "") return !1;
+		let n = t.toLowerCase(), r = this.getEligibleItems().find((e) => this.getItemTypeaheadLabel(e).toLowerCase().startsWith(n));
+		return r ? (this.applyRovingTabindex(r, "programmatic"), !0) : !1;
+	}
+	hostConnected() {
+		this.previousActive = null, this.cachedEligibleItems = null, this.cachedRows = null, this.host.addEventListener("keydown", this.boundKeydown, !0), this.host.addEventListener("focusin", this.boundFocusin, !0), this.host.addEventListener("focusout", this.boundFocusout, !0), this.refresh();
+	}
+	hostDisconnected() {
+		this.host.removeEventListener("keydown", this.boundKeydown, !0), this.host.removeEventListener("focusin", this.boundFocusin, !0), this.host.removeEventListener("focusout", this.boundFocusout, !0);
+	}
+	isRtl() {
+		return getComputedStyle(this.host).direction === "rtl";
+	}
+	isNodeWithinHostScope(e) {
+		if (!e) return !1;
+		let t = this.host, n = e;
+		for (; n;) {
+			if (n === t) return !0;
+			let e = n.parentNode;
+			if (e) n = e;
+			else if (n instanceof ShadowRoot) n = n.host;
+			else return !1;
+		}
+		return !1;
+	}
+	getRawItems() {
+		return this.options.getItems().filter((e) => this.isNodeWithinHostScope(e));
+	}
+	getEligibleItems() {
+		return this.cachedEligibleItems || (this.cachedEligibleItems = this.getRawItems().filter((e) => this.isNavigableItem(e))), this.cachedEligibleItems;
+	}
+	getRows(e) {
+		return this.cachedRows || (this.cachedRows = this.buildRows(e)), this.cachedRows;
+	}
+	isNavigableItem(e) {
+		if (!e.isConnected || e.hasAttribute("inert") || e.closest("[inert]")) return !1;
+		let t = getComputedStyle(e);
+		return !(t.visibility === "hidden" || t.display === "none" || this.options.skipDisabled && this.isDisabledForSkip(e));
+	}
+	isDisabledForSkip(e) {
+		return "disabled" in e && e.disabled ? !0 : e.getAttribute("aria-disabled") === "true";
+	}
+	getItemTypeaheadLabel(e) {
+		var t, n, r, i;
+		let a = (t = e.getAttribute("aria-label")) == null ? void 0 : t.trim();
+		if (a) return a;
+		let o = (n = e.getAttribute("aria-labelledby")) == null ? void 0 : n.trim();
+		if (o) {
+			let t = e.getRootNode(), n = [];
+			for (let r of o.split(/\s+/)) {
+				var s, c;
+				if (!r) continue;
+				let i = t instanceof ShadowRoot ? (s = t.getElementById(r)) == null ? e.ownerDocument.getElementById(r) : s : e.ownerDocument.getElementById(r), a = i == null || (c = i.textContent) == null ? void 0 : c.trim();
+				a && n.push(a);
+			}
+			let r = n.join(" ").trim();
+			if (r) return r;
+		}
+		return (r = (i = e.textContent) == null ? void 0 : i.trim()) == null ? "" : r;
+	}
+	isNativelyDisabled(e) {
+		return "disabled" in e && e.disabled === !0;
+	}
+	applyRovingTabindex(e, t) {
+		let n = this.getEligibleItems(), r = new Set(n);
+		for (let e of this.getRawItems()) r.has(e) || (e.tabIndex = -1);
+		if (n.length === 0) return;
+		let i = r.has(e) ? e : n[0], a = i;
+		if (this.isNativelyDisabled(i)) {
+			var o;
+			i = (o = n.find((e) => !this.isNativelyDisabled(e))) == null ? i : o;
+		}
+		for (let e of n) e === i ? e.tabIndex = 0 : e.tabIndex = -1;
+		if (a !== this.previousActive) {
+			var s, c;
+			this.previousActive = a, this.dispatchActiveChange(a, t), (s = (c = this.options).onActiveItemChange) == null || s.call(c, i);
+		}
+	}
+	dispatchActiveChange(e, t) {
+		this.host.dispatchEvent(new CustomEvent(n, {
+			bubbles: !0,
+			composed: !0,
+			detail: {
+				activeElement: e,
+				source: t
+			}
+		}));
+	}
+	resolveManagedFocusTarget(e, t) {
+		if (t.length === 0) return null;
+		let n = new Set(t);
+		for (let t of e.composedPath()) if (t instanceof HTMLElement) {
+			if (n.has(t)) return t;
+			if (t === this.host) break;
+		}
+		let r = this.host.shadowRoot, i = r == null ? void 0 : r.activeElement;
+		return i instanceof HTMLElement && n.has(i) ? i : null;
+	}
+	handleFocusin(e) {
+		if (this.isNavigating) return;
+		this.cachedEligibleItems = null, this.cachedRows = null;
+		let t = this.getEligibleItems(), n = this.resolveManagedFocusTarget(e, t);
+		n && (this.applyRovingTabindex(n, "focus"), this.options.memory && (this.lastFocused = n));
+	}
+	handleFocusout(e) {
+		let t = e.relatedTarget;
+		if (t instanceof Node && this.isNodeWithinHostScope(t)) return;
+		let n = e.target;
+		if (this.options.memory && n instanceof HTMLElement && this.getRawItems().includes(n) && (this.lastFocused = n), !this.options.memory) {
+			this.cachedEligibleItems = null, this.cachedRows = null;
+			let e = this.getEligibleItems();
+			e.length > 0 && this.applyRovingTabindex(e[0], "focus");
+		}
+	}
+	resolveManagedKeydownTarget(e, t) {
+		if (t.length === 0) return null;
+		let n = new Set(t);
+		for (let t of e.composedPath()) if (t instanceof HTMLElement) {
+			if (n.has(t)) return t;
+			if (t === this.host) break;
+		}
+		let r = this.host.shadowRoot, i = r == null ? void 0 : r.activeElement;
+		return i instanceof HTMLElement && n.has(i) ? i : null;
+	}
+	handleKeydown(e) {
+		if (e.defaultPrevented || e.altKey) return;
+		this.cachedEligibleItems = null, this.cachedRows = null;
+		let t = this.getEligibleItems(), n = this.resolveManagedKeydownTarget(e, t);
+		if (!n) return;
+		let r = this.options.direction === "grid", i = r ? this.getRows(t) : null;
+		if (r && e.ctrlKey && !e.metaKey && (e.key === "Home" || e.key === "End")) {
+			if (i.length > 0) {
+				var a, o;
+				let t = i[0], r = i[i.length - 1], s = e.key === "Home" ? (a = t == null ? void 0 : t[0]) == null ? null : a : (o = r == null ? void 0 : r[r.length - 1]) == null ? null : o;
+				s && s !== n && (e.preventDefault(), this.moveKeyNavigationFocusTo(s));
+			}
+			return;
+		}
+		if (e.ctrlKey || e.metaKey) return;
+		let s = this.getEffectivePageMagnitude();
+		if (s !== null && (e.key === "PageUp" || e.key === "PageDown")) {
+			let r = this.navigatePage(t, n, e.key === "PageDown" ? s : -s, i);
+			r && r !== n && (e.preventDefault(), this.moveKeyNavigationFocusTo(r));
+			return;
+		}
+		let c = this.isRtl(), l = null;
+		switch (this.options.direction) {
+			case "horizontal":
+				l = this.navigateLinear(t, n, e.key, "horizontal", c);
+				break;
+			case "vertical":
+				l = this.navigateLinear(t, n, e.key, "vertical", c);
+				break;
+			case "both":
+				l = this.navigateBothAxes(t, n, e.key, c);
+				break;
+			case "grid":
+				l = this.navigateGrid(n, e.key, c, i);
+				break;
+			default: break;
+		}
+		if (l && l !== n) {
+			e.preventDefault(), this.moveKeyNavigationFocusTo(l);
+			return;
+		}
+		if (e.key === "Home" || e.key === "End") if (r) {
+			let t = this.findGridIndex(i, n);
+			if (!t) return;
+			let r = i[t.row];
+			if (!(r != null && r.length)) return;
+			let a = e.key === "Home" ? r[0] : r[r.length - 1];
+			a && a !== n && (e.preventDefault(), this.moveKeyNavigationFocusTo(a));
+		} else {
+			if (t.length === 0) return;
+			let r = e.key === "Home" ? t[0] : t[t.length - 1];
+			r && r !== n && (e.preventDefault(), this.moveKeyNavigationFocusTo(r));
+		}
+	}
+	moveKeyNavigationFocusTo(e) {
+		this.isNavigating = !0;
+		try {
+			this.getEligibleItems().includes(e) && (this.applyRovingTabindex(e, "keyboard"), this.options.memory && (this.lastFocused = e), e.focus());
+		} finally {
+			this.isNavigating = !1;
+		}
+	}
+	getEffectivePageMagnitude() {
+		let e = this.options.pageStep;
+		if (e === void 0) return null;
+		let t = Math.trunc(Number(e));
+		return !Number.isFinite(t) || t === 0 ? null : Math.abs(t);
+	}
+	navigatePage(e, t, n, r) {
+		return this.options.direction === "grid" ? this.navigatePageGridRows(t, n, r) : this.navigatePageLinearItems(e, t, n);
+	}
+	navigatePageLinearItems(e, t, n) {
+		var r;
+		let i = e.indexOf(t);
+		if (i < 0 || e.length === 0) return null;
+		let a = i + n;
+		if (this.options.wrap) {
+			let t = e.length;
+			a = (a % t + t) % t;
+		} else a = Math.max(0, Math.min(e.length - 1, a));
+		return (r = e[a]) == null ? null : r;
+	}
+	navigatePageGridRows(e, t, n) {
+		var r;
+		if (n.length === 0) return null;
+		let i = this.findGridIndex(n, e);
+		if (!i) return null;
+		let { row: a, col: o } = i, s = a + t;
+		if (this.options.wrap) {
+			let e = n.length;
+			s = (s % e + e) % e;
+		} else s = Math.max(0, Math.min(n.length - 1, s));
+		let c = n[s];
+		return c != null && c.length ? (r = c[Math.min(o, c.length - 1)]) == null ? null : r : null;
+	}
+	navigateLinear(e, t, n, r, i) {
+		var a;
+		let o = e.indexOf(t);
+		if (o < 0) return null;
+		let s = 0;
+		if (r === "horizontal" ? n === "ArrowLeft" ? s = i ? 1 : -1 : n === "ArrowRight" && (s = i ? -1 : 1) : n === "ArrowUp" ? s = -1 : n === "ArrowDown" && (s = 1), s === 0) return null;
+		let c = o + s;
+		if (this.options.wrap) c = (c + e.length) % e.length;
+		else if (c < 0 || c >= e.length) return null;
+		return (a = e[c]) == null ? null : a;
+	}
+	navigateBothAxes(e, t, n, r) {
+		var i;
+		let a = e.indexOf(t);
+		if (a < 0) return null;
+		let o = 0;
+		if (n === "ArrowLeft" ? o = r ? 1 : -1 : n === "ArrowRight" ? o = r ? -1 : 1 : n === "ArrowUp" ? o = -1 : n === "ArrowDown" && (o = 1), o === 0) return null;
+		let s = a + o;
+		if (this.options.wrap) s = (s + e.length) % e.length;
+		else if (s < 0 || s >= e.length) return null;
+		return (i = e[s]) == null ? null : i;
+	}
+	navigateGrid(e, t, n, r) {
+		var i, a;
+		let o = this.findGridIndex(r, e);
+		if (!o) return null;
+		let { row: s, col: c } = o, l = (i = r[s]) == null ? [] : i, u = s, d = c;
+		switch (t) {
+			case "ArrowLeft":
+				d = n ? c + 1 : c - 1;
+				break;
+			case "ArrowRight":
+				d = n ? c - 1 : c + 1;
+				break;
+			case "ArrowUp":
+				u = s - 1;
+				break;
+			case "ArrowDown":
+				u = s + 1;
+				break;
+			default: return null;
+		}
+		if (t === "ArrowLeft" || t === "ArrowRight") {
+			if (d >= 0 && d < l.length) {
+				var f;
+				return (f = l[d]) == null ? null : f;
+			}
+			if (this.options.wrap && l.length > 0) {
+				var p;
+				return (p = l[(d + l.length) % l.length]) == null ? null : p;
+			}
+			return null;
+		}
+		if (u < 0 || u >= r.length) if (this.options.wrap && r.length > 0) u = (u + r.length) % r.length;
+		else return null;
+		let m = r[u];
+		return m != null && m.length ? (a = m[Math.min(c, m.length - 1)]) == null ? null : a : null;
+	}
+	buildRows(e) {
+		let n = [];
+		for (let r of e) {
+			let e = r.getBoundingClientRect().top, i = n.find((n) => Math.abs(n.top - e) <= t);
+			i || (i = {
+				top: e,
+				elements: []
+			}, n.push(i)), i.elements.push(r);
+		}
+		return n.sort((e, t) => e.top - t.top), n.map((e) => e.elements.sort((e, t) => e.getBoundingClientRect().left - t.getBoundingClientRect().left));
+	}
+	findGridIndex(e, t) {
+		for (let n = 0; n < e.length; n++) {
+			let r = e[n].indexOf(t);
+			if (r !== -1) return {
+				row: n,
+				col: r
+			};
+		}
+		return null;
+	}
+};
+//#endregion
+export { r as FocusgroupNavigationController, n as focusgroupNavigationActiveChange };
+
+//# sourceMappingURL=focusgroup-navigation-controller.js.map

package/dist/controllers/focusgroup-navigation-controller/src/focusgroup-navigation-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusgroup-navigation-controller.js","names":[],"sources":["../../../../controllers/focusgroup-navigation-controller/src/focusgroup-navigation-controller.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 type { ReactiveController, ReactiveElement } from 'lit';\n\n// ─────────────────────────\n//     TYPES\n// ─────────────────────────\n\n/**\n * Spatial mode for arrow-key movement. Aligns with logical axes (inline/block) and a\n * 2D layout mode derived from element geometry.\n *\n * - **horizontal**: Arrow keys on the inline axis move focus (respects `dir`).\n * - **vertical**: Arrow keys on the block axis move focus.\n * - **both**: **ArrowLeft** / **ArrowRight** move along `getItems()` order like **horizontal**\n *   (respects `dir`); **ArrowUp** / **ArrowDown** move backward / forward in the same order.\n * - **grid**: Arrow keys move in rows and columns using bounding-rect layout; Ctrl+Home / Ctrl+End\n *   jump to the first cell of the first row or the last cell of the last row.\n */\nexport type FocusgroupDirection = 'horizontal' | 'vertical' | 'both' | 'grid';\n\n/**\n * Options for {@link FocusgroupNavigationController}.\n */\nexport type FocusgroupNavigationOptions = {\n  /**\n   * Returns the current set of items that participate in roving tabindex and\n   * directional navigation. Callers typically close over the host (for example\n   * querying slotted or shadow DOM children).\n   */\n  getItems: () => HTMLElement[];\n\n  /**\n   * Determines which arrow keys move focus and how grid navigation is computed.\n   * Use **`both`** when the same linear order should respond to horizontal and vertical arrow keys.\n   */\n  direction: FocusgroupDirection;\n\n  /**\n   * When true, arrow keys wrap from the last item to the first (and reverse).\n   * Defaults to false.\n   */\n  wrap?: boolean;\n\n  /**\n   * When true, restoring focus into the composite (for example with Tab) targets\n   * the item that was last focused, if it is still a member of the group.\n   * Similar to the default memory behavior described for `focusgroup` in Open UI.\n   * Defaults to true.\n   */\n  memory?: boolean;\n\n  /**\n   * When true, both natively `disabled` and `aria-disabled=\"true\"` items are\n   * skipped for arrow navigation and are not chosen as the roving tab stop.\n   * When false (default), disabled items remain in sequence — useful for\n   * patterns such as menus where disabled items may still be focusable per\n   * APG guidance.\n   *\n   * **Note:** Regardless of this flag, natively `disabled` elements are never\n   * chosen as the roving tab stop (`tabindex=\"0\"`) because they cannot receive\n   * browser focus; see {@link applyRovingTabindex}. A future revision may\n   * decouple native `disabled` and `aria-disabled` into separate options if\n   * component migrations surface the need.\n   *\n   * Defaults to false.\n   */\n  skipDisabled?: boolean;\n\n  /**\n   * Invoked after the active item changes and `tabindex` values are synchronized.\n   * The argument is the new active element, or null when the group has no eligible items.\n   */\n  onActiveItemChange?: (active: HTMLElement | null) => void;\n\n  /**\n   * When set to a **non-zero** integer, **Page Up** / **Page Down** move focus by that many\n   * positions in `getItems()` order for **`horizontal`**, **`vertical`**, and **`both`** modes\n   * (respects **`wrap`** the same way as single-step arrows).\n   * For **`grid`**, page keys move by that many **rows** (column index is clamped to each row’s\n   * length). Omitted, `0`, `NaN`, and non-finite values disable page keys. The sign of the\n   * number is ignored; only the magnitude is used.\n   */\n  pageStep?: number;\n};\n\n// ─────────────────────────\n//     CONSTANTS\n// ─────────────────────────\n\n/**\n * Default boolean flags merged with the constructor `options` object.\n *\n * @internal\n */\nconst DEFAULT_OPTIONS = {\n  wrap: false,\n  memory: true,\n  skipDisabled: false,\n} as const;\n\n/**\n * Tolerance in CSS pixels for grouping items into the same grid row when using\n * {@link FocusgroupDirection | `grid`} mode.\n *\n * @internal\n */\nconst GRID_ROW_TOLERANCE_PX = 6;\n\n/**\n * Name of the `CustomEvent` dispatched on the host when the roving tabindex active item changes.\n *\n * The event `bubbles` and is `composed`. Handlers read\n * {@link FocusgroupNavigationActiveChangeDetail} from `event.detail`.\n */\nexport const focusgroupNavigationActiveChange =\n  'swc-focusgroup-navigation-active-change';\n\n/**\n * Describes why the active item changed in a {@link focusgroupNavigationActiveChange} event.\n *\n * - **`keyboard`** — Arrow key, Home, or End navigation moved focus.\n * - **`focus`** — A managed item received DOM focus directly (pointer click or Tab-key entry).\n * - **`refresh`** — {@link FocusgroupNavigationController.refresh} re-parked the roving tab stop.\n * - **`programmatic`** — {@link FocusgroupNavigationController.setActiveItem} or\n *   {@link FocusgroupNavigationController.focusFirstItemByTextPrefix} was called directly.\n */\nexport type FocusgroupActiveChangeSource =\n  | 'keyboard'\n  | 'focus'\n  | 'refresh'\n  | 'programmatic';\n\n/**\n * `detail` object for the {@link focusgroupNavigationActiveChange} event.\n */\nexport type FocusgroupNavigationActiveChangeDetail = {\n  /**\n   * Element that now has `tabindex=\"0\"` among managed items, or null when the group is empty.\n   */\n  activeElement: HTMLElement | null;\n\n  /**\n   * Why the active item changed. Hosts that implement selection-follows-focus (e.g. automatic\n   * activation in a tab list) should react to `'keyboard'` and `'focus'` sources and ignore\n   * `'refresh'` and `'programmatic'` to avoid spurious selection changes on mount or when\n   * toggling `disabled`.\n   */\n  source: FocusgroupActiveChangeSource;\n};\n\n/**\n * **FocusgroupNavigation** — implements the roving `tabindex` pattern from the APG\n * keyboard guide and directional navigation similar to the proposed `focusgroup`\n * attribute (Open UI). The exported class name is `FocusgroupNavigationController`.\n *\n * The controller:\n * - Keeps exactly one item in the tab order (`tabindex=\"0\"`) per composite; sets\n *   `tabindex=\"-1\"` on other items it manages.\n * - Handles Arrow keys, Home, and End for focus movement (and optionally wrap). **`both`**\n *   direction accepts horizontal and vertical arrows on the same `getItems()` sequence.\n *   In **`grid`** mode only, **Ctrl+Home** / **Ctrl+End** move to the first cell of the first\n *   row or the last cell of the last row (by layout-derived rows).\n * - Optional **`pageStep`**: **Page Up** / **Page Down** move by that many items (linear modes)\n *   or rows (**`grid`**).\n * - Optional **`skipDisabled`**: omit **`disabled`** and **`aria-disabled=\"true\"`** items from\n *   roving tabindex and arrow navigation.\n * - Supports optional last-focused memory when re-entering via Tab.\n * - Exposes {@link FocusgroupNavigationController.setActiveItem} to choose the roving tab stop\n *   without calling `focus()`, and {@link FocusgroupNavigationController.focusFirstItemByTextPrefix}\n *   for typeahead-style roving `tabindex` (call {@link FocusgroupNavigationController.getActiveItem}\n *   and `focus()` yourself when you want keyboard focus to move). Arrow-key handling calls\n *   `setActiveItem` and `focus()` together.\n *\n * Dispatches a bubbling, composed `CustomEvent` named\n * {@link focusgroupNavigationActiveChange} when the active item changes.\n *\n * This is not a browser `focusgroup` implementation; it is a Lit reactive controller\n * for custom elements until native `focusgroup` is available.\n *\n * @example\n * ```typescript\n * class MyToolbar extends LitElement {\n *   private readonly navigation = new FocusgroupNavigationController(this, {\n *     direction: 'horizontal',\n *     wrap: true,\n *     getItems: () =>\n *       Array.from(this.renderRoot.querySelectorAll<HTMLElement>('button')),\n *   });\n *\n *   protected override firstUpdated(): void {\n *     super.firstUpdated();\n *     this.navigation.refresh();\n *   }\n * }\n * ```\n *\n * @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#keyboardnavigationinsidecomponents\n * @see https://open-ui.org/components/scoped-focusgroup.explainer/\n *\n * **Native `focusgroup` (future):** The comment block immediately below this class lists which\n * parts of this file are the most likely candidates for deprecation or deletion once browsers\n * ship built-in focus-group behavior that covers the same cases (especially roving tabindex and\n * arrow-key focus moves). Some options (for example rect-based **grid**, **pageStep**, or\n * **skipDisabled**) may remain useful longer if the platform surface stays narrower.\n */\n// ─────────────────────────────────────────────────────────────────────────────\n// Native `focusgroup` (future) — likely deprecation candidates\n//\n// If/when browsers implement `focusgroup` (or equivalent) with behavior comparable to this\n// controller for your targets, consider removing or shrinking the following areas first:\n//\n// 1. Roving tabindex — `applyRovingTabindex()`, the tabindex portions of `refresh()` and\n//    `setActiveItem()`, and assigning `tabIndex` to ineligible raw items.\n//\n// 2. Host keyboard interception — `handleKeydown()`, `hostConnected` / `hostDisconnected`\n//    `keydown` listeners, `resolveManagedKeydownTarget()` (shadow retargeting workaround), and\n//    navigation helpers: `navigateLinear`, `navigateBothAxes`, `navigateGrid`, `navigatePage`,\n//    `navigatePageLinearItems`, `navigatePageGridRows`, `getEffectivePageMagnitude`, plus\n//    Home/End and Ctrl+Home/Ctrl+End branches inside `handleKeydown`.\n//\n// 3. JS “memory” for Tab re-entry — `lastFocused`, `handleFocusin` / `handleFocusout` memory\n//    paths, and `refresh()`’s preference for `lastFocused` when native group memory replaces\n//    this pattern.\n//\n// Often slower to retire (verify against shipped HTML/Open UI behavior): `buildRows` and\n// geometry-based **grid** navigation; **pageStep** (Page Up/Down magnitude); **skipDisabled** and\n// `isDisabledForSkip`; `isNodeWithinHostScope` / `getRawItems` if declarative scoping differs in\n// shadow DOM; `dispatchActiveChange`, `onActiveItemChange`, and the exported event name if\n// products still want a single composed integration hook; `focusFirstItemByTextPrefix` for\n// typeahead roving tabindex (callers focus `getActiveItem()` unless the platform adds an equivalent).\n// `isRtl()` may\n// duplicate or diverge from native axis mapping — revisit when testing RTL with native focusgroup.\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport class FocusgroupNavigationController implements ReactiveController {\n  /**\n   * Lit reactive host this controller is attached to.\n   */\n  private host: ReactiveElement;\n\n  /**\n   * Effective options (defaults merged with the latest `setOptions` / constructor values).\n   */\n  private options: FocusgroupNavigationOptions;\n\n  /**\n   * Capture-phase `keydown` listener reference for removal on disconnect.\n   */\n  private readonly boundKeydown = this.handleKeydown.bind(this);\n\n  /**\n   * Capture-phase `focusin` listener reference for removal on disconnect.\n   */\n  private readonly boundFocusin = this.handleFocusin.bind(this);\n\n  /**\n   * Capture-phase `focusout` listener reference for removal on disconnect.\n   */\n  private readonly boundFocusout = this.handleFocusout.bind(this);\n\n  /**\n   * Cached item for {@link FocusgroupNavigationOptions.memory} when the user moves focus\n   * inside or out of the composite. Cleared when that node is no longer returned by\n   * `getItems` or when the group becomes empty.\n   */\n  private lastFocused: HTMLElement | null = null;\n\n  /**\n   * Tracks the previously dispatched active item so that\n   * {@link applyRovingTabindex} only fires the active-change event and\n   * {@link FocusgroupNavigationOptions.onActiveItemChange} callback when the\n   * active item actually changes.\n   */\n  private previousActive: HTMLElement | null = null;\n\n  /**\n   * Guard flag set during keyboard navigation so that the `focusin` triggered\n   * by `item.focus()` does not redundantly call {@link applyRovingTabindex}.\n   */\n  private isNavigating = false;\n\n  /**\n   * Cached result of {@link getEligibleItems}, populated on first access within\n   * a refresh cycle and cleared at the start of each entry point\n   * ({@link refresh}, {@link handleFocusin}, {@link handleKeydown}).\n   */\n  private cachedEligibleItems: HTMLElement[] | null = null;\n\n  /**\n   * Cached result of {@link buildRows}, populated on first access within a\n   * keydown cycle and cleared alongside {@link cachedEligibleItems}.\n   */\n  private cachedRows: HTMLElement[][] | null = null;\n\n  // ─────────────────────────\n  //     PUBLIC API\n  // ─────────────────────────\n\n  /**\n   * Registers this instance on `host` via `addController` and merges `options` with defaults.\n   *\n   * @param host - Reactive element that owns the composite (arrow keys and tab order apply within its subtree).\n   * @param options - `getItems`, `direction`, and optional behavior flags.\n   */\n  constructor(host: ReactiveElement, options: FocusgroupNavigationOptions) {\n    this.host = host;\n    this.options = { ...DEFAULT_OPTIONS, ...options };\n    host.addController(this);\n  }\n\n  /**\n   * Merges `partial` into the current options and reapplies roving `tabindex` to the item set.\n   *\n   * @param partial - Fields to override; omitted keys keep their previous values.\n   */\n  public setOptions(partial: Partial<FocusgroupNavigationOptions>): void {\n    this.options = { ...this.options, ...partial };\n    this.refresh();\n  }\n\n  /**\n   * Returns the eligible managed item that currently participates in the sequential focus order\n   * (`tabindex=\"0\"`), or null if no eligible item has tab index zero.\n   *\n   * @returns The active roving item, or null.\n   */\n  public getActiveItem(): HTMLElement | null {\n    for (const el of this.getEligibleItems()) {\n      if (el.tabIndex === 0) {\n        return el;\n      }\n    }\n    return null;\n  }\n\n  /**\n   * Re-queries `getItems()`, recomputes eligibility, and syncs roving `tabindex`.\n   *\n   * Call after the item list or item eligibility changes (for example after Lit\n   * `updated()` or slot changes). When {@link FocusgroupNavigationOptions.memory} is true,\n   * prefers the stored last-focused item if it is still eligible; otherwise keeps the\n   * current active item or falls back to the first eligible item.\n   */\n  public refresh(): void {\n    this.cachedEligibleItems = null;\n    this.cachedRows = null;\n    const items = this.getEligibleItems();\n    if (items.length === 0) {\n      for (const el of this.getRawItems()) {\n        el.tabIndex = -1;\n      }\n      this.lastFocused = null;\n      if (this.previousActive !== null) {\n        this.previousActive = null;\n        this.dispatchActiveChange(null, 'refresh');\n        this.options.onActiveItemChange?.(null);\n      }\n      return;\n    }\n\n    const preferred =\n      (this.options.memory &&\n      this.lastFocused &&\n      items.includes(this.lastFocused)\n        ? this.lastFocused\n        : null) ??\n      this.getActiveItem() ??\n      items[0];\n\n    this.applyRovingTabindex(preferred, 'refresh');\n  }\n\n  /**\n   * Sets roving `tabindex` so `item` is the active tab stop (`tabindex=\"0\"`) and others in the\n   * group are `-1`. Does **not** call `focus()`. When {@link FocusgroupNavigationOptions.memory}\n   * is true, updates the stored last-focused item so Tab re-entry can target this item.\n   *\n   * @param item - Item to mark active; must be returned by `getItems` and pass eligibility checks.\n   * @returns False if `item` is not in the current eligible item list.\n   */\n  public setActiveItem(item: HTMLElement): boolean {\n    const items = this.getEligibleItems();\n    if (!items.includes(item)) {\n      return false;\n    }\n    this.applyRovingTabindex(item, 'programmatic');\n    if (this.options.memory) {\n      this.lastFocused = item;\n    }\n    return true;\n  }\n\n  /**\n   * Updates roving `tabindex` so the first **eligible** item (same set as arrow navigation)\n   * whose typeahead label starts with `prefix` becomes the active tab stop (`tabindex=\"0\"`).\n   * Matching is **case-insensitive**. The label is the first non-empty of: trimmed\n   * **`aria-label`**, trimmed text from **`aria-labelledby`** references (in order, space-joined),\n   * or trimmed **`textContent`**. Search order matches arrow-key traversal.\n   *\n   * Does **not** call `focus()`. After this returns `true`, call `focus()` on\n   * {@link FocusgroupNavigationController.getActiveItem} (for example `getActiveItem()?.focus()`),\n   * often from a **microtask** when the caller runs from a pointer handler so focus is not\n   * overwritten by the clicked control.\n   *\n   * Typical use: menu typeahead; wire `keydown` or `input` at the host and debounce as needed.\n   *\n   * @param prefix - String to match as a leading substring after `trim`; whitespace-only yields\n   *   no match and returns `false`.\n   * @returns True if a matching item was found and roving tabindex was applied.\n   */\n  public focusFirstItemByTextPrefix(prefix: string): boolean {\n    const trimmed = prefix.trim();\n    if (trimmed === '') {\n      return false;\n    }\n    const needle = trimmed.toLowerCase();\n    const items = this.getEligibleItems();\n    const match = items.find((el) => {\n      const label = this.getItemTypeaheadLabel(el).toLowerCase();\n      return label.startsWith(needle);\n    });\n    if (!match) {\n      return false;\n    }\n    this.applyRovingTabindex(match, 'programmatic');\n    return true;\n  }\n\n  /**\n   * Lit `ReactiveController` hook: registers capture-phase listeners on `host` and runs\n   * an initial {@link refresh}.\n   */\n  public hostConnected(): void {\n    this.previousActive = null;\n    this.cachedEligibleItems = null;\n    this.cachedRows = null;\n    this.host.addEventListener('keydown', this.boundKeydown, true);\n    this.host.addEventListener('focusin', this.boundFocusin, true);\n    this.host.addEventListener('focusout', this.boundFocusout, true);\n    this.refresh();\n  }\n\n  /**\n   * Lit `ReactiveController` hook: removes listeners registered in {@link hostConnected}.\n   */\n  public hostDisconnected(): void {\n    this.host.removeEventListener('keydown', this.boundKeydown, true);\n    this.host.removeEventListener('focusin', this.boundFocusin, true);\n    this.host.removeEventListener('focusout', this.boundFocusout, true);\n  }\n\n  // ─────────────────────────\n  //     IMPLEMENTATION\n  // ─────────────────────────\n  //\n  // Which parts may become redundant under native `focusgroup` is summarized in the\n  // “Native `focusgroup` (future)” comment block directly above the class declaration.\n\n  /**\n   * Resolves writing direction from the computed style of the host element.\n   *\n   * Uses `getComputedStyle` rather than walking `dir` attributes so that\n   * CSS-inherited direction (the gen2 default) is correctly detected.\n   *\n   * @returns True when horizontal arrow directions should follow RTL semantics.\n   */\n  private isRtl(): boolean {\n    return getComputedStyle(this.host).direction === 'rtl';\n  }\n\n  /**\n   * Whether `node` is the host or reachable from it by walking `parentNode` and\n   * `ShadowRoot.host` (so shadow descendants count, including nested shadow roots).\n   *\n   * `Element.contains()` is not used because it returns false for nodes inside the\n   * host's shadow tree, which would drop every item for typical Lit components.\n   *\n   * @param node - Node to test (may be null).\n   * @returns True if `node` is in the host's shadow-inclusive subtree.\n   */\n  private isNodeWithinHostScope(node: Node | null): boolean {\n    if (!node) {\n      return false;\n    }\n    const host = this.host;\n    let current: Node | null = node;\n    while (current) {\n      if (current === host) {\n        return true;\n      }\n      const parent: Node | null = current.parentNode;\n      if (parent) {\n        current = parent;\n      } else if (current instanceof ShadowRoot) {\n        current = current.host;\n      } else {\n        return false;\n      }\n    }\n    return false;\n  }\n\n  /**\n   * Items returned by `getItems` that lie within `host` (shadow-inclusive tree).\n   *\n   * @returns Candidates before eligibility filtering.\n   */\n  private getRawItems(): HTMLElement[] {\n    return this.options\n      .getItems()\n      .filter((el) => this.isNodeWithinHostScope(el));\n  }\n\n  /**\n   * {@link getRawItems} filtered by {@link isNavigableItem}.\n   *\n   * @returns Items that participate in roving tabindex and arrow navigation.\n   */\n  private getEligibleItems(): HTMLElement[] {\n    if (this.cachedEligibleItems) {\n      return this.cachedEligibleItems;\n    }\n    this.cachedEligibleItems = this.getRawItems().filter((el) =>\n      this.isNavigableItem(el)\n    );\n    return this.cachedEligibleItems;\n  }\n\n  /**\n   * {@link buildRows} with per-cycle caching, cleared alongside\n   * {@link cachedEligibleItems}.\n   *\n   * @param items - Eligible items to lay out as a grid.\n   * @returns Cached row-major array of rows.\n   */\n  private getRows(items: HTMLElement[]): HTMLElement[][] {\n    if (this.cachedRows) {\n      return this.cachedRows;\n    }\n    this.cachedRows = this.buildRows(items);\n    return this.cachedRows;\n  }\n\n  /**\n   * Whether `el` may participate in the focus group (connected, visible, not inert,\n   * and not skipped when {@link FocusgroupNavigationOptions.skipDisabled} is true).\n   *\n   * @param el - Candidate from `getItems`.\n   * @returns True if the element counts as navigable for this controller.\n   */\n  private isNavigableItem(el: HTMLElement): boolean {\n    if (!el.isConnected) {\n      return false;\n    }\n    if (el.hasAttribute('inert') || el.closest('[inert]')) {\n      return false;\n    }\n    const style = getComputedStyle(el);\n    if (style.visibility === 'hidden' || style.display === 'none') {\n      return false;\n    }\n    if (this.options.skipDisabled && this.isDisabledForSkip(el)) {\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Whether `el` should be treated as disabled for {@link FocusgroupNavigationOptions.skipDisabled}.\n   *\n   * @param el - Element to test.\n   * @returns True if the native `disabled` property is true or `aria-disabled` is `\"true\"`.\n   */\n  private isDisabledForSkip(el: HTMLElement): boolean {\n    if ('disabled' in el && (el as HTMLButtonElement).disabled) {\n      return true;\n    }\n    return el.getAttribute('aria-disabled') === 'true';\n  }\n\n  /**\n   * String used for {@link focusFirstItemByTextPrefix}: prefers **`aria-label`**, then text from\n   * **`aria-labelledby`** (IDs resolved in the shadow root or document), else **`textContent`**.\n   * All branches are trimmed; empty strings fall through to the next source.\n   */\n  private getItemTypeaheadLabel(el: HTMLElement): string {\n    const fromAria = el.getAttribute('aria-label')?.trim();\n    if (fromAria) {\n      return fromAria;\n    }\n    const labelledBy = el.getAttribute('aria-labelledby')?.trim();\n    if (labelledBy) {\n      const root = el.getRootNode();\n      const chunks: string[] = [];\n      for (const id of labelledBy.split(/\\s+/)) {\n        if (!id) {\n          continue;\n        }\n        const ref =\n          root instanceof ShadowRoot\n            ? (root.getElementById(id) ?? el.ownerDocument.getElementById(id))\n            : el.ownerDocument.getElementById(id);\n        const t = ref?.textContent?.trim();\n        if (t) {\n          chunks.push(t);\n        }\n      }\n      const joined = chunks.join(' ').trim();\n      if (joined) {\n        return joined;\n      }\n    }\n    return el.textContent?.trim() ?? '';\n  }\n\n  /**\n   * Whether `el` is natively disabled and therefore unable to receive focus\n   * regardless of its `tabindex` value.\n   */\n  private isNativelyDisabled(el: HTMLElement): boolean {\n    return 'disabled' in el && (el as HTMLButtonElement).disabled === true;\n  }\n\n  /**\n   * Sets `tabindex=\"-1\"` on ineligible raw items, then assigns `tabindex=\"0\"` to\n   * `active` (or the first eligible item if `active` is not eligible) and `-1` to the rest.\n   *\n   * When `skipDisabled` is false, natively disabled items remain in the eligible list\n   * for arrow navigation but are never chosen as the roving tab stop because they\n   * cannot receive focus. The tab stop falls through to the nearest non-disabled item.\n   *\n   * Dispatches the active-change event and {@link FocusgroupNavigationOptions.onActiveItemChange}.\n   *\n   * @param active - Preferred item to mark as the single tab stop when eligible.\n   * @param source - Why the active item is changing; included in the dispatched event detail.\n   */\n  private applyRovingTabindex(\n    active: HTMLElement,\n    source: FocusgroupActiveChangeSource\n  ): void {\n    const items = this.getEligibleItems();\n    const eligibleSet = new Set(items);\n    for (const el of this.getRawItems()) {\n      if (!eligibleSet.has(el)) {\n        el.tabIndex = -1;\n      }\n    }\n    if (items.length === 0) {\n      return;\n    }\n\n    let safeActive = eligibleSet.has(active) ? active : items[0];\n\n    // Natively disabled elements cannot receive focus even with tabindex=\"0\".\n    // Fall through to the first non-disabled eligible item so the group\n    // remains reachable via Tab.\n    //\n    // The active-change event is dispatched with the originally requested item\n    // (before the fallback), not the fallback tab-stop. This lets consumers\n    // such as a tab list in automatic-activation mode inspect the item and skip\n    // the selection change when it is disabled — without being misled by the\n    // roving tab stop landing on a different element.\n    const reportedActive = safeActive;\n    if (this.isNativelyDisabled(safeActive)) {\n      safeActive =\n        items.find((el) => !this.isNativelyDisabled(el)) ?? safeActive;\n    }\n\n    for (const el of items) {\n      if (el === safeActive) {\n        el.tabIndex = 0;\n      } else {\n        el.tabIndex = -1;\n      }\n    }\n    if (reportedActive !== this.previousActive) {\n      this.previousActive = reportedActive;\n      this.dispatchActiveChange(reportedActive, source);\n      this.options.onActiveItemChange?.(safeActive);\n    }\n  }\n\n  /**\n   * Dispatches {@link focusgroupNavigationActiveChange} on the reactive host with the given detail.\n   *\n   * @param activeElement - New active item, or null when clearing selection.\n   * @param source - Why the active item changed.\n   */\n  private dispatchActiveChange(\n    activeElement: HTMLElement | null,\n    source: FocusgroupActiveChangeSource\n  ): void {\n    this.host.dispatchEvent(\n      new CustomEvent<FocusgroupNavigationActiveChangeDetail>(\n        focusgroupNavigationActiveChange,\n        {\n          bubbles: true,\n          composed: true,\n          detail: { activeElement, source },\n        }\n      )\n    );\n  }\n\n  /**\n   * Resolves the managed item that actually received focus inside the shadow tree.\n   *\n   * Same retargeting problem as {@link resolveManagedKeydownTarget}: listeners on\n   * the shadow host see `event.target` retargeted to the host when focus lands on a\n   * descendant inside the shadow root. Walk `composedPath()` and fall back to\n   * `shadowRoot.activeElement` to find the real focused managed item.\n   *\n   * @param event - Focus event dispatched while focus moves into the composite.\n   * @param items - Current eligible items from {@link getEligibleItems}.\n   * @returns The managed element that received focus, or null.\n   */\n  private resolveManagedFocusTarget(\n    event: FocusEvent,\n    items: HTMLElement[]\n  ): HTMLElement | null {\n    if (items.length === 0) {\n      return null;\n    }\n    const set = new Set(items);\n    for (const node of event.composedPath()) {\n      if (!(node instanceof HTMLElement)) {\n        continue;\n      }\n      if (set.has(node)) {\n        return node;\n      }\n      if (node === this.host) {\n        break;\n      }\n    }\n    const root = this.host.shadowRoot;\n    const active = root?.activeElement;\n    if (active instanceof HTMLElement && set.has(active)) {\n      return active;\n    }\n    return null;\n  }\n\n  /**\n   * Capture-phase `focusin` handler: syncs roving `tabindex` when focus moves to a managed item\n   * (for example via pointer), and updates memory when enabled.\n   *\n   * @param event - Focus event whose target may be a group item.\n   */\n  private handleFocusin(event: FocusEvent): void {\n    if (this.isNavigating) {\n      return;\n    }\n    this.cachedEligibleItems = null;\n    this.cachedRows = null;\n    const items = this.getEligibleItems();\n    const target = this.resolveManagedFocusTarget(event, items);\n    if (!target) {\n      return;\n    }\n    this.applyRovingTabindex(target, 'focus');\n    if (this.options.memory) {\n      this.lastFocused = target;\n    }\n  }\n\n  /**\n   * Capture-phase `focusout` handler: when focus leaves the host subtree, stores the\n   * previous target for {@link FocusgroupNavigationOptions.memory}.\n   *\n   * @param event - Focus event; `relatedTarget` stays inside the host when moving between items.\n   */\n  private handleFocusout(event: FocusEvent): void {\n    const next = event.relatedTarget;\n    if (next instanceof Node && this.isNodeWithinHostScope(next)) {\n      return;\n    }\n    const target = event.target;\n    if (\n      this.options.memory &&\n      target instanceof HTMLElement &&\n      this.getRawItems().includes(target)\n    ) {\n      this.lastFocused = target;\n    }\n    // When memory is off, reset the roving tab stop to the first eligible\n    // item so Tab re-entry always starts from the beginning.\n    if (!this.options.memory) {\n      this.cachedEligibleItems = null;\n      this.cachedRows = null;\n      const items = this.getEligibleItems();\n      if (items.length > 0) {\n        this.applyRovingTabindex(items[0], 'focus');\n      }\n    }\n  }\n\n  /**\n   * Resolves which managed item should receive arrow, Home, End, or grid Ctrl+Home / Ctrl+End\n   * handling for this key event.\n   *\n   * Listeners on the shadow **host** often see a **retargeted** {@link KeyboardEvent.target}\n   * (the host) while focus is on a descendant inside the shadow tree, so matching\n   * `event.target` against `getItems()` fails. {@link Event.composedPath} still includes the\n   * focused node; we also fall back to {@link ShadowRoot.activeElement} when needed.\n   *\n   * @param event - Keyboard event dispatched while focus is in this composite.\n   * @param items - Current eligible items from {@link getEligibleItems}.\n   * @returns The managed element to treat as keydown target, or null.\n   */\n  private resolveManagedKeydownTarget(\n    event: KeyboardEvent,\n    items: HTMLElement[]\n  ): HTMLElement | null {\n    if (items.length === 0) {\n      return null;\n    }\n    const set = new Set(items);\n    for (const node of event.composedPath()) {\n      if (!(node instanceof HTMLElement)) {\n        continue;\n      }\n      if (set.has(node)) {\n        return node;\n      }\n      if (node === this.host) {\n        break;\n      }\n    }\n    const root = this.host.shadowRoot;\n    const active = root?.activeElement;\n    if (active instanceof HTMLElement && set.has(active)) {\n      return active;\n    }\n    return null;\n  }\n\n  /**\n   * Capture-phase `keydown` handler: arrow keys and Home/End move focus among eligible items\n   * when the event target is managed; calls `preventDefault` when handling navigation.\n   *\n   * When {@link FocusgroupDirection | `direction`} is **`both`**, **ArrowLeft** / **ArrowRight**\n   * and **ArrowUp** / **ArrowDown** all participate (see {@link navigateBothAxes}).\n   *\n   * When {@link FocusgroupDirection | `direction`} is **`grid`**, **Ctrl+Home** focuses the\n   * first cell in the first row and **Ctrl+End** focuses the last cell in the last row (from\n   * {@link buildRows}); other modifier combinations are ignored except plain Home/End.\n   *\n   * When {@link FocusgroupNavigationOptions.pageStep} is a non-zero finite number, **Page Up**\n   * and **Page Down** are handled before arrow keys (see {@link navigatePage}).\n   *\n   * @param event - Keyboard event from the focused element inside the host.\n   */\n  private handleKeydown(event: KeyboardEvent): void {\n    if (event.defaultPrevented || event.altKey) {\n      return;\n    }\n\n    this.cachedEligibleItems = null;\n    this.cachedRows = null;\n    const items = this.getEligibleItems();\n    const target = this.resolveManagedKeydownTarget(event, items);\n    if (!target) {\n      return;\n    }\n\n    const isGrid = this.options.direction === 'grid';\n    const rows = isGrid ? this.getRows(items) : null;\n\n    if (\n      isGrid &&\n      event.ctrlKey &&\n      !event.metaKey &&\n      (event.key === 'Home' || event.key === 'End')\n    ) {\n      if (rows!.length > 0) {\n        const firstRow = rows![0];\n        const lastRow = rows![rows!.length - 1];\n        const boundary =\n          event.key === 'Home'\n            ? (firstRow?.[0] ?? null)\n            : (lastRow?.[lastRow.length - 1] ?? null);\n        if (boundary && boundary !== target) {\n          event.preventDefault();\n          this.moveKeyNavigationFocusTo(boundary);\n        }\n      }\n      return;\n    }\n\n    if (event.ctrlKey || event.metaKey) {\n      return;\n    }\n\n    const pageMagnitude = this.getEffectivePageMagnitude();\n    if (\n      pageMagnitude !== null &&\n      (event.key === 'PageUp' || event.key === 'PageDown')\n    ) {\n      const pageNext = this.navigatePage(\n        items,\n        target,\n        event.key === 'PageDown' ? pageMagnitude : -pageMagnitude,\n        rows\n      );\n      if (pageNext && pageNext !== target) {\n        event.preventDefault();\n        this.moveKeyNavigationFocusTo(pageNext);\n      }\n      return;\n    }\n\n    const rtl = this.isRtl();\n    let next: HTMLElement | null = null;\n\n    switch (this.options.direction) {\n      case 'horizontal':\n        next = this.navigateLinear(items, target, event.key, 'horizontal', rtl);\n        break;\n      case 'vertical':\n        next = this.navigateLinear(items, target, event.key, 'vertical', rtl);\n        break;\n      case 'both':\n        next = this.navigateBothAxes(items, target, event.key, rtl);\n        break;\n      case 'grid':\n        next = this.navigateGrid(target, event.key, rtl, rows!);\n        break;\n      default:\n        break;\n    }\n\n    if (next && next !== target) {\n      event.preventDefault();\n      this.moveKeyNavigationFocusTo(next);\n      return;\n    }\n\n    if (event.key === 'Home' || event.key === 'End') {\n      if (isGrid) {\n        // APG grid pattern: Home/End scope to the current row.\n        // Ctrl+Home/End (entire grid) is handled above.\n        const pos = this.findGridIndex(rows!, target);\n        if (!pos) {\n          return;\n        }\n        const currentRow = rows![pos.row];\n        if (!currentRow?.length) {\n          return;\n        }\n        const boundary =\n          event.key === 'Home'\n            ? currentRow[0]\n            : currentRow[currentRow.length - 1];\n        if (boundary && boundary !== target) {\n          event.preventDefault();\n          this.moveKeyNavigationFocusTo(boundary);\n        }\n      } else {\n        if (items.length === 0) {\n          return;\n        }\n        const boundary =\n          event.key === 'Home' ? items[0] : items[items.length - 1];\n        if (boundary && boundary !== target) {\n          event.preventDefault();\n          this.moveKeyNavigationFocusTo(boundary);\n        }\n      }\n    }\n  }\n\n  /**\n   * Applies roving tabindex to `item` and moves DOM focus; used for keyboard navigation only.\n   */\n  private moveKeyNavigationFocusTo(item: HTMLElement): void {\n    this.isNavigating = true;\n    try {\n      const items = this.getEligibleItems();\n      if (items.includes(item)) {\n        this.applyRovingTabindex(item, 'keyboard');\n        if (this.options.memory) {\n          this.lastFocused = item;\n        }\n        item.focus();\n      }\n    } finally {\n      this.isNavigating = false;\n    }\n  }\n\n  /**\n   * Positive step count for {@link FocusgroupNavigationOptions.pageStep}, or null when page keys\n   * are disabled.\n   */\n  private getEffectivePageMagnitude(): number | null {\n    const raw = this.options.pageStep;\n    if (raw === undefined) {\n      return null;\n    }\n    const n = Math.trunc(Number(raw));\n    if (!Number.isFinite(n) || n === 0) {\n      return null;\n    }\n    return Math.abs(n);\n  }\n\n  /**\n   * Target for **Page Up** / **Page Down** when {@link getEffectivePageMagnitude} is set.\n   *\n   * @param items - Eligible items.\n   * @param current - Focused item.\n   * @param signedDelta - `+magnitude` for Page Down or `-magnitude` for Page Up (items for\n   *   linear modes, rows for `grid`).\n   */\n  private navigatePage(\n    items: HTMLElement[],\n    current: HTMLElement,\n    signedDelta: number,\n    rows: HTMLElement[][] | null\n  ): HTMLElement | null {\n    if (this.options.direction === 'grid') {\n      return this.navigatePageGridRows(current, signedDelta, rows!);\n    }\n    return this.navigatePageLinearItems(items, current, signedDelta);\n  }\n\n  /**\n   * Page Up/Down along `getItems()` order (used for `horizontal`, `vertical`, and `both`).\n   */\n  private navigatePageLinearItems(\n    items: HTMLElement[],\n    current: HTMLElement,\n    deltaIdx: number\n  ): HTMLElement | null {\n    const idx = items.indexOf(current);\n    if (idx < 0 || items.length === 0) {\n      return null;\n    }\n    let nextIdx = idx + deltaIdx;\n    if (this.options.wrap) {\n      const len = items.length;\n      nextIdx = ((nextIdx % len) + len) % len;\n    } else {\n      nextIdx = Math.max(0, Math.min(items.length - 1, nextIdx));\n    }\n    return items[nextIdx] ?? null;\n  }\n\n  /**\n   * Page Up/Down by whole rows in `grid` mode (column clamped per {@link navigateGrid}).\n   */\n  private navigatePageGridRows(\n    current: HTMLElement,\n    rowDelta: number,\n    grid: HTMLElement[][]\n  ): HTMLElement | null {\n    if (grid.length === 0) {\n      return null;\n    }\n    const pos = this.findGridIndex(grid, current);\n    if (!pos) {\n      return null;\n    }\n    const { row, col } = pos;\n    let nextRow = row + rowDelta;\n    if (this.options.wrap) {\n      const n = grid.length;\n      nextRow = ((nextRow % n) + n) % n;\n    } else {\n      nextRow = Math.max(0, Math.min(grid.length - 1, nextRow));\n    }\n    const targetRow = grid[nextRow];\n    if (!targetRow?.length) {\n      return null;\n    }\n    const clampedCol = Math.min(col, targetRow.length - 1);\n    return targetRow[clampedCol] ?? null;\n  }\n\n  /**\n   * Computes the next focus target for linear {@link FocusgroupDirection} modes.\n   *\n   * @param items - Eligible items in traversal order.\n   * @param current - Currently focused item.\n   * @param key - `KeyboardEvent.key` value.\n   * @param mode - `horizontal` (inline axis) or `vertical` (block axis).\n   * @param rtl - When true, horizontal Left/Right swap forward/backward.\n   * @returns Next item, or null if the key is not a navigation key or movement is blocked.\n   */\n  private navigateLinear(\n    items: HTMLElement[],\n    current: HTMLElement,\n    key: string,\n    mode: 'horizontal' | 'vertical',\n    rtl: boolean\n  ): HTMLElement | null {\n    const idx = items.indexOf(current);\n    if (idx < 0) {\n      return null;\n    }\n\n    let delta = 0;\n    if (mode === 'horizontal') {\n      if (key === 'ArrowLeft') {\n        delta = rtl ? 1 : -1;\n      } else if (key === 'ArrowRight') {\n        delta = rtl ? -1 : 1;\n      }\n    } else {\n      if (key === 'ArrowUp') {\n        delta = -1;\n      } else if (key === 'ArrowDown') {\n        delta = 1;\n      }\n    }\n\n    if (delta === 0) {\n      return null;\n    }\n\n    let nextIdx = idx + delta;\n    if (this.options.wrap) {\n      nextIdx = (nextIdx + items.length) % items.length;\n    } else if (nextIdx < 0 || nextIdx >= items.length) {\n      return null;\n    }\n    return items[nextIdx] ?? null;\n  }\n\n  /**\n   * Computes the next focus target when {@link FocusgroupDirection | `direction`} is **`both`**:\n   * inline arrows use the same deltas as {@link navigateLinear} `horizontal` mode; **ArrowUp** /\n   * **ArrowDown** step backward / forward in `getItems()` order (not flipped by `dir`).\n   *\n   * @param items - Eligible items in traversal order.\n   * @param current - Currently focused item.\n   * @param key - `KeyboardEvent.key` value.\n   * @param rtl - When true, horizontal Left/Right swap forward/backward.\n   * @returns Next item, or null if the key is not handled or movement is blocked.\n   */\n  private navigateBothAxes(\n    items: HTMLElement[],\n    current: HTMLElement,\n    key: string,\n    rtl: boolean\n  ): HTMLElement | null {\n    const idx = items.indexOf(current);\n    if (idx < 0) {\n      return null;\n    }\n\n    let delta = 0;\n    if (key === 'ArrowLeft') {\n      delta = rtl ? 1 : -1;\n    } else if (key === 'ArrowRight') {\n      delta = rtl ? -1 : 1;\n    } else if (key === 'ArrowUp') {\n      delta = -1;\n    } else if (key === 'ArrowDown') {\n      delta = 1;\n    }\n\n    if (delta === 0) {\n      return null;\n    }\n\n    let nextIdx = idx + delta;\n    if (this.options.wrap) {\n      nextIdx = (nextIdx + items.length) % items.length;\n    } else if (nextIdx < 0 || nextIdx >= items.length) {\n      return null;\n    }\n    return items[nextIdx] ?? null;\n  }\n\n  /**\n   * Computes the next focus target for `grid` {@link FocusgroupDirection} mode using\n   * row clustering and column indices.\n   *\n   * @param current - Currently focused item.\n   * @param key - `KeyboardEvent.key` value.\n   * @param rtl - When true, horizontal Left/Right swap column direction within a row.\n   * @param grid - Pre-built row grid from {@link buildRows}.\n   * @returns Next cell item, or null if the key is not handled or movement is blocked.\n   */\n  private navigateGrid(\n    current: HTMLElement,\n    key: string,\n    rtl: boolean,\n    grid: HTMLElement[][]\n  ): HTMLElement | null {\n    const pos = this.findGridIndex(grid, current);\n    if (!pos) {\n      return null;\n    }\n    const { row, col } = pos;\n    const rowItems = grid[row] ?? [];\n    let nextRow = row;\n    let nextCol = col;\n\n    switch (key) {\n      case 'ArrowLeft':\n        nextCol = rtl ? col + 1 : col - 1;\n        break;\n      case 'ArrowRight':\n        nextCol = rtl ? col - 1 : col + 1;\n        break;\n      case 'ArrowUp':\n        nextRow = row - 1;\n        break;\n      case 'ArrowDown':\n        nextRow = row + 1;\n        break;\n      default:\n        return null;\n    }\n\n    if (key === 'ArrowLeft' || key === 'ArrowRight') {\n      if (nextCol >= 0 && nextCol < rowItems.length) {\n        return rowItems[nextCol] ?? null;\n      }\n      if (this.options.wrap && rowItems.length > 0) {\n        const wrappedCol = (nextCol + rowItems.length) % rowItems.length;\n        return rowItems[wrappedCol] ?? null;\n      }\n      return null;\n    }\n\n    if (nextRow < 0 || nextRow >= grid.length) {\n      if (this.options.wrap && grid.length > 0) {\n        nextRow = (nextRow + grid.length) % grid.length;\n      } else {\n        return null;\n      }\n    }\n\n    const targetRow = grid[nextRow];\n    if (!targetRow?.length) {\n      return null;\n    }\n    const clampedCol = Math.min(col, targetRow.length - 1);\n    return targetRow[clampedCol] ?? null;\n  }\n\n  /**\n   * Groups `items` into rows by similar `getBoundingClientRect().top`, then sorts each row by `left`.\n   *\n   * @param items - Eligible elements to lay out as a grid.\n   * @returns Row-major array of rows; each row is left-to-right.\n   */\n  private buildRows(items: HTMLElement[]): HTMLElement[][] {\n    type RowAcc = { top: number; elements: HTMLElement[] };\n    const rows: RowAcc[] = [];\n\n    for (const el of items) {\n      const top = el.getBoundingClientRect().top;\n      let row = rows.find(\n        (r) => Math.abs(r.top - top) <= GRID_ROW_TOLERANCE_PX\n      );\n      if (!row) {\n        row = { top, elements: [] };\n        rows.push(row);\n      }\n      row.elements.push(el);\n    }\n\n    rows.sort((a, b) => a.top - b.top);\n    return rows.map((r) =>\n      r.elements.sort(\n        (a, b) =>\n          a.getBoundingClientRect().left - b.getBoundingClientRect().left\n      )\n    );\n  }\n\n  /**\n   * Locates `el` in a row-major grid built by {@link buildRows}.\n   *\n   * @param grid - Rows of elements.\n   * @param el - Element to find.\n   * @returns Row and column indices, or null if absent.\n   */\n  private findGridIndex(\n    grid: HTMLElement[][],\n    el: HTMLElement\n  ): { row: number; col: number } | null {\n    for (let r = 0; r < grid.length; r++) {\n      const c = grid[r].indexOf(el);\n      if (c !== -1) {\n        return { row: r, col: c };\n      }\n    }\n    return null;\n  }\n}\n"],"mappings":"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"}

package/dist/controllers/hover-controller/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+export { HoverController, type HoverControllerHost, type HoverControllerOptions, } from './src/hover-controller.js';

package/dist/controllers/hover-controller/index.js

@@ -0,0 +1,2 @@
+import { HoverController as e } from "./src/hover-controller.js";
+export { e as HoverController };

package/dist/controllers/hover-controller/src/hover-controller.d.ts

@@ -0,0 +1,118 @@
+import { ReactiveController, ReactiveElement } from 'lit';
+/** Minimum interface required from any element that hosts a {@link HoverController}. */
+export interface HoverControllerHost extends ReactiveElement {
+    /** Warm-up duration in milliseconds before the popover opens on hover. `0` opens immediately. */
+    readonly delay: number;
+    /**
+     * Cooldown duration in milliseconds after the pointer leaves the trigger or
+     * popover before the popover closes. Independent of `delay` so that the
+     * WCAG 1.4.13 pointer bridge always has enough time to cancel the close,
+     * regardless of how quickly the popover opened.
+     *
+     * Defaults to `300` when omitted.
+     */
+    readonly closeDelay?: number;
+    /** When `true`, the controller skips all event wiring. */
+    readonly manual: boolean;
+    /** When `true`, the controller skips all event wiring. */
+    readonly disabled: boolean;
+    /**
+     * Asks the host to open. The host owns its visibility state and is the single
+     * source of truth; the controller never drives the Popover API directly. Must
+     * be idempotent — calling it while already open is a no-op.
+     */
+    requestOpen(): void;
+    /**
+     * Asks the host to close. Must be idempotent — calling it while already closed
+     * is a no-op.
+     */
+    requestClose(): void;
+}
+/** Configuration options for {@link HoverController}. */
+export interface HoverControllerOptions {
+    /**
+     * Per-component-type key used to namespace shared warm state on `document`.
+     * Use the element tag name (e.g. `'swc-tooltip'`). Must be static; must not
+     * vary per instance.
+     */
+    warmStateKey: string;
+}
+/**
+ * A Lit {@link ReactiveController} that manages hover and keyboard-focus event
+ * wiring for components that use the native Popover API.
+ *
+ * See the Storybook stories for full usage documentation and interactive demos.
+ *
+ * @example
+ * ```ts
+ * class SwcTooltip extends LitElement implements HoverControllerHost {
+ *   @property({ type: Number }) delay = 1500;
+ *   @property({ type: Boolean }) manual = false;
+ *   @property({ type: Boolean }) disabled = false;
+ *
+ *   private hoverController = new HoverController(this, { warmStateKey: 'swc-tooltip' });
+ *
+ *   protected override updated(changes: PropertyValues): void {
+ *     super.updated(changes);
+ *     if (changes.has('triggerElement')) {
+ *       this.hoverController.setTarget(this.triggerElement ?? null);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class HoverController implements ReactiveController {
+    private readonly host;
+    private readonly warmStateKey;
+    private target;
+    private warmupTimer;
+    private isBridgeWired;
+    /**
+     * Tracks whether the `disabled`/`manual` guard is currently active. Used by
+     * `hostUpdated()` to skip the rewire on every Lit update when the guard state
+     * hasn't changed.
+     */
+    private isGuardActive;
+    /** True while the trigger has keyboard focus; pointer-driven timers are suppressed. */
+    private hasFocusOpen;
+    /**
+     * Set by `pointerdown` on the trigger and cleared asynchronously after `focusin`
+     * fires. The async reset ensures the flag is still `true` when `focusin` arrives
+     * synchronously later in the same click event sequence.
+     */
+    private hadPointerdown;
+    private readonly boundPointerDownTrigger;
+    private readonly boundPointerEnterTrigger;
+    private readonly boundPointerLeaveTrigger;
+    private readonly boundFocusin;
+    private readonly boundFocusout;
+    private readonly boundPointerEnterHost;
+    private readonly boundPointerLeaveHost;
+    constructor(host: HoverControllerHost, options: HoverControllerOptions);
+    /**
+     * Sets the element that receives pointer and focus listeners. Call this whenever
+     * the resolved trigger changes (e.g. in `updated()` after a `for` attribute change).
+     * Passing `null` detaches all listeners from the previous target.
+     */
+    setTarget(trigger: HTMLElement | null): void;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Re-evaluates `disabled` and `manual` guards whenever the host updates. */
+    hostUpdated(): void;
+    private wireTarget;
+    private unwireTarget;
+    private wireBridge;
+    private unwireBridge;
+    private showWithBridge;
+    private callHidePopover;
+    private clearWarmupTimer;
+    private clearCooldownTimer;
+    private startCooldown;
+    private handlePointerDownTrigger;
+    private handlePointerEnterTrigger;
+    private handlePointerLeaveTrigger;
+    private handleFocusin;
+    private handleFocusout;
+    private handlePointerEnterHost;
+    private handlePointerLeaveHost;
+}