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

package/src/utils/pressFeedback.test.ts

@@ -12,6 +12,10 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
+import {TEMPO_RANGE, expandThemeMotion} from '../theme/themeMotion';
+import {readFileSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import {
   durationToMs,
@@ -317,6 +321,122 @@ describe('the release', () => {
     expect(rows[0].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
   });
 
+  it('scales the fade by the tempo its stylesheet reads, a theme\u2019s or an adaptation rule\u2019s (spec:AST-108 FR4, component:Button FR15)', () => {
+    // A rule writes the tempo (a media-query adaptation, say); browsers
+    // inherit it from the theme, jsdom only reads it where it is declared.
+    const style = document.createElement('style');
+    style.textContent = '.slow-row { --_astryx-motion-tempo: 1.5; }';
+    document.head.appendChild(style);
+    rows[0].classList.add('slow-row');
+    try {
+      press(rows[0], 'pointerdown', 10, 10);
+      vi.advanceTimersByTime(PRESS_ONSET_MS);
+      press(rows[0], 'pointerup', 10, 10);
+      vi.advanceTimersByTime(PRESS_FADE_MS);
+      expect(rows[0].getAttribute(PRESSED_ATTRIBUTE)).toBe('fading');
+      vi.advanceTimersByTime(PRESS_FADE_MS / 2);
+      expect(rows[0].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
+    } finally {
+      style.remove();
+    }
+  });
+
+  it('under Reduce Motion a tempo may shorten the fade but never lengthens it past 200 ms (spec:AST-108 FR4)', () => {
+    vi.stubGlobal(
+      'matchMedia',
+      (query: string): MediaQueryList =>
+        ({
+          matches: /prefers-reduced-motion:\s*reduce/.test(query),
+          media: query,
+          onchange: null,
+          addListener: () => undefined,
+          removeListener: () => undefined,
+          addEventListener: () => undefined,
+          removeEventListener: () => undefined,
+          dispatchEvent: () => false,
+        }) as MediaQueryList,
+    );
+    const style = document.createElement('style');
+    style.textContent =
+      '.slow-row { --_astryx-motion-tempo: 1.5; } .quick-row { --_astryx-motion-tempo: 0.75; }';
+    document.head.appendChild(style);
+    try {
+      rows[0].classList.add('slow-row');
+      press(rows[0], 'pointerdown', 10, 10);
+      vi.advanceTimersByTime(PRESS_ONSET_MS);
+      press(rows[0], 'pointerup', 10, 10);
+      vi.advanceTimersByTime(PRESS_FADE_MS);
+      expect(rows[0].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
+      rows[0].classList.replace('slow-row', 'quick-row');
+      press(rows[0], 'pointerdown', 10, 10);
+      vi.advanceTimersByTime(PRESS_ONSET_MS);
+      press(rows[0], 'pointerup', 10, 10);
+      vi.advanceTimersByTime(PRESS_FADE_MS * 0.75);
+      expect(rows[0].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
+    } finally {
+      rows[0].classList.remove('slow-row', 'quick-row');
+      style.remove();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('bounds the release’s tempo at its own maximum, so the bound changes nothing', () => {
+    // The clock's 1.5 is TEMPO_RANGE.max, and every tempo a theme writes is
+    // clamped to it: a theme asking for 3 writes 1.5.
+    const source = readFileSync(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        'interactionOverlay.stylex.ts',
+      ),
+      'utf8',
+    );
+    expect(source).toContain(
+      `min(var(--_astryx-motion-tempo, 1), ${TEMPO_RANGE.max})`,
+    );
+    expect(expandThemeMotion({tempo: 3})['--_astryx-motion-tempo']).toBe(
+      String(TEMPO_RANGE.max),
+    );
+  });
+
+  it('caps the stylesheet’s release fade under Reduce Motion', () => {
+    const source = readFileSync(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        'interactionOverlay.stylex.ts',
+      ),
+      'utf8',
+    );
+    expect(source).toMatch(
+      /min\(\$\{pressConsts\.releaseMs\}ms, calc\(\$\{pressConsts\.releaseMs\}ms \* var\(--_astryx-motion-tempo, 1\)\)\)/,
+    );
+    expect(source).toMatch(
+      /'@media \(prefers-reduced-motion: reduce\)': PRESS_RELEASE_DURATION_REDUCED/,
+    );
+  });
+
+  it('keeps the 200 ms fade without a tempo', () => {
+    press(rows[0], 'pointerdown', 10, 10);
+    vi.advanceTimersByTime(PRESS_ONSET_MS);
+    press(rows[0], 'pointerup', 10, 10);
+    vi.advanceTimersByTime(PRESS_FADE_MS);
+    expect(rows[0].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
+  });
+
+  it('times the stylesheet’s release fade by the same tempo', () => {
+    // The animation the attribute drives, scaled by the custom property a
+    // theme with a tempo writes beside its duration tokens.
+    const source = readFileSync(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        'interactionOverlay.stylex.ts',
+      ),
+      'utf8',
+    );
+    expect(source).toMatch(
+      /calc\(\$\{pressConsts\.releaseMs\}ms \* min\(var\(--_astryx-motion-tempo, 1\),/,
+    );
+  });
+
   it('answers a tap too quick for the delay, at the release', () => {
     press(rows[0], 'pointerdown', 10, 10);
     vi.advanceTimersByTime(20);
@@ -418,6 +538,24 @@ describe('a phone or tablet paints a mouse or Space press itself', () => {
     expect(rows[1].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
   });
 
+  it('fades a mouse press by the theme\u2019s tempo too (spec:AST-108 FR4, component:Button FR15)', () => {
+    const style = document.createElement('style');
+    style.textContent = '.slow-row { --_astryx-motion-tempo: 1.5; }';
+    document.head.appendChild(style);
+    rows[1].classList.add('slow-row');
+    try {
+      press(rows[1], 'pointerdown', 10, 100, 'mouse');
+      press(rows[1], 'pointerup', 10, 100, 'mouse');
+      vi.advanceTimersByTime(PRESS_FADE_MS);
+      expect(rows[1].getAttribute(PRESSED_ATTRIBUTE)).toBe('fading');
+      vi.advanceTimersByTime(PRESS_FADE_MS / 2);
+      expect(rows[1].hasAttribute(PRESSED_ATTRIBUTE)).toBe(false);
+    } finally {
+      rows[1].classList.remove('slow-row');
+      style.remove();
+    }
+  });
+
   it('keeps the paint while the mouse is dragged off the surface, as `:active` does', () => {
     press(rows[1], 'pointerdown', 10, 100, 'mouse');
     press(document.body, 'pointermove', 400, 900, 'mouse');

package/src/utils/pressFeedback.ts

@@ -156,6 +156,24 @@ const TIMER_MS: Record<NonNullable<PressStep['timer']>, number> = {
   onset: PRESS_ONSET_MS,
 };
 
+/**
+ * The release fade's clock on `element`, read once, at the release, from the
+ * property its stylesheet reads: the theme's `--_astryx-motion-tempo`
+ * (`spec:AST-108` FR4, `component:Button` FR15). Under Reduce Motion a tempo
+ * may shorten the fade, never lengthen it past 200 ms.
+ */
+function fadeMs(element: Element): number {
+  const style = getComputedStyle(element);
+  const value = style.getPropertyValue('--_astryx-motion-tempo').trim();
+  const read = value === '' ? Number.NaN : Number(value);
+  const tempo = Number.isFinite(read) && read > 0 ? read : 1;
+  const scaled = PRESS_FADE_MS * tempo;
+  const reduced =
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  return reduced ? Math.min(scaled, PRESS_FADE_MS) : scaled;
+}
+
 const TIMER_EVENT = {
   fade: 'fadeEnd',
   flash: 'flashEnd',
@@ -217,17 +235,22 @@ function apply(slot: Slot, step: PressStep): void {
     // A TIMER, never `requestAnimationFrame`: iOS throttles frame callbacks
     // while a scroll runs, so a frame-based delay would fire late, after the
     // scroll, and paint a control nobody is pressing any more.
-    live.timer = setTimeout(() => {
-      if (slot.live != null) {
-        slot.live.timer = null;
-      }
-      apply(
-        slot,
-        pressGestureStep(slot.live?.gesture ?? idlePressGesture(), {
-          kind: TIMER_EVENT[kind],
-        }),
-      );
-    }, TIMER_MS[kind]);
+    live.timer = setTimeout(
+      () => {
+        if (slot.live != null) {
+          slot.live.timer = null;
+        }
+        apply(
+          slot,
+          pressGestureStep(slot.live?.gesture ?? idlePressGesture(), {
+            kind: TIMER_EVENT[kind],
+          }),
+        );
+      },
+      // The release fade follows the theme's tempo (`spec:AST-108` FR4,
+      // `component:Button` FR15); the onset delay and the tap flash do not.
+      kind === 'fade' ? fadeMs(live.element) : TIMER_MS[kind],
+    );
   }
 }
 

package/src/utils/pressGesture.test.ts

@@ -14,6 +14,7 @@
  */
 
 import {describe, expect, it} from 'vitest';
+import {UIKIT_GESTURES} from '../motion/uikit/gestures';
 import type {PressEvent, PressGesture, PressPaint} from './pressGesture';
 import {
   idlePressGesture,
@@ -54,6 +55,14 @@ describe('the clocks are the native ones', () => {
     expect(PRESS_FADE_MS).toBe(200);
     expect(PRESS_FLASH_MS).toBe(100);
   });
+
+  it("are the UIKit table's measured values, one definition each", () => {
+    // The machine keeps its own constants, so a pressable page loads no
+    // motion table; the table's entries stay the one definition.
+    expect(PRESS_ONSET_MS).toBe(UIKIT_GESTURES.press.contentTouchDelay.value);
+    expect(PRESS_FLASH_MS).toBe(UIKIT_GESTURES.press.quickTapFlash.value);
+    expect(PRESS_SLOP_PX).toBe(UIKIT_GESTURES.press.slop.value);
+  });
 });
 
 describe('nothing paints until the press is believed', () => {

package/src/utils/pressPaintPriority.test.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pressPaintPriority.test.ts
+ * @input Uses vitest, Babel with the StyleX plugin (the repository's shared
+ *   module resolution) and interactionOverlay.stylex.ts
+ * @output Checks, in the compiled CSS, that the press paint outranks the
+ *   coarse-pointer `:active` reset of the overlay
+ * @position Regression test for the cascade order of the press overlay
+ *
+ * WebKit applies `:active` during a touch. Under a coarse pointer the overlay
+ * turns the bare `:active` image off, and the press paint
+ * (`[data-astryx-press="on"]`) must still win: its rule has to sit in a
+ * higher StyleX priority than the reset. The order is a property of how
+ * each key is spelled: an imported `defineConsts` key compiles to a higher
+ * priority than the same literal, which put the reset above the paint and
+ * erased the touch-down frame.
+ */
+
+import fs from 'node:fs';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import stylexResolution from '../../../../scripts/stylex-module-resolution.cjs';
+
+type Rule = [string, {ltr: string}, number];
+
+// Babel's types are not part of core's typecheck; type the one call used.
+const {transformSync} = createRequire(import.meta.url)('@babel/core') as {
+  transformSync: (
+    code: string,
+    options: Record<string, unknown>,
+  ) => {metadata?: unknown} | null;
+};
+
+function compiledRules(file: string): Rule[] {
+  const output = transformSync(fs.readFileSync(file, 'utf8'), {
+    filename: file,
+    babelrc: false,
+    configFile: false,
+    parserOpts: {plugins: ['typescript', 'jsx']},
+    plugins: [
+      [
+        '@stylexjs/babel-plugin',
+        {
+          dev: false,
+          runtimeInjection: false,
+          genConditionalClasses: true,
+          treeshakeCompensation: true,
+          unstable_moduleResolution: stylexResolution.stylexModuleResolution,
+        },
+      ],
+    ],
+  });
+  return (output?.metadata as {stylex?: Rule[]}).stylex ?? [];
+}
+
+describe('press overlay cascade', () => {
+  it('ranks the press paint above the coarse-pointer :active reset', () => {
+    const rules = compiledRules(
+      path.resolve(__dirname, 'interactionOverlay.stylex.ts'),
+    );
+    const resets = rules.filter(
+      // Matched without its condition's text: an imported key compiles to a
+      // placeholder until the bundle step.
+      ([, {ltr}]) =>
+        ltr.includes(':active') && ltr.includes('background-image:none'),
+    );
+    const paints = rules.filter(
+      ([, {ltr}]) =>
+        ltr.includes('[data-astryx-press="on"]') &&
+        ltr.includes('background-image:'),
+    );
+    expect(resets.length).toBeGreaterThan(0);
+    expect(paints.length).toBeGreaterThan(0);
+    const highestReset = Math.max(...resets.map(([, , priority]) => priority));
+    const lowestPaint = Math.min(...paints.map(([, , priority]) => priority));
+    expect(highestReset).toBeLessThan(lowestPaint);
+  });
+});

package/src/utils/primaryClick.test.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file primaryClick.test.ts
+ * @input isPrimaryClick over button presses on Apple and other platforms
+ * @output Tests that only the main button, and not a ctrl-click on macOS,
+ *   is a primary click (spec:AST-094 FR43)
+ * @position Unit tests of packages/core/src/utils/primaryClick.ts
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {isPrimaryClick} from './primaryClick';
+
+function onPlatform(platform: string) {
+  vi.spyOn(navigator, 'platform', 'get').mockReturnValue(platform);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('isPrimaryClick (spec:AST-094 FR43)', () => {
+  it('takes the main button, and no right click or pen barrel button', () => {
+    onPlatform('Win32');
+    expect(isPrimaryClick({button: 0, ctrlKey: false})).toBe(true);
+    expect(isPrimaryClick({button: 2, ctrlKey: false})).toBe(false);
+    expect(isPrimaryClick({button: 1, ctrlKey: false})).toBe(false);
+  });
+
+  it("takes no ctrl-click on macOS, that platform's context click, and a ctrl-click elsewhere", () => {
+    onPlatform('MacIntel');
+    expect(isPrimaryClick({button: 0, ctrlKey: true})).toBe(false);
+    expect(isPrimaryClick({button: 0, ctrlKey: false})).toBe(true);
+    vi.restoreAllMocks();
+    onPlatform('Win32');
+    expect(isPrimaryClick({button: 0, ctrlKey: true})).toBe(true);
+  });
+});

package/src/utils/primaryClick.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file primaryClick.ts
+ * @input A mouse or pen button press: its `button` and `ctrlKey`
+ * @output Exports isPrimaryClick
+ * @position Internal util, the one primary-click rule: the gesture host
+ *   starts a press only for one, and the press controller paints only one;
+ *   platform detection is utils/isApplePlatform.ts
+ *
+ * Deliberately absent from utils/index.ts: packages/core/src/index.ts does
+ * `export * from './utils'`, so naming it there would publish it as API.
+ */
+
+import {isApplePlatform} from './isApplePlatform';
+
+/**
+ * Whether a button press is a primary click: the main button, and not a
+ * ctrl-click on macOS or iPadOS, which is that platform's context click
+ * (`spec:AST-094` FR43). A right click, a pen's barrel button and a macOS
+ * ctrl-click start no press.
+ */
+export function isPrimaryClick(event: {
+  readonly button: number;
+  readonly ctrlKey: boolean;
+}): boolean {
+  return event.button === 0 && !(event.ctrlKey && isApplePlatform());
+}

package/src/utils/sharedMutationObserver.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, vi} from 'vitest';
-import {observeContent} from './sharedMutationObserver';
+import {observeContent, observeMutations} from './sharedMutationObserver';
 
 const flush = async () => new Promise(resolve => setTimeout(resolve, 0));
 
@@ -51,3 +51,56 @@ describe('observeContent', () => {
     unsubscribeLive();
   });
 });
+
+describe('observeMutations', () => {
+  it('shares one observer across registrations with the same options', async () => {
+    const Native = globalThis.MutationObserver;
+    let constructed = 0;
+    vi.stubGlobal(
+      'MutationObserver',
+      class extends Native {
+        constructor(callback: MutationCallback) {
+          super(callback);
+          constructed += 1;
+        }
+      },
+    );
+    const options = {attributes: true, attributeFilter: ['dir']};
+    const first = document.createElement('div');
+    const second = document.createElement('div');
+    const firstCallback = vi.fn();
+    const secondCallback = vi.fn();
+    const stops = [
+      observeMutations(first, options, firstCallback),
+      observeMutations(second, {...options}, secondCallback),
+    ];
+
+    first.dir = 'rtl';
+    await flush();
+
+    expect(constructed).toBe(1);
+    expect(firstCallback).toHaveBeenCalledTimes(1);
+    expect(secondCallback).not.toHaveBeenCalled();
+    stops.forEach(stop => stop());
+    vi.unstubAllGlobals();
+  });
+
+  it('reports a descendant only to a subtree registration', async () => {
+    const outer = document.createElement('div');
+    const inner = document.createElement('span');
+    outer.append(inner);
+    const self = vi.fn();
+    const subtree = vi.fn();
+    const stops = [
+      observeMutations(outer, {attributes: true}, self),
+      observeMutations(outer, {attributes: true, subtree: true}, subtree),
+    ];
+
+    inner.className = 'changed';
+    await flush();
+
+    expect(self).not.toHaveBeenCalled();
+    expect(subtree).toHaveBeenCalledTimes(1);
+    stops.forEach(stop => stop());
+  });
+});

package/src/utils/sharedMutationObserver.ts

@@ -5,58 +5,105 @@
 /**
  * @file sharedMutationObserver.ts
  * @input MutationObserver API
- * @output Exports observeContent for shared content-change observation
- * @position Internal utility; consumed by useTruncation. The content-change
- *   counterpart of sharedResizeObserver: one observer for every element, so a
- *   repeated cell or row path does not create one observer per instance.
+ * @output Exports observeMutations (one shared observer per set of options)
+ *   and observeContent, its text-and-children form
+ * @position Internal utility; consumed by useTruncation, hitArea and AppShell's
+ *   main-overflow observer. The mutation counterpart of sharedResizeObserver:
+ *   one observer for every element observed with the same options, so a
+ *   repeated cell, row or region does not create one observer per instance.
  */
 
-type ContentCallback = () => void;
+type MutationCallback = () => void;
 
-const OPTIONS: MutationObserverInit = {
+const CONTENT_OPTIONS: MutationObserverInit = {
   characterData: true,
   childList: true,
   subtree: true,
 };
 
-let observer: MutationObserver | null = null;
-const callbacks = new Map<Node, Set<ContentCallback>>();
+interface SharedObserver {
+  readonly observer: MutationObserver;
+  readonly callbacks: Map<Node, Set<MutationCallback>>;
+}
+
+/**
+ * One observer per distinct set of options: an observer holds one set of
+ * options per node, so registrations that need different options cannot
+ * share one.
+ */
+const observers = new Map<string, SharedObserver>();
+
+function optionsKey(options: MutationObserverInit): string {
+  return JSON.stringify([
+    options.attributes === true,
+    options.attributeFilter == null
+      ? null
+      : [...options.attributeFilter].sort(),
+    options.characterData === true,
+    options.childList === true,
+    options.subtree === true,
+  ]);
+}
 
-function dispatch(records: MutationRecord[]): void {
-  // One call per callback per batch, however many records it received. A
-  // record's target can be any descendant, so walk up to the observed roots.
-  const pending = new Set<ContentCallback>();
-  for (const record of records) {
-    for (let node: Node | null = record.target; node; node = node.parentNode) {
-      callbacks.get(node)?.forEach(callback => pending.add(callback));
+function createSharedObserver(options: MutationObserverInit): SharedObserver {
+  const callbacks = new Map<Node, Set<MutationCallback>>();
+  const isSubtree = options.subtree === true;
+  const observer = new MutationObserver(records => {
+    // One call per callback per batch, however many records it received.
+    // With `subtree`, a record's target can be any descendant, so walk up to
+    // the observed roots; without it, the target is the observed node.
+    const pending = new Set<MutationCallback>();
+    for (const record of records) {
+      if (!isSubtree) {
+        callbacks
+          .get(record.target)
+          ?.forEach(callback => pending.add(callback));
+        continue;
+      }
+      for (
+        let node: Node | null = record.target;
+        node;
+        node = node.parentNode
+      ) {
+        callbacks.get(node)?.forEach(callback => pending.add(callback));
+      }
     }
-  }
-  pending.forEach(callback => callback());
+    pending.forEach(callback => callback());
+  });
+  return {observer, callbacks};
 }
 
 /**
- * Call `callback` when the element's text or children change (including
- * descendants). Returns an unsubscribe that removes only this registration.
+ * Call `callback` for mutations of `element` matching `options`, through the
+ * one observer shared by every registration with the same options. Returns an
+ * unsubscribe that removes only this registration.
  *
  * MutationObserver has no per-target unobserve, so a released element stays
- * registered with the shared observer until no element remains; its records
- * match no callback and are ignored. The observer disconnects and is released
- * when the last registration goes.
+ * registered with its shared observer until no element remains; its records
+ * match no callback and are ignored. An observer disconnects and is released
+ * when its last registration goes.
  */
-export function observeContent(
-  element: Element,
-  callback: ContentCallback,
+export function observeMutations(
+  element: Node,
+  options: MutationObserverInit,
+  callback: MutationCallback,
 ): () => void {
   if (typeof MutationObserver === 'undefined') {
     return () => {};
   }
-  observer ??= new MutationObserver(dispatch);
+  const key = optionsKey(options);
+  let shared = observers.get(key);
+  if (shared == null) {
+    shared = createSharedObserver(options);
+    observers.set(key, shared);
+  }
+  const {observer, callbacks} = shared;
   const existing = callbacks.get(element);
   if (existing) {
     existing.add(callback);
   } else {
     callbacks.set(element, new Set([callback]));
-    observer.observe(element, OPTIONS);
+    observer.observe(element, options);
   }
 
   let isSubscribed = true;
@@ -70,9 +117,20 @@ export function observeContent(
     if (targetCallbacks?.size === 0) {
       callbacks.delete(element);
     }
-    if (callbacks.size === 0 && observer) {
+    if (callbacks.size === 0 && observers.get(key)?.observer === observer) {
       observer.disconnect();
-      observer = null;
+      observers.delete(key);
     }
   };
 }
+
+/**
+ * Call `callback` when the element's text or children change (including
+ * descendants). Returns an unsubscribe that removes only this registration.
+ */
+export function observeContent(
+  element: Element,
+  callback: MutationCallback,
+): () => void {
+  return observeMutations(element, CONTENT_OPTIONS, callback);
+}