@astryxdesign/core 0.7.5 → 0.7.6-canary.bb18c81

package/dist/motion/animator.js

@@ -69,13 +69,17 @@
  * Chromium starts it after the block.
  *
  * Promotion: Mobile Safari runs an animation whose start time is set from
- * script on its compositor at its first commit only if the element already
- * has a compositing layer; without one, a block right after that commit
- * freezes it (iOS 26.2 simulator: 2 of 7 runs kept moving). Every animation
- * the animator creates, and every `set`, therefore promotes its channels in
- * the same task: inline `will-change` on the element, merged with the
- * element's own. That is enough (5 of 5, and 4 of 4 through the animator);
- * promotion ends PROMOTION_LINGER_MS after the last motion.
+ * script on its compositor at its first commit only if the element (or the
+ * pseudo-element) already has a compositing layer; without one, a block
+ * right after that commit freezes it (iOS 26.2 simulator: 2 of 7 runs kept
+ * moving, 0 of 5 on a ::before). Every animation the animator creates, and
+ * every `set`, therefore promotes its channels in the same task: inline
+ * `will-change` on the element, merged with the element's own, or the custom
+ * property `--astryx-motion-will-change-<pseudo>` on the host for a
+ * pseudo-element, whose style opts in with
+ * `will-change: var(--astryx-motion-will-change-before, auto)`. That is
+ * enough (5 of 5, and 4 of 4 through the animator); promotion ends
+ * PROMOTION_LINGER_MS after the last motion.
  *
  * Known limits, iOS Safari (measured on the iOS 26.2 simulator):
  * - a block in the task that starts a motion delays it: it starts when the
@@ -125,6 +129,14 @@
  * Motion policy above, a cross-fade on a coarse pointer or after a touch
  * release (`touchRelease`) and at once elsewhere (DR2, DR3).
  *
+ * A pseudo-element (`options.pseudoElement`, a dialog's `::backdrop`) has no
+ * inline style: its end value is held by a static filling animation (after a
+ * curve ends, and after `set`) until the next animation replaces it, and for
+ * as long as the pseudo-element exists. The browser makes a `::backdrop`
+ * again each time its dialog opens, without the hold, so a presentation
+ * calls `set` with its starting value right after `showModal()`, in the same
+ * task: a `set` before it lands on the backdrop the open replaces.
+ *
  * SSR-safe: nothing touches `window` or `document` at module scope, and an
  * animator created without an element only keeps state until one is attached.
  *
@@ -285,7 +297,7 @@ function format(channel, value) {
 const shared = new WeakMap();
 
 /**
- * The one animator for `element`, created on
+ * The one animator for `element` (and `options.pseudoElement`), created on
  * first use. Code that animates one element from several places (a swipe on
  * x, a removal on y) shares it, so their curves compose in one `translate`
  * track and retargeting one axis leaves the other on its curve; two
@@ -294,10 +306,16 @@ const shared = new WeakMap();
  * elsewhere or `dispose` it: it lives as long as the element.
  */
 export function animatorFor(element, options = {}) {
-  let animator = shared.get(element);
+  let byPseudo = shared.get(element);
+  if (byPseudo == null) {
+    byPseudo = new Map();
+    shared.set(element, byPseudo);
+  }
+  const key = options.pseudoElement ?? '';
+  let animator = byPseudo.get(key);
   if (animator == null) {
     animator = createAnimator(element, options);
-    shared.set(element, animator);
+    byPseudo.set(key, animator);
   }
   return animator;
 }
@@ -413,6 +431,7 @@ export function createAnimator(element, options = {}) {
   const requestFrame = options.requestFrame ?? (typeof requestAnimationFrame === 'function' ? callback => {
     requestAnimationFrame(() => callback());
   } : null);
+  const pseudoElement = options.pseudoElement;
   // Reduced Motion reads the person's settings and nothing else: no option
   // overrides them (design:reduced-motion DR4).
   const prefersReducedMotion = defaultPrefersReducedMotion;
@@ -463,6 +482,8 @@ export function createAnimator(element, options = {}) {
   /** The stylesheet's will-change when there is no inline value. */
   let sheetWillChange = '';
   let demoteTimer = null;
+  /** A pseudo-element is promoted through a custom property on its host. */
+  const promotionProperty = pseudoElement == null ? null : `--astryx-motion-will-change-${pseudoElement.replace(/^:+/, '')}`;
   /** Channels whose identity the last node held inline (see `attach`). */
   let heldIdentity = new Set();
 
@@ -533,7 +554,7 @@ export function createAnimator(element, options = {}) {
 
   const finalValue = property => segments.get(property)?.target ?? resting[property];
   const writeInline = (channel, value) => {
-    if (target == null) {
+    if (target == null || pseudoElement != null) {
       return;
     }
     touched.add(channel);
@@ -588,14 +609,36 @@ export function createAnimator(element, options = {}) {
     }
     return times;
   };
+
+  /** A pseudo-element's resting value, held by a static filling animation. */
+  const hold = (channel, time) => {
+    if (target == null) {
+      return;
+    }
+    const value = format(channel, finalValue);
+    const animation = target.animate([{
+      [channel]: value
+    }, {
+      [channel]: value
+    }], {
+      duration: 1,
+      fill: 'both',
+      pseudoElement
+    });
+    animation.startTime = time;
+    running.set(channel, animation);
+  };
   const rebuild = (channel, time) => {
     const previous = running.get(channel);
     running.delete(channel);
     clearTimeout(retireTimers.get(channel));
     retireTimers.delete(channel);
-    // The element's inline style holds the end state, so its old animation
-    // can go first.
-    previous?.cancel();
+    // An element's inline style holds the end state, so its old animation can
+    // go first. A pseudo-element has none: its old animation keeps holding the
+    // value until the new one exists (same task, no frame in between).
+    if (pseudoElement == null) {
+      previous?.cancel();
+    }
     const properties = CHANNELS[channel];
     // Settled curves become resting values.
     for (const property of properties) {
@@ -612,6 +655,10 @@ export function createAnimator(element, options = {}) {
       return;
     }
     if (moving.length === 0) {
+      if (pseudoElement != null) {
+        hold(channel, time);
+      }
+      previous?.cancel();
       return;
     }
     // A channel rebuilt by an explicit call (set, rebase, a retarget of
@@ -624,6 +671,10 @@ export function createAnimator(element, options = {}) {
     const from = waiting?.provisional ?? time;
     const end = Math.min(from + MAX_DURATION_MS, Math.max(...moving.map(p => segments.get(p).start + segments.get(p).duration)));
     if (end <= from) {
+      if (pseudoElement != null) {
+        hold(channel, time);
+      }
+      previous?.cancel();
       return;
     }
     if (callGroup != null) {
@@ -702,7 +753,10 @@ export function createAnimator(element, options = {}) {
       // The main thread drops the animation once it runs after the end; the
       // inline style already holds the same values, so that changes no pixel.
       fill: 'both',
-      easing: 'linear'
+      easing: 'linear',
+      ...(pseudoElement != null ? {
+        pseudoElement
+      } : {})
     });
     if (waiting != null) {
       // From rest: no start time, so the browser starts the animation when
@@ -723,7 +777,9 @@ export function createAnimator(element, options = {}) {
 
   /**
    * Once the main thread runs after the curve's end, the animation leaves the
-   * running state: the element's inline style already shows the end values.
+   * running state: an element's inline style already shows the end values; a
+   * pseudo-element's end value moves to a static holding animation, created
+   * before the long one goes.
    */
   const scheduleRetire = (channel, animation, end) => {
     clearTimeout(retireTimers.get(channel));
@@ -740,6 +796,12 @@ export function createAnimator(element, options = {}) {
         return;
       }
       running.delete(channel);
+      // A pseudo-element holds its resting value, unless the stylesheet
+      // takes it back now (a borrowed dip that has ended).
+      const handsBack = channel === 'opacity' && borrowedOpacity != null && ![...landings].some(landing => landing.fadeIn?.isBorrowed === true);
+      if (pseudoElement != null && !handsBack) {
+        hold(channel, now());
+      }
       animation.cancel();
       releaseIdentity(channel);
       flushReleases();
@@ -750,20 +812,30 @@ export function createAnimator(element, options = {}) {
   /** The element's own (stylesheet) opacity, read once when a dip starts. */
   const ownOpacity = () => {
     const view = target?.ownerDocument.defaultView;
-    const value = target == null ? NaN : Number.parseFloat(view?.getComputedStyle(target).getPropertyValue('opacity') ?? '');
+    const value = target == null ? NaN : Number.parseFloat(view?.getComputedStyle(target, pseudoElement ?? null).getPropertyValue('opacity') ?? '');
     return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 1;
   };
 
   /**
    * Whether the animator holds an opacity of its own on the element: an inline
-   * value it wrote (a `set` over a stylesheet that hides or dims it). A dip
-   * returns to that value.
+   * value it wrote, or a pseudo-element's holding animation (a `set` over a
+   * stylesheet that hides or dims it). A dip returns to that value.
    */
-  const writesOwnOpacity = () => (target?.style.getPropertyValue('opacity') ?? '') !== '';
+  const writesOwnOpacity = () => pseudoElement == null ? (target?.style.getPropertyValue('opacity') ?? '') !== '' : running.has('opacity');
 
-  /** Gives the element's opacity back to its stylesheet: its inline value goes. */
+  /**
+   * Gives the element's opacity back to its stylesheet: an element's inline
+   * value goes; a pseudo-element, which has no inline style, loses the
+   * animation holding its value.
+   */
   const releaseOwnOpacity = () => {
-    target?.style.removeProperty('opacity');
+    if (pseudoElement == null) {
+      target?.style.removeProperty('opacity');
+      return;
+    }
+    const held = running.get('opacity');
+    running.delete('opacity');
+    held?.cancel();
   };
 
   /**
@@ -844,6 +916,9 @@ export function createAnimator(element, options = {}) {
       releaseOwnOpacity();
       return;
     }
+    if (pseudoElement != null) {
+      return;
+    }
     if (target.style.getPropertyValue(channel) !== IDENTITY_TEXT[channel]) {
       return;
     }
@@ -903,9 +978,17 @@ export function createAnimator(element, options = {}) {
 
   // -- promotion -------------------------------------------------------------
 
-  /** Writes the promoted channels as will-change. */
+  /** Writes the promoted channels as will-change (or the pseudo's property). */
   const writePromotion = element => {
     const list = [...promoted].join(', ');
+    if (promotionProperty != null) {
+      if (list === '') {
+        element.style.removeProperty(promotionProperty);
+      } else {
+        element.style.setProperty(promotionProperty, list);
+      }
+      return;
+    }
     if (list === '') {
       element.style.willChange = ownWillChange ?? '';
       ownWillChange = null;
@@ -924,7 +1007,7 @@ export function createAnimator(element, options = {}) {
   };
 
   /**
-   * Gives the element a compositing layer for
+   * Gives the element (or its pseudo-element) a compositing layer for
    * `channel` from the task that starts the motion: Mobile Safari runs an
    * animation whose start time is set from script on its compositor at its
    * first commit only if the element already has a layer.
@@ -1747,7 +1830,11 @@ export function createAnimator(element, options = {}) {
       }
       // After the landing's commit, which can promote the element again.
       demote();
+      // A pseudo-element holds an identity with a static animation, which the
+      // cancel below drops: note the channels to hold again on the next node
+      // (never a borrowed opacity, which is the stylesheet's).
       const isOpacityBorrowed = borrowedOpacity != null || [...landings].some(landing => landing.restoreIsBorrowed === true);
+      const pseudoHeld = pseudoElement == null || target == null ? null : new Set(Object.keys(CHANNELS).filter(channel => running.has(channel) && !(channel === 'opacity' && isOpacityBorrowed) && CHANNELS[channel].every(p => !segments.has(p) && resting[p] === IDENTITY[p])));
       for (const animation of running.values()) {
         animation.cancel();
       }
@@ -1767,7 +1854,7 @@ export function createAnimator(element, options = {}) {
       // differs, kept through a detach for the node that comes next.
       if (target != null) {
         const outgoing = target;
-        heldIdentity = new Set(Object.keys(CHANNELS).filter(channel => outgoing.style.getPropertyValue(channel) === IDENTITY_TEXT[channel]));
+        heldIdentity = pseudoHeld ?? new Set(Object.keys(CHANNELS).filter(channel => outgoing.style.getPropertyValue(channel) === IDENTITY_TEXT[channel]));
       }
       const held = heldIdentity;
       target = next;
@@ -1792,8 +1879,13 @@ export function createAnimator(element, options = {}) {
         } else if (held.has(channel)) {
           // An identity the animator held inline over a stylesheet that
           // differs goes onto the new node too (writeInline keeps it only
-          // where the new node's stylesheet still differs).
-          writeInline(channel, property => resting[property]);
+          // where the new node's stylesheet still differs); a pseudo-element's
+          // is held again.
+          if (pseudoElement != null) {
+            hold(channel, time);
+          } else {
+            writeInline(channel, property => resting[property]);
+          }
         }
       }
       flushReleases();

package/dist/theme/defineTheme.js

@@ -68,7 +68,7 @@ import { resolveOnMedia } from "./onMediaTokens.js";
 import { colorDefaults, spacingDefaults, sizeDefaults, borderDefaults, focusDefaults, radiusDefaults, shadowDefaults, durationDefaults, easeDefaults, typographyDefaults, textSizeDefaults, fontWeightDefaults, typeScaleDefaults } from "./tokens.stylex.js";
 import { resolveThemeValues } from "./resolveThemeValues.js";
 import { normalizeThemeAdaptations, resolveThemeAdaptationRules, resolveThemeGenerativeAxes } from "./themeAdaptations.js";
-import { domainTokenDefaults } from "./domainTokens/index.js";
+import { domainTokenDefaults } from "./domainTokens/domainTokenDefaults.js";
 import { registerTheme } from "./themeRegistry.js";
 import { resolveLocalTokenContract } from "./localTokens.js";
 

package/dist/theme/domainTokens/domainTokenDefaults.d.ts

@@ -0,0 +1,3 @@
+/** All domain token defaults merged — used by defineTheme for validation */
+export declare const domainTokenDefaults: Record<string, string>;
+//# sourceMappingURL=domainTokenDefaults.d.ts.map

package/dist/theme/domainTokens/domainTokenDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domainTokenDefaults.d.ts","sourceRoot":"","sources":["../../../src/theme/domainTokens/domainTokenDefaults.ts"],"names":[],"mappings":"AAcA,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGtD,CAAC"}

package/dist/theme/domainTokens/domainTokenDefaults.js

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file domainTokens/domainTokenDefaults.ts
+ * @input syntaxTokenDefaults, dataTokenDefaults
+ * @output domainTokenDefaults
+ * @position Merges the domain token defaults for defineTheme. Kept out of the
+ *   domainTokens barrel because defineTheme sits in a lazily imported module
+ *   graph, which imports no barrel (pinned by scripts/core-single-bundle.test.mjs).
+ */
+
+import { syntaxTokenDefaults } from "../syntax/tokens.js";
+import { dataTokenDefaults } from "./dataTokens.js";
+
+/** All domain token defaults merged — used by defineTheme for validation */
+export const domainTokenDefaults = {
+  ...syntaxTokenDefaults,
+  ...dataTokenDefaults
+};

package/dist/theme/domainTokens/index.d.ts

@@ -4,17 +4,18 @@
  * @output domainTokenDefaults, DomainTokenName
  * @position Token aggregator; consumed by defineTheme for validation + autocomplete
  *
- * Merges all domain token defaults into a single map for defineTheme.
- * Actual token definitions live in their own directories (syntax/, dataviz/).
+ * Re-exports only. The merged map lives in domainTokenDefaults.ts so that
+ * defineTheme, inside a lazily imported module graph, imports it without a
+ * barrel. Actual token definitions live in their own directories (syntax/,
+ * dataviz/).
  */
 export { syntaxTokenDefaults } from '../syntax/tokens.js';
 export type { SyntaxTokenName } from '../syntax/tokens.js';
 export { dataTokenDefaults } from './dataTokens.js';
 export type { DataTokenName } from './dataTokens.js';
+export { domainTokenDefaults } from './domainTokenDefaults.js';
 import type { SyntaxTokenName } from '../syntax/tokens.js';
 import type { DataTokenName } from './dataTokens.js';
-/** All domain token defaults merged — used by defineTheme for validation */
-export declare const domainTokenDefaults: Record<string, string>;
 /** Union of all domain token names */
 export type DomainTokenName = SyntaxTokenName | DataTokenName;
 //# sourceMappingURL=index.d.ts.map

package/dist/theme/domainTokens/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/theme/domainTokens/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAC,iBAAiB,EAAC,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAIhD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGtD,CAAC;AAEF,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/theme/domainTokens/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAC,iBAAiB,EAAC,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,aAAa,CAAC"}

package/dist/theme/domainTokens/index.js

@@ -6,18 +6,14 @@
  * @output domainTokenDefaults, DomainTokenName
  * @position Token aggregator; consumed by defineTheme for validation + autocomplete
  *
- * Merges all domain token defaults into a single map for defineTheme.
- * Actual token definitions live in their own directories (syntax/, dataviz/).
+ * Re-exports only. The merged map lives in domainTokenDefaults.ts so that
+ * defineTheme, inside a lazily imported module graph, imports it without a
+ * barrel. Actual token definitions live in their own directories (syntax/,
+ * dataviz/).
  */
 
 export { syntaxTokenDefaults } from "../syntax/tokens.js";
 export { dataTokenDefaults } from "./dataTokens.js";
-import { syntaxTokenDefaults } from "../syntax/tokens.js";
-import { dataTokenDefaults } from "./dataTokens.js";
-/** All domain token defaults merged — used by defineTheme for validation */
-export const domainTokenDefaults = {
-  ...syntaxTokenDefaults,
-  ...dataTokenDefaults
-};
+export { domainTokenDefaults } from "./domainTokenDefaults.js";
 
 /** Union of all domain token names */

package/dist/utils/focusReturn.d.ts

@@ -1,3 +1,15 @@
+/**
+ * @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 —
+ *   and a focus move whose ring follows the last input.
+ * @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.
+ */
+import { type InteractionModality } from './interactionModality.js';
 /**
  * True when focus rests on nothing in particular — no active element, or the
  * document body / root element.
@@ -21,8 +33,12 @@ export declare function isFocusDetached(doc?: Document): boolean;
  * 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`.
+ *
  * Make sure modality tracking is active (`useInteractionModalityTracking()`)
  * in the component that calls this.
  */
-export declare function focusForLastInput(element: HTMLElement, options?: FocusOptions): void;
+export declare function focusForLastInput(element: HTMLElement, options?: FocusOptions, modality?: InteractionModality): void;
 //# sourceMappingURL=focusReturn.d.ts.map

package/dist/utils/focusReturn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"focusReturn.d.ts","sourceRoot":"","sources":["../../src/utils/focusReturn.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAwBN"}
+{"version":3,"file":"focusReturn.d.ts","sourceRoot":"","sources":["../../src/utils/focusReturn.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,YAAY,EACtB,QAAQ,GAAE,mBAA8C,GACvD,IAAI,CA2BN"}

package/dist/utils/focusReturn.js

@@ -41,14 +41,21 @@ export function isFocusDetached(doc = document) {
  * 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`.
+ *
  * Make sure modality tracking is active (`useInteractionModalityTracking()`)
  * in the component that calls this.
  */
-export function focusForLastInput(element, options) {
+export function focusForLastInput(element, options, modality = getInteractionModality()) {
   // 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.
-  const isTextEntry = element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement || element.isContentEditable;
-  if (isTextEntry || getInteractionModality() !== 'pointer') {
+  // goes, and an extra blur there can run validation or mark it touched. The
+  // field's own window: one in an iframe or a Picture-in-Picture window is
+  // never an instance of the page's constructors.
+  const view = element.ownerDocument.defaultView ?? window;
+  const isTextEntry = element instanceof view.HTMLInputElement || element instanceof view.HTMLTextAreaElement || element instanceof view.HTMLSelectElement || element.isContentEditable;
+  if (isTextEntry || modality !== 'pointer') {
     if (options === undefined) {
       element.focus();
     } else {

package/dist/utils/getNodeText.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+/**
+ * The plain text a node renders through strings, numbers and element
+ * children, joined with spaces. Text a component renders internally, from
+ * props other than `children`, is not reachable and yields `''`.
+ */
+export declare function getNodeText(node: ReactNode): string;
+//# sourceMappingURL=getNodeText.d.ts.map

package/dist/utils/getNodeText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getNodeText.d.ts","sourceRoot":"","sources":["../../src/utils/getNodeText.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAkBnD"}

package/dist/utils/getNodeText.js

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getNodeText.ts
+ * @input Receives a React node
+ * @output Exports getNodeText, the node's plain text
+ * @position Shared utility; consumed where a rendered node also needs a
+ *   spoken name (Toast announcements, Table column-resize handle names)
+ */
+
+import { isValidElement } from 'react';
+/**
+ * The plain text a node renders through strings, numbers and element
+ * children, joined with spaces. Text a component renders internally, from
+ * props other than `children`, is not reachable and yields `''`.
+ */
+export function getNodeText(node) {
+  if (node == null || typeof node === 'boolean') {
+    return '';
+  }
+  if (typeof node === 'string') {
+    return node;
+  }
+  if (typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(getNodeText).filter(Boolean).join(' ');
+  }
+  if (/*#__PURE__*/isValidElement(node)) {
+    const {
+      children
+    } = node.props;
+    return getNodeText(children);
+  }
+  return '';
+}

package/dist/utils/interactionModality.d.ts

@@ -2,8 +2,17 @@ export type InteractionModality = 'keyboard' | 'pointer';
 declare function trackInteractionModality(): () => void;
 /** Activate shared modality tracking when the first consumer mounts. */
 export declare function useInteractionModalityTracking(): void;
-/** How the user last interacted with the page. */
-export declare function getInteractionModality(): InteractionModality;
+/**
+ * Track a second document while a consumer there is mounted: a component an
+ * app renders into a same-origin iframe or a Document Picture-in-Picture
+ * window gets input there that never reaches the page's listeners. The first
+ * consumer installs the document's listener pair and the last one's cleanup
+ * removes it. Read the value with `getInteractionModality(doc)`. The page's
+ * own document keeps its document-lifetime listeners.
+ */
+export declare function trackInteractionModalityIn(targetDocument: Document): () => void;
+/** How the user last interacted with the page, or with `targetDocument`. */
+export declare function getInteractionModality(targetDocument?: Document): InteractionModality;
 /** Test-only: restore the initial state between cases. */
 export declare function __resetInteractionModalityForTest(): void;
 /** Test-only: activate the tracker without rendering a hook. */

package/dist/utils/interactionModality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interactionModality.d.ts","sourceRoot":"","sources":["../../src/utils/interactionModality.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAC;AA8CzD,iBAAS,wBAAwB,IAAI,MAAM,IAAI,CAsB9C;AAED,wEAAwE;AACxE,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED,kDAAkD;AAClD,wBAAgB,sBAAsB,IAAI,mBAAmB,CAI5D;AAED,0DAA0D;AAC1D,wBAAgB,iCAAiC,IAAI,IAAI,CAIxD;AAED,gEAAgE;AAChE,eAAO,MAAM,yCAAyC,iCAC5B,CAAC"}
+{"version":3,"file":"interactionModality.d.ts","sourceRoot":"","sources":["../../src/utils/interactionModality.ts"],"names":[],"mappings":"AAwCA,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAC;AAgDzD,iBAAS,wBAAwB,IAAI,MAAM,IAAI,CAsB9C;AAED,wEAAwE;AACxE,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,QAAQ,GACvB,MAAM,IAAI,CAkCZ;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CACpC,cAAc,CAAC,EAAE,QAAQ,GACxB,mBAAmB,CAOrB;AAED,0DAA0D;AAC1D,wBAAgB,iCAAiC,IAAI,IAAI,CAIxD;AAED,gEAAgE;AAChE,eAAO,MAAM,yCAAyC,iCAC5B,CAAC"}

package/dist/utils/interactionModality.js

@@ -6,7 +6,9 @@
  * @file interactionModality.ts
  * @input Global pointerdown/keydown events
  * @output `useInteractionModalityTracking()` activates document-lifetime tracking;
- *   `getInteractionModality()` reads how the user last interacted
+ *   `getInteractionModality()` reads how the user last interacted;
+ *   `trackInteractionModalityIn(doc)` and `getInteractionModality(doc)` do the
+ *   same for a second document
  * @position Internal document-wide singleton; used where `:focus-visible` alone
  *   is too broad
  *
@@ -26,8 +28,12 @@
  * The store lives on `document`, so duplicate Astryx bundles share one state
  * value and one listener pair. The first mounted consumer activates tracking;
  * the listeners then remain for the document lifetime so input during a gap
- * between consumers is not lost. Importing this module has no DOM side effects,
- * and server rendering keeps the keyboard-safe default.
+ * between consumers is not lost. A second document (a same-origin iframe, a
+ * Document Picture-in-Picture window) gets its own store when a component
+ * tracks it, since input there never reaches the page's listeners; its
+ * listeners stay only while a consumer there is mounted. Importing this module
+ * has no DOM side effects, and server rendering keeps the keyboard-safe
+ * default.
  */
 import { useEffect } from 'react';
 const interactionModalityStoreKey = Symbol.for('@astryxdesign/core/interaction-modality/v1');
@@ -89,8 +95,55 @@ export function useInteractionModalityTracking() {
   useEffect(() => trackInteractionModality(), []);
 }
 
-/** How the user last interacted with the page. */
-export function getInteractionModality() {
+/**
+ * Track a second document while a consumer there is mounted: a component an
+ * app renders into a same-origin iframe or a Document Picture-in-Picture
+ * window gets input there that never reaches the page's listeners. The first
+ * consumer installs the document's listener pair and the last one's cleanup
+ * removes it. Read the value with `getInteractionModality(doc)`. The page's
+ * own document keeps its document-lifetime listeners.
+ */
+export function trackInteractionModalityIn(targetDocument) {
+  if (typeof document !== 'undefined' && targetDocument === document) {
+    return trackInteractionModality();
+  }
+  const store = getStore(targetDocument);
+  store.consumers = (store.consumers ?? 0) + 1;
+  if (store.consumers === 1) {
+    store.isListening = true;
+    targetDocument.addEventListener('pointerdown', store.onPointerDown, {
+      capture: true,
+      passive: true
+    });
+    targetDocument.addEventListener('keydown', store.onKeyDown, {
+      capture: true,
+      passive: true
+    });
+  }
+  let isReleased = false;
+  return () => {
+    if (isReleased) {
+      return;
+    }
+    isReleased = true;
+    store.consumers = (store.consumers ?? 1) - 1;
+    if (store.consumers === 0) {
+      store.isListening = false;
+      targetDocument.removeEventListener('pointerdown', store.onPointerDown, {
+        capture: true
+      });
+      targetDocument.removeEventListener('keydown', store.onKeyDown, {
+        capture: true
+      });
+    }
+  };
+}
+
+/** How the user last interacted with the page, or with `targetDocument`. */
+export function getInteractionModality(targetDocument) {
+  if (targetDocument != null) {
+    return getStore(targetDocument).modality;
+  }
   return typeof document === 'undefined' ? 'keyboard' : getStore(document).modality;
 }