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

package/_internal/packages/lumx-core/src/js/utils/InfiniteScroll/setupInfiniteScrollObserver.js

@@ -0,0 +1,18 @@
+//#region ../lumx-core/src/js/utils/InfiniteScroll/setupInfiniteScrollObserver.ts
+/**
+* Sets up an IntersectionObserver on the given element.
+* Calls `callback` when at least one observed entry is intersecting.
+* Returns a cleanup function that unobserves the element.
+*/
+function setupInfiniteScrollObserver(element, callback, options) {
+	const observer = new IntersectionObserver((entries = []) => {
+		if (!entries.some((entry) => entry.isIntersecting)) return;
+		callback();
+	}, options);
+	observer.observe(element);
+	return () => {
+		observer.unobserve(element);
+	};
+}
+//#endregion
+export { setupInfiniteScrollObserver };

package/_internal/packages/lumx-core/src/js/utils/Portal/index.d.ts

@@ -0,0 +1,28 @@
+//#region ../lumx-core/src/js/utils/Portal/index.d.ts
+/**
+ * Shared types for Portal and PortalProvider.
+ *
+ * Portal renders children in a subtree outside the current DOM hierarchy.
+ * PortalProvider customizes where Portal children render.
+ *
+ * Unlike other core components, Portal has no shared render function
+ * since the implementation is entirely framework-specific
+ * (React's createPortal vs Vue's Teleport).
+ */
+type Container = DocumentFragment | Element | string;
+/**
+ * Portal initializing function.
+ * If it does not provide a container, the Portal children will render in the standard component tree and not in a portal.
+ */
+type PortalInit = () => {
+  container?: Container;
+  teardown?: () => void;
+};
+interface PortalProps {
+  enabled?: boolean;
+}
+interface PortalProviderProps {
+  value: PortalInit;
+}
+//#endregion
+export { PortalInit, PortalProps, PortalProviderProps };

package/_internal/packages/lumx-core/src/js/utils/_internal/color/resolveColorWithVariants.js

@@ -0,0 +1,9 @@
+//#region ../lumx-core/src/js/utils/_internal/color/resolveColorWithVariants.ts
+/** Resolve color & color variant from a `ColorWithVariants` and optionally a `ColorVariant`. */
+function resolveColorWithVariants(colorWithVariants, colorVariant) {
+	if (!colorWithVariants) return [void 0, colorVariant];
+	const [color, baseColorVariant] = colorWithVariants.split("-");
+	return [color, colorVariant || baseColorVariant];
+}
+//#endregion
+export { resolveColorWithVariants };

package/_internal/packages/lumx-core/src/js/utils/browser/createSelectorTreeWalker.js

@@ -0,0 +1,20 @@
+//#region ../lumx-core/src/js/utils/browser/createSelectorTreeWalker.ts
+/**
+* Create a TreeWalker that iterates over elements matching a CSS selector
+* within a container.
+*
+* Uses `NodeFilter.SHOW_ELEMENT` and accepts nodes that match the given
+* selector, skipping everything else. The returned walker can be used with
+* `nextNode()` / `previousNode()` for lazy, sequential DOM traversal.
+*
+* @param container The root element to walk within.
+* @param selector CSS selector that items must match.
+* @returns A TreeWalker scoped to the container and filtered by the selector.
+*/
+function createSelectorTreeWalker(container, selector) {
+	return document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, { acceptNode(node) {
+		return node.matches(selector) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+	} });
+}
+//#endregion
+export { createSelectorTreeWalker };

package/_internal/packages/lumx-core/src/js/utils/browser/css/combineSize.js

@@ -0,0 +1,14 @@
+//#region ../lumx-core/src/js/utils/browser/css/combineSize.ts
+/** Create a CSS min()/max() combiner function. */
+function combineSize(combinator) {
+	return (size1, size2) => {
+		if (size1 && size2) return `${combinator}(${size1}, ${size2})`;
+		return size1 || size2 || "";
+	};
+}
+/** Combine two CSS values with `min()`. */
+var cssMin = combineSize("min");
+/** Combine two CSS values with `max()`. */
+var cssMax = combineSize("max");
+//#endregion
+export { cssMax, cssMin };

package/_internal/packages/lumx-core/src/js/utils/browser/css/resolveCssSize.js

@@ -0,0 +1,8 @@
+import { Size } from "../../../constants/enums/index.js";
+//#region ../lumx-core/src/js/utils/browser/css/resolveCssSize.ts
+function resolveCssSize(value) {
+	if (value && value in Size) return `var(--lumx-size-${value})`;
+	return value;
+}
+//#endregion
+export { resolveCssSize };

package/_internal/packages/lumx-core/src/js/utils/browser/css/types.d.ts

@@ -0,0 +1,7 @@
+//#region ../lumx-core/src/js/utils/browser/css/types.d.ts
+/** Viewport-relative height value, e.g. `50vh`. */
+type VHSize = `${number}vh`;
+/** Pixel value, e.g. `12px`. */
+type PXSize = `${number}px`;
+//#endregion
+export { PXSize, VHSize };

package/_internal/packages/lumx-core/src/js/utils/browser/isFocusVisible.js

@@ -0,0 +1,11 @@
+//#region ../lumx-core/src/js/utils/browser/isFocusVisible.ts
+/** Check if the focus is visible on the given element */
+var isFocusVisible = (element) => {
+	try {
+		return element?.matches?.(":focus-visible, [data-focus-visible-added]");
+	} catch (_ignored) {
+		return true;
+	}
+};
+//#endregion
+export { isFocusVisible };

package/_internal/packages/lumx-core/src/js/utils/browser/isHoverNotSupported.js

@@ -0,0 +1,5 @@
+//#region ../lumx-core/src/js/utils/browser/isHoverNotSupported.ts
+/** Return true if the browser does not support pointer hover */
+var isHoverNotSupported = () => !!window.matchMedia?.("(hover: none)").matches;
+//#endregion
+export { isHoverNotSupported };

package/_internal/packages/lumx-core/src/js/utils/browser/isPrintableKey.js

@@ -0,0 +1,12 @@
+//#region ../lumx-core/src/js/utils/browser/isPrintableKey.ts
+/**
+* Is the key a single printable character (not Space, no modifier keys)?
+*
+* Used by typeahead-style keyboard handlers (menu, combobox) to detect when a
+* keypress should start/continue a type-to-search rather than trigger navigation.
+*/
+function isPrintableKey({ key, altKey, ctrlKey, metaKey }) {
+	return key.length === 1 && key !== " " && !altKey && !ctrlKey && !metaKey;
+}
+//#endregion
+export { isPrintableKey };

package/_internal/packages/lumx-core/src/js/utils/browser/lastDescendant.js

@@ -0,0 +1,9 @@
+//#region ../lumx-core/src/js/utils/browser/lastDescendant.ts
+/** Deepest last-child descendant of `el` (or `el` itself if it has no children). */
+function lastDescendant(element) {
+	let node = element;
+	while (node.lastElementChild) node = node.lastElementChild;
+	return node;
+}
+//#endregion
+export { lastDescendant };

package/_internal/packages/lumx-core/src/js/utils/browser/querySelectorInclusive.js

@@ -0,0 +1,18 @@
+//#region ../lumx-core/src/js/utils/browser/querySelectorInclusive.ts
+/**
+* Like `querySelectorAll`, but also tests the root node itself.
+*
+* Yields the root element first (if it matches), then all matching descendants
+* in document order. Being a generator, callers that only need the first match
+* can break early without collecting the full list.
+*
+* @param node  The starting DOM node.
+* @param selector  CSS selector to match against.
+*/
+function* querySelectorInclusive(node, selector) {
+	if (!(node instanceof HTMLElement)) return;
+	if (node.matches(selector)) yield node;
+	yield* node.querySelectorAll(selector);
+}
+//#endregion
+export { querySelectorInclusive };

package/_internal/packages/lumx-core/src/js/utils/browser/trackContainerFocus.js

@@ -0,0 +1,28 @@
+//#region ../lumx-core/src/js/utils/browser/trackContainerFocus.ts
+/**
+* Track whether the container currently has focus.
+*
+* We can't rely on `document.activeElement` inside MutationObserver callbacks because
+* the browser moves focus to `<body>` before they fire. focusout with `relatedTarget === null`
+* (element removed from DOM) keeps the flag true so the observer can move focus to a fallback.
+*/
+function trackContainerFocus(container, signal) {
+	let hasFocus = container.contains(document.activeElement);
+	container.addEventListener("focusin", () => {
+		hasFocus = true;
+	}, { signal });
+	container.addEventListener("focusout", (evt) => {
+		const newTarget = evt.relatedTarget;
+		if (newTarget && !container.contains(newTarget)) hasFocus = false;
+	}, { signal });
+	return {
+		get hasFocus() {
+			return hasFocus;
+		},
+		reset() {
+			hasFocus = false;
+		}
+	};
+}
+//#endregion
+export { trackContainerFocus };

package/_internal/packages/lumx-core/src/js/utils/classNames/action-area/index.js

@@ -0,0 +1,22 @@
+import { block } from "../bem/block.js";
+//#region ../lumx-core/src/js/utils/classNames/action-area/index.ts
+var PREFIX = "lumx-action-area";
+var ACTION_ELEMENT = `${PREFIX}__action`;
+/**
+* Action area CSS utility.
+*
+* Apply `actionArea()` to the container element to make it a positioning context
+* for the action's expanded click area.
+*
+* Apply `actionArea.action()` to the primary interactive element (link or button)
+* whose click area should expand to fill the entire container.
+*/
+var actionArea = Object.assign(
+	/** Action area container class. Sets `position: relative`. */
+	() => PREFIX,
+	{ 
+	/** Action element class. Adds a `::before` pseudo-element with `position: absolute; inset: 0` to expand the click area. */
+action: (modifiers) => block(ACTION_ELEMENT, modifiers) }
+);
+//#endregion
+export { actionArea };

package/_internal/packages/lumx-core/src/js/utils/classNames/bem/block.js

@@ -0,0 +1,18 @@
+import { __toESM } from "../../../../../../../_virtual/_rolldown/runtime.js";
+import { require_classnames } from "../../../../../../../node_modules/classnames/index.js";
+import { modifier } from "./modifier.js";
+//#region ../lumx-core/src/js/utils/classNames/bem/block.ts
+var import_classnames = /* @__PURE__ */ __toESM(require_classnames(), 1);
+function block(baseName, modifiersOrAdditionalClasses, additionalClasses) {
+	let modifiers;
+	let classes;
+	if (typeof modifiersOrAdditionalClasses === "string" || Array.isArray(modifiersOrAdditionalClasses)) classes = modifiersOrAdditionalClasses;
+	else {
+		modifiers = modifiersOrAdditionalClasses;
+		classes = additionalClasses;
+	}
+	if (!modifiers && !classes) return baseName;
+	return (0, import_classnames.default)(classes, baseName, modifiers ? modifier(baseName, modifiers) : null);
+}
+//#endregion
+export { block };

package/_internal/packages/lumx-core/src/js/utils/classNames/bem/element.js

@@ -0,0 +1,7 @@
+import { block } from "./block.js";
+//#region ../lumx-core/src/js/utils/classNames/bem/element.ts
+function element(baseClass, elem, modifiersOrAdditionalClasses, additionalClasses) {
+	return block(`${baseClass}__${elem}`, modifiersOrAdditionalClasses, additionalClasses);
+}
+//#endregion
+export { element };

package/_internal/packages/lumx-core/src/js/utils/classNames/bem/index.js

@@ -0,0 +1,22 @@
+import { modifier } from "./modifier.js";
+import { block } from "./block.js";
+import { element } from "./element.js";
+//#region ../lumx-core/src/js/utils/classNames/bem/index.ts
+/**
+* Setup BEM block & element generation for a given base name.
+*/
+function bem(baseName) {
+	function blockFn(modifiersOrAdditionalClasses, additionalClasses) {
+		return block(baseName, modifiersOrAdditionalClasses, additionalClasses);
+	}
+	function elementFn(elem, modifiersOrAdditionalClasses, additionalClasses) {
+		return element(baseName, elem, modifiersOrAdditionalClasses, additionalClasses);
+	}
+	return {
+		block: blockFn,
+		element: elementFn,
+		modifier: (modifiers) => modifier(baseName, modifiers)
+	};
+}
+//#endregion
+export { bem };

package/_internal/packages/lumx-core/src/js/utils/classNames/bem/modifier.js

@@ -0,0 +1,19 @@
+//#region ../lumx-core/src/js/utils/classNames/bem/modifier.ts
+/**
+* Generates BEM modifier class names.
+*
+* @param baseName   The base BEM class to attach modifiers to.
+* @param modifiers  Map of modifier names to boolean values.
+* @returns Combined modifier class names string.
+*
+* @example
+* modifier('button', { active: true }); // 'button--active'
+* modifier('button', { active: true, disabled: false }); // 'button--active'
+*/
+function modifier(baseName, modifiers) {
+	const modifierClasses = [];
+	for (const [key, value] of Object.entries(modifiers)) if (value) modifierClasses.push(`${baseName}--${key}`);
+	return modifierClasses.join(" ");
+}
+//#endregion
+export { modifier };

package/_internal/packages/lumx-core/src/js/utils/classNames/color/index.js

@@ -0,0 +1,38 @@
+import { resolveColorWithVariants } from "../../_internal/color/resolveColorWithVariants.js";
+import { ColorVariant } from "@lumx/core/js/constants";
+//#region ../lumx-core/src/js/utils/classNames/color/index.ts
+/**
+* Generates a Lumx color class name for the given type, color and variant.
+* This is the base function used by font() and background() utilities.
+*
+* @param type - The color class type ('font' or 'background')
+* @param propColor - The color palette name (e.g., 'primary', 'dark') with optional variant suffix (e.g., 'primary-L2')
+* @param propColorVariant - Optional color variant override (e.g., 'L1', 'L2', 'D1', 'N')
+* @returns The Lumx color class name or undefined if no color is provided
+*
+* @example
+* color('font', 'dark', 'L2'); // 'lumx-color-font-dark-L2'
+* color('background', 'primary'); // 'lumx-color-background-primary-N'
+* color('font', 'primary-L2'); // 'lumx-color-font-primary-L2'
+* color('font', undefined); // undefined
+*/
+function color(type, propColor, propColorVariant) {
+	const [cColor, cColorVariant = ColorVariant.N] = resolveColorWithVariants(propColor, propColorVariant);
+	return `lumx-color-${type}-${cColor}-${cColorVariant}`;
+}
+/**
+* Generates a Lumx font color class name for the given color and variant.
+*
+* @param propColor - The color palette name (e.g., 'primary', 'dark') with optional variant suffix (e.g., 'primary-L2')
+* @param propColorVariant - Optional color variant override (e.g., 'L1', 'L2', 'D1', 'N')
+* @returns The Lumx font color class name or undefined if no color is provided
+*
+* @example
+* font('dark', 'L2'); // 'lumx-color-font-dark-L2'
+* font('primary-L2'); // 'lumx-color-font-primary-L2'
+* font('primary'); // 'lumx-color-font-primary-N'
+* font(undefined); // undefined
+*/
+var font = (propColor, propColorVariant) => color("font", propColor, propColorVariant);
+//#endregion
+export { color, font };

package/_internal/packages/lumx-core/src/js/utils/classNames/index.js

@@ -0,0 +1,12 @@
+import { __toESM } from "../../../../../../_virtual/_rolldown/runtime.js";
+import { require_classnames } from "../../../../../../node_modules/classnames/index.js";
+import "./action-area/index.js";
+import "./color/index.js";
+import "./typography/index.js";
+import "./spacing/index.js";
+import "./visually-hidden/index.js";
+import "./bem/index.js";
+//#region ../lumx-core/src/js/utils/classNames/index.ts
+var import_classnames = /* @__PURE__ */ __toESM(require_classnames(), 1);
+//#endregion
+export { import_classnames };

package/_internal/packages/lumx-core/src/js/utils/classNames/spacing/index.js

@@ -0,0 +1,31 @@
+import "../../../../../../../_virtual/_rolldown/runtime.js";
+import { require_classnames } from "../../../../../../../node_modules/classnames/index.js";
+import { Size } from "@lumx/core/js/constants";
+require_classnames();
+/** Set of valid AbstractSize values for runtime detection. */
+var ABSTRACT_SIZES = new Set([
+	Size.tiny,
+	Size.regular,
+	Size.medium,
+	Size.big,
+	Size.huge
+]);
+function isAbstractSize(value) {
+	return typeof value === "string" && ABSTRACT_SIZES.has(value);
+}
+function spacing(type, directionOrSize, size) {
+	const isShorthand = isAbstractSize(directionOrSize) || directionOrSize === null && size === void 0;
+	const direction = isShorthand ? void 0 : directionOrSize ?? void 0;
+	const resolvedSize = isShorthand ? directionOrSize : size;
+	let baseClass = `lumx-spacing-${type}`;
+	if (direction && direction !== "all") baseClass = `${baseClass}-${direction}`;
+	if (resolvedSize) baseClass = `${baseClass}-${resolvedSize}`;
+	else if (resolvedSize === null) baseClass = `${baseClass}-none`;
+	return baseClass;
+}
+function padding(directionOrSize, size) {
+	if (isAbstractSize(directionOrSize) || directionOrSize === null && size === void 0) return spacing("padding", directionOrSize);
+	return spacing("padding", directionOrSize ?? void 0, size);
+}
+//#endregion
+export { padding, spacing };

package/_internal/packages/lumx-core/src/js/utils/classNames/typography/index.js

@@ -0,0 +1,10 @@
+//#region ../lumx-core/src/js/utils/classNames/typography/index.ts
+/**
+* Returns the classname associated to the given typography. For example, for Typography.title it returns
+* lumx-typography-title
+*/
+function typography(typo) {
+	return `lumx-typography-${typo}`;
+}
+//#endregion
+export { typography };

package/_internal/packages/lumx-core/src/js/utils/classNames/visually-hidden/index.js

@@ -0,0 +1,9 @@
+import { VISUALLY_HIDDEN } from "@lumx/core/js/constants";
+//#region ../lumx-core/src/js/utils/classNames/visually-hidden/index.ts
+/**
+* Visually hidden class name.
+* Used to hide elements from view but keep them readable from screen readers
+*/
+var visuallyHidden = () => VISUALLY_HIDDEN;
+//#endregion
+export { visuallyHidden };

package/_internal/packages/lumx-core/src/js/utils/disabledState/index.js

@@ -0,0 +1,13 @@
+//#region ../lumx-core/src/js/utils/disabledState/index.ts
+/**
+* Calculate the disabled state based on context and props.
+*/
+function getDisabledState(context, props) {
+	const { disabled, isDisabled = disabled, "aria-disabled": ariaDisabled } = props;
+	return {
+		disabled: context?.state === "disabled" || !!isDisabled,
+		"aria-disabled": ariaDisabled === true || ariaDisabled === "true"
+	};
+}
+//#endregion
+export { getDisabledState };

package/_internal/packages/lumx-core/src/js/utils/events/keyboard.js

@@ -0,0 +1,15 @@
+//#region ../lumx-core/src/js/utils/events/keyboard.ts
+/**
+* Make sure the pressed key is the enter key before calling the callback.
+*
+* @param  handler The handler to call on enter/return press.
+* @return The decorated function.
+*/
+function onEnterPressed(handler) {
+	return (evt) => {
+		if (evt.key !== "Enter") return;
+		handler(evt);
+	};
+}
+//#endregion
+export { onEnterPressed };

package/_internal/packages/lumx-core/src/js/utils/focus/constants.js

@@ -0,0 +1,13 @@
+//#region ../lumx-core/src/js/utils/focus/constants.ts
+/** CSS selector listing all tabbable elements. */
+var TABBABLE_ELEMENTS_SELECTOR = "a[href], button, textarea, input:not([type=\"hidden\"]):not([hidden]), [tabindex]";
+/**
+* CSS selector matching elements that should be excluded from focus traversal.
+*
+* Note: `aria-disabled` is intentionally NOT in this list — per ARIA semantics, an `aria-disabled` element
+* remains focusable (and discoverable by assistive tech). To remove an element from the tab order, use
+* `tabindex="-1"` instead.
+*/
+var DISABLED_SELECTOR = "[hidden], [tabindex=\"-1\"], [disabled]:not([disabled=\"false\"])";
+//#endregion
+export { DISABLED_SELECTOR, TABBABLE_ELEMENTS_SELECTOR };

package/_internal/packages/lumx-core/src/js/utils/focus/getFirstAndLastFocusable.js

@@ -0,0 +1,20 @@
+import { getFocusableElements } from "./getFocusableElements.js";
+//#region ../lumx-core/src/js/utils/focus/getFirstAndLastFocusable.ts
+/**
+* Get first and last elements focusable in an element.
+*
+* @param parentElement The element in which to search focusable elements.
+* @return first and last focusable elements
+*/
+function getFirstAndLastFocusable(parentElement) {
+	const focusableElements = getFocusableElements(parentElement);
+	const first = focusableElements[0];
+	const last = focusableElements[focusableElements.length - 1];
+	if (last && first) return {
+		first,
+		last
+	};
+	return {};
+}
+//#endregion
+export { getFirstAndLastFocusable };

package/_internal/packages/lumx-core/src/js/utils/focus/getFocusableElements.js

@@ -0,0 +1,8 @@
+import { DISABLED_SELECTOR, TABBABLE_ELEMENTS_SELECTOR } from "./constants.js";
+//#region ../lumx-core/src/js/utils/focus/getFocusableElements.ts
+var isNotDisabled = (element) => !element.matches(DISABLED_SELECTOR);
+function getFocusableElements(element) {
+	return Array.from(element.querySelectorAll(TABBABLE_ELEMENTS_SELECTOR)).filter(isNotDisabled);
+}
+//#endregion
+export { getFocusableElements };

package/_internal/packages/lumx-core/src/js/utils/focus/setupFocusTrap.js

@@ -0,0 +1,83 @@
+import { makeListenerTowerContext } from "../function/listenerTower.js";
+import { getFirstAndLastFocusable } from "./getFirstAndLastFocusable.js";
+//#region ../lumx-core/src/js/utils/focus/setupFocusTrap.ts
+/**
+* Shared listener tower for focus traps.
+*
+* When multiple traps are activated, only the last registered one is active. When it tears down, the previously
+* registered trap is re-enabled.
+*/
+var FOCUS_TRAPS = makeListenerTowerContext();
+/**
+* Trap 'Tab' focus switch inside the `focusZoneElement`.
+*
+* Setup behavior:
+* 1. Focus `focusElement` if provided and contained in the zone.
+* 2. Otherwise focus the first focusable descendant.
+* 3. Otherwise focus the zone element itself (falling back to setting `tabindex="-1"` if needed) so that
+*    keyboard users (especially screen reader users) land inside the trapped region (e.g. an empty dialog).
+*
+* Tab key behavior:
+* - With at least one focusable descendant: focus cycles between the first and last focusable in the zone.
+* - With no focusable descendant: Tab is swallowed and focus is restored to the zone element itself.
+*
+* Multiple traps stack — only the latest one is active; previous traps re-enable when the latest is torn down.
+*
+* @param options Trap configuration.
+* @param signal  AbortSignal used to tear down the trap.
+*/
+function setupFocusTrap(options, signal) {
+	const { focusZoneElement, focusElement } = options;
+	if (!focusZoneElement || signal.aborted) return;
+	const rootNode = focusZoneElement.getRootNode();
+	let addedTabIndex = false;
+	/** Make the zone element programmatically focusable (so we can fall back to it). */
+	const ensureZoneIsFocusable = () => {
+		if (!focusZoneElement.hasAttribute("tabindex")) {
+			focusZoneElement.setAttribute("tabindex", "-1");
+			addedTabIndex = true;
+		}
+	};
+	/** Focus the zone element itself as a last-resort fallback. */
+	const focusZoneFallback = () => {
+		ensureZoneIsFocusable();
+		focusZoneElement.focus({ preventScroll: true });
+	};
+	const trapTabFocusInFocusZone = (evt) => {
+		if (evt.key !== "Tab") return;
+		const focusable = getFirstAndLastFocusable(focusZoneElement);
+		if (!focusable.first) {
+			evt.preventDefault();
+			focusZoneFallback();
+			return;
+		}
+		const { activeElement } = rootNode;
+		if (!activeElement || !evt.shiftKey && activeElement === focusable.last || !focusZoneElement.contains(activeElement)) {
+			focusable.first.focus();
+			evt.preventDefault();
+			return;
+		}
+		if (evt.shiftKey && activeElement === focusable.first) {
+			focusable.last.focus();
+			evt.preventDefault();
+		}
+	};
+	const keydownHandler = trapTabFocusInFocusZone;
+	const focusTrap = {
+		enable: () => rootNode.addEventListener("keydown", keydownHandler),
+		disable: () => rootNode.removeEventListener("keydown", keydownHandler)
+	};
+	if (focusElement && focusZoneElement.contains(focusElement)) focusElement.focus({ preventScroll: true });
+	else {
+		const firstFocusable = getFirstAndLastFocusable(focusZoneElement).first;
+		if (firstFocusable) firstFocusable.focus({ preventScroll: true });
+		else focusZoneFallback();
+	}
+	FOCUS_TRAPS.register(focusTrap);
+	signal.addEventListener("abort", () => {
+		FOCUS_TRAPS.unregister(focusTrap);
+		if (addedTabIndex) focusZoneElement.removeAttribute("tabindex");
+	}, { once: true });
+}
+//#endregion
+export { setupFocusTrap };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/createActiveItemState.js

@@ -0,0 +1,38 @@
+//#region ../lumx-core/src/js/utils/focusNavigation/createActiveItemState.ts
+/**
+* Create shared active item state with cleanup on abort.
+*
+* Callback invocation:
+* - `setActive(item)`: calls `onDeactivate(previous)` then `onActivate(item)`.
+* - `clear()`: calls `onDeactivate(current)` then `onClear()`.
+* - On `signal.abort()`: same as `clear()`.
+*
+* @param callbacks Focus state change callbacks.
+* @param signal AbortSignal for cleanup.
+* @param initialItem Optional item to silently pre-select on creation (no callbacks fired).
+*/
+function createActiveItemState(callbacks, signal, initialItem) {
+	let activeItem = initialItem ?? null;
+	function clear() {
+		if (activeItem) {
+			callbacks.onDeactivate(activeItem);
+			activeItem = null;
+		}
+		callbacks.onClear?.();
+	}
+	signal.addEventListener("abort", clear);
+	return {
+		get active() {
+			return activeItem;
+		},
+		setActive(item) {
+			if (activeItem === item) return;
+			if (activeItem) callbacks.onDeactivate(activeItem);
+			activeItem = item;
+			if (item) callbacks.onActivate(item);
+		},
+		clear
+	};
+}
+//#endregion
+export { createActiveItemState };