@astryxdesign/core 0.7.5 → 0.7.6-canary.00146a7

package/src/theme/tokens.ts

@@ -17,6 +17,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/useTheme.ts
+ * - /packages/core/src/theme/tokenReferences.ts (the `var()` resolver)
  * - /packages/core/src/theme/index.ts
  */
 
@@ -28,6 +29,11 @@ import {
 } from './defineTheme';
 import {parseColor, formatColor} from '../utils/color';
 import {generatedScopedStatusRoleDefaults} from './generateThemeRules';
+import {
+  findMatchingParen,
+  resolveTokenReferences,
+  splitTopLevelComma,
+} from './tokenReferences';
 
 /** Resolved color mode used when choosing the side of light/dark token values. */
 export type ResolvedThemeMode = 'light' | 'dark';
@@ -70,52 +76,6 @@ export const tokenVars: Record<TokenName, string> = Object.fromEntries(
   Object.keys(tokenDefaults).map(name => [name, tokenVar(name)]),
 ) as Record<TokenName, string>;
 
-/**
- * Split the arguments of a CSS function body on the first top-level comma.
- * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.
- */
-function splitTopLevelComma(input: string): [string, string] | null {
-  let depth = 0;
-  let quote: '"' | "'" | null = null;
-  let isEscaped = false;
-
-  for (let i = 0; i < input.length; i++) {
-    const char = input[i];
-
-    if (quote !== null) {
-      if (isEscaped) {
-        isEscaped = false;
-      } else if (char === '\\') {
-        isEscaped = true;
-      } else if (char === quote) {
-        quote = null;
-      }
-      continue;
-    }
-
-    if (char === '"' || char === "'") {
-      quote = char;
-      continue;
-    }
-
-    if (char === '(') {
-      depth++;
-      continue;
-    }
-
-    if (char === ')') {
-      depth = Math.max(0, depth - 1);
-      continue;
-    }
-
-    if (char === ',' && depth === 0) {
-      return [input.slice(0, i).trim(), input.slice(i + 1).trim()];
-    }
-  }
-
-  return null;
-}
-
 /** Parse a CSS light-dark(light, dark) function into its two argument values. */
 function parseLightDark(value: string): [light: string, dark: string] | null {
   const trimmed = value.trim();
@@ -158,27 +118,11 @@ function resolveXDSTokenValue(
 // Generated themes emit derived tokens as references to other tokens rather
 // than baked-in values, so a scoped CSS override of a base token re-themes the
 // subtree that references it. The CSS cascade resolves those references, but
-// non-CSS consumers (canvas, SVG, data-viz) need the concrete value. These
-// helpers replay the same resolution in JS: follow `var()` references through
-// the resolved token map (iteratively, guarding against cycles) and evaluate
-// the CSS color functions used by the theme generator against those values.
-
-/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
-function findMatchingParen(input: string, openIndex: number): number {
-  let depth = 0;
-  for (let i = openIndex; i < input.length; i++) {
-    const char = input[i];
-    if (char === '(') {
-      depth++;
-    } else if (char === ')') {
-      depth--;
-      if (depth === 0) {
-        return i;
-      }
-    }
-  }
-  return -1;
-}
+// non-CSS consumers (canvas, SVG, data-viz) need the concrete value. The same
+// resolution replays in JS: tokenReferences.ts follows `var()` references
+// through the resolved token map (guarding against cycles), and these helpers
+// evaluate the CSS color functions used by the theme generator against those
+// values.
 
 /** Split a color-mix component into its color and optional percentage. */
 function parseMixComponent(
@@ -290,93 +234,6 @@ function evaluateColorFunctions(expr: string): string {
   );
 }
 
-/**
- * Substitute `var(--name[, fallback])` references with their resolved values.
- * `seen` tracks the reference chain so cycles resolve to the literal reference
- * instead of recursing forever.
- */
-function substituteVars(
-  expr: string,
-  raw: Record<string, string>,
-  cache: Record<string, string>,
-  seen: Set<string>,
-): string {
-  const start = expr.indexOf('var(');
-  if (start === -1) {
-    return expr;
-  }
-  const openIndex = start + 'var'.length;
-  const closeIndex = findMatchingParen(expr, openIndex);
-  if (closeIndex === -1) {
-    return expr;
-  }
-
-  const inner = expr.slice(openIndex + 1, closeIndex);
-  const commaSplit = splitTopLevelComma(inner);
-  const name = (commaSplit ? commaSplit[0] : inner).trim();
-  const fallback = commaSplit ? commaSplit[1] : null;
-
-  let replacement: string;
-  if (seen.has(name)) {
-    replacement = expr.slice(start, closeIndex + 1);
-  } else if (name in raw) {
-    seen.add(name);
-    replacement = resolveReference(name, raw, cache, seen);
-    seen.delete(name);
-  } else if (fallback !== null) {
-    replacement = substituteVars(fallback.trim(), raw, cache, seen);
-  } else {
-    replacement = expr.slice(start, closeIndex + 1);
-  }
-
-  const rest = substituteVars(expr.slice(closeIndex + 1), raw, cache, seen);
-  return expr.slice(0, start) + replacement + rest;
-}
-
-/** Fully resolve a single expression: substitute references, then evaluate colors. */
-function resolveExpression(
-  expr: string,
-  raw: Record<string, string>,
-  cache: Record<string, string>,
-  seen: Set<string>,
-): string {
-  if (!expr.includes('var(') && !expr.includes('color-mix(')) {
-    return expr;
-  }
-  const substituted = substituteVars(expr, raw, cache, seen);
-  return evaluateColorFunctions(substituted);
-}
-
-/** Resolve one token by name, memoizing the result in `cache`. */
-function resolveReference(
-  name: string,
-  raw: Record<string, string>,
-  cache: Record<string, string>,
-  seen: Set<string>,
-): string {
-  if (name in cache) {
-    return cache[name];
-  }
-  const value = raw[name];
-  if (value === undefined) {
-    return '';
-  }
-  const resolved = resolveExpression(value, raw, cache, seen);
-  cache[name] = resolved;
-  return resolved;
-}
-
-/** Resolve every reference/color function in a raw token map to concrete values. */
-function resolveReferences(
-  raw: Record<string, string>,
-): Record<string, string> {
-  const cache: Record<string, string> = {};
-  for (const name of Object.keys(raw)) {
-    resolveReference(name, raw, cache, new Set<string>());
-  }
-  return cache;
-}
-
 /**
  * Resolve all Astryx token values for a theme and effective color mode.
  *
@@ -403,7 +260,7 @@ export function resolveThemeTokens(
   }
 
   if (theme == null) {
-    return resolveReferences(resolved);
+    return resolveTokenReferences(resolved, evaluateColorFunctions);
   }
 
   // A theme's local tokens resolve its references to them, then leave the
@@ -436,9 +293,9 @@ export function resolveThemeTokens(
   }
 
   return Object.fromEntries(
-    Object.entries(resolveReferences(resolved)).filter(
-      ([key]) => !localKeys.has(key),
-    ),
+    Object.entries(
+      resolveTokenReferences(resolved, evaluateColorFunctions),
+    ).filter(([key]) => !localKeys.has(key)),
   );
 }
 

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/focusOutline.stylex.ts

@@ -160,6 +160,34 @@ export const focusOutlineStyles = stylex.create({
       ':has(> :first-child:focus-visible)': FOCUS_OUTLINE_OFFSET,
     },
   },
+  /**
+   * Like {@link focusOutlineStyles.focusWithin}, but only for a direct child
+   * with `role="combobox"` — for a control box that paints the ring for its
+   * combobox trigger while sibling controls inside it (a status info-tip, a
+   * clear button) ring themselves. One focus move, one ring
+   * (architecture:interaction-modality INV3).
+   */
+  focusWithinCombobox: {
+    outlineWidth: {
+      default: '0',
+      ':has(> [role="combobox"]:focus-visible)':
+        focusOutlineLonghands.outlineWidth,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':has(> [role="combobox"]:focus-visible)':
+        focusOutlineLonghands.outlineStyle,
+    },
+    outlineColor: {
+      default: null,
+      ':has(> [role="combobox"]:focus-visible)':
+        focusOutlineLonghands.outlineColor,
+    },
+    outlineOffset: {
+      default: '0',
+      ':has(> [role="combobox"]:focus-visible)': FOCUS_OUTLINE_OFFSET,
+    },
+  },
   /**
    * Draws no ring, and keeps the UA's own off — for an element whose ring an
    * ancestor paints.

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,31 @@ 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 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.
  */
 export function focusForLastInput(
   element: HTMLElement,
   options?: FocusOptions,
+  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.
+  // 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.ts

@@ -0,0 +1,38 @@
+// 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 {isRenderable} from './isRenderable';
+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 (!isRenderable(node)) {
+    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.ts

@@ -5,8 +5,13 @@
 /**
  * @file interactionModality.ts
  * @input Global pointerdown/keydown events
- * @output `useInteractionModalityTracking()` activates document-lifetime tracking;
- *   `getInteractionModality()` reads how the user last interacted
+ * @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
  *
@@ -26,17 +31,31 @@
  * 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. 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';
 
 type InteractionModalityStore = {
   modality: InteractionModality;
   isListening: boolean;
+  /** Mounted consumers holding a second document's listeners. */
+  consumers?: number;
   onPointerDown: () => void;
   onKeyDown: (event: KeyboardEvent) => void;
 };
@@ -78,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,
@@ -95,20 +119,173 @@ 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 {
+/**
+ * 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. The page's own document keeps its document-lifetime listeners.
+ */
+function trackInteractionModalityIn(targetDocument: Document): () => void {
+  if (typeof document !== 'undefined' && targetDocument === document) {
+    return trackInteractionModality();
+  }
+  const store = getStore(targetDocument);
+  store.consumers = (store.consumers ?? 0) + 1;
+  setListening(targetDocument, store, true);
+  let isReleased = false;
+  return () => {
+    if (isReleased) {
+      return;
+    }
+    isReleased = true;
+    store.consumers = (store.consumers ?? 1) - 1;
+    if (store.consumers === 0) {
+      setListening(targetDocument, store, false);
+    }
+  };
+}
+
+/** 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};
 }
 
-/** How the user last interacted with the page. */
-export function getInteractionModality(): InteractionModality {
+/**
+ * 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(
+  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;
+  }
   return typeof document === 'undefined'
     ? 'keyboard'
     : getStore(document).modality;
@@ -124,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/interactionOverlay.stylex.ts

@@ -116,8 +116,14 @@ export const pressConsts = stylex.defineConsts({
   releaseMs: 200,
 });
 
-/** The release's clock as CSS. */
-const PRESS_RELEASE_DURATION = `${pressConsts.releaseMs}ms`;
+/**
+ * The release's clock as CSS, scaled by the theme's `--_astryx-motion-tempo`
+ * (`spec:AST-108` FR4, `component:Button` FR15) up to 1.5, its maximum. The
+ * controller's timer reads the same property.
+ */
+const PRESS_RELEASE_DURATION = `calc(${pressConsts.releaseMs}ms * min(var(--_astryx-motion-tempo, 1), 1.5))`;
+/** The same clock under Reduce Motion: a tempo may shorten it, never lengthen it. */
+const PRESS_RELEASE_DURATION_REDUCED = `min(${pressConsts.releaseMs}ms, calc(${pressConsts.releaseMs}ms * var(--_astryx-motion-tempo, 1)))`;
 
 const ENABLED = ':where(:not(:disabled,[aria-disabled="true"]))';
 const HOVER_HOVER = '@media (hover: hover)';
@@ -205,7 +211,10 @@ const pressReleaseAnimation = {
   },
   animationDuration: {
     default: null,
-    '[data-astryx-press="fading"]': PRESS_RELEASE_DURATION,
+    '[data-astryx-press="fading"]': {
+      default: PRESS_RELEASE_DURATION,
+      '@media (prefers-reduced-motion: reduce)': PRESS_RELEASE_DURATION_REDUCED,
+    },
   },
   animationTimingFunction: {
     default: null,