@astryxdesign/core 0.7.5 → 0.7.6-canary.e482998

package/src/motion/animator.ts

@@ -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.
  *
@@ -220,6 +232,12 @@ export interface MotionCurve {
  * Options of `createAnimator`.
  */
 export interface AnimatorOptions {
+  /**
+   * Animates a pseudo-element of the element instead (`'::backdrop'` of a
+   * native dialog). A pseudo-element has no inline style, so a static filling
+   * animation holds its value after a curve ends and after `set`.
+   */
+  pseudoElement?: string;
   /** Starting values; identity by default. Never read from the DOM. */
   initial?: MotionValues;
   /** Clock in ms on the document timeline's time base. */
@@ -558,10 +576,10 @@ function format(
   }
 }
 
-const shared = new WeakMap<HTMLElement, Animator>();
+const shared = new WeakMap<HTMLElement, Map<string, Animator>>();
 
 /**
- * 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
@@ -573,10 +591,16 @@ export function animatorFor(
   element: HTMLElement,
   options: AnimatorOptions = {},
 ): Animator {
-  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;
 }
@@ -712,6 +736,7 @@ export function createAnimator(
           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;
@@ -762,6 +787,11 @@ export function createAnimator(
   /** The stylesheet's will-change when there is no inline value. */
   let sheetWillChange = '';
   let demoteTimer: ReturnType<typeof setTimeout> | null = 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<Channel>();
 
@@ -843,7 +873,7 @@ export function createAnimator(
     channel: Channel,
     value: (property: MotionProperty) => number,
   ) => {
-    if (target == null) {
+    if (target == null || pseudoElement != null) {
       return;
     }
     touched.add(channel);
@@ -908,14 +938,32 @@ export function createAnimator(
     return times;
   };
 
+  /** A pseudo-element's resting value, held by a static filling animation. */
+  const hold = (channel: Channel, time: number) => {
+    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: Channel, time: number) => {
     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) {
@@ -932,6 +980,10 @@ export function createAnimator(
       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
@@ -958,6 +1010,10 @@ export function createAnimator(
       ),
     );
     if (end <= from) {
+      if (pseudoElement != null) {
+        hold(channel, time);
+      }
+      previous?.cancel();
       return;
     }
     if (callGroup != null) {
@@ -1041,6 +1097,7 @@ export function createAnimator(
       // inline style already holds the same values, so that changes no pixel.
       fill: 'both',
       easing: 'linear',
+      ...(pseudoElement != null ? {pseudoElement} : {}),
     });
     if (waiting != null) {
       // From rest: no start time, so the browser starts the animation when
@@ -1061,7 +1118,9 @@ export function createAnimator(
 
   /**
    * 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: Channel,
@@ -1088,6 +1147,15 @@ export function createAnimator(
         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();
@@ -1102,22 +1170,36 @@ export function createAnimator(
       target == null
         ? NaN
         : Number.parseFloat(
-            view?.getComputedStyle(target).getPropertyValue('opacity') ?? '',
+            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 = (): boolean =>
-    (target?.style.getPropertyValue('opacity') ?? '') !== '';
+    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();
   };
 
   /**
@@ -1202,6 +1284,9 @@ export function createAnimator(
       releaseOwnOpacity();
       return;
     }
+    if (pseudoElement != null) {
+      return;
+    }
     if (target.style.getPropertyValue(channel) !== IDENTITY_TEXT[channel]) {
       return;
     }
@@ -1265,9 +1350,17 @@ export function createAnimator(
 
   // -- promotion -------------------------------------------------------------
 
-  /** Writes the promoted channels as will-change. */
+  /** Writes the promoted channels as will-change (or the pseudo's property). */
   const writePromotion = (element: HTMLElement) => {
     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;
@@ -1294,7 +1387,7 @@ export function createAnimator(
   };
 
   /**
-   * 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.
@@ -2226,9 +2319,25 @@ export function createAnimator(
       }
       // 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) as Channel[]).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();
       }
@@ -2248,13 +2357,15 @@ export function createAnimator(
       // differs, kept through a detach for the node that comes next.
       if (target != null) {
         const outgoing = target;
-        heldIdentity = new Set(
-          (Object.keys(CHANNELS) as Channel[]).filter(
-            channel =>
-              outgoing.style.getPropertyValue(channel) ===
-              IDENTITY_TEXT[channel],
-          ),
-        );
+        heldIdentity =
+          pseudoHeld ??
+          new Set(
+            (Object.keys(CHANNELS) as Channel[]).filter(
+              channel =>
+                outgoing.style.getPropertyValue(channel) ===
+                IDENTITY_TEXT[channel],
+            ),
+          );
       }
       const held = heldIdentity;
       target = next;
@@ -2284,8 +2395,13 @@ export function createAnimator(
         } 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/src/theme/defineTheme.ts

@@ -132,7 +132,7 @@ import {
 } from './themeAdaptations';
 
 import type {DomainTokenName} from './domainTokens';
-import {domainTokenDefaults} from './domainTokens';
+import {domainTokenDefaults} from './domainTokens/domainTokenDefaults';
 import type {SyntaxThemeDefinition} from './syntax';
 import {registerTheme} from './themeRegistry';
 import {resolveLocalTokenContract} from './localTokens';

package/src/theme/derivedVarRegistry.test.ts

@@ -106,6 +106,10 @@ const STRUCTURAL_VARS = new Set([
   // authored by a theme.
   '--_layout-flush-block-start',
   '--_layout-flush-block-end',
+  // ProgressBar's filled share of the track, written inline from `value` on
+  // every render and read by the fill's transform. Runtime state, never
+  // authored by a theme.
+  '--_progress-bar-fill',
 ]);
 
 /**

package/src/theme/domainTokens/domainTokenDefaults.ts

@@ -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';
+import {dataTokenDefaults} from './dataTokens';
+
+/** All domain token defaults merged — used by defineTheme for validation */
+export const domainTokenDefaults: Record<string, string> = {
+  ...syntaxTokenDefaults,
+  ...dataTokenDefaults,
+};

package/src/theme/domainTokens/index.ts

@@ -6,8 +6,10 @@
  * @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';
@@ -16,16 +18,10 @@ export type {SyntaxTokenName} from '../syntax/tokens';
 export {dataTokenDefaults} from './dataTokens';
 export type {DataTokenName} from './dataTokens';
 
-import {syntaxTokenDefaults} from '../syntax/tokens';
-import {dataTokenDefaults} from './dataTokens';
+export {domainTokenDefaults} from './domainTokenDefaults';
+
 import type {SyntaxTokenName} from '../syntax/tokens';
 import type {DataTokenName} from './dataTokens';
 
-/** All domain token defaults merged — used by defineTheme for validation */
-export const domainTokenDefaults: Record<string, string> = {
-  ...syntaxTokenDefaults,
-  ...dataTokenDefaults,
-};
-
 /** Union of all domain token names */
 export type DomainTokenName = SyntaxTokenName | DataTokenName;

package/src/utils/focusReturn.ts

@@ -12,7 +12,10 @@
  *   overlays (Dialog, DropdownMenu) that move focus programmatically.
  */
 
-import {getInteractionModality} from './interactionModality';
+import {
+  getInteractionModality,
+  type InteractionModality,
+} from './interactionModality';
 
 /**
  * True when focus rests on nothing in particular — no active element, or the
@@ -43,21 +46,29 @@ export function isFocusDetached(doc: Document = 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 function focusForLastInput(
   element: HTMLElement,
   options?: FocusOptions,
+  modality: InteractionModality = getInteractionModality(),
 ): 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.
+  // 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 HTMLInputElement ||
-    element instanceof HTMLTextAreaElement ||
-    element instanceof HTMLSelectElement ||
+    element instanceof view.HTMLInputElement ||
+    element instanceof view.HTMLTextAreaElement ||
+    element instanceof view.HTMLSelectElement ||
     element.isContentEditable;
-  if (isTextEntry || getInteractionModality() !== 'pointer') {
+  if (isTextEntry || modality !== 'pointer') {
     if (options === undefined) {
       element.focus();
     } else {

package/src/utils/getNodeText.test.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {createElement} from 'react';
+import {describe, expect, it} from 'vitest';
+
+import {getNodeText} from './getNodeText';
+
+describe('getNodeText', () => {
+  it('reads strings, numbers and element children, joined with spaces', () => {
+    expect(getNodeText('Name')).toBe('Name');
+    expect(getNodeText(42)).toBe('42');
+    expect(getNodeText(createElement('span', null, 'Amount (EUR)'))).toBe(
+      'Amount (EUR)',
+    );
+    expect(getNodeText(['Total', createElement('b', null, 3)])).toBe('Total 3');
+  });
+
+  it('yields nothing for empty nodes and text a component renders from other props', () => {
+    for (const node of [null, undefined, true, false, []])
+      {expect(getNodeText(node)).toBe('');}
+    const Labelled = ({label}: {label: string}) => label;
+    expect(getNodeText(createElement(Labelled, {label: 'Hidden'}))).toBe('');
+  });
+});

package/src/utils/getNodeText.ts

@@ -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';
+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 function getNodeText(node: ReactNode): string {
+  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 (isValidElement(node)) {
+    const {children} = node.props as {children?: ReactNode};
+    return getNodeText(children);
+  }
+  return '';
+}

package/src/utils/interactionModality.test.ts

@@ -3,7 +3,8 @@
 /**
  * @file interactionModality.test.ts
  * @input The interaction-modality utility loaded more than once
- * @output Verifies document-wide continuity and shared Shift-key modality policy
+ * @output Verifies document-wide continuity, shared Shift-key modality policy,
+ *   and a second document's separate value
  * @position Unit coverage for interactionModality.ts
  */
 
@@ -88,6 +89,49 @@ describe('interactionModality', () => {
     ).toHaveLength(1);
   });
 
+  it("keeps a second document's input apart from the page's", async () => {
+    const pageDocument = document.implementation.createHTMLDocument();
+    const secondDocument = document.implementation.createHTMLDocument();
+    vi.stubGlobal('document', pageDocument);
+    const tracker = await loadTracker();
+    tracker.__startInteractionModalityTrackingForTest();
+    tracker.trackInteractionModalityIn(secondDocument);
+
+    pageDocument.dispatchEvent(new Event('pointerdown'));
+    secondDocument.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'}));
+    expect(tracker.getInteractionModality()).toBe('pointer');
+    expect(tracker.getInteractionModality(pageDocument)).toBe('pointer');
+    expect(tracker.getInteractionModality(secondDocument)).toBe('keyboard');
+
+    secondDocument.dispatchEvent(new Event('pointerdown'));
+    pageDocument.dispatchEvent(new KeyboardEvent('keydown', {key: 'Tab'}));
+    expect(tracker.getInteractionModality()).toBe('keyboard');
+    expect(tracker.getInteractionModality(secondDocument)).toBe('pointer');
+  });
+
+  it("releases a second document's listeners with its last consumer", async () => {
+    const secondDocument = document.implementation.createHTMLDocument();
+    const tracker = await loadTracker();
+    const removeEventListener = vi.spyOn(secondDocument, 'removeEventListener');
+    const releaseFirst = tracker.trackInteractionModalityIn(secondDocument);
+    const releaseSecond = tracker.trackInteractionModalityIn(secondDocument);
+    secondDocument.dispatchEvent(new Event('pointerdown'));
+    expect(tracker.getInteractionModality(secondDocument)).toBe('pointer');
+
+    releaseFirst();
+    releaseFirst();
+    secondDocument.dispatchEvent(new KeyboardEvent('keydown', {key: 'Tab'}));
+    expect(tracker.getInteractionModality(secondDocument)).toBe('keyboard');
+    expect(removeEventListener).not.toHaveBeenCalled();
+
+    releaseSecond();
+    expect(removeEventListener.mock.calls.map(([type]) => type).sort()).toEqual(
+      ['keydown', 'pointerdown'],
+    );
+    secondDocument.dispatchEvent(new Event('pointerdown'));
+    expect(tracker.getInteractionModality(secondDocument)).toBe('keyboard');
+  });
+
   it('uses the keyboard-safe default without a document', async () => {
     vi.stubGlobal('document', undefined);
     const serverModule = await loadTracker();