@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/utils/pressFeedback.js

@@ -2,49 +2,40 @@
 
 /**
  * @file pressFeedback.ts
- * @input The press state machine (pressGesture.ts) and the document's pointer,
- *   keyboard, scroll and visibility events
- * @output Exports PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps and
+ * @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 PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps and
  *   installPressFeedback
- * @position The DOM half of the touch press model: one delegated controller
- *   per document that writes `data-astryx-press` on the nearest pressable surface.
- *   Installed by usePressFeedback (hooks/usePressFeedback.ts) on first mount;
- *   the CSS arms that read the attribute live in interactionOverlay.stylex.ts
- *   and in each component with its own `:active` rule. Tested by
- *   pressFeedback.test.ts.
- *
- * ONE listener set for every pressable surface in the document.
- *
- * Why a delegated document-level controller and not a hook on the element: a
- * virtualized list can carry more than a thousand rows, and four listeners
- * plus a state hook per row is not a cost a list like that can pay. This is
- * a handful of listeners for the whole document, and a press costs one
- * attribute write on one element: no React render, no subscription, no
- * per-element anything. It also makes the behaviour uniform for free: every
- * component that paints a press carries {@link PRESSABLE_ATTRIBUTE}, so all of
- * them change together.
- *
- * Where the primary pointer is fine (a desktop), the controller ignores the
- * mouse and the keyboard: CSS `:active` keeps their press, as it always has,
- * and the mouse path costs nothing. Under a finger the `:active` arm is
- * dropped by the CSS (`@media (pointer: coarse)`) and this writes
- * `data-astryx-press="on"` when the press is believed and
- * `data-astryx-press="fading"` for the release's exit.
- *
- * That query reads the PRIMARY pointer, so on a phone or a tablet the
- * stylesheet drops `:active` for every press, including a mouse or trackpad
- * click and a Space press on a focused button. There, the controller paints
- * those too: at once (no scroller can claim a mouse button or a key, so
- * nothing waits), held while the button or key is down, and faded at the
- * release, the way a finger's press leaves. The query is the stylesheet's
- * own, so the two cannot disagree about which presses are the controller's.
+ * @position The DOM half of the touch press model. usePressFeedback installs
+ *   it, and the CSS arms live in interactionOverlay.stylex.ts.
  *
  * SYNC: When modified, update pressGesture.ts, hooks/usePressFeedback.ts,
  * hooks/usePressFeedback.doc.mjs, utils/interactionOverlay.stylex.ts and
  * pressFeedback.test.ts.
  */
 
+// One delegated controller per document writes `data-astryx-press` on the
+// nearest pressable surface. A virtualized list can have more than a thousand
+// rows, and listeners and state for each row cost too much. A press here
+// costs one attribute write and no React render.
+//
+// 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.
+//
+// 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
+// it, through the gesture host. The `touchcancel` listener is on only while
+// the primary pointer is coarse.
+
+import { MENU_PRESS_MARKER } from "../hooks/menuPressMarker.js";
 import { idlePressGesture, PRESS_FADE_MS, PRESS_FLASH_MS, PRESS_ONSET_MS, PRESS_SCROLL_BRAKE_MS, pressGestureStep } from "./pressGesture.js";
+import { isCoarsePointer, watchCoarsePointer } from "./coarsePointer.js";
+import { subscribeInput } from "./inputStream.js";
 import { TOUCH_QUERY } from "./touchPresentation.js";
 
 /**
@@ -90,11 +81,10 @@ const DISABLED = ':disabled, [aria-disabled="true"]';
 const SPACE_ACTIVATED_INPUT_TYPES = new Set(['button', 'image', 'reset', 'submit']);
 
 /**
- * A menu's own highlight is its only paint (`module:DropdownMenu/useMenuPress`
- * FR6, DEC-6): a press held on one row while the highlight follows the
- * pointer to another would light two rows.
+ * A menu's own highlight is its only paint. 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}]`;
 
 /**
  * One tracking slot. A finger's press runs the whole machine (the delay, the
@@ -134,9 +124,8 @@ const TIMER_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.
+ * property its stylesheet reads: the theme's `--_astryx-motion-tempo`. Under
+ * Reduce Motion a tempo may shorten the fade, never lengthen it past 200 ms.
  */
 function fadeMs(element) {
   const style = getComputedStyle(element);
@@ -169,22 +158,16 @@ function clearTimer(slot) {
 /**
  * Run one event through the machine and make the DOM say what it answered.
  *
- * THE TIMER RULE, and why it is not "clear, then maybe re-arm": a step that
- * returns `timer: null` WITHOUT changing phase is a pass-through, and the
- * phase it left running still owes its transition. Clearing unconditionally
- * strands three gestures, each ending with a paint on a control nobody is
- * touching, until some later touch happens to clean it up:
- *
- *  - a finger that jitters inside the slop during the 150 ms delay (which is
- *    every real finger; only a synthetic touch holds perfectly still) kills
- *    the onset timer, so the press never paints at all;
- *  - a `pointercancel` or a scroll inside a quick tap's 100 ms flash kills
- *    `flashEnd`, leaving `data-astryx-press="on"` painted indefinitely. iOS Safari
- *    delivers that cancel at `scrollend`, seconds after the tap, so it is not
- *    a corner case;
- *  - the same inside the 200 ms fade strands `data-astryx-press="fading"` and the
- *    controller's single tracking slot, holding a reference to an element a
- *    virtualized list may already have unmounted.
+ * A step that returns `timer: null` without a phase change is a
+ * pass-through: the running phase still owes its transition. So do not clear
+ * the timer on every step. That would strand a paint on a control that nobody
+ * touches:
+ * - Finger jitter inside the slop during the onset delay kills the onset
+ *   timer, so the press never paints.
+ * - A `pointercancel` or scroll during a quick tap's flash leaves `on`
+ *   painted. iOS Safari sends that cancel at `scrollend`, seconds later.
+ * - The same during the fade strands `fading` and the tracking slot, which
+ *   holds an element that a virtualized list may have unmounted.
  */
 function apply(slot, step) {
   const live = slot.live;
@@ -214,8 +197,8 @@ function apply(slot, step) {
         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.
+    // The release fade follows the theme's tempo (AST-108). The onset delay
+    // and the tap flash do not.
     kind === 'fade' ? fadeMs(live.element) : TIMER_MS[kind]);
   }
 }
@@ -240,25 +223,14 @@ function surfaceAt(target) {
 }
 
 /**
- * Is this touch a BRAKE on a list the finger set moving, rather than a press?
+ * Is this touch a brake on a list that the finger set moving, not a press?
+ * A native list highlights nothing for a brake. No later signal cancels it,
+ * because the stopped scroll sends no more events.
  *
- * A native list highlights nothing for one, and nothing else would cancel it:
- * stopping the scroll is exactly what makes the scroll events stop arriving,
- * so there is no later signal to react to.
- *
- * Two narrowings, because "a scroll happened recently" is far too broad and
- * would swallow presses nobody asked it to. Apps scroll things by themselves
- * all the time: a transcript pinned to the bottom scrolls on every streamed
- * frame, keyboard navigation calls `scrollIntoView`, a route change restores
- * a position. None of those is a finger braking anything.
- *
- *  1. The scroller must CONTAIN the pressed element. A pane scrolling itself
- *     says nothing about a control elsewhere.
- *  2. The scroll must have been driven by a finger IN THAT SCROLLER, which is
- *     what `onScroll` records. "Any finger anywhere, recently" is not enough:
- *     tap a control, then within the memory window press a button inside a
- *     pane that is scrolling on its own, and that press would be swallowed by
- *     a scroll no finger drove.
+ * Apps often scroll by themselves (a pinned transcript, `scrollIntoView`, a
+ * restored position), so two conditions narrow it:
+ * 1. The scroller contains the pressed element.
+ * 2. A finger in that scroller drove the scroll, as `onScroll` records.
  */
 function scrollerIsBraking(element) {
   if (Date.now() - lastScrollAt >= PRESS_SCROLL_BRAKE_MS) {
@@ -308,9 +280,8 @@ function takeOver(other, element) {
  * so a layout that must not depend on it stays independent.
  */
 function stylesheetDroppedActive() {
-  // The shared touch resolver's key (`spec:AST-012` FR2): the condition the
-  // stylesheet drops `:active` under (`COARSE` in
-  // interactionOverlay.stylex.ts), read once per press.
+  // The shared touch resolver's key (AST-012): the condition under which the
+  // stylesheet drops `:active`, read once per press.
   return typeof window.matchMedia === 'function' && window.matchMedia(TOUCH_QUERY).matches;
 }
 
@@ -384,6 +355,7 @@ function onPointerDown(event) {
     }
     return;
   }
+  armTouchCancel();
   if (finger.live != null) {
     const fingerIsUp = finger.live.gesture.phase === 'fading' || finger.live.gesture.phase === 'flash';
     // A finger still down means a SECOND finger: a pinch or a two-finger
@@ -463,10 +435,9 @@ function onPointerUp(event) {
 /**
  * The scroller claimed the gesture, or the platform took it.
  *
- * `pointercancel` is the primary one: measured on iOS 26.2 it fires before
- * the first `scroll` event (+303 ms against +304 ms on a slow drag, +31 ms
- * against +47 ms on a fling), which is what puts this cancel one frame ahead
- * of the list's motion, the way UIKit's `touchesCancelled` is.
+ * `pointercancel` is the primary signal. On iOS it fires before the first
+ * `scroll` event, so this cancel runs one frame ahead of the list's motion,
+ * as UIKit's `touchesCancelled` does.
  */
 function onCancel(event) {
   // A cancelled mouse pointer ends the mouse's press, not a finger's.
@@ -574,40 +545,74 @@ function onVisibilityChange() {
     finish(button);
   }
 }
-const PASSIVE_CAPTURE = {
-  capture: true,
-  passive: true
-};
-const PASSIVE = {
-  passive: true
-};
+
+/** The input stream subscriptions while installed. */
+let unsubscribers = [];
+
+/** The touch-only `touchcancel` subscription, while the pointer is coarse. */
+let stopTouchCancel = null;
+let stopWatchingPointer = null;
+
+/**
+ * The touch-only listener is on only while the primary pointer is coarse.
+ * Where it is fine, a finger's press still ends through `pointercancel`.
+ */
+function hearTouchCancel(on) {
+  if (on === (stopTouchCancel != null)) {
+    return;
+  }
+  if (on) {
+    stopTouchCancel = subscribeInput(window, 'touchcancel', onCancel);
+  } else {
+    stopTouchCancel?.();
+    stopTouchCancel = null;
+  }
+}
+
+/**
+ * Read the primary pointer when the first finger or pen lands, and follow it
+ * from then on: installing asks nothing, so a page no one touches never
+ * queries it.
+ */
+function armTouchCancel() {
+  if (stopWatchingPointer != null) {
+    return;
+  }
+  stopWatchingPointer = watchCoarsePointer(window, hearTouchCancel);
+  hearTouchCancel(isCoarsePointer(window));
+}
+
+// The pointer, drag, scroll and visibility listeners are passive and on the
+// window's capture phase, through the shared input stream
+// (utils/inputStream.ts): a page of pressables blocks no scroll, and an app's
+// capture-phase stopPropagation at the document cannot starve the controller.
 function addListeners() {
-  window.addEventListener('pointerdown', onPointerDown, PASSIVE_CAPTURE);
-  window.addEventListener('pointermove', onPointerMove, PASSIVE_CAPTURE);
-  window.addEventListener('pointerup', onPointerUp, PASSIVE_CAPTURE);
-  window.addEventListener('pointercancel', onCancel, PASSIVE_CAPTURE);
-  window.addEventListener('touchcancel', onCancel, PASSIVE_CAPTURE);
-  window.addEventListener('dragstart', onDragStart, PASSIVE_CAPTURE);
-  // `scroll` does not bubble, so the capture phase is the only way one
-  // listener hears every scroller in the document.
-  document.addEventListener('scroll', onScroll, PASSIVE_CAPTURE);
-  document.addEventListener('visibilitychange', onVisibilityChange);
-  // Only Space's press needs the key's release and focus loss, so those two
-  // are attached while it is held (holdKey).
+  unsubscribers = [subscribeInput(window, 'pointerdown', onPointerDown), subscribeInput(window, 'pointermove', onPointerMove), subscribeInput(window, 'pointerup', onPointerUp), subscribeInput(window, 'pointercancel', onCancel), subscribeInput(window, 'dragstart', onDragStart),
+  // `scroll` does not bubble; the capture phase hears every scroller.
+  subscribeInput(window, 'scroll', onScroll), subscribeInput(window, 'visibilitychange', onVisibilityChange)];
+  // The key path listens after the page's own handlers, at the window's
+  // bubble phase: a Space press the page cancels (`defaultPrevented`) paints
+  // nothing. Only Space's press needs the key's release and focus loss, so
+  // those two are attached while it is held (holdKey).
   window.addEventListener('keydown', onKeyDown, PASSIVE);
 }
 function removeListeners() {
-  window.removeEventListener('pointerdown', onPointerDown, PASSIVE_CAPTURE);
-  window.removeEventListener('pointermove', onPointerMove, PASSIVE_CAPTURE);
-  window.removeEventListener('pointerup', onPointerUp, PASSIVE_CAPTURE);
-  window.removeEventListener('pointercancel', onCancel, PASSIVE_CAPTURE);
-  window.removeEventListener('touchcancel', onCancel, PASSIVE_CAPTURE);
-  window.removeEventListener('dragstart', onDragStart, PASSIVE_CAPTURE);
-  document.removeEventListener('scroll', onScroll, PASSIVE_CAPTURE);
-  document.removeEventListener('visibilitychange', onVisibilityChange);
+  for (const unsubscribe of unsubscribers.splice(0)) {
+    unsubscribe();
+  }
+  stopWatchingPointer?.();
+  stopWatchingPointer = null;
+  hearTouchCancel(false);
   window.removeEventListener('keydown', onKeyDown);
   holdKey(false);
 }
+const PASSIVE_CAPTURE = {
+  capture: true,
+  passive: true
+};
+const PASSIVE = {
+  passive: true
+};
 
 /** Whether the key-release listeners are attached. */
 let keyHeld = false;

package/dist/utils/pressGesture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pressGesture.d.ts","sourceRoot":"","sources":["../../src/utils/pressGesture.ts"],"names":[],"mappings":"AAsCA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAA8B,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GACpB,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAClB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC;AACtC;;;;GAIG;GACD;IAAC,IAAI,EAAE,YAAY,CAAA;CAAC;AACtB,0EAA0E;GACxE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,GACpC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAC;AACd,4FAA4F;GAC1F;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC;AAClB,iEAAiE;GAC/D;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC;AACjB,yDAAyD;GACvD;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC;AACpB,wDAAwD;GACtD;IAAC,IAAI,EAAE,SAAS,CAAA;CAAC,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CACnD;AAkBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,UAAU,GAChB,SAAS,CA6GX;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAE/C"}
+{"version":3,"file":"pressGesture.d.ts","sourceRoot":"","sources":["../../src/utils/pressGesture.ts"],"names":[],"mappings":"AA4BA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAA8B,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GACpB,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAClB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC;AACtC;;;;GAIG;GACD;IAAC,IAAI,EAAE,YAAY,CAAA;CAAC;AACtB,0EAA0E;GACxE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,GACpC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAC;AACd,4FAA4F;GAC1F;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC;AAClB,iEAAiE;GAC/D;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC;AACjB,yDAAyD;GACvD;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC;AACpB,wDAAwD;GACtD;IAAC,IAAI,EAAE,SAAS,CAAA;CAAC,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CACnD;AAkBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,UAAU,GAChB,SAAS,CA6GX;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAE/C"}

package/dist/utils/pressGesture.js

@@ -9,31 +9,21 @@
  * @position Pure half of the touch press model; driven by pressFeedback.ts,
  *   tested by pressGesture.test.ts without a browser
  *
- * WHAT A FINGER MEANS, AS A STATE MACHINE.
- *
- * A native (UIKit) list delays a press by 0.15 s, cancels it the instant a
- * scroll claims the gesture, never brings it back inside that gesture, and
- * fades it only on release. CSS `:active` on iOS Safari does none of those
- * things: measured on iOS 26.2, it paints within 14 ms of the touch and was
- * still painted 1.6 s into a scroll. So on a coarse pointer the pressed state
- * is owned here, in JavaScript, and `:active` keeps only the mouse.
- *
- * The stylesheet drops `:active` by the PRIMARY pointer, so a mouse, trackpad
- * or Space key on such a device has lost `:active` too. Their presses come
- * here as `buttonDown`: painted at once, held through any travel, faded on
- * release like a finger's.
- *
- * Every constant below was measured against the real Settings and Contacts
- * apps on an iPhone simulator, driven with real HID touches at 60 fps, before
- * it was written down. The machine is deliberately ignorant of the DOM: it
- * takes what happened and answers with what should be painted, so
- * {@link pressGestureStep}'s table of cases IS the state diagram, one arm per
- * requirement.
- *
  * SYNC: When modified, update pressFeedback.ts (the controller) and
  * pressGesture.test.ts.
  */
 
+// A native list delays a press by 0.15 s, cancels it when a scroll claims the
+// gesture, never brings it back in that gesture, and fades it only on
+// release. On iOS Safari, CSS `:active` paints at once and stays painted into
+// a scroll. So on a coarse pointer this machine owns the pressed state, and
+// `:active` keeps only the mouse. The stylesheet drops `:active` by the
+// primary pointer, so a mouse, trackpad or Space press on such a device comes
+// here as `buttonDown`: painted at once and faded on release.
+//
+// The constants were measured against native apps. The machine knows nothing
+// of the DOM, so {@link pressGestureStep}'s cases are the state diagram.
+
 import { pressConsts } from "./interactionOverlay.stylex.js";
 
 /**

package/dist/utils/rtlStyles.d.ts

@@ -5,30 +5,6 @@
  * @position Core utility; applied to directional icons in Calendar, Lightbox,
  *   Pagination, Carousel and the Table expand/disclosure plugins
  *
- * `mirror` flips its element on the horizontal axis only when an ancestor
- * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the
- * vertical axis intact, and applying it OUTSIDE any state-driven rotation lets
- * it compose correctly — e.g. a Table disclosure chevron still rotates to point
- * down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
- * MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
- *
- * `centerInline(blockOffset?)` horizontally centers an absolutely-positioned,
- * auto-width element on the inline axis, correctly in BOTH LTR and RTL, with an
- * optional block-axis (Y) offset composed into the same transform. It
- * intentionally uses PHYSICAL `left: 50%` + `translateX(-50%)`: both reference
- * the same physical edge, so the pair is direction-symmetric and centers
- * identically regardless of `dir`. A logical `insetInlineStart: 50%` would flip
- * the anchor edge in RTL while the physical translate does not, leaving the
- * element off-center by its own width (centered in LTR, broken in RTL). This is
- * the one case where physical `left` is the correct choice, so the
- * `no-physical-properties` suppression lives here ONCE rather than at each call
- * site. The `@astryx/no-physical-properties` lint recognises this exact pattern
- * and points offenders here.
- *
- * `blockOffset` is any CSS length/percentage for translateY (pass `'0px'` for
- * none): e.g. `centerInline('100%')` sits the element one full height below its
- * anchor, `centerInline('-50%')` centers it on both axes.
- *
  * SYNC: When modified, update:
  * - /packages/core/src/utils/index.ts
  */

package/dist/utils/rtlStyles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rtlStyles.d.ts","sourceRoot":"","sources":["../../src/utils/rtlStyles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C,eAAO,MAAM,SAAS;;;;;;;;EASpB,CAAC"}
+{"version":3,"file":"rtlStyles.d.ts","sourceRoot":"","sources":["../../src/utils/rtlStyles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAeH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C,eAAO,MAAM,SAAS;;;;;;;;EASpB,CAAC"}

package/dist/utils/rtlStyles.js

@@ -7,34 +7,23 @@
  * @position Core utility; applied to directional icons in Calendar, Lightbox,
  *   Pagination, Carousel and the Table expand/disclosure plugins
  *
- * `mirror` flips its element on the horizontal axis only when an ancestor
- * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the
- * vertical axis intact, and applying it OUTSIDE any state-driven rotation lets
- * it compose correctly — e.g. a Table disclosure chevron still rotates to point
- * down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
- * MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
- *
- * `centerInline(blockOffset?)` horizontally centers an absolutely-positioned,
- * auto-width element on the inline axis, correctly in BOTH LTR and RTL, with an
- * optional block-axis (Y) offset composed into the same transform. It
- * intentionally uses PHYSICAL `left: 50%` + `translateX(-50%)`: both reference
- * the same physical edge, so the pair is direction-symmetric and centers
- * identically regardless of `dir`. A logical `insetInlineStart: 50%` would flip
- * the anchor edge in RTL while the physical translate does not, leaving the
- * element off-center by its own width (centered in LTR, broken in RTL). This is
- * the one case where physical `left` is the correct choice, so the
- * `no-physical-properties` suppression lives here ONCE rather than at each call
- * site. The `@astryx/no-physical-properties` lint recognises this exact pattern
- * and points offenders here.
- *
- * `blockOffset` is any CSS length/percentage for translateY (pass `'0px'` for
- * none): e.g. `centerInline('100%')` sits the element one full height below its
- * anchor, `centerInline('-50%')` centers it on both axes.
- *
  * SYNC: When modified, update:
  * - /packages/core/src/utils/index.ts
  */
 
+// `mirror` uses `scaleX(-1)`, not `scale(-1, -1)`, so the vertical axis
+// stays. Apply it outside any state-driven rotation, so a disclosure chevron
+// still rotates down under RTL. It matches `:is([dir="rtl"] *)`, so
+// `direction: rtl` alone does not trigger it.
+//
+// `centerInline` uses physical `left: 50%` and `translateX(-50%)` on purpose.
+// Both use the same physical edge, so the element centers in LTR and RTL. A
+// logical `insetInlineStart: 50%` flips the anchor in RTL but the translate
+// does not, so the element is off by its own width. The lint suppression
+// lives here once, and `@astryx/no-physical-properties` points offenders
+// here. `blockOffset` is a translateY length: `'100%'` sits the element one
+// height below its anchor, and `'-50%'` centers it on both axes.
+
 import * as stylex from '@stylexjs/stylex';
 const _temp = {
   kbCHJM: "x1nrll8i",

package/dist/utils/selectionLock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether a contact of this pointer kind takes the lock: a finger or a pen,
+ * under any primary pointer, a laptop's touchscreen and a desktop pen tablet
+ * included, since a pen's hold acts as a finger's.
+ */
+export declare function locksSelectionFor(pointerType: string): boolean;
+/**
+ * Refuse a selection and the touch callout on `elements` (and on a non-text
+ * input target inside one of them) until the returned function runs, while
+ * any holder holds. Idempotent release.
+ */
+export declare function lockSelection(elements: Iterable<Element>, target: EventTarget | null): () => void;
+//# sourceMappingURL=selectionLock.d.ts.map

package/dist/utils/selectionLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectionLock.d.ts","sourceRoot":"","sources":["../../src/utils/selectionLock.ts"],"names":[],"mappings":"AAkDA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9D;AAWD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAC3B,MAAM,EAAE,WAAW,GAAG,IAAI,GACzB,MAAM,IAAI,CAyEZ"}

package/dist/utils/selectionLock.js

@@ -0,0 +1,159 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file selectionLock.ts
+ * @input The elements a held touch contact presses, and the touch's target
+ * @output lockSelection: no text selection and no touch callout under the
+ *   held finger until the release runs; and locksSelectionFor: which contacts
+ *   take it
+ * @position Brought by the recognizers whose hold does something. The gesture
+ *   host calls it and never imports it.
+ *
+ * SYNC: When modified, update GestureHost.ts and utils/pressFeedback.ts; the
+ * iOS query matches utils/touchPresentation.ts.
+ */
+
+// A hold that does something never starts a selection or the callout under
+// the finger (AST-094). A text field keeps its selection, because a held
+// finger places its caret. A style change repaints what it covers, so the
+// way to refuse differs by engine:
+// - iOS WebKit fires no `selectstart` for a long press, so only
+//   `user-select` refuses it. The lock covers every held element, inline and
+//   refcounted. A lock on only the element under the finger let a long press
+//   select a word beside it. WebKit makes every input selectable, so an input
+//   under the finger is locked too.
+// - Elsewhere, cancelling `selectstart` refuses the selection with no style
+//   write, so nothing repaints.
+//
+// A mouse never takes the lock, so its released behavior stays (AST-017).
+
+import { containsAlongFlatTree } from "./flatTree.js";
+import { isIosWebKit } from "./touchQueries.js";
+
+/** What a held finger must not start on a control or a cell. */
+const SELECTION_LOCK = ['-webkit-touch-callout', '-webkit-user-select', 'user-select'];
+
+/** Inputs whose text a held finger edits: it places the caret there. */
+const TEXT_ENTRY_TYPES = new Set(['text', 'search', 'email', 'url', 'tel', 'password', 'number']);
+
+/**
+ * Whether a contact of this pointer kind takes the lock: a finger or a pen,
+ * under any primary pointer, a laptop's touchscreen and a desktop pen tablet
+ * included, since a pen's hold acts as a finger's.
+ */
+export function locksSelectionFor(pointerType) {
+  return pointerType !== 'mouse';
+}
+
+/** Locked elements, how many contacts hold each, and what to restore. */
+const locks = new WeakMap();
+
+/**
+ * Refuse a selection and the touch callout on `elements` (and on a non-text
+ * input target inside one of them) until the returned function runs, while
+ * any holder holds. Idempotent release.
+ */
+export function lockSelection(elements, target) {
+  const set = new Set(elements);
+  if (isSelectableControl(target) && [...set].some(element => containsAlongFlatTree(element, target))) {
+    set.add(target);
+  }
+  if (!isIosWebKit()) {
+    const refuse = event => {
+      if (!isTextEntry(event.target)) {
+        event.preventDefault();
+      }
+    };
+    for (const element of set) {
+      element.addEventListener('selectstart', refuse);
+    }
+    let isRefusing = true;
+    return () => {
+      if (isRefusing) {
+        isRefusing = false;
+        for (const element of set) {
+          element.removeEventListener('selectstart', refuse);
+        }
+      }
+    };
+  }
+  const locked = [];
+  for (const element of set) {
+    const style = styleOf(element);
+    if (style == null) {
+      continue;
+    }
+    locked.push(element);
+    const lock = locks.get(element);
+    if (lock != null) {
+      lock.count += 1;
+      continue;
+    }
+    locks.set(element, {
+      count: 1,
+      saved: SELECTION_LOCK.map(name => ({
+        name,
+        value: style.getPropertyValue(name),
+        priority: style.getPropertyPriority(name)
+      }))
+    });
+    for (const name of SELECTION_LOCK) {
+      style.setProperty(name, 'none');
+    }
+  }
+  let isReleased = false;
+  return () => {
+    if (isReleased) {
+      return;
+    }
+    isReleased = true;
+    for (const element of locked) {
+      const lock = locks.get(element);
+      if (lock == null || --lock.count > 0) {
+        continue;
+      }
+      locks.delete(element);
+      const style = styleOf(element);
+      for (const {
+        name,
+        value,
+        priority
+      } of lock.saved) {
+        if (value === '') {
+          style?.removeProperty(name);
+        } else {
+          style?.setProperty(name, value, priority);
+        }
+      }
+    }
+  };
+}
+
+/**
+ * A form control WebKit's own stylesheet makes selectable, which no
+ * ancestor's lock reaches: every input that is not a text field.
+ */
+function isSelectableControl(node) {
+  return node instanceof Element && node.localName === 'input' && !TEXT_ENTRY_TYPES.has(node.type);
+}
+
+/** Text a held finger edits: it places the caret there. */
+function isTextEntry(node) {
+  const element = node instanceof Element ? node : node instanceof Node ? node.parentElement : null;
+  if (element == null) {
+    return false;
+  }
+  if (element.localName === 'textarea') {
+    return true;
+  }
+  if (element.localName === 'input') {
+    return TEXT_ENTRY_TYPES.has(element.type);
+  }
+  return element.isContentEditable;
+}
+
+/** An element's inline style, when it has one (HTML and SVG elements). */
+function styleOf(element) {
+  const style = element.style;
+  return style instanceof Object ? style : null;
+}

package/dist/utils/sharedMutationObserver.d.ts

@@ -3,8 +3,8 @@
  * @input MutationObserver API
  * @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:
+ * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
+ *   main-overflow observer and ModalAnnounceProvider's presentation watch. 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.
  */

package/dist/utils/sharedMutationObserver.js

@@ -7,8 +7,8 @@
  * @input MutationObserver API
  * @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:
+ * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
+ *   main-overflow observer and ModalAnnounceProvider's presentation watch. 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.
  */