@lumx/react 4.17.1-alpha.2 → 4.17.1-alpha.3

package/_internal/packages/lumx-core/src/js/components/Combobox/setupCombobox.js

@@ -0,0 +1,350 @@
+import { getOptionValue, isOptionDisabled, isSelected, notifySection } from "./utils.js";
+import { setupListbox } from "./setupListbox.js";
+//#region ../lumx-core/src/js/components/Combobox/setupCombobox.ts
+/**
+* Set up combobox behavior (WAI-ARIA combobox pattern) on a trigger + listbox pair.
+*
+* The trigger and listbox are registered separately via the returned handle,
+* allowing framework components to register them on mount. The behavior is
+* fully attached once both are registered.
+*
+* @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+*
+* @param callbacks Callbacks invoked on combobox events (e.g. option selection).
+* @param options Options for configuring the shared combobox behavior.
+* @param onTriggerAttach Optional callback invoked when the trigger is registered and the signal is ready.
+*                        Used by mode-specific wrappers (setupComboboxInput/Button) to automatically
+*                        attach the appropriate controller.
+* @returns A ComboboxHandle for interacting with the combobox.
+*/
+function setupCombobox(callbacks, options, onTriggerAttach) {
+	const { wrapNavigation = false } = options ?? {};
+	let trigger = null;
+	let listbox = null;
+	let focusNav = null;
+	let isOpenState = false;
+	/** Current filter value (empty string = no filtering). */
+	let filterValue = "";
+	/** Registered options: maps DOM element → { callback, last notified state }. */
+	const optionRegistrations = /* @__PURE__ */ new Map();
+	/** Registered sections: maps DOM element → { callback, last notified state }. */
+	const sectionRegistrations = /* @__PURE__ */ new Map();
+	/** AbortController for all structural event listeners. */
+	let abortController = null;
+	/** Last notified visible option count, to avoid redundant `optionsChange` notifications. */
+	let lastOptionsLength = 0;
+	/** Last notified input value, to re-fire `optionsChange` when the user keeps typing while empty. */
+	let lastInputValue = "";
+	/** Event subscribers managed by the handle. */
+	const subscribers = {
+		open: /* @__PURE__ */ new Set(),
+		activeDescendantChange: /* @__PURE__ */ new Set(),
+		optionsChange: /* @__PURE__ */ new Set(),
+		loadingChange: /* @__PURE__ */ new Set(),
+		loadingAnnouncement: /* @__PURE__ */ new Set()
+	};
+	/** Notify all subscribers for a given event. */
+	function notify(event, value) {
+		subscribers[event].forEach((cb) => cb(value));
+	}
+	/**
+	* Notify all registered sections and fire `optionsChange` if the visible option count changed
+	* or if the input value changed while the list is empty (so `emptyMessage` callbacks get
+	* the updated query string).
+	* Called whenever the set of visible options may have changed (option register/unregister, filter change).
+	*/
+	function notifyVisibilityChange() {
+		for (const [sectionElement] of sectionRegistrations) notifySection(sectionElement, sectionRegistrations, optionRegistrations);
+		let visibleCount = 0;
+		for (const reg of optionRegistrations.values()) if (!reg.lastFiltered) visibleCount += 1;
+		const inputValue = trigger?.value ?? "";
+		if (visibleCount !== lastOptionsLength || visibleCount === 0 && inputValue !== lastInputValue) {
+			lastOptionsLength = visibleCount;
+			lastInputValue = inputValue;
+			notify("optionsChange", {
+				optionsLength: visibleCount,
+				inputValue
+			});
+		}
+	}
+	/** Delay before announcing loading in the live region (ms). */
+	const LOADING_ANNOUNCEMENT_DELAY = 500;
+	/** Number of currently mounted skeleton placeholders. */
+	let skeletonCount = 0;
+	/** Timer for debounced loading announcement. */
+	let loadingTimer;
+	/** Whether a loading announcement has been sent since the last open. */
+	let announcementSent = false;
+	/** Start or restart the debounced loading announcement timer if conditions are met. */
+	function startLoadingAnnouncementTimer() {
+		clearTimeout(loadingTimer);
+		if (skeletonCount > 0 && isOpenState) loadingTimer = setTimeout(() => {
+			if (skeletonCount > 0 && isOpenState) {
+				announcementSent = true;
+				notify("loadingAnnouncement", true);
+			}
+		}, LOADING_ANNOUNCEMENT_DELAY);
+	}
+	/**
+	* Called when the skeleton count transitions between 0 and >0 (or vice versa).
+	* Fires `loadingChange` immediately and manages the debounced `loadingAnnouncement`.
+	*/
+	function onSkeletonCountChange() {
+		const isLoading = skeletonCount > 0;
+		notify("loadingChange", isLoading);
+		if (isLoading) startLoadingAnnouncementTimer();
+		else {
+			clearTimeout(loadingTimer);
+			if (announcementSent) {
+				announcementSent = false;
+				notify("loadingAnnouncement", false);
+			}
+		}
+	}
+	let handle;
+	/** Detach everything (abort all listeners, clear state). */
+	function detach() {
+		abortController?.abort();
+		abortController = null;
+		focusNav = null;
+	}
+	/**
+	* Attach the shared keydown listener to the trigger.
+	*
+	* Handles: Enter, ArrowDown, ArrowUp, Escape (2-tier), PageUp, PageDown.
+	* Mode-specific keys (Space, Home, End, ArrowLeft/Right, printable chars, etc.)
+	* are delegated to the `onKeydown` hook provided by the mode controller.
+	*/
+	function attachTriggerKeydown(triggerEl, signal, onKeydown) {
+		function handleKeydown(event) {
+			if (onKeydown?.(event)) {
+				event.stopPropagation();
+				event.preventDefault();
+				return;
+			}
+			let flag = false;
+			const { altKey } = event;
+			const nav = handle.focusNav;
+			switch (event.key) {
+				case "Enter":
+					if (handle.isOpen && nav?.selectors.activeItem) {
+						const { activeItem } = nav.selectors;
+						if (!isOptionDisabled(activeItem)) activeItem.click();
+						flag = true;
+					} else if (handle.isOpen && !handle.isMultiSelect) handle.setIsOpen(false);
+					break;
+				case "ArrowDown":
+					if (!handle.isOpen) {
+						handle.setIsOpen(true);
+						if (!altKey) nav?.goTo((s) => s.getMatching(isSelected) ?? s.getFirst());
+					} else if (nav?.selectors.hasNavigableItems && !altKey) if (nav.selectors.activeItem) nav.goDown();
+					else nav.goTo((s) => s.getMatching(isSelected) ?? s.getFirst());
+					flag = true;
+					break;
+				case "ArrowUp":
+					if (!handle.isOpen && !altKey) {
+						handle.setIsOpen(true);
+						nav?.goTo((s) => s.getMatching(isSelected) ?? s.getLast());
+					} else if (handle.isOpen && nav?.selectors.hasNavigableItems) {
+						if (nav.selectors.activeItem) nav.goUp();
+						else if (!altKey) nav.goTo((s) => s.getMatching(isSelected) ?? s.getLast());
+					}
+					flag = true;
+					break;
+				case "Escape":
+					if (handle.isOpen) handle.setIsOpen(false);
+					else handle.select(null);
+					flag = true;
+					break;
+				case "PageUp":
+					if (handle.isOpen && nav?.selectors.activeItem) nav.goToOffset(-10);
+					flag = true;
+					break;
+				case "PageDown":
+					if (handle.isOpen && nav?.selectors.activeItem) nav.goToOffset(10);
+					flag = true;
+					break;
+				default: break;
+			}
+			if (flag) {
+				event.stopPropagation();
+				event.preventDefault();
+			}
+		}
+		triggerEl.addEventListener("keydown", (e) => handleKeydown(e), { signal });
+	}
+	/** Try to fully attach when both trigger and listbox are available. */
+	function tryAttach() {
+		if (!trigger) return;
+		const isNewController = !abortController;
+		if (!abortController) abortController = new AbortController();
+		if (!trigger.getAttribute("aria-activedescendant")) trigger.setAttribute("aria-activedescendant", "");
+		trigger.setAttribute("aria-expanded", String(isOpenState));
+		if (isNewController) {
+			const onKeydown = onTriggerAttach?.(handle, abortController.signal) || void 0;
+			attachTriggerKeydown(trigger, abortController.signal, onKeydown);
+			trigger.addEventListener("focusout", () => {
+				handle.setIsOpen(false);
+			}, { signal: abortController.signal });
+		}
+		if (listbox && !focusNav) focusNav = setupListbox(handle, abortController.signal, notify, { wrapNavigation });
+	}
+	handle = {
+		get trigger() {
+			return trigger;
+		},
+		get listbox() {
+			return listbox;
+		},
+		get focusNav() {
+			return focusNav;
+		},
+		get isOpen() {
+			return isOpenState;
+		},
+		get isMultiSelect() {
+			return listbox?.getAttribute("aria-multiselectable") === "true";
+		},
+		get isLoading() {
+			return skeletonCount > 0;
+		},
+		setIsOpen(isOpen) {
+			if (isOpenState === isOpen) return;
+			isOpenState = isOpen;
+			if (!isOpen) {
+				focusNav?.clear();
+				clearTimeout(loadingTimer);
+				if (announcementSent) {
+					announcementSent = false;
+					notify("loadingAnnouncement", false);
+				}
+			} else if (skeletonCount > 0) startLoadingAnnouncementTimer();
+			trigger?.setAttribute("aria-expanded", String(isOpen));
+			notify("open", isOpen);
+		},
+		select(option) {
+			callbacks.onSelect?.({ value: option ? getOptionValue(option) : "" });
+			if (option && !handle.isMultiSelect) {
+				handle.focusNav?.clear();
+				requestAnimationFrame(() => {
+					handle.setIsOpen(false);
+				});
+			}
+		},
+		flushPendingNavigation() {
+			focusNav?.flushPendingNavigation();
+		},
+		registerOption(element, callback) {
+			const filterLower = filterValue.toLowerCase();
+			const text = getOptionValue(element).toLowerCase();
+			const isFiltered = filterLower.length > 0 && !text.includes(filterLower);
+			optionRegistrations.set(element, {
+				callback,
+				lastFiltered: isFiltered
+			});
+			callback(isFiltered);
+			notifyVisibilityChange();
+			return () => {
+				optionRegistrations.delete(element);
+				notifyVisibilityChange();
+			};
+		},
+		setFilter(newFilter) {
+			filterValue = newFilter;
+			const filterLower = newFilter.toLowerCase();
+			for (const [element, reg] of optionRegistrations) {
+				const text = getOptionValue(element).toLowerCase();
+				const isFiltered = filterLower.length > 0 && !text.includes(filterLower);
+				if (isFiltered !== reg.lastFiltered) {
+					reg.lastFiltered = isFiltered;
+					reg.callback(isFiltered);
+				}
+			}
+			notifyVisibilityChange();
+		},
+		refilterOption(element) {
+			const reg = optionRegistrations.get(element);
+			if (!reg) return;
+			const filterLower = filterValue.toLowerCase();
+			const text = getOptionValue(element).toLowerCase();
+			const isFiltered = filterLower.length > 0 && !text.includes(filterLower);
+			if (isFiltered !== reg.lastFiltered) {
+				reg.lastFiltered = isFiltered;
+				reg.callback(isFiltered);
+				notifyVisibilityChange();
+			}
+		},
+		registerSection(element, callback) {
+			sectionRegistrations.set(element, {
+				callback,
+				last: {
+					hidden: false,
+					"aria-hidden": false
+				}
+			});
+			notifySection(element, sectionRegistrations, optionRegistrations, true);
+			return () => {
+				sectionRegistrations.delete(element);
+			};
+		},
+		registerSkeleton() {
+			const wasLoading = skeletonCount > 0;
+			skeletonCount += 1;
+			if (!wasLoading) onSkeletonCountChange();
+			return () => {
+				skeletonCount -= 1;
+				if (skeletonCount === 0) onSkeletonCountChange();
+			};
+		},
+		registerTrigger(newTrigger) {
+			if (trigger && trigger !== newTrigger) detach();
+			trigger = newTrigger;
+			tryAttach();
+			return () => {
+				if (trigger === newTrigger) {
+					detach();
+					trigger = null;
+				}
+			};
+		},
+		registerListbox(newListbox) {
+			if (listbox === newListbox) return () => {};
+			const hadListbox = !!listbox;
+			listbox = newListbox;
+			if (trigger && abortController) if (!hadListbox) focusNav = setupListbox(handle, abortController.signal, notify, { wrapNavigation });
+			else {
+				detach();
+				tryAttach();
+			}
+			return () => {
+				if (listbox === newListbox) {
+					listbox = null;
+					focusNav = null;
+				}
+			};
+		},
+		subscribe(event, callback) {
+			subscribers[event].add(callback);
+			return () => {
+				subscribers[event].delete(callback);
+			};
+		},
+		destroy() {
+			detach();
+			trigger = null;
+			listbox = null;
+			filterValue = "";
+			lastOptionsLength = 0;
+			lastInputValue = "";
+			optionRegistrations.clear();
+			sectionRegistrations.clear();
+			skeletonCount = 0;
+			clearTimeout(loadingTimer);
+			announcementSent = false;
+			for (const set of Object.values(subscribers)) set.clear();
+		}
+	};
+	return handle;
+}
+//#endregion
+export { setupCombobox };

package/_internal/packages/lumx-core/src/js/components/Combobox/setupComboboxButton.js

@@ -0,0 +1,84 @@
+import { createSelectorTreeWalker } from "../../utils/browser/createSelectorTreeWalker.js";
+import { getOptionLabel } from "./utils.js";
+import { setupCombobox } from "./setupCombobox.js";
+import { createTypeahead } from "../../utils/typeahead/index.js";
+import { isPrintableKey } from "../../utils/browser/isPrintableKey.js";
+//#region ../lumx-core/src/js/components/Combobox/setupComboboxButton.ts
+/**
+* Set up a combobox with a button trigger (select-only pattern).
+*
+* Creates a full combobox handle with the button-mode controller automatically
+* wired in and the trigger registered. The consumer only needs to call
+* `handle.registerListbox(listbox)`.
+*
+* Handles: Space (select/open), Home/End (listbox navigation),
+* printable characters (typeahead), and click (toggle).
+*
+* @param button    The button element to use as the combobox trigger.
+* @param callbacks Callbacks for select and open/close events.
+* @returns A ComboboxHandle for interacting with the combobox.
+*/
+function setupComboboxButton(button, callbacks) {
+	const handle = setupCombobox(callbacks, void 0, (combobox, signal) => {
+		const typeahead = createTypeahead(() => {
+			if (!combobox.listbox) return null;
+			const selector = combobox.focusNav?.type === "grid" ? "[role=\"gridcell\"]" : "[role=\"option\"]";
+			return createSelectorTreeWalker(combobox.listbox, selector);
+		}, getOptionLabel, signal);
+		button.addEventListener("click", () => combobox.setIsOpen(!combobox.isOpen), { signal });
+		return (event) => {
+			const nav = combobox.focusNav;
+			switch (event.key) {
+				case "Tab":
+					if (combobox.isOpen && nav?.selectors.activeItem) combobox.select(nav.selectors.activeItem);
+					return false;
+				case " ":
+					if (combobox.isOpen && nav?.selectors.activeItem) nav.selectors.activeItem.click();
+					else combobox.setIsOpen(true);
+					return true;
+				case "ArrowUp":
+					if (event.altKey && combobox.isOpen && nav?.selectors.activeItem) {
+						combobox.select(nav.selectors.activeItem);
+						combobox.setIsOpen(false);
+						return true;
+					}
+					return false;
+				case "Home":
+					combobox.setIsOpen(true);
+					nav?.goTo((n) => n.getFirst());
+					return true;
+				case "End":
+					combobox.setIsOpen(true);
+					nav?.goTo((n) => n.getLast());
+					return true;
+				case "ArrowLeft":
+					if (nav?.type === "grid" && combobox.isOpen && nav.selectors.activeItem) {
+						nav.goLeft();
+						return true;
+					}
+					return false;
+				case "ArrowRight":
+					if (nav?.type === "grid" && combobox.isOpen && nav.selectors.activeItem) {
+						nav.goRight();
+						return true;
+					}
+					return false;
+				case "Escape":
+					if (combobox.isOpen) combobox.setIsOpen(false);
+					return true;
+				default:
+					if (isPrintableKey(event)) {
+						combobox.setIsOpen(true);
+						typeahead.handle(event.key, nav?.selectors.activeItem ?? null);
+						nav?.goTo((n) => typeahead.rematch(n.activeItem));
+						return true;
+					}
+					return false;
+			}
+		};
+	});
+	handle.registerTrigger(button);
+	return handle;
+}
+//#endregion
+export { setupComboboxButton };

package/_internal/packages/lumx-core/src/js/components/Combobox/setupComboboxInput.js

@@ -0,0 +1,95 @@
+import { setupCombobox } from "./setupCombobox.js";
+//#region ../lumx-core/src/js/components/Combobox/setupComboboxInput.ts
+/**
+* Set up a combobox with an input trigger (autocomplete/filter pattern).
+*
+* Creates a full combobox handle with the input-mode controller automatically
+* wired in and the trigger registered. The consumer only needs to call
+* `handle.registerListbox(listbox)`.
+*
+* Handles: Home/End (text cursor), ArrowLeft/Right (clear active descendant),
+* filtering (on input and on open), and focus behavior.
+*
+* @param input   The input element to use as the combobox trigger.
+* @param options Options and callbacks for configuring the input-mode controller.
+* @returns A ComboboxHandle for interacting with the combobox.
+*/
+function setupComboboxInput(input, options) {
+	let handle;
+	const { filter = "auto", onSelect: optionOnSelect, onInput: onInputCallback } = options;
+	const openOnFocus = options.openOnFocus ?? filter === "off";
+	const autoFilter = filter === "auto";
+	/** Check if the input is disabled (native `disabled` attribute or `aria-disabled="true"`). */
+	const isDisabled = () => input.disabled || input.getAttribute("aria-disabled") === "true";
+	/**
+	* True when the current input value came from user typing (real InputEvent).
+	* False when the value was set programmatically (select, clear, etc.).
+	* Used to decide whether to re-apply the filter when the combobox opens.
+	*/
+	let userHasTyped = false;
+	/**
+	* Wraps the consumer's onSelect to perform input-mode side effects after selection:
+	* resets the filter and typing state.
+	*/
+	const onSelect = (option) => {
+		optionOnSelect?.(option);
+		userHasTyped = false;
+		if (autoFilter) handle.setFilter("");
+	};
+	handle = setupCombobox({ onSelect }, { wrapNavigation: true }, (combobox, signal) => {
+		signal.addEventListener("abort", () => {
+			userHasTyped = false;
+		});
+		input.addEventListener("input", (event) => {
+			if (!(event instanceof InputEvent)) return;
+			if (isDisabled()) return;
+			combobox.focusNav?.clear();
+			userHasTyped = true;
+			onInputCallback?.(input.value);
+			combobox.setIsOpen(true);
+			if (autoFilter) combobox.setFilter(input.value);
+		}, { signal });
+		input.addEventListener("focus", () => {
+			if (isDisabled()) return;
+			combobox.focusNav?.clear();
+			if (openOnFocus) combobox.setIsOpen(true);
+		}, { signal });
+		input.addEventListener("click", () => {
+			if (isDisabled()) return;
+			combobox.setIsOpen(true);
+		}, { signal });
+		const unsubscribeOpen = combobox.subscribe("open", (isOpen) => {
+			if (isOpen && autoFilter && userHasTyped) combobox.setFilter(input.value);
+		});
+		signal.addEventListener("abort", unsubscribeOpen);
+		return (event) => {
+			const nav = combobox.focusNav;
+			switch (event.key) {
+				case "Home":
+					input.setSelectionRange(0, 0);
+					nav?.clear();
+					return true;
+				case "End": {
+					const len = input.value.length;
+					input.setSelectionRange(len, len);
+					nav?.clear();
+					return true;
+				}
+				case "ArrowLeft":
+				case "ArrowRight":
+					if (nav?.type === "grid" && nav.selectors.activeItem) {
+						if (event.key === "ArrowLeft") nav.goLeft();
+						else nav.goRight();
+						return true;
+					}
+					nav?.clear();
+					return false;
+				default: return false;
+			}
+		};
+	});
+	handle.registerTrigger(input);
+	return handle;
+}
+//#endregion
+export { setupComboboxInput };

package/_internal/packages/lumx-core/src/js/components/Combobox/setupListbox.js

@@ -0,0 +1,84 @@
+import { createListFocusNavigation } from "../../utils/focusNavigation/createListFocusNavigation.js";
+import { createGridFocusNavigation } from "../../utils/focusNavigation/createGridFocusNavigation.js";
+import { isActionCell, isOptionDisabled } from "./utils.js";
+//#region ../lumx-core/src/js/components/Combobox/setupListbox.ts
+/**
+* Set up focus navigation and delegated event listeners on a listbox element.
+*
+* This merges two concerns:
+* 1. Creating the appropriate {@link FocusNavigationController} (grid or list mode)
+*    with callbacks that manage `aria-activedescendant` and visual focus indicators.
+* 2. Attaching delegated `click` and `mousedown` listeners to the listbox for
+*    option selection and blur prevention.
+*
+* The caller is responsible for guarding against duplicate calls (i.e., checking
+* that a focus navigation controller does not already exist before calling)
+* and ensuring `handle.trigger` and `handle.listbox` are non-null.
+*
+* @param handle The combobox handle (provides trigger, listbox, select, etc.).
+* @param signal Abort signal used to clean up all attached listeners.
+* @param notify Notify subscribers of combobox events.
+* @returns The created focus navigation controller.
+*/
+function setupListbox(handle, signal, notify, options) {
+	const trigger = handle.trigger;
+	const listbox = handle.listbox;
+	const isGrid = listbox.getAttribute("role") === "grid";
+	const itemSelector = "[role=\"option\"]";
+	const focusCallbacks = {
+		onActivate: (item) => {
+			item.setAttribute("data-focus-visible-added", "true");
+			trigger.setAttribute("aria-activedescendant", item.id);
+			notify("activeDescendantChange", item.id);
+			requestAnimationFrame(() => {
+				if (item === (!isGrid && listbox.querySelector(`:scope > :has(${itemSelector}):not(:has(~ * ${itemSelector})) ${itemSelector}`))) listbox.lastElementChild?.scrollIntoView({ block: "nearest" });
+				else (item.closest("[role=listbox] > *") || item).scrollIntoView({ block: "nearest" });
+			});
+		},
+		onDeactivate: (item) => {
+			item.removeAttribute("data-focus-visible-added");
+		},
+		onClear: () => {
+			trigger.setAttribute("aria-activedescendant", "");
+			notify("activeDescendantChange", null);
+		}
+	};
+	let focusNav;
+	if (isGrid) {
+		focusNav = createGridFocusNavigation({
+			type: "grid",
+			container: listbox,
+			rowSelector: "[role=\"row\"]",
+			cellSelector: "[role=\"gridcell\"]",
+			wrap: true
+		}, focusCallbacks, signal);
+		trigger.setAttribute("aria-haspopup", "grid");
+	} else focusNav = createListFocusNavigation({
+		type: "list",
+		container: listbox,
+		itemSelector,
+		wrap: options?.wrapNavigation,
+		getActiveItem: () => {
+			const id = trigger.getAttribute("aria-activedescendant");
+			return id && listbox.querySelector(`#${CSS.escape(id)}`) || null;
+		}
+	}, focusCallbacks, signal);
+	const cellSelector = isGrid ? "[role=\"gridcell\"]" : "[role=\"option\"]";
+	listbox.addEventListener("click", (event) => {
+		const cell = event.target.closest(cellSelector);
+		if (!cell) return;
+		if (isOptionDisabled(cell)) {
+			event.stopPropagation();
+			return;
+		}
+		if (isGrid && isActionCell(cell)) return;
+		handle.select(cell);
+		trigger.focus();
+	}, { signal });
+	listbox.addEventListener("mousedown", (event) => {
+		if (event.target.closest(cellSelector)) event.preventDefault();
+	}, { signal });
+	return focusNav;
+}
+//#endregion
+export { setupListbox };

package/_internal/packages/lumx-core/src/js/components/Combobox/subscribeComboboxState.js

@@ -0,0 +1,43 @@
+//#region ../lumx-core/src/js/components/Combobox/subscribeComboboxState.ts
+/**
+* Delay before inserting content into the aria-live region after the popover opens (ms).
+*
+* The popover uses `closeMode="hide"` (`display:none` when closed), so the live region
+* container is not in the accessibility tree until the popover becomes visible.
+* Screen readers only detect content *changes* in live regions that are already visible.
+* This delay ensures the popover's `display:none` is removed and the accessibility tree
+* is updated before content is inserted, so screen readers reliably announce it.
+*/
+var OPEN_ANNOUNCEMENT_DELAY = 100;
+/**
+* Subscribe to the combobox handle events needed by `ComboboxState`.
+*
+* Manages three subscriptions:
+* - `loadingChange` → `setIsLoading` (+ synchronous initial read of `handle.isLoading`)
+* - `loadingAnnouncement` → `setShouldAnnounce`
+* - `open` → `setIsOpen` (deferred by {@link OPEN_ANNOUNCEMENT_DELAY}ms on open, immediate on close)
+*
+* @param handle  The combobox handle to subscribe to.
+* @param setters Framework-specific state setters.
+* @returns A cleanup function that unsubscribes all events and clears timers.
+*/
+function subscribeComboboxState(handle, setters) {
+	const { setIsLoading, setShouldAnnounce, setIsOpen } = setters;
+	setIsLoading(handle.isLoading);
+	const unsubLoadingChange = handle.subscribe("loadingChange", setIsLoading);
+	const unsubLoadingAnnouncement = handle.subscribe("loadingAnnouncement", setShouldAnnounce);
+	let openTimer;
+	const unsubOpen = handle.subscribe("open", (open) => {
+		clearTimeout(openTimer);
+		if (open) openTimer = setTimeout(() => setIsOpen(true), OPEN_ANNOUNCEMENT_DELAY);
+		else setIsOpen(false);
+	});
+	return () => {
+		unsubLoadingChange();
+		unsubLoadingAnnouncement();
+		unsubOpen();
+		clearTimeout(openTimer);
+	};
+}
+//#endregion
+export { subscribeComboboxState };