@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/motion/animator.ts

@@ -59,7 +59,11 @@
  * commit: a main-thread block before that frame delays the motion instead of
  * skipping into it. Everything the call starts, and every
  * call from rest in the same task, starts at that one time, which
- * `handle.started` reports. A call that continues motion on
+ * `handle.started` reports. Where the compositor starts it and the page
+ * learns that start only a frame or more later (Chromium), the call starts
+ * at the frame that commits it, the start the compositor takes, so a
+ * retarget or a rebase before then continues from the frame on screen. A
+ * call that continues motion on
  * screen (a retarget, a catch) keeps an explicit start at the call time, or
  * `options.at` to line several animators up, so the new curve continues
  * from the frame on screen. Keyframes are sampled from the call's start, so
@@ -504,6 +508,12 @@ interface StartGroup {
    * browser's, whatever it says (startAfterBlock).
    */
   framed?: boolean;
+  /**
+   * Made in an animation-frame callback of an animator's own (a presented
+   * call's second frame): the browser commits its animations in that frame,
+   * so the frame after it is not the one that starts them.
+   */
+  madeInFrame?: boolean;
   /** The task it was made in, with every call made in that task. */
   task?: TaskMark;
   /** A later call in the same task that took over its curves. */
@@ -663,6 +673,9 @@ interface TaskMark {
 /** The task the current calls from rest are made in, until it ends. */
 let openTask: TaskMark | null = null;
 
+/** How many of the animators' animation-frame callbacks are running now. */
+let frameDepth = 0;
+
 /** The mark of the running task, opened by its first call from rest. */
 function markTask(time: number, clock: () => number): TaskMark {
   if (openTask == null) {
@@ -909,13 +922,28 @@ export function createAnimator(
   options: AnimatorOptions = {},
 ): Animator {
   const now = options.now ?? defaultNow;
-  const requestFrame =
+  const frameSource =
     options.requestFrame ??
     (typeof requestAnimationFrame === 'function'
       ? (callback: () => void) => {
           requestAnimationFrame(() => callback());
         }
       : null);
+  // Every frame callback of an animator's counts itself, so a call made in
+  // one knows its animations commit in that frame.
+  const requestFrame =
+    frameSource == null
+      ? null
+      : (callback: () => void) => {
+          frameSource(() => {
+            frameDepth += 1;
+            try {
+              callback();
+            } finally {
+              frameDepth -= 1;
+            }
+          });
+        };
   const pseudoElement = options.pseudoElement;
   // Reduced Motion reads the person's settings and nothing else: no option
   // overrides them (design:reduced-motion DR4).
@@ -1921,6 +1949,7 @@ export function createAnimator(
     // call's is its second frame's callback, wherever in its frame the call
     // was made.
     group.task = markTask(now(), now);
+    group.madeInFrame = frameDepth > 0;
     queueMicrotask(() => {
       group.fresh = false;
     });
@@ -1940,6 +1969,30 @@ export function createAnimator(
     requestFrame?.(() => {
       syncGroup(group);
       group.framed = true;
+      // Chromium's compositor starts a composited animation when the frame
+      // that commits it reaches it, and tells the page that start a frame or
+      // more later (longer under load). Until then the call would read as
+      // not started while the screen moves it, and a retarget or a rebase
+      // would replay its curve from the start. A call made in a task, still
+      // waiting in the first frame after it, starts now, which the compositor
+      // then takes as its start: the time this frame runs, not its timestamp,
+      // which after a block is the frame time from before the block. Only
+      // when this frame is the one that commits it: not for a call made in a
+      // frame callback, whose frame committed it already, nor when a block
+      // ran between the call and this frame (more than LATE_START_MS), after
+      // which this frame cannot tell a call made in a task from one a page's
+      // own frame callback made; those keep the browser's start.
+      if (
+        !group.resolved &&
+        group.madeInFrame !== true &&
+        now() - (group.task?.first ?? group.provisional) <= LATE_START_MS &&
+        group.animations.some(
+          animation =>
+            animation.startTime == null && animation.playState === 'running',
+        )
+      ) {
+        resolveGroup(group, now());
+      }
     });
     ready.then(
       () => syncGroup(group),

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/focusReturn.ts

@@ -46,9 +46,11 @@ 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`.
+ * `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 +58,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') {

package/src/utils/interactionModality.ts

@@ -5,10 +5,13 @@
 /**
  * @file interactionModality.ts
  * @input Global pointerdown/keydown events
- * @output `useInteractionModalityTracking()` activates document-lifetime tracking;
- *   `getInteractionModality()` reads how the user last interacted;
- *   `trackInteractionModalityIn(doc)` and `getInteractionModality(doc)` do the
- *   same for a second document
+ * @output `useInteractionModalityTracking()` activates tracking for the page and
+ *   returns a callback ref that tracks the element's second document, if any,
+ *   with a reader for that element's own document;
+ *   `useInteractionModalityTrackingFor(objectRef)` does the same for hooks
+ *   that receive a consumer's object ref;
+ *   `getInteractionModality(target?)` reads how the user last interacted in a
+ *   node's or document's own document (the page by default)
  * @position Internal document-wide singleton; used where `:focus-visible` alone
  *   is too broad
  *
@@ -31,12 +34,20 @@
  * 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
+ * listeners stay only while a consumer there is mounted. A component attaches
+ * the one hook's callback ref to its element and gets both; it never tracks a
+ * document itself. Importing this module
  * has no DOM side effects, and server rendering keeps the keyboard-safe
  * default.
  */
 
-import {useEffect} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  type RefCallback,
+  type RefObject,
+} from 'react';
 
 export type InteractionModality = 'keyboard' | 'pointer';
 
@@ -86,15 +97,20 @@ function getStore(targetDocument: Document): InteractionModalityStore {
   return store;
 }
 
-function trackInteractionModality(): () => void {
-  if (typeof document === 'undefined') {
-    return () => {};
+/**
+ * Start or stop hearing a document's input. The one place that listens, so a
+ * change in how input is heard touches nothing else.
+ */
+function setListening(
+  targetDocument: Document,
+  store: InteractionModalityStore,
+  isListening: boolean,
+): void {
+  if (store.isListening === isListening) {
+    return;
   }
-
-  const targetDocument = document;
-  const store = getStore(targetDocument);
-  if (!store.isListening) {
-    store.isListening = true;
+  store.isListening = isListening;
+  if (isListening) {
     targetDocument.addEventListener('pointerdown', store.onPointerDown, {
       capture: true,
       passive: true,
@@ -103,45 +119,42 @@ function trackInteractionModality(): () => void {
       capture: true,
       passive: true,
     });
+  } else {
+    targetDocument.removeEventListener('pointerdown', store.onPointerDown, {
+      capture: true,
+    });
+    targetDocument.removeEventListener('keydown', store.onKeyDown, {
+      capture: true,
+    });
   }
+}
+
+function trackInteractionModality(): () => void {
+  if (typeof document === 'undefined') {
+    return () => {};
+  }
+
+  setListening(document, getStore(document), true);
 
   // The document owns these listeners once activated. Removing them when the
   // last consumer unmounts would miss input before the next consumer mounts.
   return () => {};
 }
 
-/** Activate shared modality tracking when the first consumer mounts. */
-export function useInteractionModalityTracking(): void {
-  useEffect(() => trackInteractionModality(), []);
-}
-
 /**
  * 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.
+ * removes it. The page's own document keeps its document-lifetime listeners.
  */
-export function trackInteractionModalityIn(
-  targetDocument: Document,
-): () => void {
+function trackInteractionModalityIn(targetDocument: Document): () => void {
   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,
-    });
-  }
+  setListening(targetDocument, store, true);
   let isReleased = false;
   return () => {
     if (isReleased) {
@@ -150,21 +163,126 @@ export function trackInteractionModalityIn(
     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,
-      });
+      setListening(targetDocument, store, false);
     }
   };
 }
 
-/** How the user last interacted with the page, or with `targetDocument`. */
+/** What a component gets from its one modality call. */
+export type InteractionModalityTracking = {
+  /**
+   * Attach to the element the component renders (merge it with the element's
+   * other refs with useMergedRefs, or call it with each node and `null` from
+   * a callback ref of the component's own without returning its cleanup).
+   * While the element lives in a second document (a same-origin iframe, a
+   * Document Picture-in-Picture window), that document is tracked; detaching
+   * or replacing the node releases it first (INV6).
+   */
+  ref: RefCallback<Element>;
+  /** How the user last interacted in the element's own document. */
+  readModality: () => InteractionModality;
+};
+
+/**
+ * A second-document hold for the node a ref callback receives: called with
+ * each node and with `null`, it releases the previous document before it holds
+ * a new one, and its returned cleanup releases it too, so React's ref cleanup
+ * and `null` calls both work and a release never runs twice.
+ */
+function holdNodeDocument(
+  node: Element | null,
+  previous: {release: (() => void) | null},
+): (() => void) | undefined {
+  previous.release?.();
+  previous.release = null;
+  const ownerDocument = node?.ownerDocument;
+  if (
+    ownerDocument == null ||
+    (typeof document !== 'undefined' && ownerDocument === document)
+  ) {
+    return undefined;
+  }
+  const release = trackInteractionModalityIn(ownerDocument);
+  previous.release = release;
+  return () => {
+    release();
+    if (previous.release === release) {
+      previous.release = null;
+    }
+  };
+}
+
+/**
+ * Activate shared modality tracking when the first consumer mounts, and read
+ * it for the element the component renders: attach the returned `ref` to that
+ * element. The component makes this one call and adds no effect, listener or
+ * tracker of its own for modality.
+ */
+export function useInteractionModalityTracking(): InteractionModalityTracking {
+  useEffect(() => trackInteractionModality(), []);
+  const nodeRef = useRef<Element | null>(null);
+  const holdRef = useRef<{release: (() => void) | null}>({release: null});
+  const ref = useCallback((node: Element | null) => {
+    nodeRef.current = node;
+    const release = holdNodeDocument(node, holdRef.current);
+    // React's ref cleanup runs instead of a `null` call; it must also forget
+    // the detached node, so the reader never answers from a document whose
+    // listeners are gone.
+    return () => {
+      release?.();
+      if (nodeRef.current === node) {
+        nodeRef.current = null;
+      }
+    };
+  }, []);
+  const readModality = useCallback(
+    () => getInteractionModality(nodeRef.current),
+    [],
+  );
+  return {ref, readModality};
+}
+
+/**
+ * The same, for a hook that receives an object ref its consumer owns
+ * (useMenuPress's `menuRef`, useTouchTrigger's trigger), so it cannot attach a
+ * callback ref. After every commit it holds the ref's CURRENT owner document,
+ * and the same Effect's cleanup releases it (INV3), so a detached, replaced or
+ * moved node releases the old document before the new one is held (INV6).
+ */
+export function useInteractionModalityTrackingFor(
+  elementRef: RefObject<Element | null>,
+): () => InteractionModality {
+  useEffect(() => trackInteractionModality(), []);
+  useEffect(() => {
+    const ownerDocument = elementRef.current?.ownerDocument;
+    if (
+      ownerDocument == null ||
+      (typeof document !== 'undefined' && ownerDocument === document)
+    ) {
+      return undefined;
+    }
+    return trackInteractionModalityIn(ownerDocument);
+  });
+  return useCallback(
+    () => getInteractionModality(elementRef.current),
+    [elementRef],
+  );
+}
+
+/**
+ * How the user last interacted with the page, or in `target`'s own document
+ * (a document, or any node in one: an element in a same-origin iframe or a
+ * Document Picture-in-Picture window answers for that document).
+ */
 export function getInteractionModality(
-  targetDocument?: Document,
+  target?: Document | Node | null,
 ): InteractionModality {
+  const targetDocument =
+    target == null
+      ? null
+      : target.nodeType === 9
+        ? (target as Document)
+        : target.ownerDocument;
   if (targetDocument != null) {
     return getStore(targetDocument).modality;
   }
@@ -183,3 +301,6 @@ export function __resetInteractionModalityForTest(): void {
 /** Test-only: activate the tracker without rendering a hook. */
 export const __startInteractionModalityTrackingForTest =
   trackInteractionModality;
+
+/** Test-only: track a second document without rendering a hook. */
+export const __trackInteractionModalityInForTest = trackInteractionModalityIn;

package/src/utils/pressDisabled.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pressDisabled.ts
+ * @input An element
+ * @output `isDisabledControl`: whether an element is a disabled control, so a
+ *   press on it performs no action
+ * @position The one disabled-control check that press feedback
+ *   (../gestures/haptics) and the hover layers' touch trigger
+ *   (../Layer/useTouchTrigger) share, so the two never disagree about a
+ *   control. It lives outside the gesture code, which a public import that
+ *   uses no gesture never carries (architecture:react-component-runtime
+ *   INV13).
+ */
+
+/**
+ * Whether `element` is a disabled control: `aria-disabled="true"`, or a form
+ * control the browser counts as `:disabled` (a disabled fieldset's controls
+ * included). A disabled control performs no action, so it gives no press
+ * feedback (spec:AST-094 FR23), and a tap on it opens its reason instead
+ * (component:Tooltip FR5).
+ */
+export function isDisabledControl(element: Element): boolean {
+  if (element.getAttribute('aria-disabled') === 'true') {
+    return true;
+  }
+  try {
+    return element.matches(':disabled');
+  } catch {
+    return false;
+  }
+}

package/src/utils/pressFeedback.ts

@@ -2,8 +2,9 @@
 
 /**
  * @file pressFeedback.ts
- * @input The press state machine (pressGesture.ts) and the document's pointer,
- *   keyboard, scroll and visibility events
+ * @input The press state machine (pressGesture.ts), the menu-press marker
+ *   (hooks/menuPressMarker.ts) and the document's pointer, keyboard, scroll and
+ *   visibility events
  * @output Exports PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps and
  *   installPressFeedback
  * @position The DOM half of the touch press model: one delegated controller
@@ -44,6 +45,7 @@
  * pressFeedback.test.ts.
  */
 
+import {MENU_PRESS_MARKER} from '../hooks/menuPressMarker';
 import type {PressGesture, PressPaint, PressStep} from './pressGesture';
 import {
   idlePressGesture,
@@ -107,7 +109,7 @@ const SPACE_ACTIVATED_INPUT_TYPES: ReadonlySet<string> = new Set([
  * FR6, DEC-6): a press held on one row while the highlight follows the
  * pointer to another would light two rows.
  */
-const MENU_PRESS_ROOT = '[data-astryx-menu-press]';
+const MENU_PRESS_ROOT = `[${MENU_PRESS_MARKER}]`;
 
 interface LiveGesture {
   element: HTMLElement;