@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

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

@@ -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';
@@ -37,6 +43,8 @@ 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;
 };
@@ -107,8 +115,59 @@ export function useInteractionModalityTracking(): void {
   useEffect(() => trackInteractionModality(), []);
 }
 
-/** How the user last interacted with the page. */
-export 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 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,
+    });
+  }
+  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?: Document,
+): InteractionModality {
+  if (targetDocument != null) {
+    return getStore(targetDocument).modality;
+  }
   return typeof document === 'undefined'
     ? 'keyboard'
     : getStore(document).modality;

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,

package/src/utils/plainDate.ts

@@ -374,10 +374,65 @@ export function plainDateFormat(
   options: Intl.DateTimeFormatOptions,
   locale: Locale = 'en',
 ): string {
-  return new Intl.DateTimeFormat(locale, {
+  const calendar = options.calendar ?? 'gregory';
+  if (options.timeZone != null) {
+    return dateTimeFormatFor(locale, {...options, calendar}).format(
+      plainDateToDate(pd),
+    );
+  }
+  if (TIME_OF_DAY_FIELDS.some(field => options[field] != null)) {
+    // A zone name or a time of day reads local midnight in the zone current
+    // at the call. A cached formatter would keep the zone it was built in,
+    // so this one is built for the call.
+    return new Intl.DateTimeFormat(locale, {...options, calendar}).format(
+      plainDateToDate(pd),
+    );
+  }
+  // Date fields alone: UTC midnight formatted in UTC, so neither the cached
+  // formatter nor the date depends on the host's zone, which can change while
+  // a page is open.
+  return dateTimeFormatFor(locale, {
     ...options,
-    calendar: options.calendar ?? 'gregory',
-  }).format(plainDateToDate(pd));
+    calendar,
+    timeZone: 'UTC',
+  }).format(utcTime(pd.year, pd.month - 1, pd.day));
+}
+
+/** Options that print a time of day or a zone, which a PlainDate lacks. */
+const TIME_OF_DAY_FIELDS = [
+  'timeZoneName',
+  'hour',
+  'minute',
+  'second',
+  'fractionalSecondDigits',
+  'dayPeriod',
+  'timeStyle',
+] as const satisfies ReadonlyArray<keyof Intl.DateTimeFormatOptions>;
+
+/**
+ * One `Intl.DateTimeFormat` per locale and options, built on first use.
+ * Building a formatter costs far more than formatting with it, and a calendar
+ * formats each of a month's 42 day labels with the same options on every
+ * render. The options are keyed in a fixed order, so the same options written
+ * in another order share a formatter.
+ */
+const dateTimeFormats = new Map<string, Intl.DateTimeFormat>();
+
+/** @internal plainDateFormat's formatter cache; not part of the public API. */
+export function dateTimeFormatFor(
+  locale: Locale,
+  options: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+  const key = JSON.stringify([
+    locale,
+    Object.entries(options).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  ]);
+  let format = dateTimeFormats.get(key);
+  if (format == null) {
+    format = new Intl.DateTimeFormat(locale, options);
+    dateTimeFormats.set(key, format);
+  }
+  return format;
 }
 
 /**