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

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

package/src/utils/presentation.ts

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file presentation.ts
+ * @input A component's `presentation` prop (a caller's value, or omitted),
+ *   what the component does when it is omitted, and the touch presentation
+ *   (utils/touchPresentation.ts)
+ * @output usePresentation and readPresentation (and the pure
+ *   resolvePresentation): the surface to render and whether the component's
+ *   touch input modes apply
+ * @position Internal resolver for stable components that, under a finger,
+ *   present a different surface or switch how an open surface follows input
+ *   (architecture:public-component-api INV16)
+ *
+ * A caller's explicit `presentation` always wins over the touch default:
+ *
+ * - `'popover'`: the fine-pointer surface AND input modes, on every device;
+ * - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a
+ *   finger;
+ * - `'adaptive'`: the sheet on a compact touch screen and the popover
+ *   elsewhere, with touch input modes under a finger;
+ * - omitted: the component's default. `whenOmitted: 'popover'` answers as
+ *   `'popover'` (today's components). `whenOmitted: 'touch'` keeps the
+ *   popover surface and turns the component's touch input modes on under a
+ *   finger, as UIMenu tracks a finger in an anchored menu. Making `'touch'`
+ *   a released component's default is a functional default change
+ *   (`spec:AST-017` FR3) whose Changeset names `presentation="popover"`.
+ *
+ * One touch model on every touch device: the modes depend on the pointer,
+ * never on the platform. Touch styling (press paint, the text-size floor)
+ * and touch-only behavior that a component's own record defines (a row
+ * swipe, a slider's thumb) do not read this: they keep the touch
+ * presentation.
+ *
+ * CSS: a style that implements a touch surface or input mode is applied with
+ * `touchModes` (`stylex.props(touchModes && styles.touchMode)`), never as a
+ * bare media key on a base style, so a pinned `'popover'` keeps none of it.
+ * A rule inside it that needs the touch query uses the touch presentation's
+ * touch key; the iOS `@supports` gate is only for the one style iOS WebKit
+ * itself requires (the 16px text-size floor), never for a touch mode. On the
+ * server and while hydrating, `touchModes` is false and `'adaptive'` is the
+ * popover: a touch surface or mode opens only after hydration
+ * (`spec:AST-094` FR13), and no hint changes that. usePresentation listens
+ * only to the queries a request reads (`architecture:react-component-runtime`
+ * INV5): none for a pinned `'popover'`.
+ *
+ * SYNC: When modified, update presentation.test.ts.
+ */
+
+import {useCallback, useMemo, useSyncExternalStore} from 'react';
+import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
+import type {CompactDefinition} from '../theme/themeAdaptations';
+import {
+  readTouchPresentation,
+  TOUCH_QUERY,
+  useCompactDefinition,
+  type TouchPresentation,
+} from './touchPresentation';
+
+/** What a component does when the caller omits `presentation`. */
+export type PresentationDefault = 'popover' | 'touch';
+
+export interface ResolvedPresentation {
+  /** The surface to render. */
+  readonly surface: 'popover' | 'bottom-sheet';
+  /**
+   * The component's touch input modes apply: a finger, and `presentation`
+   * not pinned to `'popover'`.
+   */
+  readonly touchModes: boolean;
+}
+
+export interface PresentationOptions {
+  /** What an omitted `presentation` means. @default 'popover' */
+  readonly whenOmitted?: PresentationDefault;
+}
+
+/**
+ * usePresentation's options. There is no server hint: the server and
+ * hydrating render never present touch modes (`spec:AST-094` FR13).
+ */
+export type UsePresentationOptions = PresentationOptions;
+
+export interface ReadPresentationOptions extends PresentationOptions {
+  /** The window to read; the global one by default. */
+  readonly view?: Window | null;
+  /**
+   * The active theme's compact definition (`useCompactDefinition()`, read
+   * while rendering), so a theme that moves `md` moves the sheet too
+   * (`spec:AST-012` FR9).
+   */
+  readonly compact: CompactDefinition;
+}
+
+/** The decision, from a presentation request and a touch presentation. */
+export function resolvePresentation(
+  presentation: AdaptivePresentation | undefined,
+  touch: TouchPresentation,
+  whenOmitted: PresentationDefault = 'popover',
+): ResolvedPresentation {
+  const request = presentation ?? whenOmitted;
+  const surface =
+    request === 'bottom-sheet' ||
+    (request === 'adaptive' && touch.isTouch && touch.isCompact)
+      ? 'bottom-sheet'
+      : 'popover';
+  const touchModes = request !== 'popover' && touch.isTouch;
+  return {surface, touchModes};
+}
+
+const noSubscription = () => () => {};
+/** The server and hydrating render match no query (`spec:AST-094` FR13). */
+const matchesNothing = () => false;
+
+/**
+ * A media query's match, subscribed only while `query` is given
+ * (`architecture:react-component-runtime` INV5); false on the server and
+ * while hydrating (`spec:AST-094` FR13).
+ */
+function useMatchWhileRead(query: string | null): boolean {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (query == null) {
+        return noSubscription();
+      }
+      const mql = window.matchMedia(query);
+      mql.addEventListener('change', onStoreChange);
+      return () => mql.removeEventListener('change', onStoreChange);
+    },
+    [query],
+  );
+  const getSnapshot = useCallback(
+    () => query != null && window.matchMedia(query).matches,
+    [query],
+  );
+  return useSyncExternalStore(subscribe, getSnapshot, matchesNothing);
+}
+
+/**
+ * The presentation now, following the pointer and the size as they change
+ * (a tablet docking a trackpad). SSR-safe: renders the server default (not
+ * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes
+ * only to what the request reads: a pinned `'popover'` to neither query,
+ * `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and
+ * `'adaptive'` to the pointer and the compact size.
+ */
+export function usePresentation(
+  presentation: AdaptivePresentation | undefined,
+  {whenOmitted = 'popover'}: UsePresentationOptions = {},
+): ResolvedPresentation {
+  const request = presentation ?? whenOmitted;
+  const compact = useCompactDefinition();
+  const isTouch = useMatchWhileRead(request === 'popover' ? null : TOUCH_QUERY);
+  const isCompact = useMatchWhileRead(
+    request === 'adaptive' ? compact.query : null,
+  );
+  return useMemo(
+    () => resolvePresentation(presentation, {isTouch, isCompact}, whenOmitted),
+    [presentation, isTouch, isCompact, whenOmitted],
+  );
+}
+
+/**
+ * The presentation at this moment, for a decision taken once (a menu
+ * deciding how it follows the finger that opened it).
+ */
+export function readPresentation(
+  presentation: AdaptivePresentation | undefined,
+  {whenOmitted = 'popover', view, compact}: ReadPresentationOptions,
+): ResolvedPresentation {
+  const target =
+    view === undefined ? (typeof window === 'undefined' ? null : window) : view;
+  return resolvePresentation(
+    presentation,
+    readTouchPresentation(target, compact),
+    whenOmitted,
+  );
+}

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;
@@ -156,6 +158,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 +237,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/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.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);
+}