@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/utils/pressFeedback.ts

@@ -2,48 +2,37 @@
 
 /**
  * @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';
 import type {PressGesture, PressPaint, PressStep} from './pressGesture';
 import {
   idlePressGesture,
@@ -53,6 +42,8 @@ import {
   PRESS_SCROLL_BRAKE_MS,
   pressGestureStep,
 } from './pressGesture';
+import {isCoarsePointer, watchCoarsePointer} from './coarsePointer';
+import {subscribeInput} from './inputStream';
 import {TOUCH_QUERY} from './touchPresentation';
 
 /**
@@ -103,11 +94,10 @@ const SPACE_ACTIVATED_INPUT_TYPES: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * 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}]`;
 
 interface LiveGesture {
   element: HTMLElement;
@@ -158,9 +148,8 @@ const TIMER_MS: Record<NonNullable<PressStep['timer']>, number> = {
 
 /**
  * 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: Element): number {
   const style = getComputedStyle(element);
@@ -198,22 +187,16 @@ function clearTimer(slot: Slot): void {
 /**
  * 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: Slot, step: PressStep): void {
   const live = slot.live;
@@ -247,8 +230,8 @@ function apply(slot: Slot, step: PressStep): void {
           }),
         );
       },
-      // 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],
     );
   }
@@ -274,25 +257,14 @@ function surfaceAt(target: EventTarget | null): HTMLElement | null {
 }
 
 /**
- * Is this touch a BRAKE on a list the finger set moving, rather than a press?
- *
- * 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.
+ * 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.
  *
- *  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: HTMLElement): boolean {
   if (Date.now() - lastScrollAt >= PRESS_SCROLL_BRAKE_MS) {
@@ -342,9 +314,8 @@ function takeOver(other: Slot, element: HTMLElement): void {
  * so a layout that must not depend on it stays independent.
  */
 function stylesheetDroppedActive(): boolean {
-  // 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
@@ -417,6 +388,7 @@ function onPointerDown(event: PointerEvent): void {
     }
     return;
   }
+  armTouchCancel();
   if (finger.live != null) {
     const fingerIsUp =
       finger.live.gesture.phase === 'fading' ||
@@ -510,10 +482,9 @@ function onPointerUp(event: PointerEvent): void {
 /**
  * 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?: Event): void {
   // A cancelled mouse pointer ends the mouse's press, not a finger's.
@@ -638,38 +609,78 @@ function onVisibilityChange(): void {
   }
 }
 
-const PASSIVE_CAPTURE = {capture: true, passive: true} as const;
-const PASSIVE = {passive: true} as const;
+/** The input stream subscriptions while installed. */
+let unsubscribers: (() => void)[] = [];
+
+/** The touch-only `touchcancel` subscription, while the pointer is coarse. */
+let stopTouchCancel: (() => void) | null = null;
+let stopWatchingPointer: (() => void) | null = 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: boolean): void {
+  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(): void {
+  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(): void {
-  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(): void {
-  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} as const;
+const PASSIVE = {passive: true} as const;
+
 /** Whether the key-release listeners are attached. */
 let keyHeld = false;
 

package/src/utils/pressGesture.ts

@@ -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';
 
 /**

package/src/utils/rtlStyles.ts

@@ -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';
 
 export const rtlStyles = stylex.create({

package/src/utils/selectionLock.ts

@@ -0,0 +1,188 @@
+// 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';
+import {isIosWebKit} from './touchQueries';
+
+/** What a held finger must not start on a control or a cell. */
+const SELECTION_LOCK = [
+  '-webkit-touch-callout',
+  '-webkit-user-select',
+  'user-select',
+] as const;
+
+/** 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: string): boolean {
+  return pointerType !== 'mouse';
+}
+
+/** Locked elements, how many contacts hold each, and what to restore. */
+const locks = new WeakMap<
+  Element,
+  {
+    count: number;
+    saved: ReadonlyArray<{name: string; value: string; priority: string}>;
+  }
+>();
+
+/**
+ * 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: Iterable<Element>,
+  target: EventTarget | null,
+): () => void {
+  const set = new Set(elements);
+  if (
+    isSelectableControl(target) &&
+    [...set].some(element => containsAlongFlatTree(element, target))
+  ) {
+    set.add(target);
+  }
+  if (!isIosWebKit()) {
+    const refuse = (event: 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: Element[] = [];
+  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: unknown): node is HTMLInputElement {
+  return (
+    node instanceof Element &&
+    node.localName === 'input' &&
+    !TEXT_ENTRY_TYPES.has((node as HTMLInputElement).type)
+  );
+}
+
+/** Text a held finger edits: it places the caret there. */
+function isTextEntry(node: EventTarget | null): boolean {
+  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 as HTMLInputElement).type);
+  }
+  return (element as HTMLElement).isContentEditable;
+}
+
+/** An element's inline style, when it has one (HTML and SVG elements). */
+function styleOf(element: Element): CSSStyleDeclaration | null {
+  const style = (element as Partial<ElementCSSInlineStyle>).style;
+  return style instanceof Object ? style : null;
+}

package/src/utils/sharedMutationObserver.ts

@@ -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.
  */

package/src/utils/standaloneMonthCapitals.generated.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-cldr-month-capitals.mjs from Unicode CLDR 48.2.0.
+ * Do not edit by hand. Run `pnpm generate:cldr-month-capitals` instead.
+ */
+
+/** Shipped languages whose stand-alone month names start with a capital. */
+export const standaloneMonthCapitalLanguages: ReadonlySet<string> = new Set([
+  'es',
+  'fr',
+  'it',
+  'nl',
+  'pl',
+  'ru',
+  'uk',
+]);

package/src/utils/timeFormat.ts

@@ -7,19 +7,11 @@
  * @position Internal shared helper for TimeInput and DateTimeInput; not part
  *   of the public surface
  *
- * Time of day as the locale writes it. The hour cycle, digits, separator, and
- * day-period words all come from Intl rather than a table, so a field reads
- * the same way `Timestamp` does beside it.
- *
- * The hour cycle is the locale's own: `en-US` and `ko-KR` read twelve-hour,
- * `en-GB`, `de-DE`, and `vi-VN` read twenty-four-hour. A `-u-hc-` extension
- * on the provider locale (`en-US-u-hc-h23`) carries an app's per-user
- * preference through the same path, so every Astryx time honors it.
- *
- * The parser reads back what the formatter writes: the locale's digits, its
- * hour-minute separator, and its day-period words, on either side of the time.
- * Whatever is left goes through the shared English-tolerant parser, so "2:30
- * PM" and "14:30" keep working in every locale.
+ * The hour cycle, digits, separator and day-period words come from Intl, so a
+ * field reads like `Timestamp`. A `-u-hc-` extension on the provider locale
+ * carries an app's per-user hour cycle. The parser reads back what the
+ * formatter writes, and the rest goes through the English-tolerant parser,
+ * so "2:30 PM" and "14:30" work in every locale.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/utils/timeFormat.test.ts