@eocrm/design-system 0.6.24 → 0.7.0

package/dist/components/_internal/fieldWiring.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode } from 'react';
+/**
+ * `Boolean(n)`, plus: an empty RE-ITERABLE container (array, `Set`, or `Map`
+ * used directly — NOT `Map.values()`/`.entries()`, see below) and an empty
+ * fragment (`<></>`) count as ABSENT rather than present. `Boolean(label)`
+ * alone treats both as truthy when empty, so `Field`/`SettingRow` used to render
+ * a real, empty `<label>` and point `aria-labelledby` at it — and a
+ * real-but-empty referent is authoritative in the accname algorithm, so it
+ * silently named the control `""` instead of falling through to anything else.
+ * Use this everywhere a `hasX` predicate feeds BOTH a render gate (should
+ * something visible exist) and an ARIA reference (does that visible thing
+ * actually name/describe the control) — `hasLabel`, `hasDescription`, `hasError`.
+ *
+ * Known, deliberate limits:
+ * - This cannot see a REAL element with empty visual content
+ *   (`label={<span />}`) or a whitespace-only string (`label="   "`) — both are
+ *   still truthy content as far as this function is concerned, same as
+ *   `Boolean(x)` was. Detecting those needs rendering the element and
+ *   inspecting its content, which this predicate does not attempt.
+ * - A one-shot iterator — `Map.prototype.values()`, a generator — always
+ *   counts as PRESENT, empty or not. Round 8 tried inspecting it (spreading
+ *   the iterator to check), which reads correctly here but then hands React
+ *   the same, now-exhausted iterator to render — React gets nothing, so a
+ *   non-empty generator silently produced an empty `<label>` and suppressed
+ *   the control's own `aria-label`: this predicate's own bug, reintroduced by
+ *   the fix for it. You cannot ask a one-shot iterator whether it is empty
+ *   without spending it, so this only inspects containers that survive being
+ *   read twice (arrays, `Set`, a `Map` itself — iterating any of them fresh
+ *   each time, unlike the iterator `.values()`/`.entries()` RETURN) and
+ *   otherwise falls back to `Boolean(n)`, which is `true` for any non-null
+ *   object — same as an untouched iterator reaching React does. Nobody
+ *   passes `label={someGenerator()}` on purpose; React itself dev-warns on
+ *   both iterator and `Map` children regardless ("Using Maps as children is
+ *   not supported").
+ */
+export declare function hasContent(n: ReactNode): boolean;
+/** The wiring a field-like component hands to its control. Spread onto the control in render-prop form. */
+export interface FieldRenderProps {
+    id: string;
+    'aria-describedby': string | undefined;
+    /** Id of the label element to name the control — set only when a label is rendered. */
+    'aria-labelledby': string | undefined;
+    'aria-invalid': boolean | undefined;
+    invalid: boolean;
+    required: boolean;
+    /** Id of the label/caption element — for manual `aria-labelledby` wiring. */
+    labelId: string;
+}
+export interface FieldWiringOptions {
+    /** Explicit control id. Omit to let the wiring own it (auto-generated). */
+    id?: string;
+    /** Whether the caller renders a label — drives `aria-labelledby` injection. */
+    hasLabel: boolean;
+    /** Whether the caller renders a description — drives `aria-describedby` when there is no error. */
+    hasDescription: boolean;
+    /** Truthy when the caller renders an error message. */
+    hasError: boolean;
+    /** Marks the control required. */
+    required?: boolean;
+    /** Group mode (radio/checkbox sets): skip id/ARIA injection, inject only `invalid`/`required`. */
+    asGroup?: boolean;
+}
+export interface FieldWiring {
+    controlId: string;
+    labelId: string;
+    descriptionId: string;
+    errorId: string;
+    /** The id the control's `aria-describedby` should point at — error wins over description. */
+    describedBy: string | undefined;
+    /** The id the control's `aria-labelledby` should point at — set only when a label is rendered. */
+    labelledBy: string | undefined;
+    invalid: boolean;
+    /** Auto-wire a single element child, or invoke a render-prop with `field`. */
+    wire: (children: ReactNode | ((field: FieldRenderProps) => ReactNode)) => ReactNode;
+}
+/**
+ * Shared control wiring for `<Field>` and `<SettingRow>`: id ownership, the
+ * `aria-describedby` error-over-description choice, `aria-invalid`, and the
+ * `cloneElement` injection onto a single child.
+ *
+ * Extracted rather than copied because the `||`-not-`??` rule below is subtle
+ * and load-bearing for every named input in the library.
+ */
+export declare function useFieldWiring({ id, hasLabel, hasDescription, hasError, required, asGroup, }: FieldWiringOptions): FieldWiring;

package/dist/components/_internal/fieldWiring.js

@@ -0,0 +1,102 @@
+'use client';
+import { Fragment, cloneElement, isValidElement, useId } from "react";
+// src/components/_internal/fieldWiring.ts
+/**
+* `Boolean(n)`, plus: an empty RE-ITERABLE container (array, `Set`, or `Map`
+* used directly — NOT `Map.values()`/`.entries()`, see below) and an empty
+* fragment (`<></>`) count as ABSENT rather than present. `Boolean(label)`
+* alone treats both as truthy when empty, so `Field`/`SettingRow` used to render
+* a real, empty `<label>` and point `aria-labelledby` at it — and a
+* real-but-empty referent is authoritative in the accname algorithm, so it
+* silently named the control `""` instead of falling through to anything else.
+* Use this everywhere a `hasX` predicate feeds BOTH a render gate (should
+* something visible exist) and an ARIA reference (does that visible thing
+* actually name/describe the control) — `hasLabel`, `hasDescription`, `hasError`.
+*
+* Known, deliberate limits:
+* - This cannot see a REAL element with empty visual content
+*   (`label={<span />}`) or a whitespace-only string (`label="   "`) — both are
+*   still truthy content as far as this function is concerned, same as
+*   `Boolean(x)` was. Detecting those needs rendering the element and
+*   inspecting its content, which this predicate does not attempt.
+* - A one-shot iterator — `Map.prototype.values()`, a generator — always
+*   counts as PRESENT, empty or not. Round 8 tried inspecting it (spreading
+*   the iterator to check), which reads correctly here but then hands React
+*   the same, now-exhausted iterator to render — React gets nothing, so a
+*   non-empty generator silently produced an empty `<label>` and suppressed
+*   the control's own `aria-label`: this predicate's own bug, reintroduced by
+*   the fix for it. You cannot ask a one-shot iterator whether it is empty
+*   without spending it, so this only inspects containers that survive being
+*   read twice (arrays, `Set`, a `Map` itself — iterating any of them fresh
+*   each time, unlike the iterator `.values()`/`.entries()` RETURN) and
+*   otherwise falls back to `Boolean(n)`, which is `true` for any non-null
+*   object — same as an untouched iterator reaching React does. Nobody
+*   passes `label={someGenerator()}` on purpose; React itself dev-warns on
+*   both iterator and `Map` children regardless ("Using Maps as children is
+*   not supported").
+*/
+function hasContent(n) {
+	if (Array.isArray(n) || n instanceof Set || n instanceof Map) return [...n].some(hasContent);
+	if (isValidElement(n) && n.type === Fragment) return hasContent(n.props.children);
+	return Boolean(n);
+}
+/**
+* Shared control wiring for `<Field>` and `<SettingRow>`: id ownership, the
+* `aria-describedby` error-over-description choice, `aria-invalid`, and the
+* `cloneElement` injection onto a single child.
+*
+* Extracted rather than copied because the `||`-not-`??` rule below is subtle
+* and load-bearing for every named input in the library.
+*/
+function useFieldWiring({ id, hasLabel, hasDescription, hasError, required, asGroup = false }) {
+	const reactId = useId();
+	const controlId = id ?? reactId;
+	const labelId = `${controlId}-label`;
+	const descriptionId = `${controlId}-description`;
+	const errorId = `${controlId}-error`;
+	const invalid = hasError;
+	const requiredBool = Boolean(required);
+	const describedBy = hasError ? errorId : hasDescription ? descriptionId : void 0;
+	const labelledBy = hasLabel ? labelId : void 0;
+	const field = {
+		id: controlId,
+		"aria-describedby": describedBy,
+		"aria-labelledby": labelledBy,
+		"aria-invalid": invalid || void 0,
+		invalid,
+		required: requiredBool,
+		labelId
+	};
+	const wire = (children) => {
+		if (typeof children === "function") return children(field);
+		if (!isValidElement(children)) return children;
+		const child = children;
+		const childProps = child.props;
+		let injected;
+		if (asGroup) injected = {
+			invalid: childProps.invalid ?? invalid,
+			required: childProps.required ?? requiredBool
+		};
+		else {
+			injected = {
+				id: controlId,
+				"aria-describedby": childProps["aria-describedby"] || describedBy,
+				invalid: childProps.invalid ?? invalid,
+				required: childProps.required ?? requiredBool
+			};
+			injected["aria-labelledby"] = childProps["aria-labelledby"] || labelledBy;
+		}
+		return cloneElement(child, injected);
+	};
+	return {
+		controlId,
+		labelId,
+		descriptionId,
+		errorId,
+		describedBy,
+		labelledBy,
+		invalid,
+		wire
+	};
+}
+export { hasContent, useFieldWiring };

package/dist/components/_internal/gridSpan.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Column-span vocabulary shared by `Grid.Item` and `Sortable.Item` (grid
+ * arrangement). Lives in `_internal` so both components reference one source of
+ * the fraction→track mapping without either importing the other (which would
+ * imply a render-composition edge in the component manifest that doesn't exist).
+ */
+/**
+ * Column span for a grid cell. Numbers span that many tracks of whatever
+ * `columns` the parent grid declares. Fraction strings assume a 12-column
+ * grid (`columns={12}`): `'25%'`→3, `'33%'`→4, `'50%'`→6, `'67%'`→8,
+ * `'75%'`→9 tracks. `'100%'` / `'full'` span the entire row (`1 / -1`) and
+ * are safe in ANY grid, including auto-fit.
+ */
+export type GridItemSpan = number | 'full' | '25%' | '33%' | '50%' | '67%' | '75%' | '100%';
+/**
+ * Resolve a `GridItemSpan` to a CSS `grid-column` value (or `undefined` when
+ * no span is set; callers substitute `'auto'`).
+ * - `undefined` → `undefined`
+ * - `'full'` / `'100%'` → `'1 / -1'`
+ * - number → `'span N'`
+ * - fraction → `'span <tracks>'`
+ */
+export declare function resolveGridItemSpan(span: GridItemSpan | undefined): string | undefined;
+/**
+ * Resolve a span against a graduated-collapse step's column count: spans that
+ * fit keep their track count, spans >= the step's columns clamp to the full
+ * row (`1 / -1`), full-row spans stay full-row, span-less stays `auto`.
+ */
+export declare function resolveCollapsedGridItemSpan(span: GridItemSpan | undefined, columns: number): string;

package/dist/components/_internal/gridSpan.js

@@ -0,0 +1,35 @@
+// src/components/_internal/gridSpan.ts
+/** Fraction → 12-col track count. 100%/full handled separately (1 / -1). */
+var FRACTION_TRACKS = {
+	"25%": 3,
+	"33%": 4,
+	"50%": 6,
+	"67%": 8,
+	"75%": 9
+};
+/**
+* Resolve a `GridItemSpan` to a CSS `grid-column` value (or `undefined` when
+* no span is set; callers substitute `'auto'`).
+* - `undefined` → `undefined`
+* - `'full'` / `'100%'` → `'1 / -1'`
+* - number → `'span N'`
+* - fraction → `'span <tracks>'`
+*/
+function resolveGridItemSpan(span) {
+	if (span === void 0) return void 0;
+	if (span === "full" || span === "100%") return "1 / -1";
+	if (typeof span === "number") return `span ${span}`;
+	return `span ${FRACTION_TRACKS[span]}`;
+}
+/**
+* Resolve a span against a graduated-collapse step's column count: spans that
+* fit keep their track count, spans >= the step's columns clamp to the full
+* row (`1 / -1`), full-row spans stay full-row, span-less stays `auto`.
+*/
+function resolveCollapsedGridItemSpan(span, columns) {
+	if (span === void 0) return "auto";
+	if (span === "full" || span === "100%" || columns <= 1) return "1 / -1";
+	const tracks = typeof span === "number" ? span : FRACTION_TRACKS[span];
+	return tracks >= columns ? "1 / -1" : `span ${tracks}`;
+}
+export { resolveCollapsedGridItemSpan, resolveGridItemSpan };

package/dist/components/_internal/isoDay.d.ts

@@ -0,0 +1,6 @@
+/** `'2026-10-07'` → `Date` at 2026-10-07T00:00:00Z. Throws on anything else. */
+export declare function parseIsoDay(iso: string): Date;
+/** Format one ISO day in UTC. */
+export declare function formatIsoDay(iso: string, locale: string, options: Intl.DateTimeFormatOptions): string;
+/** Format a first..last ISO day range in UTC ("October 2026", "September – October 2026"). */
+export declare function formatIsoRange(first: string, last: string, locale: string, options: Intl.DateTimeFormatOptions): string;

package/dist/components/_internal/isoDay.js

@@ -0,0 +1,29 @@
+// src/components/_internal/isoDay.ts
+/**
+* Calendar days as ISO `'YYYY-MM-DD'` strings, formatted in UTC so the host
+* timezone can never shift a day (a booking's day belongs to the business's
+* timezone, not the browser's). Used by DateStrip.
+*/
+var ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** `'2026-10-07'` → `Date` at 2026-10-07T00:00:00Z. Throws on anything else. */
+function parseIsoDay(iso) {
+	const m = ISO_DAY.exec(iso);
+	if (!m) throw new Error(`[isoDay] expected 'YYYY-MM-DD', got '${iso}'`);
+	return new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+}
+/** Format one ISO day in UTC. */
+function formatIsoDay(iso, locale, options) {
+	return new Intl.DateTimeFormat(locale, {
+		...options,
+		timeZone: "UTC"
+	}).format(parseIsoDay(iso));
+}
+/** Format a first..last ISO day range in UTC ("October 2026", "September – October 2026"). */
+function formatIsoRange(first, last, locale, options) {
+	const f = new Intl.DateTimeFormat(locale, {
+		...options,
+		timeZone: "UTC"
+	});
+	return first === last ? f.format(parseIsoDay(first)) : f.formatRange(parseIsoDay(first), parseIsoDay(last));
+}
+export { formatIsoDay, formatIsoRange, parseIsoDay };

package/dist/components/_internal/letterKey.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Layout-independent letter-shortcut match (#654).
+ *
+ * `event.key` is the character the layout produced, so on a Russian layout the
+ * K key yields `'л'` and a `key === 'k'` check silently drops the shortcut.
+ * `event.code` is the physical key (`'KeyK'`) on every layout — but on a remapped
+ * Latin layout (AZERTY, Dvorak) it names the wrong letter. So: trust `key` when
+ * it is a Latin letter, fall back to `code` only when it is a non-ASCII
+ * character (Cyrillic, Greek, …). ASCII punctuation on a letter position is a
+ * real key (Dvorak's `;` sits on KeyZ), so it never falls back.
+ *
+ * No fallback while Alt is held: Windows reports AltGr as Ctrl+Alt, so AltGr+Z
+ * on a Polish layout (`'ż'`, `KeyZ`, ctrlKey) is typing, not ⌘Z; the same goes
+ * for macOS Option+letter.
+ *
+ * `letter` is a single lowercase a–z.
+ */
+export declare function isLetterKey(event: {
+    key: string;
+    code: string;
+    altKey?: boolean;
+}, letter: string): boolean;

package/dist/components/_internal/letterKey.js

@@ -0,0 +1,24 @@
+// src/components/_internal/letterKey.ts
+/**
+* Layout-independent letter-shortcut match (#654).
+*
+* `event.key` is the character the layout produced, so on a Russian layout the
+* K key yields `'л'` and a `key === 'k'` check silently drops the shortcut.
+* `event.code` is the physical key (`'KeyK'`) on every layout — but on a remapped
+* Latin layout (AZERTY, Dvorak) it names the wrong letter. So: trust `key` when
+* it is a Latin letter, fall back to `code` only when it is a non-ASCII
+* character (Cyrillic, Greek, …). ASCII punctuation on a letter position is a
+* real key (Dvorak's `;` sits on KeyZ), so it never falls back.
+*
+* No fallback while Alt is held: Windows reports AltGr as Ctrl+Alt, so AltGr+Z
+* on a Polish layout (`'ż'`, `KeyZ`, ctrlKey) is typing, not ⌘Z; the same goes
+* for macOS Option+letter.
+*
+* `letter` is a single lowercase a–z.
+*/
+function isLetterKey(event, letter) {
+	const key = event.key.toLowerCase();
+	if (/^[a-z]$/.test(key)) return key === letter;
+	return key.length === 1 && key > "" && !event.altKey && event.code === `Key${letter.toUpperCase()}`;
+}
+export { isLetterKey };

package/dist/components/_internal/overlay/focusRestore.d.ts

@@ -0,0 +1,11 @@
+/** Focus is "lost" when nothing live holds it: `<body>`, nothing, or a detached node. */
+export declare function isFocusLost(): boolean;
+/**
+ * Focus `el` on overlay close, retrying once in a microtask if the first
+ * `focus()` did not take. A lower overlay in `stackMode="replace"` is still
+ * `display: none` when the upper one closes — its `isTop` update renders just
+ * after that commit — so focusing an element inside it no-ops (#551). The
+ * retry only runs if focus is still lost by then, so it never steals focus
+ * from wherever something else put it.
+ */
+export declare function restoreFocusTo(el: HTMLElement): void;

package/dist/components/_internal/overlay/focusRestore.js

@@ -0,0 +1,22 @@
+// src/components/_internal/overlay/focusRestore.ts
+/** Focus is "lost" when nothing live holds it: `<body>`, nothing, or a detached node. */
+function isFocusLost() {
+	const active = document.activeElement;
+	return !active || active === document.body || !active.isConnected;
+}
+/**
+* Focus `el` on overlay close, retrying once in a microtask if the first
+* `focus()` did not take. A lower overlay in `stackMode="replace"` is still
+* `display: none` when the upper one closes — its `isTop` update renders just
+* after that commit — so focusing an element inside it no-ops (#551). The
+* retry only runs if focus is still lost by then, so it never steals focus
+* from wherever something else put it.
+*/
+function restoreFocusTo(el) {
+	el.focus({ preventScroll: true });
+	if (document.activeElement === el) return;
+	queueMicrotask(() => {
+		if (el.isConnected && isFocusLost()) el.focus({ preventScroll: true });
+	});
+}
+export { isFocusLost, restoreFocusTo };

package/dist/components/_internal/overlay/index.d.ts

@@ -0,0 +1,6 @@
+export { useFocusTrap } from './useFocusTrap.js';
+export { useInOverlay } from './useInOverlay.js';
+export { useScrollLock } from './useScrollLock.js';
+export { useFloatingSurface, useOverlayStack, overlayStack, type OverlayStackMode, type OverlayStackState, } from './useOverlayStack.js';
+export { isFocusLost, restoreFocusTo } from './focusRestore.js';
+export { TOUR_CURRENT_TARGET, isTourHeld } from './tourHold.js';

package/dist/components/_internal/overlay/tourHold.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Set by Tour on the current step's found target (any step kind, modal or
+ * not) while the tour is open. Distinct from `data-tour-active-target`, which
+ * only marks interactive modal-step targets for overlay elevation (#684).
+ */
+export declare const TOUR_CURRENT_TARGET = "data-tour-current-target";
+/**
+ * True when a floating surface must ignore a dismiss caused by `node` (a
+ * pointerdown target or the element focus moved to): `node` is inside the
+ * tour layer AND the tour's current target is inside `panel` or `trigger`.
+ * A tour pointing into an open menu/picker must not close it just because
+ * the user pressed Next or the tour focused its card (#684).
+ */
+export declare function isTourHeld(node: EventTarget | null, panel: Element | null, trigger: Element | null): boolean;

package/dist/components/_internal/overlay/tourHold.js

@@ -0,0 +1,20 @@
+// src/components/_internal/overlay/tourHold.ts
+/**
+* Set by Tour on the current step's found target (any step kind, modal or
+* not) while the tour is open. Distinct from `data-tour-active-target`, which
+* only marks interactive modal-step targets for overlay elevation (#684).
+*/
+var TOUR_CURRENT_TARGET = "data-tour-current-target";
+/**
+* True when a floating surface must ignore a dismiss caused by `node` (a
+* pointerdown target or the element focus moved to): `node` is inside the
+* tour layer AND the tour's current target is inside `panel` or `trigger`.
+* A tour pointing into an open menu/picker must not close it just because
+* the user pressed Next or the tour focused its card (#684).
+*/
+function isTourHeld(node, panel, trigger) {
+	if (!(node instanceof Element) || !node.closest("[data-tour-portal-root]")) return false;
+	const target = document.querySelector(`[${TOUR_CURRENT_TARGET}]`);
+	return !!target && (!!panel?.contains(target) || !!trigger?.contains(target));
+}
+export { TOUR_CURRENT_TARGET, isTourHeld };

package/dist/components/_internal/overlay/useFocusTrap.d.ts

@@ -0,0 +1,18 @@
+import { type RefObject } from 'react';
+export declare const FOCUSABLE_SELECTOR: string;
+/**
+ * Focus trap: keeps Tab focus cycling inside `containerRef`. Attaches a
+ * `keydown` listener to detect Tab at the first/last focusable and wrap, plus
+ * a `focusin` listener at document level to redirect any focus that escapes
+ * the container back to it.
+ *
+ * `active = false` no-ops the trap (used by Modal when not top of stack — the
+ * inner modal mounts but only the topmost modal owns focus).
+ *
+ * `extra` (optional) — an element outside the container that joins the Tab cycle after it (Tour's interactive target).
+ *
+ * @example
+ * const contentRef = useRef<HTMLDivElement | null>(null);
+ * useFocusTrap(contentRef, open);
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean, extra?: HTMLElement | null): void;

package/dist/components/_internal/overlay/useFocusTrap.js

@@ -0,0 +1,96 @@
+'use client';
+import { useEffect } from "react";
+// src/components/_internal/overlay/useFocusTrap.ts
+var FOCUSABLE_SELECTOR = [
+	"button:not([disabled])",
+	"[href]",
+	"input:not([disabled]):not([type=\"hidden\"])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"[tabindex]:not([tabindex=\"-1\"])"
+].join(",");
+var FLOATING_BYPASS_SELECTOR = [
+	"[data-popover-content]",
+	"[data-rte-overlay]",
+	"[data-dropdown-menu-content]",
+	"[role=\"tooltip\"]",
+	"[role=\"menu\"]",
+	"[role=\"listbox\"]",
+	"[role=\"dialog\"]"
+].join(",");
+function getFocusables(container) {
+	return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+}
+/**
+* Focus trap: keeps Tab focus cycling inside `containerRef`. Attaches a
+* `keydown` listener to detect Tab at the first/last focusable and wrap, plus
+* a `focusin` listener at document level to redirect any focus that escapes
+* the container back to it.
+*
+* `active = false` no-ops the trap (used by Modal when not top of stack — the
+* inner modal mounts but only the topmost modal owns focus).
+*
+* `extra` (optional) — an element outside the container that joins the Tab cycle after it (Tour's interactive target).
+*
+* @example
+* const contentRef = useRef<HTMLDivElement | null>(null);
+* useFocusTrap(contentRef, open);
+*/
+function useFocusTrap(containerRef, active, extra = null) {
+	useEffect(() => {
+		if (!active) return;
+		const container = containerRef.current;
+		if (!container) return;
+		function extraFocusables() {
+			if (!extra) return [];
+			return [extra, ...getFocusables(extra)].filter((el) => el.matches(FOCUSABLE_SELECTOR));
+		}
+		function onKeyDown(e) {
+			if (e.key !== "Tab") return;
+			const focusables = [...getFocusables(container), ...extraFocusables()];
+			if (focusables.length === 0) {
+				e.preventDefault();
+				container.focus();
+				return;
+			}
+			if (extra) {
+				const n = focusables.length;
+				const i = focusables.indexOf(document.activeElement);
+				const next = i === -1 ? e.shiftKey ? n - 1 : 0 : (i + (e.shiftKey ? -1 : 1) + n) % n;
+				e.preventDefault();
+				focusables[next].focus();
+				return;
+			}
+			const first = focusables[0];
+			const last = focusables[focusables.length - 1];
+			if (!e.shiftKey && document.activeElement === last) {
+				e.preventDefault();
+				first.focus();
+			} else if (e.shiftKey && document.activeElement === first) {
+				e.preventDefault();
+				last.focus();
+			}
+		}
+		function onFocusIn(e) {
+			const target = e.target;
+			if (!target || !container) return;
+			if (container.contains(target)) return;
+			if (extra?.contains(target)) return;
+			if (target.closest(FLOATING_BYPASS_SELECTOR)) return;
+			container.focus();
+		}
+		container.addEventListener("keydown", onKeyDown);
+		extra?.addEventListener("keydown", onKeyDown);
+		document.addEventListener("focusin", onFocusIn);
+		return () => {
+			container.removeEventListener("keydown", onKeyDown);
+			extra?.removeEventListener("keydown", onKeyDown);
+			document.removeEventListener("focusin", onFocusIn);
+		};
+	}, [
+		containerRef,
+		active,
+		extra
+	]);
+}
+export { FOCUSABLE_SELECTOR, useFocusTrap };

package/dist/components/_internal/overlay/useInOverlay.d.ts

@@ -0,0 +1,37 @@
+import { type RefObject } from 'react';
+/**
+ * True when `referenceRef`'s element is rendered inside an overlay host — a
+ * `Modal`/`Drawer`/`Lightbox`/`Tour` portal, a `Popover.Content` / `DropdownMenu`
+ * content panel, an interactive `Tour` step's target (`[data-tour-active-target]`),
+ * or ANY already-elevated surface carrying `[data-in-overlay]`
+ * (transitive elevation). Floating surfaces (`Select` / `Popover` /
+ * `DropdownMenu` / `DatePicker` / `DateRangePicker` / `TimeField` / the
+ * `Rail.Group` collapsed-mode flyout) use this
+ * to elevate their portaled content above the host — their default z-index
+ * sits below `--z-modal` (and at/below an open Popover, and below `--z-tour`),
+ * so without elevation they render behind it. Covers a kebab `DropdownMenu`,
+ * nested `Popover`, or `ConfirmationPopover` opened from inside a Popover
+ * panel; a floating surface opened from inside a `Tour` step's card body
+ * (`[data-tour-portal-root]`) or from an interactive modal-tour step's target
+ * (`[data-tour-active-target]`); and, via the transitive marker, the embedded
+ * `TimeField` clock inside an elevated `DatePicker` calendar (#272).
+ *
+ * Consumers MUST place `data-in-overlay` on the portaled FLOATING element,
+ * never on the reference element itself — `closest()` includes the start
+ * node, so a marked reference would self-match on the next recompute.
+ *
+ * Recomputed whenever `active` toggles (the trigger is mounted by then). Uses
+ * `useLayoutEffect` so the elevation attribute lands in the same pre-paint
+ * commit as the opened surface (no flash behind the overlay).
+ *
+ * @example
+ * // `ctx` is the component's own context (e.g. useSelectContext()) — but any
+ * // ref to the trigger or a wrapper ancestor works equally well (DatePicker/
+ * // DateRangePicker/TimeField pass their wrapperRef).
+ * const inOverlay = useInOverlay(ctx.triggerRef, ctx.open);
+ * // Empty-string presence idiom — React serializes `{true}` on a data-*
+ * // attribute as "true", so use `? '' : undefined` to match the CSS
+ * // `[data-in-overlay]` selector and the `data-*-content=""` convention:
+ * // <ul data-in-overlay={inOverlay ? '' : undefined} ...>
+ */
+export declare function useInOverlay(referenceRef: RefObject<HTMLElement | null>, active: boolean): boolean;

package/dist/components/_internal/overlay/useInOverlay.js

@@ -0,0 +1,51 @@
+'use client';
+import { useLayoutEffect, useState } from "react";
+// src/components/_internal/overlay/useInOverlay.ts
+var OVERLAY_PORTAL_SELECTOR = "[data-drawer-portal-root], [data-modal-portal-root], [data-lightbox-portal-root], [data-flowcanvas-maximized], [data-popover-content], [data-dropdown-menu-content], [data-in-overlay], [data-tour-portal-root], [data-tour-active-target]";
+/**
+* True when `referenceRef`'s element is rendered inside an overlay host — a
+* `Modal`/`Drawer`/`Lightbox`/`Tour` portal, a `Popover.Content` / `DropdownMenu`
+* content panel, an interactive `Tour` step's target (`[data-tour-active-target]`),
+* or ANY already-elevated surface carrying `[data-in-overlay]`
+* (transitive elevation). Floating surfaces (`Select` / `Popover` /
+* `DropdownMenu` / `DatePicker` / `DateRangePicker` / `TimeField` / the
+* `Rail.Group` collapsed-mode flyout) use this
+* to elevate their portaled content above the host — their default z-index
+* sits below `--z-modal` (and at/below an open Popover, and below `--z-tour`),
+* so without elevation they render behind it. Covers a kebab `DropdownMenu`,
+* nested `Popover`, or `ConfirmationPopover` opened from inside a Popover
+* panel; a floating surface opened from inside a `Tour` step's card body
+* (`[data-tour-portal-root]`) or from an interactive modal-tour step's target
+* (`[data-tour-active-target]`); and, via the transitive marker, the embedded
+* `TimeField` clock inside an elevated `DatePicker` calendar (#272).
+*
+* Consumers MUST place `data-in-overlay` on the portaled FLOATING element,
+* never on the reference element itself — `closest()` includes the start
+* node, so a marked reference would self-match on the next recompute.
+*
+* Recomputed whenever `active` toggles (the trigger is mounted by then). Uses
+* `useLayoutEffect` so the elevation attribute lands in the same pre-paint
+* commit as the opened surface (no flash behind the overlay).
+*
+* @example
+* // `ctx` is the component's own context (e.g. useSelectContext()) — but any
+* // ref to the trigger or a wrapper ancestor works equally well (DatePicker/
+* // DateRangePicker/TimeField pass their wrapperRef).
+* const inOverlay = useInOverlay(ctx.triggerRef, ctx.open);
+* // Empty-string presence idiom — React serializes `{true}` on a data-*
+* // attribute as "true", so use `? '' : undefined` to match the CSS
+* // `[data-in-overlay]` selector and the `data-*-content=""` convention:
+* // <ul data-in-overlay={inOverlay ? '' : undefined} ...>
+*/
+function useInOverlay(referenceRef, active) {
+	const [inOverlay, setInOverlay] = useState(false);
+	useLayoutEffect(() => {
+		if (!active) {
+			setInOverlay(false);
+			return;
+		}
+		setInOverlay(Boolean(referenceRef.current?.closest(OVERLAY_PORTAL_SELECTOR)));
+	}, [active, referenceRef]);
+	return inOverlay;
+}
+export { useInOverlay };