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

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();

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.test.ts

@@ -7,6 +7,7 @@ import {
   plainDateFromISO,
   plainDateToISO,
   plainDateToDate,
+  dateTimeFormatFor,
   plainDateFromDate,
   plainDateToday,
   getDaysInMonth,
@@ -28,6 +29,7 @@ import {
   plainDateGetWeekNumber,
   plainDateFormat,
   formatSharedDate,
+  DATE_FORMAT_LONG,
   DATE_FORMAT_WITH_WEEKDAY,
   DATE_FORMAT_MONTH_YEAR,
   plainDateWeekFieldName,
@@ -754,6 +756,94 @@ describe('plainDateGetWeekNumber', () => {
 });
 
 describe('plainDateFormat', () => {
+  it('keeps one formatter per locale and options, whatever order the options are in', () => {
+    // A month of day labels, as a calendar renders them, reuses one formatter.
+    const first = dateTimeFormatFor('en-NZ', DATE_FORMAT_WITH_WEEKDAY);
+    expect(dateTimeFormatFor('en-NZ', DATE_FORMAT_WITH_WEEKDAY)).toBe(first);
+    expect(
+      dateTimeFormatFor('en-NZ', {
+        year: 'numeric',
+        day: 'numeric',
+        month: 'long',
+        weekday: 'long',
+      }),
+    ).toBe(first);
+    // Other options, or another locale, get their own.
+    expect(dateTimeFormatFor('en-NZ', DATE_FORMAT_MONTH_YEAR)).not.toBe(first);
+    expect(dateTimeFormatFor('en-ZA', DATE_FORMAT_WITH_WEEKDAY)).not.toBe(
+      first,
+    );
+  });
+
+  it('formats the same date after the host zone moves', () => {
+    // The page stays open while the device travels east: a formatter cached
+    // in the first zone must not move the date.
+    const zone = process.env.TZ;
+    try {
+      process.env.TZ = 'America/Los_Angeles';
+      expect(
+        plainDateFormat(
+          {year: 2026, month: 2, day: 1},
+          DATE_FORMAT_MONTH_YEAR,
+          'en-IE',
+        ),
+      ).toBe('February 2026');
+      process.env.TZ = 'America/New_York';
+      expect(
+        plainDateFormat(
+          {year: 2026, month: 2, day: 1},
+          DATE_FORMAT_MONTH_YEAR,
+          'en-IE',
+        ),
+      ).toBe('February 2026');
+      process.env.TZ = 'Pacific/Kiritimati';
+      expect(
+        plainDateFormat(
+          {year: 2026, month: 2, day: 1},
+          DATE_FORMAT_WITH_WEEKDAY,
+          'en-IE',
+        ),
+      ).toBe('Sunday 1 February 2026');
+    } finally {
+      if (zone === undefined) {
+        delete process.env.TZ;
+      } else {
+        process.env.TZ = zone;
+      }
+    }
+  });
+
+  it('prints a zone name or a time of day in the host zone, as before', () => {
+    // A PlainDate has neither: such fields read local midnight in the zone
+    // current at the call, not the UTC the date-only path formats in.
+    const zone = process.env.TZ;
+    try {
+      process.env.TZ = 'America/Los_Angeles';
+      const withZone = plainDateFormat(
+        {year: 2026, month: 1, day: 25},
+        {...DATE_FORMAT_LONG, timeZoneName: 'short'},
+        'en-US',
+      );
+      expect(withZone).toContain('January 25, 2026');
+      expect(withZone).toContain('PST');
+      expect(withZone).not.toContain('UTC');
+      process.env.TZ = 'America/New_York';
+      expect(
+        plainDateFormat(
+          {year: 2026, month: 1, day: 25},
+          {...DATE_FORMAT_LONG, timeZoneName: 'short'},
+          'en-US',
+        ),
+      ).toContain('EST');
+    } finally {
+      if (zone === undefined) {
+        delete process.env.TZ;
+      } else {
+        process.env.TZ = zone;
+      }
+    }
+  });
+
   it('returns a human-readable date string with weekday', () => {
     const result = plainDateFormat(
       {year: 2026, month: 1, day: 25},

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;
 }
 
 /**