@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/_internal/fieldWiring.ts

@@ -0,0 +1,225 @@
+import {
+  cloneElement,
+  Fragment,
+  isValidElement,
+  useId,
+  type ReactElement,
+  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 function hasContent(n: ReactNode): boolean {
+  // Only RE-ITERABLE containers are inspected — reading them (`[...n]`) to
+  // check for content doesn't consume what React later reads to render them.
+  // A one-shot iterator (generator, `Map.values()`/`.entries()`) is
+  // deliberately NOT matched here — see the "Known, deliberate limits" doc
+  // above. `n instanceof Map` catches a Map passed DIRECTLY (its default
+  // iteration yields `[k, v]` tuples — themselves arrays of ReactNode-legal
+  // values, so this recurses into them correctly), which is a real,
+  // type-legal, re-iterable input distinct from its one-shot `.values()`.
+  if (Array.isArray(n) || n instanceof Set || n instanceof Map) {
+    return [...(n as Iterable<ReactNode>)].some(hasContent);
+  }
+  if (isValidElement(n) && n.type === Fragment) {
+    return hasContent((n.props as { children?: ReactNode }).children);
+  }
+  return Boolean(n);
+}
+
+/** 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 function useFieldWiring({
+  id,
+  hasLabel,
+  hasDescription,
+  hasError,
+  required,
+  asGroup = false,
+}: FieldWiringOptions): FieldWiring {
+  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 : undefined;
+  // Single source for the labelledby value, same shape as describedBy above —
+  // computed once and reused by the render-prop field object, the
+  // cloneElement branch below, AND returned to the caller (Field's `asGroup`
+  // wrapper reads this instead of re-deriving `hasLabel ? labelId : undefined`
+  // a third time), so none of them can recompute `hasLabel` a different way
+  // and drift (that drift is exactly what shipped: the render-prop path and
+  // the cloneElement path used to each derive this independently).
+  const labelledBy = hasLabel ? labelId : undefined;
+
+  const field: FieldRenderProps = {
+    id: controlId,
+    'aria-describedby': describedBy,
+    'aria-labelledby': labelledBy,
+    'aria-invalid': invalid || undefined,
+    invalid,
+    required: requiredBool,
+    labelId,
+  };
+
+  const wire = (children: ReactNode | ((f: FieldRenderProps) => ReactNode)): ReactNode => {
+    if (typeof children === 'function') return children(field);
+    if (!isValidElement(children)) return children;
+
+    const child = children as ReactElement<Record<string, unknown>>;
+    const childProps = child.props;
+    let injected: Record<string, unknown>;
+    if (asGroup) {
+      injected = {
+        invalid: childProps.invalid ?? invalid,
+        required: childProps.required ?? requiredBool,
+      };
+    } else {
+      injected = {
+        id: controlId,
+        // `||`, not `??`, on both ARIA id references: `aria-labelledby={sectionId ?? ''}`
+        // is ordinary consumer code, and an empty id list references nothing — it
+        // contributes no name and lets the computation fall through, exactly like an
+        // empty `aria-label`. Treating it as an explicit override would suppress
+        // `labelId` and leave the control anonymous, which matters more here than
+        // anywhere else: Field names every input in the library through
+        // `aria-labelledby` rather than `<label for>`. `invalid` / `required` keep `??`
+        // — those are booleans, where `false` is a meaningful explicit value.
+        'aria-describedby': childProps['aria-describedby'] || describedBy,
+        invalid: childProps.invalid ?? invalid,
+        required: childProps.required ?? requiredBool,
+      };
+      // ROUND 7 — round 6 shipped `if (hasLabel && !childProps['aria-label'])`:
+      // skip injecting aria-labelledby whenever the child already carries its
+      // own aria-label, reasoning it as the same "child's explicit value wins"
+      // rule as the `||` two lines up. Both round-7 reviewers measured that
+      // this is the wrong fix, at the wrong altitude: `aria-describedby` is
+      // SUPPLEMENTARY (a consumer overriding it loses helper text — nothing
+      // breaks), but the accessible NAME is the control's identity, and WCAG
+      // 2.5.3 (Level A) requires a control's VISIBLE label text to be
+      // contained in that name. `<Field label="Work email"><Input
+      // aria-label="Email address" /></Field>` — a completely ordinary,
+      // defensive pattern an agent writes reflexively — computed name
+      // "Work email" before round 6 and "Email address" after: the visible
+      // text silently dropped out of the name on the library's single most
+      // common path. Reverted.
+      //
+      // The REAL fix is hasLabel itself: it now reads hasContent(label), not
+      // Boolean(label) — see that function's doc. An empty label
+      // (`label={<></>}`, `label={[]}`) no longer renders a `<label>` at all,
+      // hasLabel is correctly false, and `labelledBy` above is `undefined` —
+      // on BOTH this cloneElement path AND the render-prop `field` object,
+      // which reads the same hoisted `hasLabel` (round 6's fix could not
+      // reach the render-prop path at all, since that object is built before
+      // the child is known and has no childProps to inspect — this fix has
+      // no such asymmetry).
+      //
+      // No `if (hasLabel)` guard here, on purpose, verified by mutation: one
+      // was restored in an earlier round-7 draft and stayed green with the
+      // condition hardcoded `true`, and again with the `if` deleted outright
+      // — because `labelledBy` is already `hasLabel ? labelId : undefined`,
+      // so when `!hasLabel` this line reduces to `childProps['aria-labelledby']
+      // || undefined`, and `cloneElement` receiving an explicit `undefined`
+      // for a key the child never set is indistinguishable from omitting the
+      // key — the same argument that killed round 5's and round 6's guards
+      // here. Unlike those, this isn't a wrong claim shipped with a live
+      // gate; there's no gate left to be wrong about.
+      injected['aria-labelledby'] = childProps['aria-labelledby'] || labelledBy;
+    }
+    return cloneElement(child, injected);
+  };
+
+  return {
+    controlId,
+    labelId,
+    descriptionId,
+    errorId,
+    describedBy,
+    labelledBy,
+    invalid,
+    wire,
+  };
+}

package/src/components/_internal/gridSpan.ts

@@ -0,0 +1,54 @@
+/**
+ * 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%';
+
+/** Fraction → 12-col track count. 100%/full handled separately (1 / -1). */
+const FRACTION_TRACKS: Record<Exclude<GridItemSpan, number | 'full' | '100%'>, number> = {
+  '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>'`
+ */
+export function resolveGridItemSpan(span: GridItemSpan | undefined): string | undefined {
+  if (span === undefined) return undefined;
+  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`.
+ */
+export function resolveCollapsedGridItemSpan(
+  span: GridItemSpan | undefined,
+  columns: number,
+): string {
+  if (span === undefined) 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}`;
+}

package/src/components/_internal/isoDay.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+const ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/** `'2026-10-07'` → `Date` at 2026-10-07T00:00:00Z. Throws on anything else. */
+export function parseIsoDay(iso: string): Date {
+  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. */
+export function formatIsoDay(
+  iso: string,
+  locale: string,
+  options: Intl.DateTimeFormatOptions,
+): string {
+  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"). */
+export function formatIsoRange(
+  first: string,
+  last: string,
+  locale: string,
+  options: Intl.DateTimeFormatOptions,
+): string {
+  const f = new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' });
+  return first === last
+    ? f.format(parseIsoDay(first))
+    : f.formatRange(parseIsoDay(first), parseIsoDay(last));
+}

package/src/components/_internal/letterKey.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 function isLetterKey(
+  event: { key: string; code: string; altKey?: boolean },
+  letter: string,
+): boolean {
+  const key = event.key.toLowerCase();
+  if (/^[a-z]$/.test(key)) return key === letter;
+  const nonAscii = key.length === 1 && key > '\x7f';
+  return nonAscii && !event.altKey && event.code === `Key${letter.toUpperCase()}`;
+}

package/src/components/_internal/overlay/focusRestore.ts

@@ -0,0 +1,21 @@
+/** Focus is "lost" when nothing live holds it: `<body>`, nothing, or a detached node. */
+export function isFocusLost(): boolean {
+  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.
+ */
+export function restoreFocusTo(el: HTMLElement): void {
+  el.focus({ preventScroll: true });
+  if (document.activeElement === el) return;
+  queueMicrotask(() => {
+    if (el.isConnected && isFocusLost()) el.focus({ preventScroll: true });
+  });
+}

package/src/components/_internal/overlay/index.ts

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

package/src/components/_internal/overlay/tourHold.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 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 function isTourHeld(
+  node: EventTarget | null,
+  panel: Element | null,
+  trigger: Element | null,
+): boolean {
+  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));
+}

package/src/components/_internal/overlay/useFocusTrap.ts

@@ -0,0 +1,120 @@
+import { useEffect, type RefObject } from 'react';
+
+export const FOCUSABLE_SELECTOR = [
+  'button:not([disabled])',
+  '[href]',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+// Floating UI surfaces whose portals are direct body-siblings of our modal
+// portal. Focus moving into these should not be redirected back to the modal —
+// the popover / dropdown / tooltip is handling its own focus session.
+// The DatePicker/DateRangePicker calendar popovers rely on the [role="dialog"]
+// entry here: they move real DOM focus into body-portaled grid cells while
+// open inside a Modal (unlike Select's aria-activedescendant pattern), so
+// removing that entry would re-trap their keyboard users (#272).
+const FLOATING_BYPASS_SELECTOR = [
+  '[data-popover-content]',
+  // RTE link-editor / attachment-config bubbles: form-like, hold their own
+  // focus while open inside a Modal (#274).
+  '[data-rte-overlay]',
+  '[data-dropdown-menu-content]',
+  '[role="tooltip"]',
+  '[role="menu"]',
+  '[role="listbox"]',
+  '[role="dialog"]',
+].join(',');
+
+function getFocusables(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(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);
+ */
+export function useFocusTrap(
+  containerRef: RefObject<HTMLElement | null>,
+  active: boolean,
+  extra: HTMLElement | null = null,
+): void {
+  useEffect(() => {
+    if (!active) return;
+    const container = containerRef.current;
+    if (!container) return;
+
+    // Tour's interactive target joins the cycle AFTER the container's
+    // focusables. Its DOM position is arbitrary, so with `extra` the cycle is
+    // driven manually instead of by native Tab order.
+    function extraFocusables(): HTMLElement[] {
+      if (!extra) return [];
+      return [extra, ...getFocusables(extra)].filter((el) => el.matches(FOCUSABLE_SELECTOR));
+    }
+
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key !== 'Tab') return;
+      const focusables = [...getFocusables(container!), ...extraFocusables()];
+      if (focusables.length === 0) {
+        // Zero focusables: prevent Tab from escaping the container.
+        e.preventDefault();
+        container!.focus();
+        return;
+      }
+      if (extra) {
+        const n = focusables.length;
+        const i = focusables.indexOf(document.activeElement as HTMLElement);
+        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();
+      }
+      // Middle of the cycle: browser handles it natively.
+    }
+
+    function onFocusIn(e: FocusEvent) {
+      const target = e.target as HTMLElement | null;
+      if (!target || !container) return;
+      if (container.contains(target)) return;
+      if (extra?.contains(target)) return;
+      // Allow focus to live inside floating UI surfaces that were opened
+      // from within this modal (Popover, DropdownMenu, Tooltip, nested Modal).
+      // Their portals are body-direct siblings of our portal — checking by
+      // selector instead of containment.
+      if (target.closest(FLOATING_BYPASS_SELECTOR)) return;
+      // Focus escaped — redirect to the container.
+      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]);
+}

package/src/components/_internal/overlay/useInOverlay.ts

@@ -0,0 +1,81 @@
+import { useLayoutEffect, useState, type RefObject } from 'react';
+
+// Overlay hosts whose descendants' floating surfaces must stack above them.
+// Modal/Drawer portal roots, plus Popover.Content and DropdownMenu content
+// (so a DropdownMenu/Popover/ConfirmationPopover opened from inside a Popover —
+// or from a DropdownMenu item nested in one — elevates above its host instead
+// of rendering behind it). Reuses the existing content markers; no new attrs.
+// `[data-in-overlay]` makes elevation transitive: a surface nested inside an
+// already-elevated surface (the embedded TimeField clock inside a DatePicker
+// calendar that sits in a Modal, #272) elevates with its host — the host's
+// marker lands on the DOM via the layout effect's setState (a second
+// synchronous commit, still pre-paint) before the nested surface can open,
+// so the chain is observable by the time the child's hook runs.
+// Also the in-place maximized FlowCanvas ([data-flowcanvas-maximized]), so a
+// consumer DropdownMenu/Select/Popover opened from its controls elevates above
+// the fixed maximized surface instead of rendering behind it.
+// Also Tour's portal ([data-tour-portal-root]): a Select/Popover/DropdownMenu/
+// DatePicker opened from inside a Tour step's card body must elevate above
+// the tour (--z-tour) instead of rendering behind it.
+// Also [data-tour-active-target]: an interactive modal-tour step marks its
+// `found` target element with this attribute directly (see Tour.tsx), not a
+// wrapper around it — so unlike `data-in-overlay`, which must never sit on
+// the reference element itself (a marked reference would self-match via
+// closest() on the next recompute), this one is deliberately placed ON the
+// reference. `closest()` including the start node is exactly what's wanted:
+// the interactive target may BE a floating-surface trigger (e.g. a
+// DropdownMenu trigger button carrying `data-tour`) or contain one, and
+// either way its floating surface must elevate above the tour it was opened
+// from.
+const 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} ...>
+ */
+export function useInOverlay(
+  referenceRef: RefObject<HTMLElement | null>,
+  active: boolean,
+): boolean {
+  const [inOverlay, setInOverlay] = useState(false);
+  useLayoutEffect(() => {
+    if (!active) {
+      setInOverlay(false);
+      return;
+    }
+    setInOverlay(Boolean(referenceRef.current?.closest(OVERLAY_PORTAL_SELECTOR)));
+  }, [active, referenceRef]);
+  return inOverlay;
+}