@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/privateAttributes/hapticSwitch.stylex.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file privateAttributes/hapticSwitch.stylex.ts
+ * @input The hidden switch a label's tap haptic plays through
+ * @output markHapticSwitch, which marks that switch, and isHapticSwitch,
+ *   which reads the mark
+ * @position Owner module of the private haptic-switch attribute
+ *   (`architecture:public-component-api` INV23): the only file that writes
+ *   its name. gestures/haptics.ts marks its hidden switch; the click guard
+ *   skips that switch without importing the haptics module, so a gesture
+ *   that only guards clicks carries no haptics code
+ *   (`architecture:react-component-runtime` INV13). No package entry
+ *   exports it.
+ */
+
+const HAPTIC_SWITCH = 'data-astryx-haptic-switch';
+
+/** Marks the hidden switch a label's tap haptic plays through. */
+export function markHapticSwitch(element: Element): void {
+  element.setAttribute(HAPTIC_SWITCH, '');
+}
+
+/** Whether `target` is that hidden switch. */
+export function isHapticSwitch(target: EventTarget | null): boolean {
+  return target instanceof Element && target.hasAttribute(HAPTIC_SWITCH);
+}

package/src/privateAttributes/layerRoot.stylex.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file privateAttributes/layerRoot.stylex.ts
+ * @input A layer content root
+ * @output layerRootProps, which marks an element as a layer root, and
+ *   closestLayerRoot, which finds the nearest marked root
+ * @position Owner module of the private layer-root attribute: the only
+ *   file that writes its name. Layer's click boundary spreads the mark on
+ *   every layer root; SelectableCard reads it for its compatibility path
+ *   until the next minor. No package entry exports it.
+ */
+
+const LAYER_ROOT = 'data-astryx-layer-root';
+
+/** Spread on a layer content root. */
+export const layerRootProps: Readonly<Record<`data-${string}`, string>> = {
+  [LAYER_ROOT]: '',
+};
+
+/**
+ * The nearest layer root at or above `target`, or null outside every layer.
+ * Only marked roots count; an element that merely carries `popover` or is a
+ * `<dialog>` does not.
+ */
+export function closestLayerRoot(target: Element): Element | null {
+  return target.closest(`[${LAYER_ROOT}]`);
+}

package/src/privateAttributes/segmentDisabled.stylex.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file privateAttributes/segmentDisabled.stylex.ts
+ * @input A segment's own `isDisabled`
+ * @output segmentDisabledProps, which marks a SegmentedControl segment
+ *   disabled by its own `isDisabled`, and isSegmentDisabledOnItsOwn, which
+ *   reads that mark
+ * @position Owner module of the private segment-disabled attribute
+ *   (`architecture:public-component-api` INV23): the only file that writes
+ *   its name. SegmentedControl reads it to place the Tab stop of a control
+ *   disabled with a reason (`component:SegmentedControl` FR2). No package
+ *   entry exports it.
+ */
+
+const SEGMENT_DISABLED = 'data-astryx-segment-disabled';
+
+/** Spread on a segment: marks it when it is disabled by its own isDisabled. */
+export function segmentDisabledProps(
+  isDisabled: boolean,
+): Readonly<Record<string, string>> {
+  return isDisabled ? {[SEGMENT_DISABLED]: ''} : {};
+}
+
+/** Whether a segment element is disabled by its own isDisabled. */
+export function isSegmentDisabledOnItsOwn(segment: Element): boolean {
+  return segment.hasAttribute(SEGMENT_DISABLED);
+}

package/src/theme/Theme.tsx

@@ -83,11 +83,15 @@ const wrapperStyles = stylex.create({
 // =============================================================================
 
 /**
- * Context to detect whether this Theme is nested inside another.
- * The root provider (no parent context) syncs data-theme to <html>.
- * @internal
+ * True below a Theme; the root Theme (no parent context) syncs data-theme
+ * to <html>. A detached React root that conceptually sits inside the app
+ * (useToast's fallback viewport) provides it as `true` itself, so a Theme
+ * rendered in toast content themes its subtree without claiming <html> as
+ * if it were the app's root Theme.
+ * @internal Not exported from the theme barrel; useToast imports it from
+ * './theme/Theme' directly.
  */
-const ThemeNestingContext = React.createContext(false);
+export const ThemeNestingContext = React.createContext(false);
 ThemeNestingContext.displayName = 'ThemeNestingContext';
 
 // =============================================================================

package/src/theme/useTheme.ts

@@ -10,6 +10,8 @@
  *
  * Provides synchronous access to theme token values resolved for the
  * current color mode — no DOM reads on the provider path, no double render.
+ * The returned `mode` is always 'light' | 'dark': 'system', and any value
+ * outside the union, resolves through the OS preference.
  * Without a reachable ThemeContext it consults `<html data-theme>` and
  * `<html data-astryx-theme>` (kept in sync by Theme) via shared, refcounted
  * MutationObservers before assuming OS preference/default tokens. Provider-path
@@ -296,8 +298,11 @@ export function useTheme(): UseThemeReturn {
   const mode = ctx?.mode ?? rootAttrMode ?? 'system';
   const theme = ctx?.theme ?? getRegisteredTheme(rootThemeName);
 
+  // Anything outside light|dark (a stale persisted preference cast to
+  // ThemeMode, say) resolves like 'system', the way the root Theme's <html>
+  // sync already treats it, so the declared return type holds.
   const effectiveMode: 'light' | 'dark' =
-    mode === 'system' ? (prefersDark ? 'dark' : 'light') : mode;
+    mode === 'light' || mode === 'dark' ? mode : prefersDark ? 'dark' : 'light';
 
   // Build the full resolved map, memoized on theme + effective mode
   const tokens = useMemo(

package/src/utils/accessibleName.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file accessibleName.ts
+ * @input A rendered element
+ * @output The name an assistive technology reads for it, as far as the DOM
+ *   gives it: `aria-labelledby` targets, `aria-label`, its own labels, an
+ *   input button's value, its visible text (`aria-hidden` left out, an inner
+ *   image's alt, `aria-label` or svg title counted), then `title`
+ * @position Internal utility, not exported from the package: DropdownMenu
+ *   names a menu after a custom trigger, and SideNav finds a re-rendered
+ *   header or footer control again by name (`component:SideNav` AR3)
+ */
+
+/** Text an assistive technology reads from `element`, `aria-hidden` left out. */
+function visibleText(element: Element): string {
+  const copy = element.cloneNode(true) as Element;
+  for (const hidden of copy.querySelectorAll('[aria-hidden="true"]')) {
+    hidden.remove();
+  }
+  // An icon-only control is named by its image's alt, an inner aria-label, or
+  // an svg title rather than by text, so those count as its contents too.
+  for (const named of copy.querySelectorAll('img[alt], [aria-label]')) {
+    const name =
+      named.getAttribute(named.tagName === 'IMG' ? 'alt' : 'aria-label') ?? '';
+    named.replaceWith(copy.ownerDocument.createTextNode(` ${name} `));
+  }
+  for (const svg of copy.querySelectorAll('svg')) {
+    const title = svg.querySelector('title')?.textContent ?? '';
+    svg.replaceWith(copy.ownerDocument.createTextNode(` ${title} `));
+  }
+  return (copy.textContent ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * The accessible name of `element`: its own `aria-labelledby` targets, its
+ * `aria-label`, its labels, an input button's value, its text, or its
+ * `title`, in that order. A custom DropdownMenu trigger names the menu it
+ * labels this way.
+ */
+export function readAccessibleName(
+  element: HTMLElement | null,
+): string | undefined {
+  if (element == null) {
+    return undefined;
+  }
+  const labelledBy = element.getAttribute('aria-labelledby');
+  if (labelledBy != null && labelledBy.trim() !== '') {
+    const text = labelledBy
+      .split(/\s+/)
+      .map(id => element.ownerDocument.getElementById(id))
+      .filter((node): node is HTMLElement => node != null)
+      .map(visibleText)
+      .join(' ')
+      .trim();
+    if (text !== '') {
+      return text;
+    }
+  }
+  const label = element.getAttribute('aria-label')?.trim();
+  if (label) {
+    return label;
+  }
+  // A form control is named by its own <label>s; an input button by its value.
+  const labels =
+    'labels' in element
+      ? Array.from((element as HTMLInputElement).labels ?? [])
+      : [];
+  const labelText = labels.map(visibleText).join(' ').trim();
+  if (labelText !== '') {
+    return labelText;
+  }
+  if (
+    element instanceof HTMLInputElement &&
+    ['button', 'submit', 'reset'].includes(element.getAttribute('type') ?? '')
+  ) {
+    const value = element.value.trim();
+    if (value !== '') {
+      return value;
+    }
+  }
+  const text = visibleText(element);
+  if (text !== '') {
+    return text;
+  }
+  return element.getAttribute('title')?.trim() || undefined;
+}

package/src/utils/clickGuard.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file clickGuard.ts
+ * @input A document whose gesture already acted (a menu row's release, a
+ *   touch a gesture recognizer claimed)
+ * @output armClickGuard (and its ClickGuardOptions), disarmClickGuard,
+ *   isClickGuardArmed, withoutClickGuard and CLICK_GUARD_WINDOW_MS
+ * @position The one guard for the browser's click after a gesture that
+ *   already acted, shared by hooks/useMenuPress.ts and gestures/GestureHost.ts
+ *
+ * SYNC: When modified, update clickGuard.test.ts, hooks/useMenuPress.ts and
+ * gestures/GestureHost.ts.
+ */
+
+// Armed at a tracked release, the guard swallows the next click on the
+// window's capture phase (utils/inputStream.ts), so no framework sees it. It
+// disarms on that click, at the next `pointerdown`, or after
+// {@link CLICK_GUARD_WINDOW_MS}. After the menu press model arms it, its click
+// listener stays, so it keeps its place ahead of window listeners that the
+// page adds later (AST-057, AST-094). If only the gesture host arms it, the
+// click listener stays only while the guard is armed.
+//
+// Some clicks always pass:
+// - a click with `detail` 0: a keyboard's, a screen reader's, or one that the
+//   page dispatches;
+// - a click dispatched inside {@link withoutClickGuard};
+// - the hidden haptic switch's click (gestures/haptics.ts).
+
+import {isHapticSwitch} from '../privateAttributes/hapticSwitch.stylex';
+import {subscribeInput} from './inputStream';
+
+/**
+ * How long after a release the browser's click is still swallowed, in ms.
+ * Browsers report it right after the release; the next `pointerdown`
+ * disarms the guard first, so this bounds only a click that never comes.
+ */
+export const CLICK_GUARD_WINDOW_MS = 400;
+
+/** Options for {@link armClickGuard}. */
+export interface ClickGuardOptions {
+  /**
+   * The menu press model's arm: the window's click listener stays from then
+   * on. Any other arm keeps it only while the guard is armed.
+   * @default false
+   */
+  readonly staysInstalled?: boolean;
+}
+
+interface Guard {
+  readonly unsubscribers: (() => void)[];
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
+const guards = new Map<Document, Guard>();
+/** The click listeners that stay, by window: the menu press model's. */
+const stayingClickListeners = new WeakMap<Window, () => void>();
+let unguardedDepth = 0;
+
+/** Listen for the next click on `view`'s capture phase; returns the stop. */
+function listenForClicks(view: Window): () => void {
+  return subscribeInput(
+    view,
+    'click',
+    event => {
+      const doc = view.document;
+      if (!guards.has(doc) || isExempt(event)) {
+        return;
+      }
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      disarmClickGuard(doc);
+    },
+    {cancels: true},
+  );
+}
+
+/** Swallow the browser's next click on `doc` (see the file header). */
+export function armClickGuard(
+  doc: Document,
+  {staysInstalled = false}: ClickGuardOptions = {},
+): void {
+  const view = doc.defaultView;
+  if (view == null) {
+    return;
+  }
+  disarmClickGuard(doc);
+  const guard: Guard = {unsubscribers: [], timer: null};
+  if (staysInstalled && !stayingClickListeners.has(view)) {
+    stayingClickListeners.set(view, listenForClicks(view));
+  }
+  if (!stayingClickListeners.has(view)) {
+    // The gesture host's arm: the click listener lasts while this guard does.
+    guard.unsubscribers.push(listenForClicks(view));
+  }
+  guards.set(doc, guard);
+  guard.unsubscribers.push(
+    // The next press is a new gesture: its click must never be eaten.
+    subscribeInput(view, 'pointerdown', () => disarmClickGuard(doc)),
+  );
+  guard.timer = setTimeout(() => disarmClickGuard(doc), CLICK_GUARD_WINDOW_MS);
+}
+
+/** Stop swallowing on `doc`; idempotent. */
+export function disarmClickGuard(doc: Document): void {
+  const guard = guards.get(doc);
+  if (guard == null) {
+    return;
+  }
+  guards.delete(doc);
+  if (guard.timer != null) {
+    clearTimeout(guard.timer);
+  }
+  for (const unsubscribe of guard.unsubscribers) {
+    unsubscribe();
+  }
+}
+
+/** Whether the guard on `doc` would swallow the next click. */
+export function isClickGuardArmed(doc: Document): boolean {
+  return guards.has(doc);
+}
+
+/**
+ * Run `dispatch`, letting through every click it dispatches: a click the
+ * caller reports itself after the gesture (a row's activation, a replayed or
+ * retargeted click).
+ */
+export function withoutClickGuard<T>(dispatch: () => T): T {
+  unguardedDepth++;
+  try {
+    return dispatch();
+  } finally {
+    unguardedDepth--;
+  }
+}
+
+/**
+ * Test-only: disarm every guard between cases, and drop the current window's
+ * staying click listener, as on a fresh page.
+ */
+export function __resetClickGuardForTest(): void {
+  for (const doc of [...guards.keys()]) {
+    disarmClickGuard(doc);
+  }
+  if (typeof window !== 'undefined') {
+    stayingClickListeners.get(window)?.();
+    stayingClickListeners.delete(window);
+  }
+}
+
+function isExempt(event: MouseEvent): boolean {
+  if (event.detail === 0 || unguardedDepth > 0) {
+    return true;
+  }
+  return isHapticSwitch(event.target);
+}

package/src/utils/coarsePointer.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file coarsePointer.ts
+ * @input A window
+ * @output Exports isCoarsePointer and watchCoarsePointer: whether the
+ *   primary pointer is coarse (TOUCH_QUERY), and when it changes
+ * @position The coarse-pointer gate of packages/core/src/gestures and of
+ *   the press controller (pressFeedback.ts): touch-only work registers only
+ *   while it holds
+ *
+ * Under a coarse primary pointer, a phone's touch work stays registered: the
+ * gesture host's page listeners, the page hold and the finger scroll. Under a
+ * fine one, recognizers still attach, and the host listens on the page only
+ * during a press (AST-094). The answer can change while the page is open (a
+ * tablet docking a mouse), so a holder watches it.
+ *
+ * SYNC: When modified, update coarsePointer.test.ts.
+ */
+
+import {TOUCH_QUERY} from './touchQueries';
+
+/** Whether the primary pointer of `view` is coarse now. */
+export function isCoarsePointer(view: Window | null | undefined): boolean {
+  return (
+    typeof view?.matchMedia === 'function' &&
+    view.matchMedia(TOUCH_QUERY).matches
+  );
+}
+
+/**
+ * Call `listener` with the new answer each time the primary pointer of
+ * `view` turns coarse or fine, until the returned function is called.
+ */
+export function watchCoarsePointer(
+  view: Window | null | undefined,
+  listener: (isCoarse: boolean) => void,
+): () => void {
+  if (typeof view?.matchMedia !== 'function') {
+    return () => {};
+  }
+  const query = view.matchMedia(TOUCH_QUERY);
+  const onChange = (): void => listener(query.matches);
+  if (typeof query.addEventListener === 'function') {
+    query.addEventListener('change', onChange);
+    return () => query.removeEventListener('change', onChange);
+  }
+  // Safari before 14 only has the older pair.
+  query.addListener(onChange);
+  return () => query.removeListener(onChange);
+}

package/src/utils/devWarning.ts

@@ -6,15 +6,10 @@
  * @output Standardized `Component: message` console warnings and errors
  * @position Shared dev-logging utility used across components and hooks
  *
- * Standardizes how the design system surfaces information to the builder:
- * every message reads `Component: message` (e.g. `Field: isOptional and
- * isRequired are mutually exclusive.`), so the source is always obvious in
- * the console.
- *
- * Prefer the `useDevWarning` hook inside components — it guards against
- * repeating a warning on every render. These imperative helpers exist for
- * the non-render contexts a hook can't cover: plain functions, module
- * initialization, and inside effects.
+ * Every message reads `Component: message`, so the source is clear in the
+ * console. Prefer `useDevWarning` in components, because it does not repeat
+ * a warning on each render. These helpers are for plain functions, module
+ * initialization and effects.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/utils/index.ts

package/src/utils/flatTree.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file flatTree.ts
+ * @input A DOM node
+ * @output Exports parentAcrossShadow, and containsAlongFlatTree, which walks it
+ * @position The flat-tree parent the browser scrolls and dispatches
+ *   through, shared by the gesture host's native-scroll probe and the
+ *   selection lock (which the press feedback controller uses without the
+ *   gesture system)
+ */
+
+/** The node's parent, crossing out of shadow roots. */
+export function parentAcrossShadow(node: Node): Node | null {
+  // The flat tree the browser scrolls and dispatches through: a slotted node
+  // goes to its slot, a shadow root to its host.
+  const slot = (node as Partial<Slottable>).assignedSlot;
+  if (slot != null) {
+    return slot;
+  }
+  if (node.parentNode != null) {
+    return node.parentNode instanceof ShadowRoot
+      ? node.parentNode.host
+      : node.parentNode;
+  }
+  return null;
+}
+
+/**
+ * Whether `node` is `ancestor` or below it along the flat tree: across an open
+ * shadow root to its host, which `Node.contains` does not follow.
+ */
+export function containsAlongFlatTree(ancestor: Node, node: Node): boolean {
+  for (let at: Node | null = node; at != null; at = parentAcrossShadow(at)) {
+    if (at === ancestor) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/utils/focusOutline.stylex.ts

@@ -5,24 +5,15 @@
  * @input Uses StyleX and theme color tokens
  * @output Exports shared focus-outline prop builders
  * @position Internal utility for consistent keyboard focus outlines across core components
- *
- * Centralizes the standard Astryx focus outline, shown only for keyboard focus.
- * Every focusable surface drew the same 2px accent ring already; writing it per
- * component meant dozens of identical definitions to keep in step, and they did
- * not stay in step — offsets drifted and one ring was a border-width thick.
- *
- * Every ring in core and lab is drawn from here, with one exception recorded in
- * Switch: its condition is a component-scoped ancestor marker, which cannot be
- * shared without leaking focus state between components. A component may still
- * override the OFFSET (a ring that must sit inset, or clear of a field border);
- * width, style and color are not restated anywhere.
- *
- * Every value comes from the `--focus-outline-*` tokens, which is how a theme
- * restyles the ring: one override reaches every component at once. The
- * `:focus-visible` condition is not themeable and stays here, so a theme can
- * change what the ring looks like but cannot show it to pointer users.
  */
 
+// Every ring in core and lab comes from here, except Switch's: its condition
+// is a component-scoped ancestor marker, which cannot be shared without
+// leaking focus state. A component may override only the offset. The values
+// come from the `--focus-outline-*` tokens, so a theme restyles every ring at
+// once. The `:focus-visible` condition is not themeable, so a theme cannot
+// show the ring to pointer users.
+
 import * as stylex from '@stylexjs/stylex';
 import {focusVars} from '../theme/tokens.stylex';
 
@@ -162,10 +153,9 @@ export const focusOutlineStyles = stylex.create({
   },
   /**
    * Like {@link focusOutlineStyles.focusWithin}, but only for a direct child
-   * with `role="combobox"` — for a control box that paints the ring for its
+   * with `role="combobox"`: for a control box that paints the ring for its
    * combobox trigger while sibling controls inside it (a status info-tip, a
-   * clear button) ring themselves. One focus move, one ring
-   * (architecture:interaction-modality INV3).
+   * clear button) ring themselves. One focus move shows one ring.
    */
   focusWithinCombobox: {
     outlineWidth: {

package/src/utils/focusReturn.ts

@@ -5,11 +5,15 @@
  * @input The document's current active element and the shared interaction
  *   modality.
  * @output Whether focus is currently "detached" — on nothing in particular —
- *   and a focus move whose ring follows the last input.
+ *   or would be lost if a surface hid now; a focus move whose ring follows the
+ *   last input; and the one path that moves focus out of content a change
+ *   removed or hid (`noteFocusWithin`, `moveFocusLeftBehind`).
  * @position Utility; used by overlay triggers (e.g. DateInput, DateTimeInput)
  *   that return focus to their control when the overlay closes, but only when
  *   the dismiss did not already move focus somewhere the user chose, and by
- *   overlays (Dialog, DropdownMenu) that move focus programmatically.
+ *   overlays (Dialog, DropdownMenu) that move focus programmatically, and by
+ *   disclosures that hide focused content. Only
+ *   `isFocusDetached` is exported from the utils entry; the rest is internal.
  */
 
 import {
@@ -39,16 +43,78 @@ export function isFocusDetached(doc: Document = document): boolean {
 }
 
 /**
- * Move focus programmatically so its ring follows the last input
- * (`architecture:interaction-modality` INV1). After pointer input the browser's
+ * True when focus would be lost if `surface` hid now: nothing is focused (see
+ * isFocusDetached) or focus sits inside `surface`. Reads `surface`'s own
+ * document, so a surface in an iframe or Picture-in-Picture window is
+ * answered there. Internal: not exported from the utils barrel.
+ */
+export function isFocusLost(surface: Element | null, doc?: Document): boolean {
+  const ownerDocument = doc ?? surface?.ownerDocument ?? document;
+  return (
+    isFocusDetached(ownerDocument) ||
+    (surface != null && surface.contains(ownerDocument.activeElement))
+  );
+}
+
+/** Where focus was, inside a container, before a change removed or hid content. */
+export interface FocusWithin {
+  readonly element: Element;
+  readonly container: HTMLElement;
+}
+
+/**
+ * The focused element, if it is inside `container`. A disclosure calls this
+ * in the commit before the DOM changes (`LayoutChangeSnapshot`'s
+ * `onBeforeChange`), and passes the result to `moveFocusLeftBehind` from a
+ * layout effect of the same commit. Internal.
+ */
+export function noteFocusWithin(
+  container: HTMLElement | null | undefined,
+): FocusWithin | null {
+  const active = container?.ownerDocument.activeElement;
+  if (container == null || active == null || !container.contains(active)) {
+    return null;
+  }
+  return {element: active, container};
+}
+
+/**
+ * Moves focus noted by `noteFocusWithin` to `target` when the change lost it
+ * (`isFocusLost`): it fell to the page because its element was removed, or
+ * it is still inside `hidden`, content the change hid but kept, which the
+ * browser is about to blur. Focus that survived the change, or that was never
+ * inside, is not moved. The ring follows the last input, so the calling
+ * component keeps modality tracking active
+ * (`useInteractionModalityTracking()`). Returns whether focus moved. Internal.
+ */
+export function moveFocusLeftBehind(
+  note: FocusWithin | null,
+  target: HTMLElement | null | undefined,
+  hidden: Element | null = null,
+): boolean {
+  if (
+    note == null ||
+    target == null ||
+    !isFocusLost(hidden, note.container.ownerDocument)
+  ) {
+    return false;
+  }
+  focusForLastInput(target);
+  return true;
+}
+
+/**
+ * Move focus programmatically so its ring follows the last input. After pointer input the browser's
  * focus option keeps the element from matching `:focus-visible`, which is the
  * one way to reach an element the overlay does not render: the consumer's
  * autofocus target, the control that opened a Dialog, or a menu trigger the
  * caller renders. Pass `options` (for example `preventScroll`) as to `focus()`.
  *
- * `modality` defaults to the page's last input. A caller moving focus inside a
- * second document (a same-origin iframe, a Document Picture-in-Picture window)
- * passes that document's, which it tracks with `trackInteractionModalityIn`.
+ * `modality` defaults to the last input in the element's own document: the
+ * page's for an element on the page, and a second document's (a same-origin
+ * iframe, a Document Picture-in-Picture window) for an element there, which
+ * the component tracks by passing its element's ref to
+ * `useInteractionModalityTracking`.
  *
  * Make sure modality tracking is active (`useInteractionModalityTracking()`)
  * in the component that calls this.
@@ -56,7 +122,7 @@ export function isFocusDetached(doc: Document = document): boolean {
 export function focusForLastInput(
   element: HTMLElement,
   options?: FocusOptions,
-  modality: InteractionModality = getInteractionModality(),
+  modality: InteractionModality = getInteractionModality(element),
 ): void {
   // A text-entry field paints its own focus treatment to show where typing
   // goes, and an extra blur there can run validation or mark it touched. The

package/src/utils/getNodeText.ts

@@ -9,6 +9,7 @@
  */
 
 import {isValidElement} from 'react';
+import {isRenderable} from './isRenderable';
 import type {ReactNode} from 'react';
 
 /**
@@ -17,7 +18,7 @@ import type {ReactNode} from 'react';
  * props other than `children`, is not reachable and yields `''`.
  */
 export function getNodeText(node: ReactNode): string {
-  if (node == null || typeof node === 'boolean') {
+  if (!isRenderable(node)) {
     return '';
   }
   if (typeof node === 'string') {