@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/privateAttributes/pressGroupItem.stylex.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file privateAttributes/pressGroupItem.stylex.ts
+ * @input Nothing: the private press-group-item attribute
+ * @output pressGroupItemProps, which marks an action a group's tracker
+ *   follows with the pointers it follows, and isTrackedByGroup, which reads
+ *   the mark
+ * @position Owner module of the private press-group-item attribute: the only
+ *   file that writes its name. AlertDialog marks its actions, and the press
+ *   controller (utils/pressFeedback.ts) leaves a press of those pointers to
+ *   the group's tracker. No package entry exports it.
+ */
+
+const PRESS_GROUP_ITEM = 'data-astryx-press-group-item';
+
+/**
+ * Spread on each action that a group's tracker follows. It names the pointer
+ * types the tracker follows, such as `['touch', 'pen']`.
+ */
+export function pressGroupItemProps(
+  pointerTypes: ReadonlyArray<string>,
+): Readonly<Record<string, string>> {
+  return {[PRESS_GROUP_ITEM]: pointerTypes.join(' ')};
+}
+
+/**
+ * Whether a group's tracker paints the press on `element` or an ancestor: a
+ * press of `pointerType`, or any press when it is null.
+ */
+export function isTrackedByGroup(
+  element: Element,
+  pointerType: string | null = null,
+): boolean {
+  const marked = element.closest(`[${PRESS_GROUP_ITEM}]`);
+  if (marked == null) {
+    return false;
+  }
+  return (
+    pointerType == null ||
+    (marked.getAttribute(PRESS_GROUP_ITEM) ?? '')
+      .split(' ')
+      .includes(pointerType)
+  );
+}

package/src/privateAttributes/reducedMotion.stylex.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file privateAttributes/reducedMotion.stylex.ts
+ * @input Whether a theme reduces motion for everyone
+ * @output reducedMotionMarkProps and setRootReducedMotionMark, which write the
+ *   mark, and themeReducesMotion, which reads it
+ * @position Owner module of the private reduced-motion attribute: the only
+ *   file that writes its name. Theme marks its root, and the root theme marks
+ *   `<html>`; the animator, reducedMotionFade and the layout glide read it as
+ *   the person's Reduce Motion setting. No package entry exports it.
+ */
+
+const REDUCED_MOTION = 'data-astryx-reduced-motion';
+
+/** Spread on a theme's root when the theme reduces motion for everyone. */
+export function reducedMotionMarkProps(
+  isMarked: boolean,
+): Readonly<Record<string, string>> {
+  return isMarked ? {[REDUCED_MOTION]: ''} : {};
+}
+
+/**
+ * Marks or unmarks `<html>` for the root theme, so a layer portaled outside
+ * the theme's root reads the mark too.
+ */
+export function setRootReducedMotionMark(
+  root: HTMLElement,
+  isMarked: boolean,
+): void {
+  if (isMarked) {
+    root.setAttribute(REDUCED_MOTION, '');
+  } else {
+    root.removeAttribute(REDUCED_MOTION);
+  }
+}
+
+/**
+ * Whether the theme `element` is in reduces motion for everyone: its root,
+ * or `<html>` for the root theme, carries the mark.
+ */
+export function themeReducesMotion(
+  element: Element | null | undefined,
+): boolean {
+  return element?.closest?.(`[${REDUCED_MOTION}]`) != null;
+}

package/src/theme/Theme.tsx

@@ -45,6 +45,11 @@ import {registerTheme} from './themeRegistry';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
 import {warnOnce} from '../utils/devWarning';
+import {REDUCED_MOTION_PROPERTY, resolveMotionKnobs} from './themeMotion';
+import {
+  reducedMotionMarkProps,
+  setRootReducedMotionMark,
+} from '../privateAttributes/reducedMotion.stylex';
 
 /**
  * Theme provider props
@@ -76,6 +81,11 @@ const wrapperStyles = stylex.create({
   system: {
     colorScheme: 'light dark',
   },
+  // The mark's custom property (REDUCED_MOTION_PROPERTY), which every element
+  // under the mark inherits.
+  reducedMotion: {
+    '--_astryx-reduced-motion': '1',
+  },
 });
 
 // =============================================================================
@@ -110,6 +120,7 @@ const THEME_LAYER_ORDER = '@layer reset, astryx-base, astryx-theme;';
 function useThemeStyleInjection(theme: DefinedTheme): void {
   const id = useId();
 
+  // Syncs the document's stylesheets with the runtime theme CSS.
   useInsertionEffect(() => {
     // Built themes have their CSS in a separate file — skip injection
     if (theme.__built) {
@@ -197,12 +208,18 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
  *
  * - 'light' | 'dark' → sets data-theme="light" | "dark"
  * - 'system' → removes data-theme (reset.css defaults to color-scheme: light dark)
+ *
+ * A theme that reduces motion for everyone also marks `<html>` with
+ * `data-astryx-reduced-motion` and its custom property, so layers portaled
+ * outside the wrapper reduce their motion too.
  */
 function useRootThemeSync(
   isNested: boolean,
   mode: ThemeMode,
   themeName: string,
+  reducesMotion: boolean,
 ): void {
+  // Syncs the theme attributes on the root `<html>` element.
   useIsomorphicLayoutEffect(() => {
     if (isNested) {
       return;
@@ -220,12 +237,20 @@ function useRootThemeSync(
 
     // Sync theme name so @scope rules reach portals/fallback viewports.
     document.documentElement.setAttribute(dataAttr('theme'), themeName);
+    setRootReducedMotionMark(document.documentElement, reducesMotion);
+    if (reducesMotion) {
+      document.documentElement.style.setProperty(REDUCED_MOTION_PROPERTY, '1');
+    } else {
+      document.documentElement.style.removeProperty(REDUCED_MOTION_PROPERTY);
+    }
 
     return () => {
       document.documentElement.removeAttribute('data-theme');
       document.documentElement.removeAttribute(dataAttr('theme'));
+      setRootReducedMotionMark(document.documentElement, false);
+      document.documentElement.style.removeProperty(REDUCED_MOTION_PROPERTY);
     };
-  }, [isNested, mode, themeName]);
+  }, [isNested, mode, themeName, reducesMotion]);
 }
 
 // =============================================================================
@@ -255,7 +280,11 @@ export function Theme({
   registerTheme(theme);
 
   useThemeStyleInjection(theme);
-  useRootThemeSync(isNested, mode, theme.name);
+  // resolveMotionKnobs resolves no public theme to 'always', so no theme
+  // marks its root.
+  const reducesMotion =
+    resolveMotionKnobs(theme.__axes?.motion).reducedMotion === 'always';
+  useRootThemeSync(isNested, mode, theme.name, reducesMotion);
 
   // Get color-scheme style
   const colorSchemeStyle =
@@ -272,8 +301,13 @@ export function Theme({
     <ThemeContext value={ctxValue}>
       <ThemeNestingContext value={true}>
         <div
-          {...stylex.props(wrapperStyles.base, colorSchemeStyle)}
+          {...stylex.props(
+            wrapperStyles.base,
+            colorSchemeStyle,
+            reducesMotion && wrapperStyles.reducedMotion,
+          )}
           data-astryx-theme={theme.name}
+          {...reducedMotionMarkProps(reducesMotion)}
           data-theme={mode === 'system' ? undefined : mode}>
           {children}
         </div>

package/src/theme/generateThemeRules.ts

@@ -463,17 +463,18 @@ function joinDeclarations(
 }
 
 /**
- * Public status roles whose canonical default references an existing semantic
- * source token. StyleX owns the document defaults. A theme that authors a
- * source repeats its omitted role at the theme root so nested Theme regions
- * bind the alias locally without changing authored-token metadata.
+ * Public tokens whose canonical default references another public token: the
+ * status roles and `--duration-exit`. StyleX owns the document defaults. A
+ * theme that authors a source repeats its omitted token at the theme root so
+ * nested Theme regions bind the alias locally without changing authored-token
+ * metadata.
  *
  * Conditional scopes repeat an omitted alias only when the source changes on
  * that scope. Explicit adaptation role writes are replayed after generated
  * aliases (and on media descendants) so authored role precedence survives
  * overlapping conditions without disabling the alias in non-matching states.
  */
-const SCOPED_STATUS_ROLE_DEFAULTS: ReadonlyArray<
+const SCOPED_REFERENCE_DEFAULTS: ReadonlyArray<
   readonly [role: string, source: string]
 > = [
   ['--color-text-info', '--color-text-blue'],
@@ -493,16 +494,17 @@ const SCOPED_STATUS_ROLE_DEFAULTS: ReadonlyArray<
   ['--color-border-success', '--color-text-success'],
   ['--color-border-warning', '--color-text-warning'],
   ['--color-border-error', '--color-text-error'],
+  ['--duration-exit', '--duration-fast'],
 ];
 
-const SCOPED_STATUS_ROLE_SOURCES = new Map(SCOPED_STATUS_ROLE_DEFAULTS);
+const SCOPED_REFERENCE_SOURCES = new Map(SCOPED_REFERENCE_DEFAULTS);
 
 /** Colours INV17's derivation measures; a scope that sets one re-derives. */
 const STATUS_MEASURED =
   /^--color-(?:info|success|warning|error|on-|background-surface|background-card)/;
 
 const STATUS_ROLE_ORDER = new Map(
-  SCOPED_STATUS_ROLE_DEFAULTS.map(([role], index) => [role, index]),
+  SCOPED_REFERENCE_DEFAULTS.map(([role], index) => [role, index]),
 );
 
 type TokenValues = Record<string, unknown>;
@@ -740,7 +742,7 @@ export function generatedScopedStatusRoleDefaults(
     ),
   }));
 
-  for (const [role, source] of SCOPED_STATUS_ROLE_DEFAULTS) {
+  for (const [role, source] of SCOPED_REFERENCE_DEFAULTS) {
     const alias = `var(${source})`;
     if (
       authoredRoot[role] !== undefined ||
@@ -775,7 +777,7 @@ function authoredStatusRoleEntries(
   tokens: Record<string, string>,
 ): [string, string][] {
   const canonicalTokens = createTokenCascade(tokens).values;
-  return SCOPED_STATUS_ROLE_DEFAULTS.flatMap(([role]) => {
+  return SCOPED_REFERENCE_DEFAULTS.flatMap(([role]) => {
     const value = canonicalTokens[role];
     return value === undefined ? [] : [[role, stringifyTokenValue(value)]];
   });
@@ -789,7 +791,7 @@ function tokenValueIsAliasOf(value: unknown, source: string): boolean {
 }
 
 function mediaRoleRestorationValue(role: string, value: string): string {
-  const source = SCOPED_STATUS_ROLE_SOURCES.get(role);
+  const source = SCOPED_REFERENCE_SOURCES.get(role);
   return source !== undefined && tokenValueIsAliasOf(value, source)
     ? value
     : 'inherit';
@@ -843,7 +845,7 @@ function generatedAdaptationStatusRoleDefaults(
     // alias, and roles that follow them (icon and border) alias them here.
     const ruleRoles = new Map(aliases[index]);
     const ruleSources = {...authoredRule, ...Object.fromEntries(ruleRoles)};
-    for (const [role, source] of SCOPED_STATUS_ROLE_DEFAULTS) {
+    for (const [role, source] of SCOPED_REFERENCE_DEFAULTS) {
       const alias = `var(${source})`;
       const rootRole = rootValues[role];
       if (
@@ -921,7 +923,7 @@ function generatedMediaStatusRoleDefaults(
     return stringifyTokenValue(candidate.values[role]);
   };
 
-  for (const [role, source] of SCOPED_STATUS_ROLE_DEFAULTS) {
+  for (const [role, source] of SCOPED_REFERENCE_DEFAULTS) {
     const alias = `var(${source})`;
     const rootRole = rootValues[role];
     if (

package/src/theme/motionKnobs.ts

@@ -20,10 +20,11 @@
 export type MotionCharacter = 'crisp' | 'standard' | 'expressive';
 
 /**
- * Whose Reduce Motion setting a theme follows: `'system'`, each person's own.
- * Internal: no theme sets it until `'always'` ships (`spec:AST-108` FR6).
+ * Whose Reduce Motion setting a theme follows: `'system'`, each person's own,
+ * or `'always'`, reduced for everyone. Internal: `resolveKnobs` resolves
+ * every theme to `'system'` until `'always'` ships (`spec:AST-108` FR6).
  */
-export type ThemeReducedMotion = 'system';
+export type ThemeReducedMotion = 'system' | 'always';
 
 /** The motion knobs a theme sets (`spec:AST-108` FR1). */
 export interface ThemeMotionKnobs {

package/src/theme/themeMotion.ts

@@ -87,10 +87,25 @@ function msOf(value: string): number {
  */
 export const MOTION_TEMPO_PROPERTY = '--_astryx-motion-tempo';
 
+/**
+ * The custom property a theme whose `reducedMotion` resolves to `'always'`
+ * sets to `1` on its root, and the root theme on `<html>`: styles that cannot
+ * key a selector on the mark read it in a value.
+ */
+export const REDUCED_MOTION_PROPERTY = '--_astryx-reduced-motion';
+
+/**
+ * A reference such as `--duration-exit` follows the token it names, so tempo
+ * writes no value for it.
+ */
+const TIMED_DURATION_DEFAULTS = Object.entries(durationDefaults).filter(
+  ([, value]) => !value.startsWith('var('),
+);
+
 /** The duration tokens at `tempo`: today's values times it, to the ms. */
 export function durationTokensAt(tempo: number): Record<string, string> {
   const tokens: Record<string, string> = {};
-  for (const [name, value] of Object.entries(durationDefaults)) {
+  for (const [name, value] of TIMED_DURATION_DEFAULTS) {
     tokens[name] = `${Math.round(msOf(value) * tempo)}ms`;
   }
   return tokens;
@@ -123,7 +138,7 @@ export function expandThemeMotion(
   const tokens: Record<string, string> = {};
   if (knobs.tempoIsSet) {
     Object.assign(tokens, durationTokensAt(knobs.tempo));
-    for (const [name, value] of Object.entries(durationDefaults)) {
+    for (const [name, value] of TIMED_DURATION_DEFAULTS) {
       tokens[preTempoName(name)] = value;
     }
     // The press release fade, a fixed clock in the stylesheet, scales by the

package/src/theme/tokens.stylex.ts

@@ -307,6 +307,8 @@ export const durationDefaults = {
   '--duration-slow-min': '730ms',
   '--duration-slow': '975ms',
   '--duration-slow-max': '1300ms',
+  /** The standard dismissal duration. */
+  '--duration-exit': 'var(--duration-fast)',
 } as const;
 
 export const durationVars = stylex.defineVars(durationDefaults);

package/src/utils/dateParser.ts

@@ -32,6 +32,11 @@ export function isLocaleDayFirst(locale: Locale = 'en'): boolean {
   return dayIndex < monthIndex;
 }
 
+// Built at run time: a Unicode property escape in a literal fails a source
+// build whose Babel lacks the Unicode data.
+const LETTER_FREE = new RegExp('^[^\\p{L}]+$', 'u');
+const YEAR_FIRST = new RegExp('^\\d{4}[^\\p{L}\\d]', 'u');
+
 /**
  * Parses user input into a PlainDate.
  *
@@ -138,6 +143,17 @@ export function parseDateInput(
   if (/^\d+$/.test(trimmed)) {
     return null;
   }
+  // In a day-first locale, letter-free text that no form above matched is not
+  // a date. Native `Date` reads `a/b/c` month first. It also takes a year of
+  // one to three digits. So "12/01/2" gives a wrong date. A four-digit year
+  // written first is not ambiguous.
+  if (
+    isLocaleDayFirst(locale) &&
+    LETTER_FREE.test(trimmed) &&
+    !YEAR_FIRST.test(trimmed)
+  ) {
+    return null;
+  }
 
   const parsed = new Date(trimmed);
   if (!isNaN(parsed.getTime())) {

package/src/utils/disabledInteraction.ts

@@ -2,8 +2,9 @@
 
 /**
  * @file disabledInteraction.ts
- * @input An optional caller keydown handler
- * @output Event props that keep a focusable, aria-disabled control inert
+ * @input An optional caller keydown handler, or a control's caller props
+ * @output Event props that keep a focusable, aria-disabled control inert, and
+ *   the caller props such a control hands its element
  * @position Shared by controls that replace native `disabled` with
  *   `aria-disabled` under spec:AST-085 (FR1, FR2)
  */
@@ -38,3 +39,23 @@ export function disabledInteractionProps<T extends HTMLElement>(
     },
   };
 }
+
+/**
+ * The caller props a disabled, focusable control hands its element: every
+ * `on*` handler is dropped except focus and blur, so the control runs no
+ * caller callback, as a natively disabled one runs none. Enabled, `props` pass
+ * through unchanged.
+ */
+export function withholdCallerHandlers<P extends object>(
+  props: P,
+  isDisabled: boolean,
+): P {
+  if (!isDisabled) {
+    return props;
+  }
+  return Object.fromEntries(
+    Object.entries(props).filter(
+      ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+    ),
+  ) as P;
+}

package/src/utils/focusReturn.ts

@@ -4,43 +4,20 @@
  * @file focusReturn.ts
  * @input The document's current active element and the shared interaction
  *   modality.
- * @output Whether focus is currently "detached" — on nothing in particular —
- *   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, and by
- *   disclosures that hide focused content. Only
- *   `isFocusDetached` is exported from the utils entry; the rest is internal.
+ * @output Whether focus 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 overlays (BottomSheet, Dialog, DropdownMenu) that
+ *   move focus programmatically, and by disclosures that hide focused
+ *   content. isFocusDetached lives in isFocusDetached.ts, so the utils entry,
+ *   which exports only it, does not reach this module.
  */
 
 import {
   getInteractionModality,
   type InteractionModality,
 } from './interactionModality';
-
-/**
- * True when focus rests on nothing in particular — no active element, or the
- * document body / root element.
- *
- * An overlay (popover, calendar, dropdown) that restores focus to its trigger
- * on close should do so ONLY when this is true. A native `popover="auto"`
- * light-dismiss fires its close synchronously with the pointer event that
- * moved focus, so by the time the close handler runs, focus has already
- * landed on whatever the user clicked — another field, a button, anywhere.
- * Restoring focus unconditionally would yank it back and fight that click.
- * The one case the browser leaves unresolved is Escape or a click on
- * non-focusable empty space, which drops focus to the body; that is exactly
- * when the trigger should reclaim it.
- */
-export function isFocusDetached(doc: Document = document): boolean {
-  const active = doc.activeElement;
-  return (
-    active == null || active === doc.body || active === doc.documentElement
-  );
-}
+import {isFocusDetached} from './isFocusDetached';
 
 /**
  * True when focus would be lost if `surface` hid now: nothing is focused (see
@@ -151,3 +128,33 @@ export function focusForLastInput(
   }
   element.focus({...options, focusVisible: false});
 }
+
+/**
+ * Prepares the focus return for an open surface that may be removed while
+ * open (rendered only while open, or removed with its view). Removing a
+ * `<dialog>` runs no close and no browser focus return. Call this while the
+ * surface is mounted: it reads the frame that hosts the surface now, because a
+ * removed frame's document has no window. Call the returned function from the
+ * effect cleanup with the opener.
+ *
+ * Once the commit has finished, focus moves to the opener only when the
+ * surface really left the document (StrictMode's simulated unmount keeps it),
+ * the opener is still on the page, and the removal lost focus, both in the
+ * surface's document and in the document that hosts its frame. A control the
+ * user pressed outside the surface, or outside its frame, keeps its focus.
+ */
+export function prepareFocusReturnOnRemoval(
+  surface: Element,
+): (opener: Element | null) => void {
+  const host = surface.ownerDocument.defaultView?.frameElement ?? null;
+  return opener => {
+    queueMicrotask(() => {
+      if (surface.isConnected || opener == null || !opener.isConnected) {
+        return;
+      }
+      if (isFocusLost(surface) && (host == null || isFocusLost(host))) {
+        focusForLastInput(opener as HTMLElement);
+      }
+    });
+  };
+}

package/src/utils/index.ts

@@ -76,7 +76,7 @@ export {characterCount, firstCharacter, truncateCharacters} from './characters';
 
 export {mergeProps} from './mergeProps';
 export {mergeRefs} from './mergeRefs';
-export {isFocusDetached} from './focusReturn';
+export {isFocusDetached} from './isFocusDetached';
 export {composeEventHandlers} from './composeEventHandlers';
 export {themeProps, themeDataAttributes} from './themeProps';
 export type {

package/src/utils/interactionModality.ts

@@ -203,6 +203,7 @@ function holdNodeDocument(
  * tracker of its own for modality.
  */
 export function useInteractionModalityTracking(): InteractionModalityTracking {
+  // Syncs the document's interaction-modality tracking with this mount.
   useEffect(() => trackInteractionModality(), []);
   const nodeRef = useRef<Element | null>(null);
   const holdRef = useRef<{release: (() => void) | null}>({release: null});
@@ -236,7 +237,10 @@ export function useInteractionModalityTracking(): InteractionModalityTracking {
 export function useInteractionModalityTrackingFor(
   elementRef: RefObject<Element | null>,
 ): () => InteractionModality {
+  // Syncs the document's interaction-modality tracking with this mount.
   useEffect(() => trackInteractionModality(), []);
+  // Syncs modality tracking in the element's second document, such as an iframe
+  // or a Picture-in-Picture window.
   useEffect(() => {
     const ownerDocument = elementRef.current?.ownerDocument;
     if (

package/src/utils/interactionOverlay.stylex.ts

@@ -15,8 +15,9 @@
  * SYNC: When modified, update pressFeedback.ts, pressGesture.ts (the fade
  * clock), hooks/usePressFeedback.doc.mjs, the components that paint the touch
  * press off an ancestor scope or a pseudo-element (Switch, Tab,
- * CheckboxInput, RadioListItem, ClickableCard, SelectableCard, Thumbnail)
- * and scripts/build-css.test.mjs.
+ * CheckboxInput, RadioListItem, ClickableCard, SelectableCard, Thumbnail),
+ * Button (a tracked action sizes its `:active` image to zero) and
+ * scripts/build-css.test.mjs.
  */
 
 // Every surface that paints a press uses one of these styles, so a change to
@@ -75,8 +76,9 @@ export const pressVars = stylex.defineVars({
  *
  * `defineConsts`, so the one number is inlined here at build time and is the
  * controller's constant at run time (`PRESS_FADE_MS` in pressGesture.ts):
- * the release animation and the timer that removes the attribute after it
- * cannot drift apart.
+ * the release animation and the controller's clock cannot drift apart. When
+ * that clock runs out, the controller waits for a release animation that a
+ * busy main thread started late, then removes the attribute.
  */
 export const pressConsts = stylex.defineConsts({
   /** How long the release takes, in ms. UIKit's deselect clock. */

package/src/utils/isFocusDetached.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file isFocusDetached.ts
+ * @input The document's current active element
+ * @output Whether focus is currently "detached": on nothing in particular
+ * @position Utility, exported from utils/index.ts; 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. Apart from focusReturn.ts so the utils barrel
+ *   does not reach focusForLastInput: an overlay loaded with import() that
+ *   uses it then keeps it out of the chunk it shares with eager code.
+ */
+
+/**
+ * True when focus rests on nothing in particular — no active element, or the
+ * document body / root element.
+ *
+ * An overlay (popover, calendar, dropdown) that restores focus to its trigger
+ * on close should do so ONLY when this is true. A native `popover="auto"`
+ * light-dismiss fires its close synchronously with the pointer event that
+ * moved focus, so by the time the close handler runs, focus has already
+ * landed on whatever the user clicked — another field, a button, anywhere.
+ * Restoring focus unconditionally would yank it back and fight that click.
+ * The one case the browser leaves unresolved is Escape or a click on
+ * non-focusable empty space, which drops focus to the body; that is exactly
+ * when the trigger should reclaim it.
+ */
+export function isFocusDetached(doc: Document = document): boolean {
+  const active = doc.activeElement;
+  return (
+    active == null || active === doc.body || active === doc.documentElement
+  );
+}