@astryxdesign/core 0.7.8 → 0.7.9-canary.0a64fdb

package/src/utils/inputStream.ts

@@ -4,7 +4,8 @@
  * @file inputStream.ts
  * @input A window, and subscribers to its input events (the press feedback
  *   controller, the gesture host)
- * @output subscribeInput
+ * @output subscribeInput, and getLastPointerType: the type of the latest
+ *   pointer event the stream delivered
  * @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
@@ -22,18 +23,21 @@
 // `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.
+// Subscribers run in subscription order, after the ones subscribed `first`.
+// A first subscriber that returns `true` ends the dispatch: no later
+// subscriber hears the event. 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;
+type InputListener = (event: Event) => unknown;
 
 interface Subscriber {
   readonly listener: InputListener;
   readonly cancels: boolean;
+  readonly isFirst: boolean;
 }
 
 interface Channel {
@@ -50,12 +54,30 @@ export interface InputSubscriptionOptions {
    * @default false
    */
   readonly cancels?: boolean;
+  /**
+   * The subscriber runs before every subscriber that is not first. When it
+   * returns `true`, no later subscriber hears the event.
+   * @default false
+   */
+  readonly first?: 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>>();
+/** The type of the latest pointer event each window's stream delivered. */
+const lastPointerTypes = new WeakMap<Window, string>();
+
+/**
+ * The type of the latest pointer event `view`'s stream delivered: `mouse`,
+ * `pen` or `touch`, or `null` before any. The stream hears a pointer event
+ * type only while a subscriber listens to it, as press feedback does on any
+ * page with a pressable. Reading it adds no listener.
+ */
+export function getLastPointerType(view: Window): string | null {
+  return lastPointerTypes.get(view) ?? null;
+}
 
 /**
  * Listen to `type` on `view`'s capture phase through its shared native
@@ -64,8 +86,8 @@ const streams = new WeakMap<Window, Map<string, Channel>>();
 export function subscribeInput<K extends keyof InputEventMap>(
   view: Window,
   type: K,
-  listener: (event: InputEventMap[K]) => void,
-  {cancels = false}: InputSubscriptionOptions = {},
+  listener: (event: InputEventMap[K]) => unknown,
+  {cancels = false, first = false}: InputSubscriptionOptions = {},
 ): () => void {
   let channels = streams.get(view);
   if (channels == null) {
@@ -80,8 +102,16 @@ export function subscribeInput<K extends keyof InputEventMap>(
   const subscriber: Subscriber = {
     listener: listener as InputListener,
     cancels,
+    isFirst: first,
   };
-  channel.subscribers.push(subscriber);
+  const firstLater = first
+    ? channel.subscribers.findIndex(other => !other.isFirst)
+    : -1;
+  if (firstLater === -1) {
+    channel.subscribers.push(subscriber);
+  } else {
+    channel.subscribers.splice(firstLater, 0, subscriber);
+  }
   register(view, type, channel);
   let isSubscribed = true;
   return () => {
@@ -124,12 +154,17 @@ function register(view: Window, type: string, channel: Channel): void {
   if (wanted == null) {
     return;
   }
-  const listener: InputListener = event => dispatch(channel, event);
+  const listener: InputListener = event => dispatch(view, channel, event);
   view.addEventListener(type, listener, {capture: true, passive: !wanted});
   channel.native = {listener, cancels: wanted};
 }
 
-function dispatch(channel: Channel, event: Event): void {
+function dispatch(view: Window, channel: Channel, event: Event): void {
+  // Recorded before any subscriber runs, so each reads the pointer at hand.
+  const {pointerType} = event as Partial<PointerEvent>;
+  if (typeof pointerType === 'string' && pointerType !== '') {
+    lastPointerTypes.set(view, pointerType);
+  }
   // 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]) {
@@ -137,7 +172,9 @@ function dispatch(channel: Channel, event: Event): void {
       continue;
     }
     try {
-      subscriber.listener(event);
+      if (subscriber.listener(event) === true && subscriber.isFirst) {
+        return;
+      }
     } catch (error) {
       report(error);
     }

package/src/utils/interactionOverlay.stylex.ts

@@ -9,7 +9,8 @@
  * @input StyleX and the semantic interaction-overlay color tokens
  * @output Reusable background-color and background-image state styles, the
  *   touch press's registered strength variable (`pressVars`) and its clocks
- *   (`pressConsts`)
+ *   (`pressConsts`). The list row's compositor press layer and its clocks
+ *   are internal (privateAttributes/press.stylex.ts, utils/rowPressLayer.stylex.ts)
  * @position Internal styling utility for interactive core surfaces
  *
  * SYNC: When modified, update pressFeedback.ts, pressGesture.ts (the fade
@@ -148,7 +149,11 @@ const pressRelease = stylex.keyframes({
  * (strength ≈ 0.2 at the midpoint), which is what a deselect crossfade reads
  * as. Not the system's `--ease-standard`: that curve is for things that move,
  * and is so front-loaded (strength 0.05 at the midpoint) that the release
- * would read as half its clock.
+ * would read as half its clock. It is the constants table's
+ * `timing.press.highlightOutCurve`, which the list row's layer mirrors too
+ * (rowPressLayer.stylex.ts); interactionOverlay.cell.test.ts fails if either
+ * drifts. A copy, not an import: this module reaches nearly every component,
+ * and the row layer's constants stay with the rows.
  */
 const RELEASE_EASE = 'cubic-bezier(0, 0, 0.2, 1)';
 

package/src/utils/pressFeedback.ts

@@ -3,10 +3,10 @@
 /**
  * @file pressFeedback.ts
  * @input The press state machine (pressGesture.ts), the menu-press and
- *   press-group markers and the document's pointer, keyboard, scroll and
+ *   press-group markers, the scroll-view test (scrollView.ts) and the document's pointer, keyboard, scroll and
  *   visibility events
  * @output PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps,
- *   pressFadeMs and installPressFeedback
+ *   pressFadeMs, installPressFeedback and cancelPress
  * @position The DOM half of the touch press model. usePressFeedback installs
  *   it, and the CSS arms live in interactionOverlay.stylex.ts.
  *
@@ -23,9 +23,13 @@
 // Where the primary pointer is fine, the controller ignores the mouse and the
 // keyboard, and CSS `:active` keeps their press. Under a coarse primary
 // pointer the CSS drops `:active`, so the controller paints every press. A
-// finger's press paints after the delay. A mouse, trackpad or Space press
-// paints at once. The controller reads the same query as the stylesheet, so
-// they agree.
+// mouse, trackpad or Space press paints at once. The controller reads the
+// same query as the stylesheet, so they agree.
+//
+// A finger waits only inside a scroller. Outside one, a surface highlights in
+// the frame the finger lands, as a UIControl does. Inside one, it waits the
+// content-touch delay, because the touch can become a scroll. Rows follow the
+// same rule.
 //
 // A surface's hold does nothing, so it keeps the browser's long-press text
 // selection (AST-094). Only an element whose hold does something suppresses
@@ -44,6 +48,7 @@ import {
 } from './pressGesture';
 import {isCoarsePointer, watchCoarsePointer} from './coarsePointer';
 import {subscribeInput} from './inputStream';
+import {isInsideScrollView} from './scrollView';
 import {TOUCH_QUERY} from './touchPresentation';
 import {holdsPressThroughDrag} from '../privateAttributes/pressHoldsDrag.stylex';
 import {isTrackedByGroup} from '../privateAttributes/pressGroupItem.stylex';
@@ -247,7 +252,11 @@ function paintElement(element: HTMLElement, paint: PressPaint): void {
     element.removeAttribute(PRESSED_ATTRIBUTE);
     return;
   }
-  element.setAttribute(PRESSED_ATTRIBUTE, paint);
+  // A step that keeps the paint writes nothing, so the element sees one
+  // change per paint.
+  if (element.getAttribute(PRESSED_ATTRIBUTE) !== paint) {
+    element.setAttribute(PRESSED_ATTRIBUTE, paint);
+  }
 }
 
 function clearTimer(slot: Slot): void {
@@ -381,6 +390,21 @@ function finish(slot: Slot): void {
   }
 }
 
+/**
+ * Ends the press the controller follows on `element`, and its paint, at once.
+ * A clickable container calls it when a press starts on an interactive
+ * element inside it: that press does not activate the container, so the
+ * container shows no press.
+ */
+export function cancelPress(element: Element): void {
+  if (finger.live?.element === element) {
+    finish(finger);
+  }
+  if (button.live?.element === element) {
+    finish(button);
+  }
+}
+
 /** A new press on an element owns its paint: the other slot's gesture there ends. */
 function takeOver(other: Slot, element: HTMLElement): void {
   if (other.live?.element === element) {
@@ -521,6 +545,7 @@ function onPointerDown(event: PointerEvent): void {
       kind: 'down',
       x: event.clientX,
       y: event.clientY,
+      delayed: isInsideScrollView(element),
     }),
   );
 }

package/src/utils/pressGesture.ts

@@ -21,6 +21,10 @@
 // primary pointer, so a mouse, trackpad or Space press on such a device comes
 // here as `buttonDown`: painted at once and faded on release.
 //
+// Only a finger inside a scroller waits. The controller tells the machine
+// which touch waits (`down`'s `delayed`), and a touch that does not wait goes
+// straight to `pressed`. After that the machine is the same.
+//
 // The constants were measured against native apps. The machine knows nothing
 // of the DOM, so {@link pressGestureStep}'s cases are the state diagram.
 
@@ -105,7 +109,17 @@ export interface PressGesture {
 }
 
 export type PressEvent =
-  | {kind: 'down'; x: number; y: number}
+  | {
+      kind: 'down';
+      x: number;
+      y: number;
+      /**
+       * Whether this touch waits {@link PRESS_ONSET_MS} before it paints:
+       * a surface inside a scroller. Defaults to
+       * `true`.
+       */
+      delayed?: boolean;
+    }
   /**
    * A mouse button or the Space key went down on the surface. The
    * controller sends this only where the stylesheet has dropped `:active`
@@ -167,6 +181,15 @@ export function pressGestureStep(
   event: PressEvent,
 ): PressStep {
   if (event.kind === 'down') {
+    // A surface with no scroller above it: nothing can turn this touch into a
+    // scroll, so it paints in the frame it lands, as a UIControl highlights.
+    if (event.delayed === false) {
+      return {
+        gesture: {originX: event.x, originY: event.y, phase: 'pressed'},
+        paint: 'on',
+        timer: null,
+      };
+    }
     // A new touch always starts armed and painting nothing, whatever the last
     // gesture ended as. This is the only way out of `dead`.
     return {

package/src/utils/rowPressLayer.stylex.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rowPressLayer.stylex.ts
+ * @input StyleX
+ * @output The list row press layer's clocks (`cellPressConsts`)
+ * @position Internal to core: no package entry exports it. Only the row
+ *   layer (privateAttributes/press.stylex.ts) reads it, so a component
+ *   without a press row ships none of it; interactionOverlay.exports.test.ts
+ *   keeps it off the published paths.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * A list row's release (`rowPressLayerStyles.cell`), mirrored for the
+ * stylesheet. StyleX evaluates a style at build time and cannot read the
+ * constants table, so these are the table's press release values
+ * (`timing.press`, motion/uikit/timing.ts). interactionOverlay.cell.test.ts
+ * fails if they drift.
+ */
+export const cellPressConsts = stylex.defineConsts({
+  /** `timing.press.highlightOutMs`, in ms. */
+  cellReleaseMs: 200,
+  /** `timing.press.highlightOutCurve`, as CSS. */
+  cellReleaseEase: 'cubic-bezier(0, 0, 0.2, 1)',
+});

package/src/utils/scrollView.ts

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollView.ts
+ * @input An element and its computed styles
+ * @output Exports parseTouchAction, rootOverflow, SCROLLABLE_OVERFLOW and
+ *   isInsideScrollView: whether a touch on the element lands inside a box the
+ *   browser can scroll
+ * @position The one definition of "inside a scroll view", shared by the
+ *   press feedback controller (utils/pressFeedback.ts) and the gesture
+ *   core's native-scroll probe (gestures/nativeScroll.ts), so Core's main
+ *   entry can ask it without the gesture core
+ */
+
+import {parentAcrossShadow} from './flatTree';
+
+/** Overflow values that let a box scroll. */
+export const SCROLLABLE_OVERFLOW: ReadonlySet<string> = new Set([
+  'auto',
+  'scroll',
+  'overlay',
+]);
+
+/** How far a box must overflow, in px, before it counts as scrolling. */
+const OVERFLOW_TOLERANCE_PX = 1;
+
+export interface AllowedPans {
+  readonly x: boolean;
+  readonly y: boolean;
+}
+
+/** Which pans a `touch-action` value lets the browser perform. */
+export function parseTouchAction(value: string): AllowedPans {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.includes('auto') || tokens.includes('manipulation')) {
+    return {x: true, y: true};
+  }
+  if (tokens.includes('none')) {
+    return {x: false, y: false};
+  }
+  return {
+    x: tokens.some(
+      token =>
+        token === 'pan-x' || token === 'pan-left' || token === 'pan-right',
+    ),
+    y: tokens.some(
+      token => token === 'pan-y' || token === 'pan-up' || token === 'pan-down',
+    ),
+  };
+}
+
+/**
+ * The viewport's overflow on an axis. It scrolls unless the root or the body
+ * clips it, as a scroll lock does with `overflow: hidden`.
+ */
+export function rootOverflow(doc: Document, axis: 'x' | 'y'): string {
+  const view = doc.defaultView;
+  if (view == null) {
+    return 'hidden';
+  }
+  for (const element of [doc.documentElement, doc.body]) {
+    if (element == null) {
+      continue;
+    }
+    const style = view.getComputedStyle(element);
+    const value = axis === 'x' ? style.overflowX : style.overflowY;
+    if (value === 'hidden' || value === 'clip') {
+      return 'hidden';
+    }
+  }
+  return 'auto';
+}
+
+function overflows(element: Element, axis: 'x' | 'y'): boolean {
+  return axis === 'y'
+    ? element.scrollHeight - element.clientHeight > OVERFLOW_TOLERANCE_PX
+    : element.scrollWidth - element.clientWidth > OVERFLOW_TOLERANCE_PX;
+}
+
+/**
+ * Whether a touch on `element` lands inside a scroll view, UIKit's question
+ * for a touch: a box above it, the page included, overflows on an axis it
+ * scrolls, and `touch-action` on the way up leaves that axis to the browser.
+ * A `position: fixed` box ends the walk, because it does not move with any
+ * scroller above it. A wheel scrolls whatever `touch-action` says, so a
+ * wheel's question passes `readsTouchAction: false`.
+ */
+export function isInsideScrollView(
+  element: Element,
+  {readsTouchAction = true}: {readsTouchAction?: boolean} = {},
+): boolean {
+  const doc = element.ownerDocument;
+  const view = doc.defaultView;
+  if (view == null) {
+    return false;
+  }
+  const root = doc.scrollingElement ?? doc.documentElement;
+  let panX = true;
+  let panY = true;
+  for (let node: Node | null = element; node != null;) {
+    if (node instanceof Element) {
+      const style = view.getComputedStyle(node);
+      if (readsTouchAction) {
+        const pans = parseTouchAction(style.touchAction || 'auto');
+        panX &&= pans.x;
+        panY &&= pans.y;
+      }
+      if (node === root || node === doc.documentElement) {
+        break;
+      }
+      if (
+        (panY &&
+          SCROLLABLE_OVERFLOW.has(style.overflowY) &&
+          overflows(node, 'y')) ||
+        (panX &&
+          SCROLLABLE_OVERFLOW.has(style.overflowX) &&
+          overflows(node, 'x'))
+      ) {
+        return true;
+      }
+      if (style.position === 'fixed') {
+        return false;
+      }
+    }
+    node = parentAcrossShadow(node);
+  }
+  return (
+    (panY &&
+      SCROLLABLE_OVERFLOW.has(rootOverflow(doc, 'y')) &&
+      overflows(root, 'y')) ||
+    (panX &&
+      SCROLLABLE_OVERFLOW.has(rootOverflow(doc, 'x')) &&
+      overflows(root, 'x'))
+  );
+}

package/src/utils/selectionLock.ts

@@ -28,7 +28,11 @@
 //
 // A mouse never takes the lock, so its released behavior stays (AST-017).
 
-import {containsAlongFlatTree, parentAcrossShadow} from './flatTree';
+import {
+  containsAlongFlatTree,
+  deepActiveElement,
+  parentAcrossShadow,
+} from './flatTree';
 import {subscribeInput} from './inputStream';
 import {isIosWebKit} from './touchQueries';
 
@@ -616,15 +620,6 @@ function openShadowRootsOf(target: EventTarget | null): ShadowRoot[] {
   return roots;
 }
 
-/** The focused element, inside open shadow roots too. */
-function deepActiveElement(doc: Document | null): Element | null {
-  let active = doc?.activeElement ?? null;
-  while (active?.shadowRoot?.activeElement != null) {
-    active = active.shadowRoot.activeElement;
-  }
-  return active;
-}
-
 /**
  * The selection-lock styles on `set`, refcounted per element; idempotent
  * release.

package/src/utils/touchHitArea.stylex.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchHitArea.stylex.ts
+ * @input Uses StyleX and the insets that utils/hitArea.ts writes on a host
+ * @output Exports `touchHitAreaStyles.layer`, a host's invisible hit band
+ *   under a coarse pointer
+ * @position Internal styling utility for CheckboxInput and RadioListItem
+ *
+ * The band is the host's `::after`, grown past each edge by the measured
+ * inset. A clip path cuts out the host's box, so its content keeps its taps.
+ * A tap on the band lands on the host. SYNC: hitArea.ts HIT_INSET_PROPERTIES.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+// StyleX reads these at build time, so they are spelled out.
+const TOUCH = '@media (pointer: coarse)';
+// The insets are measured in the viewport, so the sides are physical.
+const TOP = 'var(--astryx-hit-inset-top, 0px)';
+const RIGHT = 'var(--astryx-hit-inset-right, 0px)';
+const BOTTOM = 'var(--astryx-hit-inset-bottom, 0px)';
+const LEFT = 'var(--astryx-hit-inset-left, 0px)';
+
+export const touchHitAreaStyles = stylex.create({
+  layer: {
+    '::after': {
+      content: {default: null, [TOUCH]: '""'},
+      position: {default: null, [TOUCH]: 'absolute'},
+      inset: {
+        default: null,
+        [TOUCH]: `calc(${TOP} * -1) calc(${RIGHT} * -1) calc(${BOTTOM} * -1) calc(${LEFT} * -1)`,
+      },
+      // The outer rectangle, then the host's box as an even-odd hole.
+      clipPath: {
+        default: null,
+        [TOUCH]: `polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, ${LEFT} ${TOP}, calc(100% - ${RIGHT}) ${TOP}, calc(100% - ${RIGHT}) calc(100% - ${BOTTOM}), ${LEFT} calc(100% - ${BOTTOM}), ${LEFT} ${TOP})`,
+      },
+    },
+  },
+});

package/src/utils/triggerFocus.ts

@@ -37,6 +37,22 @@ export function isFocusableTrigger(element: HTMLElement): boolean {
 export function isFocusForTrigger(
   event: Event,
   mode: TriggerFocusMode,
+): boolean {
+  return isFocusOnTrigger(
+    event.target,
+    event.currentTarget as HTMLElement | null,
+    mode,
+  );
+}
+
+/**
+ * `isFocusForTrigger` for focus already on `target`, inside `trigger`: the
+ * same rule, read when a trigger attaches with focus inside it.
+ */
+export function isFocusOnTrigger(
+  target: EventTarget | null,
+  trigger: HTMLElement | null,
+  mode: TriggerFocusMode,
 ): boolean {
   if (mode === 'always') {
     return true;
@@ -44,10 +60,7 @@ export function isFocusForTrigger(
   if (mode === 'never') {
     return false;
   }
-  const trigger = event.currentTarget as HTMLElement | null;
-  return (
-    trigger != null && (event.target === trigger || isFocusableTrigger(trigger))
-  );
+  return trigger != null && (target === trigger || isFocusableTrigger(trigger));
 }
 
 /** Remembers whether a trigger's current focus counted when it arrived. */