@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/utils/hitArea.ts

@@ -15,18 +15,16 @@
  *   a standalone control writes `watchHitArea`'s insets to an invisible
  *   coarse-only hit layer
  *
- * A finger needs a 44 × 44 px target, but a control may not grow on a phone,
- * and its hit area must never take a neighbour's taps. Each side grows toward
- * the minimum size and stops at half the gap to the nearest neighbour on that
- * side (0 when they touch), so two neighbours' areas meet in the middle and a
- * tap always goes to the nearer target. CSS cannot see where the neighbours
- * are, so a live control measures: only where the primary pointer is coarse,
- * only while on screen, and every control pending a measurement in one read
- * pass per frame (all reads, then all writes), up to a 4 ms budget, the rest
- * carried to the next frame. Until the first pass the
- * insets are 0, so first paint and server rendering never overlap anything.
  */
 
+// A finger needs a 44 × 44 px target, but a control may not grow on a phone,
+// and its hit area must never take a neighbor's taps. Each side grows toward
+// the minimum and stops at half the gap to the nearest neighbor on that side,
+// so a tap always goes to the nearer target. CSS cannot see the neighbors, so a
+// live control measures: only under a coarse primary pointer (AST-094), only on
+// screen, and in one read pass per frame within a 4 ms budget. Until the first
+// pass the insets are 0, so first paint never overlaps anything.
+
 import {observeContent} from './sharedMutationObserver';
 
 /** A rect in client pixels. */
@@ -459,10 +457,9 @@ function scheduleAll(): void {
  * neighbour, and the next tap uses the fresh insets.
  */
 function onPress(event: Event): void {
-  // One listener for every watched control, on the document: a control, a
-  // row or a handle carries none of its own (a list's listeners stay the
-  // list's, spec:AST-103 FR5). The innermost watched element the press
-  // lands in is the one it is for.
+  // One listener on the document for every watched control, so a control, row
+  // or handle has none of its own (AST-103 FR5). The innermost watched element
+  // that the press lands in is the one it is for.
   for (
     let node: Element | null =
       event.target instanceof Element ? event.target : null;
@@ -579,9 +576,9 @@ function observe(element: Element, entry: Watched): void {
 }
 
 /**
- * Everything that watches the page for hit areas: on only while the primary
- * pointer is coarse, so a mouse page runs no observer, timer or listener for
- * them (`spec:AST-094` FR24).
+ * Everything that watches the page for hit areas is on only while the
+ * primary pointer is coarse, so a mouse page runs no observer, timer or
+ * listener for them.
  */
 function startObserving(): void {
   if (view == null) {

package/src/utils/ime.ts

@@ -2,60 +2,32 @@
 
 /**
  * @file ime.ts
- * @input Receives a keyboard event (React SyntheticEvent's `nativeEvent`, or a
- *   native DOM KeyboardEvent) with optional `isComposing` / `keyCode`.
- * @output Exports `isImeKeyEvent`, the canonical predicate for "this keydown is
- *   part of an in-progress IME composition and must not be treated as a command".
- * @position Shared low-level utility; consumed by every editable/overlay surface
- *   that handles Enter/Escape/arrows in `onKeyDown` (Typeahead, PowerSearch,
- *   Dialog, ContextMenu, Tooltip, Chat composer, focus-trap Escape, ...).
- *
- * ── Why this exists (read once, here — do not re-explain at call sites) ──
- *
- * When a CJK user (Korean / Japanese / Chinese) is composing text via an IME,
- * the browser fires a `keydown` event to COMMIT or CANCEL the pending
- * composition (Enter commits the highlighted candidate; Escape cancels it;
- * ArrowUp/Down/Home/End navigate the candidate window). Crucially this
- * `keydown` fires BEFORE the `compositionend` event that actually writes the
- * committed text into the field. So a naive `onKeyDown` handler sees a bare
- * "Enter" or "Escape" and misreads the composition-commit/cancel as an
- * application command — accepting a typeahead suggestion, submitting a chat
- * message, closing a dialog/menu/tooltip, or saving a filter — mid-composition.
- * The fix is to detect the composing keydown and early-return before running
- * any command logic.
- *
- * Two signals, both needed:
- *
- *  1. `event.isComposing === true` — the modern, spec'd signal
- *     (https://www.w3.org/TR/uievents/#dom-keyboardevent-iscomposing). This is
- *     the primary check and is reliable in current evergreen browsers.
- *
- *  2. `event.keyCode === 229` — the legacy fallback. `229` is the sentinel
- *     keyCode browsers report for "the key event is being processed by an IME".
- *     It is still load-bearing: some IMEs and older Safari fire the composing
- *     `keydown` with `isComposing` NOT yet set to `true`, but DO report
- *     keyCode 229. Keeping both makes the guard robust across the browser
- *     matrix we support. Do not drop the 229 fallback without a browser-matrix
- *     audit.
- *
- * ── Which event object to pass ──
- *
- * React's SyntheticEvent for KeyboardEvent *does* surface `isComposing`, but to
- * avoid any cross-browser normalization gap prefer passing the *native* event
- * (`e.nativeEvent`) from React handlers — that is what BaseTypeahead,
- * PowerSearch, and the Chat composer do. Native DOM listeners (Dialog,
- * ContextMenu, Tooltip, focus-trap) pass the DOM `KeyboardEvent` directly.
- * The parameter is intentionally structurally typed so both shapes are accepted.
- *
- * Note: `keyCode` is deprecated on the DOM `KeyboardEvent` type but is still
- * present at runtime; we read it defensively via the optional structural field.
+ * @input A keyboard event (a React event's `nativeEvent`, or a native DOM
+ *   KeyboardEvent) with optional `isComposing` and `keyCode`
+ * @output `isImeKeyEvent`: whether a keydown is part of an IME composition and
+ *   must not act as a command
+ * @position Shared low-level utility for every surface that handles Enter,
+ *   Escape or arrows in `onKeyDown`
  */
 
+// During IME composition (Korean, Japanese, Chinese), the browser fires a
+// keydown to commit or cancel the composition before `compositionend`. A
+// plain handler sees Enter or Escape and runs a command mid-composition. So
+// return early on a composing keydown. Do not explain this again at call
+// sites.
+//
+// Both signals are needed. `isComposing` is the standard signal. keyCode 229
+// is the legacy fallback: some IMEs and older Safari send the composing
+// keydown with `isComposing` not yet true, but with keyCode 229. Do not drop
+// it without a browser-matrix audit.
+//
+// Prefer the native event (`e.nativeEvent`) from React handlers. The
+// parameter is structurally typed, so both event shapes work. `keyCode` is
+// deprecated in the DOM types but is still present at runtime.
+
 /**
- * The sentinel `keyCode` browsers report while a key event is being processed
- * by an IME (the composing keydown that fires before `compositionend`). See the
- * file header for why this legacy signal is still load-bearing alongside
- * `isComposing`.
+ * The sentinel `keyCode` that browsers report while an IME processes a key
+ * event. See the note above for why this legacy signal stays.
  */
 const IME_PROCESSING_KEY_CODE = 229;
 

package/src/utils/inputPresentation.ts

@@ -4,16 +4,16 @@
  * @file inputPresentation.ts
  * @input A presentation policy, the deprecated nativePicker value, and pointer type
  * @output The resolved picker surface for DateInput, DateTimeInput, and TimeInput
- * @position Shared presentation vocabulary owned by spec:AST-043
+ * @position Shared presentation vocabulary (AST-043)
  *
  * SYNC: When modified, update these files to stay in sync:
- * - /docs/specs/AST-043-input-presentation/spec.md (FR1–FR3 tables)
+ * - /docs/specs/AST-043-input-presentation/spec.md
  * - /packages/core/src/DateInput/DateInput.tsx
  * - /packages/core/src/DateTimeInput/DateTimeInput.tsx
  * - /packages/core/src/TimeInput/TimeInput.tsx
  */
 
-/** Picker-surface policy for date/time inputs (`spec:AST-043` FR1). */
+/** Picker-surface policy for date/time inputs. */
 export type InputPresentation =
   | 'text-input'
   | 'popover'
@@ -22,7 +22,7 @@ export type InputPresentation =
   | 'adaptive-bottom-sheet'
   | 'adaptive-native';
 
-/** `presentation` for components without a text-only surface: all except `TimeInput` exclude `text-input` (AST-043). */
+/** `presentation` for components without a text-only surface: all except `TimeInput` exclude `text-input`. */
 export type PickerPresentation = Exclude<InputPresentation, 'text-input'>;
 
 /** The surface a resolved `InputPresentation` actually renders. */
@@ -35,7 +35,7 @@ export type PickerPresentationSurface = Exclude<
   'text-input'
 >;
 
-/** Deprecated picker policy (`spec:AST-043` FR3). */
+/** Deprecated picker policy. */
 export type LegacyNativePicker = 'touch' | 'always' | 'never';
 
 /**

package/src/utils/inputStream.ts

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file inputStream.ts
+ * @input A window, and subscribers to its input events (the press feedback
+ *   controller, the gesture host)
+ * @output subscribeInput
+ * @position The one entry for document-wide input listeners in core: one
+ *   native listener per event type on the window's capture phase, shared by
+ *   every subscriber
+ *
+ * SYNC: When modified, update inputStream.test.ts.
+ */
+
+// The window's capture phase runs before document listeners, so an app's
+// `stopPropagation` there does not hide input from press feedback or the
+// gesture host. A claiming recognizer still needs the touch to reach its
+// element. A passivity switch or a new first subscriber adds a type's
+// listener again. App window-capture listeners added meanwhile then run
+// before it. Document events and element
+// `scroll` reach the window's capture phase too, and so does an element's
+// `blur` or `focus`. A subscriber for the window's own event checks
+// `event.target`.
+//
+// Subscribers run in subscription order. One that throws is reported, and
+// the rest still run.
+//
+// A type's native listener is passive, so it blocks no scroll. It is
+// non-passive only while a subscriber that cancels the event
+// (`{cancels: true}`) is subscribed. With no subscriber left, it is removed.
+
+type InputListener = (event: Event) => void;
+
+interface Subscriber {
+  readonly listener: InputListener;
+  readonly cancels: boolean;
+}
+
+interface Channel {
+  readonly subscribers: Subscriber[];
+  /** The registered native listener and whether it may cancel. */
+  native: {readonly listener: InputListener; readonly cancels: boolean} | null;
+}
+
+/** Options for {@link subscribeInput}. */
+export interface InputSubscriptionOptions {
+  /**
+   * The subscriber calls `preventDefault()` on this event type, so the
+   * native listener must not be passive while it is subscribed.
+   * @default false
+   */
+  readonly cancels?: boolean;
+}
+
+/** The events a window's capture phase sees: its own, and the document's. */
+export type InputEventMap = WindowEventMap & DocumentEventMap;
+
+const streams = new WeakMap<Window, Map<string, Channel>>();
+
+/**
+ * Listen to `type` on `view`'s capture phase through its shared native
+ * listener. Returns the unsubscribe; calling it again does nothing.
+ */
+export function subscribeInput<K extends keyof InputEventMap>(
+  view: Window,
+  type: K,
+  listener: (event: InputEventMap[K]) => void,
+  {cancels = false}: InputSubscriptionOptions = {},
+): () => void {
+  let channels = streams.get(view);
+  if (channels == null) {
+    channels = new Map();
+    streams.set(view, channels);
+  }
+  let channel = channels.get(type);
+  if (channel == null) {
+    channel = {subscribers: [], native: null};
+    channels.set(type, channel);
+  }
+  const subscriber: Subscriber = {
+    listener: listener as InputListener,
+    cancels,
+  };
+  channel.subscribers.push(subscriber);
+  register(view, type, channel);
+  let isSubscribed = true;
+  return () => {
+    if (!isSubscribed) {
+      return;
+    }
+    isSubscribed = false;
+    const current = streams.get(view)?.get(type);
+    if (current == null) {
+      return;
+    }
+    const index = current.subscribers.indexOf(subscriber);
+    if (index !== -1) {
+      current.subscribers.splice(index, 1);
+    }
+    register(view, type, current);
+    if (current.subscribers.length === 0) {
+      streams.get(view)?.delete(type);
+    }
+  };
+}
+
+/**
+ * Bring the channel's native listener in line with its subscribers: none
+ * without subscribers, non-passive while one of them cancels.
+ */
+function register(view: Window, type: string, channel: Channel): void {
+  const wanted =
+    channel.subscribers.length === 0
+      ? null
+      : channel.subscribers.some(subscriber => subscriber.cancels);
+  const native = channel.native;
+  if (native != null && native.cancels === wanted) {
+    return;
+  }
+  if (native != null) {
+    view.removeEventListener(type, native.listener, {capture: true});
+    channel.native = null;
+  }
+  if (wanted == null) {
+    return;
+  }
+  const listener: InputListener = event => dispatch(channel, event);
+  view.addEventListener(type, listener, {capture: true, passive: !wanted});
+  channel.native = {listener, cancels: wanted};
+}
+
+function dispatch(channel: Channel, event: Event): void {
+  // A subscriber may subscribe or unsubscribe while the event runs; the
+  // event goes to those subscribed when it arrived.
+  for (const subscriber of [...channel.subscribers]) {
+    if (!channel.subscribers.includes(subscriber)) {
+      continue;
+    }
+    try {
+      subscriber.listener(event);
+    } catch (error) {
+      report(error);
+    }
+  }
+}
+
+function report(error: unknown): void {
+  if (typeof globalThis.reportError === 'function') {
+    globalThis.reportError(error);
+    return;
+  }
+  queueMicrotask(() => {
+    throw error;
+  });
+}

package/src/utils/interactionModality.ts

@@ -5,38 +5,33 @@
 /**
  * @file interactionModality.ts
  * @input Global pointerdown/keydown events
- * @output `useInteractionModalityTracking()` activates document-lifetime tracking;
- *   `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
- *
- * `:focus-visible` is the right selector for a focus ring and should stay the
- * condition that draws one. It is not, on its own, "focused by keyboard":
- * per CSS Selectors 4 a pointer-focused element that supports text entry
- * matches it too, deliberately, so that a clicked text field still shows where
- * typing will go. Measured in Chromium — a bare `<input>` clicked with a mouse
- * matches `:focus-visible`.
- *
- * A component that wants a ring for keyboard focus ONLY therefore needs one bit
- * `:focus-visible` cannot give it: which device moved focus. This records that,
- * to be used as a gate ALONGSIDE `:focus-visible`, never as a replacement for
- * it — the browser's heuristic still decides everything else, including
- * `focus({focusVisible: true})`.
- *
- * 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. 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.
+ * @output useInteractionModalityTracking, useInteractionModalityTrackingFor,
+ *   and getInteractionModality, which reads how the user last interacted in a
+ *   document
+ * @position Internal document-wide singleton; used where `:focus-visible`
+ *   alone is too broad
  */
 
-import {useEffect} from 'react';
+// `:focus-visible` stays the condition that draws a focus ring. But it also
+// matches a text field that a pointer focused, so a clicked field shows where
+// typing goes. A ring for keyboard focus only needs to know which device
+// moved focus. Use this as a gate beside `:focus-visible`, never in its
+// place.
+//
+// The store lives on `document`, so duplicate Astryx bundles share one state
+// and one listener pair. The page's listeners stay for the document lifetime,
+// so input between consumers is not lost. A second document (a same-origin
+// iframe, a Document Picture-in-Picture window) gets its own store while a
+// consumer there is mounted. Importing this module has no DOM side effects,
+// and server rendering keeps the keyboard-safe default.
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  type RefCallback,
+  type RefObject,
+} from 'react';
 
 export type InteractionModality = 'keyboard' | 'pointer';
 
@@ -86,15 +81,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,
@@ -103,45 +103,42 @@ 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 {
-  useEffect(() => trackInteractionModality(), []);
-}
-
 /**
  * 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.
+ * removes it. The page's own document keeps its document-lifetime listeners.
  */
-export function trackInteractionModalityIn(
-  targetDocument: Document,
-): () => void {
+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,
-    });
-  }
+  setListening(targetDocument, store, true);
   let isReleased = false;
   return () => {
     if (isReleased) {
@@ -150,21 +147,126 @@ export function trackInteractionModalityIn(
     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,
-      });
+      setListening(targetDocument, store, false);
     }
   };
 }
 
-/** How the user last interacted with the page, or with `targetDocument`. */
+/** 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.
+   */
+  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};
+}
+
+/**
+ * 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, so a detached, replaced or moved
+ * node releases the old document before the new one is held.
+ */
+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(
-  targetDocument?: Document,
+  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;
   }
@@ -183,3 +285,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;