An open source design system that's fully customizable and agent ready
TypeScript
chore(utils): source comments in ten utility files explain only non-obvious reasons (1 of 2) (#9522)
Cindy Zhang09a09fff3b21
diff --git a/.changeset/utils-comment-cleanup.md b/.changeset/utils-comment-cleanup.mdnew file mode 100644index 0000000000..9638d58785--- /dev/null+++ b/.changeset/utils-comment-cleanup.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] Source comments in ten core utility files are shorter and explain only non-obvious reasons. Nothing a consumer imports or renders changes.++@cixzhangdiff --git a/packages/core/src/utils/clickGuard.ts b/packages/core/src/utils/clickGuard.tsindex d17ed35aee..2a81b7b85a 100644--- a/packages/core/src/utils/clickGuard.ts+++ b/packages/core/src/utils/clickGuard.ts@@ -4,38 +4,29 @@* @file clickGuard.ts* @input A document whose gesture already acted (a menu row's release, a* touch a gesture recognizer claimed)- * @output Exports armClickGuard (and its ClickGuardOptions),- * disarmClickGuard, isClickGuardArmed, withoutClickGuard and- * CLICK_GUARD_WINDOW_MS+ * @output armClickGuard (and its ClickGuardOptions), disarmClickGuard,+ * isClickGuardArmed, withoutClickGuard and CLICK_GUARD_WINDOW_MS* @position The one guard for the browser's click after a gesture that- * already acted (useMenuPress FR5, `spec:AST-057` FR6), shared by the menu- * press model (hooks/useMenuPress.ts) and the gesture host- * (gestures/GestureHost.ts)- *- * Armed at a tracked release, it swallows the next click the browser- * reports, on the window's capture phase through the input stream- * (utils/inputStream.ts), so no framework sees it. It disarms on that click,- * at the next `pointerdown` (a new gesture, whose click must act), or after- * {@link CLICK_GUARD_WINDOW_MS}; disarmed, it lets every click pass. Its- * click listener comes with an arm. Once the menu press model arms it, it- * stays: installed once per document and armed per gesture, it keeps its- * place ahead of any window listener the page adds later- * (`module:DropdownMenu/useMenuPress` PR2, which `spec:AST-094` FR24 counts- * once per page). Armed only by the gesture host, it goes when the guard- * disarms: a release-armed swallower is press work (FR24).- *- * Some clicks always pass:- * - a click whose `detail` is 0: a keyboard's, a screen reader's, or an- * activation the page dispatches;- * - a click dispatched inside {@link withoutClickGuard}: a menu row's own- * activation, or a recognizer's replayed or retargeted click;- * - the hidden haptic switch's click (gestures/haptics.ts), the tap's own- * feedback.+ * already acted, shared by hooks/useMenuPress.ts and gestures/GestureHost.ts** SYNC: When modified, update clickGuard.test.ts, hooks/useMenuPress.ts and* gestures/GestureHost.ts.*/+// Armed at a tracked release, the guard swallows the next click on the+// window's capture phase (utils/inputStream.ts), so no framework sees it. It+// disarms on that click, at the next `pointerdown`, or after+// {@link CLICK_GUARD_WINDOW_MS}. After the menu press model arms it, its click+// listener stays, so it keeps its place ahead of window listeners that the+// page adds later (AST-057, AST-094). If only the gesture host arms it, the+// click listener stays only while the guard is armed.+//+// Some clicks always pass:+// - a click with `detail` 0: a keyboard's, a screen reader's, or one that the+// page dispatches;+// - a click dispatched inside {@link withoutClickGuard};+// - the hidden haptic switch's click (gestures/haptics.ts).+import {isHapticSwitch} from '../privateAttributes/hapticSwitch.stylex';import {subscribeInput} from './inputStream';@@ -50,8 +41,7 @@ export const CLICK_GUARD_WINDOW_MS = 400;export interface ClickGuardOptions {/*** The menu press model's arm: the window's click listener stays from then- * on (`module:DropdownMenu/useMenuPress` PR2). Any other arm keeps it only- * while the guard is armed (`spec:AST-094` FR24).+ * on. Any other arm keeps it only while the guard is armed.* @default false*/readonly staysInstalled?: boolean;@@ -63,7 +53,7 @@ interface Guard {}const guards = new Map<Document, Guard>();-/** The click listeners that stay, by window: the menu press model's (PR2). */+/** The click listeners that stay, by window: the menu press model's. */const stayingClickListeners = new WeakMap<Window, () => void>();let unguardedDepth = 0;diff --git a/packages/core/src/utils/ime.ts b/packages/core/src/utils/ime.tsindex d8bd963205..c997ccaa47 100644--- a/packages/core/src/utils/ime.ts+++ b/packages/core/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;diff --git a/packages/core/src/utils/inputStream.ts b/packages/core/src/utils/inputStream.tsindex beebb18543..663c6bcca6 100644--- a/packages/core/src/utils/inputStream.ts+++ b/packages/core/src/utils/inputStream.ts@@ -4,44 +4,31 @@* @file inputStream.ts* @input A window, and subscribers to its input events (the press feedback* controller, the gesture host)- * @output Exports subscribeInput+ * @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*- * The window's capture phase runs before any document listener, so an app's- * window-capture `stopPropagation`, or a document-capture- * `stopImmediatePropagation` registered before core subscribed, no longer- * hides input from the press feedback or the gesture host, as UIKit's- * recognizers see touches before views do. A recognizer that claims a touch- * still needs the touch to reach its element: its blocking `touchmove` sits- * there, below such a stop. And the stream stays ahead of an app's own- * window-capture listener only until a type's listener is re-added: a- * passivity switch, or a subscription after the type's last subscriber left,- * appends it after every window-capture listener registered meanwhile, so an- * app listener added after core's first subscription runs before core from- * then on, and its `stopImmediatePropagation` hides the event from every- * subscriber. Events fired at the document (`visibilitychange`, the- * page's `scroll`) and every element's `scroll` reach the window's capture- * phase too. A non-bubbling event fired at an element (`blur`, `focus`)- * reaches it as well, so a subscriber that means the window's own event- * checks `event.target`.- *- * Subscribers run in subscription order, each isolated: one that throws is- * reported and the rest still run, as separate native listeners would.- *- * A type's native listener is passive, so a page that only paints presses- * blocks no scroll. It is registered non-passive only while a subscriber- * that cancels the event (`{cancels: true}`) is subscribed (the gesture- * host's `touchend` and `contextmenu` while a claiming participant is- * attached; the page hold's `touchmove` while it holds; the click guard's- * `click` while it is armed, and from the menu press model's first arm on),- * and passive again once that subscriber leaves. With no subscriber left,- * it is removed.- ** 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 {diff --git a/packages/core/src/utils/interactionModality.ts b/packages/core/src/utils/interactionModality.tsindex babb199b9f..6f4afed7d7 100644--- a/packages/core/src/utils/interactionModality.ts+++ b/packages/core/src/utils/interactionModality.ts@@ -5,42 +5,26 @@/*** @file interactionModality.ts* @input Global pointerdown/keydown events- * @output `useInteractionModalityTracking()` activates tracking for the page and- * returns a callback ref that tracks the element's second document, if any,- * with a reader for that element's own document;- * `useInteractionModalityTrackingFor(objectRef)` does the same for hooks- * that receive a consumer's object ref;- * `getInteractionModality(target?)` reads how the user last interacted in a- * node's or document's own document (the page by default)- * @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. A component attaches- * the one hook's callback ref to its element and gets both; it never tracks a- * document itself. 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*/+// `: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,@@ -176,7 +160,7 @@ export type InteractionModalityTracking = {* 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 (INV6).+ * or replacing the node releases it first.*/ref: RefCallback<Element>;/** How the user last interacted in the element's own document. */@@ -246,8 +230,8 @@ export function useInteractionModalityTracking(): InteractionModalityTracking {* 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 (INV3), so a detached, replaced or- * moved node releases the old document before the new one is held (INV6).+ * 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>,diff --git a/packages/core/src/utils/interactionOverlay.stylex.ts b/packages/core/src/utils/interactionOverlay.stylex.tsindex 9368b596e3..02aa8b243a 100644--- a/packages/core/src/utils/interactionOverlay.stylex.ts+++ b/packages/core/src/utils/interactionOverlay.stylex.ts@@ -6,78 +6,12 @@/*** @file Shared hover and pressed overlay states- * @input Uses StyleX and the semantic interaction-overlay color tokens- * @output Exports reusable background-color and background-image state styles,- * the touch press's registered strength variable (`pressVars`) and its- * clocks (`pressConsts`)+ * @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`)* @position Internal styling utility for interactive core surfaces*- * Every surface that paints a press composes one of these (or carries its own- * `:active` rule in the same shape), so a change to how the system answers a- * press is made here once. `pressedBackgroundColor` is the press without the- * hover, for controls whose hover is a colour or nothing. `pressedAlpha` is the- * touch press's strength alone, for an owner whose pressed paint lives on a- * descendant or a pseudo-element.- *- * Keep the enabled guard outside the individual states. StyleX assigns an- * extra priority bucket (and generated selector specificity) to media-nested- * rules. Repeating `:active` inside the hover-capable branch gives hover and- * press the same generated specificity; StyleX's native pseudo-state ordering- * then emits `:active` last.- *- * TWO POINTERS, TWO PRESS MODELS. A mouse keeps `:active`. A finger does not:- * on iOS Safari `:active` paints on the touch itself and can outlive the start- * of a scroll, so under `@media (pointer: coarse)` the bare `:active` arm is- * dropped and the press is written by the touch press controller- * (`utils/pressFeedback.ts`) as `data-astryx-press="on"` once the press is- * believed (150 ms, no travel, no scroll) and `data-astryx-press="fading"` for the- * 200 ms release. The query reads the PRIMARY pointer, so on a phone or tablet- * a mouse, trackpad or Space-key press loses `:active` too; the controller- * writes the same attribute for those, at once. The two arms paint those- * through ONE number:- *- * - `--astryx-press-alpha` is the press's strength, 0 to 1. It is a- * registered custom property (`@property`, syntax `<number>`, declared once- * in the shipped stylesheet by {@link pressVars}), which is what lets it- * animate: the overlay itself is a gradient layer, and gradients do not- * interpolate, but a registered number does, and every declaration that- * reads it is re-resolved on each frame. The touch paint is the pressed- * token at that strength — `color-mix(in srgb, pressed calc(alpha * 100%),- * transparent)` — declared once here as `--_press-paint` and painted as a- * background IMAGE: an image change is discrete, so a composer's colour- * transition cannot fade the onset in.- * - `[data-astryx-press="on"]` sets the strength to 1 and paints, on the- * first frame. Nothing transitions a custom property a composer never named.- * - `[data-astryx-press="fading"]` keeps the same paint and runs the release- * animation, strength 1 → 0 over {@link PRESS_RELEASE_DURATION} (UIKit's- * deselect crossfade; the controller removes the attribute when the same- * clock runs out, and by then the paint is gone). It fades to nothing, not- * to the hover strength: under a finger there is no hover to land on.- *- * WHY AN ANIMATION AND NOT A TRANSITION. Two reasons, both about composers.- * StyleX is last-wins per property, and composers own their `transition-*`- * longhands (Button, Item, Tab, Link, ...): the utility can neither append the- * strength to their transition list nor set one of its own without taking the- * whole property from them. No composer sets `animation-*` on the element that- * composes these, so those longhands are free. And a transition needs the- * declared value to change at the style change, which would make the release- * arm declare strength 0; every property reading the strength would then- * change computed value at the lift, and a composer that transitions- * `background-image` (Button, Token, TreeListItem — Chromium interpolates- * same-shape gradients) would start its own, shorter fade over this one. With- * keyframes owning both ends the release arm declares 1 like the on arm, so at- * the lift nothing a composer transitions changes; only the animation moves.- *- * Browser support: Chromium 111+, Safari 16.4+ and Firefox 128+ register the- * property and interpolate. An engine without `@property` ignores the rule,- * animates the unregistered value discretely (the paint holds for half the- * release, then goes) — a step, no worse than the arm before this one.- *- * Composers must not set `backgroundImage` of their own on the colour variants- * (none do): the touch arms own it. Composers must not set `animation-*` on- * the element that composes any of these (none do): StyleX would drop either- * the release animation or theirs.- ** SYNC: When modified, update pressFeedback.ts, pressGesture.ts (the fade* clock), hooks/usePressFeedback.doc.mjs, the components that paint the touch* press off an ancestor scope or a pseudo-element (Switch, Tab,@@ -85,6 +19,39 @@* and scripts/build-css.test.mjs.*/+// Every surface that paints a press uses one of these styles, so a change to+// the press is made here once.+//+// Keep the enabled guard outside the states. StyleX gives media-nested rules+// a higher priority. With `:active` repeated in the hover branch, hover and+// press get the same specificity, and StyleX emits `:active` last.+//+// A mouse keeps `:active`. A finger does not: on iOS Safari `:active` paints+// on the touch and can outlive the start of a scroll. So under+// `@media (pointer: coarse)` the press controller (pressFeedback.ts) writes+// `data-astryx-press`: `on` when the press is believed, and `fading` for the+// release. The query reads the primary pointer, so on a phone a mouse or+// Space-key press loses `:active` too, and the controller writes the+// attribute at once.+//+// The `on` and `fading` arms paint through `--astryx-press-alpha`, a+// registered `<number>` from 0 to 1. Gradients do not interpolate, but a registered number does.+// The touch paint is the pressed token at that strength, painted as a+// background image, so a composer's color transition cannot fade the onset+// in. `on` sets the strength to 1 on the first frame. `fading` animates it+// from 1 to 0, not to the hover strength, because a finger has no hover. The+// theme's motion tempo scales the release clock (AST-108).+//+// The release is an animation, not a transition. Composers own their+// `transition-*` longhands, and StyleX is last-wins per property. A+// transition would also make the release arm declare 0, so a composer that+// transitions `background-image` would start its own fade. With keyframes,+// both arms declare 1 and only the animation moves. An engine without+// `@property` steps the paint off at half the release.+//+// Composers must not set `backgroundImage` on the color variants, or+// `animation-*` on the element that composes them. The touch arms own both.+import * as stylex from '@stylexjs/stylex';import {colorVars} from '../theme/tokens.stylex';@@ -118,8 +85,7 @@ export const pressConsts = stylex.defineConsts({/*** The release's clock as CSS, scaled by the theme's `--_astryx-motion-tempo`- * (`spec:AST-108` FR4, `component:Button` FR15) up to 1.5, its maximum. The- * controller's timer reads the same property.+ * up to 1.5, its maximum. The controller's timer reads the same property.*/const PRESS_RELEASE_DURATION = `calc(${pressConsts.releaseMs}ms * min(var(--_astryx-motion-tempo, 1), 1.5))`;/** The same clock under Reduce Motion: a tempo may shorten it, never lengthen it. */@@ -182,21 +148,14 @@ const RELEASE_EASE = 'cubic-bezier(0, 0, 0.2, 1)';/*** The touch press's strength and its release, on the element the controller- * writes to. Every variant below carries both, as `[PRESS_ALPHA]:- * pressStrength` and `...pressReleaseAnimation`; `pressedAlpha` is the pair+ * writes to. Every variant below carries both. `pressedAlpha` is the pair* alone.*- * Both objects are written with literal keys, and the strength's own key is- * spelled inside each variant rather than here, on purpose. StyleX reads a- * `stylex.create` call from the raw AST, so a computed key written inside- * the call is still a computed key when it evaluates it. An object hoisted- * out of the call has been through every other Babel plugin by the time the- * spread is resolved, and a preset that lowers ES2015 (`next/babel` under- * the default browserslist: apps/sandbox, and a consumer's source build) has- * rewritten its computed keys into `_defineProperty` helper calls the- * evaluator cannot follow, failing the build with "Referenced constant is- * not defined". Literal keys survive the lowering; `PRESS_ALPHA` cannot be- * one, since the variable's name is generated, so it stays at each use. The+ * The keys are literal on purpose. StyleX reads `stylex.create` from the raw+ * AST. An object hoisted out of the call can first pass through a preset that+ * lowers ES2015, such as `next/babel`. That preset turns computed keys into+ * helper calls, and the build fails with "Referenced constant is not+ * defined". `PRESS_ALPHA` has a generated name, so it stays at each use. The* literal keys equal PRESSED_ON and PRESSED_FADING above.*/const pressStrength = {diff --git a/packages/core/src/utils/presentation.ts b/packages/core/src/utils/presentation.tsindex 1ea71af26a..5ec319726c 100644--- a/packages/core/src/utils/presentation.ts+++ b/packages/core/src/utils/presentation.ts@@ -4,51 +4,37 @@/*** @file presentation.ts- * @input A component's `presentation` prop (a caller's value, or omitted),- * what the component does when it is omitted, and the touch presentation- * (utils/touchPresentation.ts)- * @output usePresentation and readPresentation (and the pure- * resolvePresentation): the surface to render and whether the component's+ * @input A component's `presentation` prop, what the component does when it+ * is omitted, and the touch presentation (utils/touchPresentation.ts)+ * @output usePresentation, readPresentation, and the pure+ * resolvePresentation: the surface to render and whether the component's* touch input modes apply* @position Internal resolver for stable components that, under a finger,- * present a different surface or switch how an open surface follows input- * (architecture:public-component-api INV16)- *- * A caller's explicit `presentation` always wins over the touch default:- *- * - `'popover'`: the fine-pointer surface AND input modes, on every device;- * - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a- * finger;- * - `'adaptive'`: the sheet on a compact touch screen and the popover- * elsewhere, with touch input modes under a finger;- * - omitted: the component's default. `whenOmitted: 'popover'` answers as- * `'popover'` (today's components). `whenOmitted: 'touch'` keeps the- * popover surface and turns the component's touch input modes on under a- * finger, as UIMenu tracks a finger in an anchored menu. Making `'touch'`- * a released component's default is a functional default change- * (`spec:AST-017` FR3) whose Changeset names `presentation="popover"`.- *- * One touch model on every touch device: the modes depend on the pointer,- * never on the platform. Touch styling (press paint, the text-size floor)- * and touch-only behavior that a component's own record defines (a row- * swipe, a slider's thumb) do not read this: they keep the touch- * presentation.- *- * CSS: a style that implements a touch surface or input mode is applied with- * `touchModes` (`stylex.props(touchModes && styles.touchMode)`), never as a- * bare media key on a base style, so a pinned `'popover'` keeps none of it.- * A rule inside it that needs the touch query uses the touch presentation's- * touch key; the iOS `@supports` gate is only for the one style iOS WebKit- * itself requires (the 16px text-size floor), never for a touch mode. On the- * server and while hydrating, `touchModes` is false and `'adaptive'` is the- * popover: a touch surface or mode opens only after hydration- * (`spec:AST-094` FR13), and no hint changes that. usePresentation listens- * only to the queries a request reads (`architecture:react-component-runtime`- * INV5): none for a pinned `'popover'`.+ * present a different surface or change how an open surface follows input** SYNC: When modified, update presentation.test.ts.*/+// A caller's explicit `presentation` always wins over the touch default:+// - `'popover'`: the fine-pointer surface and input modes, on every device.+// - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a+// finger.+// - `'adaptive'`: the sheet on a compact touch screen (AST-012), else the+// popover, with touch input modes under a finger.+// - Omitted: `whenOmitted: 'popover'` answers as `'popover'`.+// `whenOmitted: 'touch'` keeps the popover surface and turns on touch input+// modes under a finger. When a released component changes its default to+// `'touch'`, that is a functional default change (AST-017).+//+// The modes depend on the pointer, never the platform. Touch styling and+// touch-only behavior from a component's own record do not read this.+//+// Apply a touch-mode style with `touchModes`+// (`stylex.props(touchModes && styles.touchMode)`), never as a bare media+// key, so a pinned `'popover'` keeps none of it. On the server and while+// hydrating, `touchModes` is false and `'adaptive'` is the popover+// (AST-094). usePresentation listens only to the queries a request reads.+import {useCallback, useMemo, useSyncExternalStore} from 'react';import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';import type {CompactDefinition} from '../theme/themeAdaptations';@@ -79,7 +65,7 @@ export interface PresentationOptions {/*** usePresentation's options. There is no server hint: the server and- * hydrating render never present touch modes (`spec:AST-094` FR13).+ * hydrating render never present touch modes.*/export type UsePresentationOptions = PresentationOptions;@@ -88,8 +74,7 @@ export interface ReadPresentationOptions extends PresentationOptions {readonly view?: Window | null;/*** The active theme's compact definition (`useCompactDefinition()`, read- * while rendering), so a theme that moves `md` moves the sheet too- * (`spec:AST-012` FR9).+ * while rendering), so a theme that moves `md` moves the sheet too.*/readonly compact: CompactDefinition;}@@ -111,13 +96,12 @@ export function resolvePresentation(}const noSubscription = () => () => {};-/** The server and hydrating render match no query (`spec:AST-094` FR13). */+/** The server and hydrating render match no query. */const matchesNothing = () => false;/**- * A media query's match, subscribed only while `query` is given- * (`architecture:react-component-runtime` INV5); false on the server and- * while hydrating (`spec:AST-094` FR13).+ * A media query's match, subscribed only while `query` is given. False on+ * the server and while hydrating.*/function useMatchWhileRead(query: string | null): boolean {const subscribe = useCallback(@@ -141,7 +125,7 @@ function useMatchWhileRead(query: string | null): boolean {/*** The presentation now, following the pointer and the size as they change* (a tablet docking a trackpad). SSR-safe: renders the server default (not- * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes+ * touch, not compact) until hydrated. It subscribes* only to what the request reads: a pinned `'popover'` to neither query,* `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and* `'adaptive'` to the pointer and the compact size.diff --git a/packages/core/src/utils/pressFeedback.ts b/packages/core/src/utils/pressFeedback.tsindex fd17a01d6d..f5aa67975a 100644--- a/packages/core/src/utils/pressFeedback.ts+++ b/packages/core/src/utils/pressFeedback.ts@@ -5,53 +5,33 @@* @input The press state machine (pressGesture.ts), the menu-press marker* (hooks/menuPressMarker.ts) and the document's pointer, keyboard, scroll and* visibility events- * @output Exports PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps and+ * @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.- *- * A surface's hold does nothing, so it keeps the browser's long-press text- * selection (`spec:AST-094` FR41); only an element whose hold does something- * suppresses it, through the gesture host (utils/selectionLock.ts).- *- * Its one touch-only listener, `touchcancel`, is on only while the primary- * pointer is coarse (coarsePointer.ts, `spec:AST-094` FR24).+ * @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 {@@ -114,9 +94,8 @@ 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 = `[${MENU_PRESS_MARKER}]`;@@ -169,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);@@ -209,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;@@ -258,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],);}@@ -285,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) {@@ -353,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@@ -522,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.@@ -658,9 +617,8 @@ let stopTouchCancel: (() => void) | null = null;let stopWatchingPointer: (() => void) | null = null;/**- * The one touch-only listener is on only while the primary pointer is coarse- * (`spec:AST-094` FR24); where it is fine, a finger's press still ends- * through `pointercancel`.+ * 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)) {diff --git a/packages/core/src/utils/rtlStyles.ts b/packages/core/src/utils/rtlStyles.tsindex 8b30003c05..e6b8383b3d 100644--- a/packages/core/src/utils/rtlStyles.ts+++ b/packages/core/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({diff --git a/packages/core/src/utils/selectionLock.ts b/packages/core/src/utils/selectionLock.tsindex e2ee0b8776..d29b1b04e1 100644--- a/packages/core/src/utils/selectionLock.ts+++ b/packages/core/src/utils/selectionLock.ts@@ -3,34 +3,30 @@/*** @file selectionLock.ts* @input The elements a held touch contact presses, and the touch's target- * @output Exports lockSelection: no text selection and no touch callout- * start under the held finger until the returned release runs; and- * locksSelectionFor: which contacts take it- * @position Brought by the recognizers whose hold does something (a long- * press, and a recognizer created with `selectionLock: lockSelection`); the- * gesture host calls it and never imports it (`spec:AST-094` FR41)- *- * A hold that does something never starts a selection or the callout under- * the finger, a link's menu and preview included (`spec:AST-094` FR41,- * DEC-9). A text field keeps its selection: a held finger places its caret.- * How it is refused differs by engine, because a style change repaints- * everything it covers:- * - Where iOS WebKit runs (its touch callout query), only `user-select` refuses- * a long-press selection: WebKit fires no `selectstart` for one. It covers- * every held element, inline and refcounted: on the element under the- * finger alone, a long press selected a word beside it (iOS 26.2- * simulator). WebKit's own stylesheet makes every input selectable- * (`-webkit-user-select: text`), out of reach of an ancestor's lock, so a- * checkbox, a radio or a switch's input under the finger is locked too.- * - Elsewhere a long press fires `selectstart`, and cancelling it refuses- * the selection with no style write, so nothing repaints (Chromium on- * Android re-rastered a held surface at the touch-down and the lift when- * the style toggled).+ * @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';@@ -55,8 +51,7 @@ const TEXT_ENTRY_TYPES = new Set([/*** 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 (`spec:AST-094` FR41). A- * mouse never does: it keeps its released behavior (`spec:AST-017` FR59).+ * included, since a pen's hold acts as a finger's.*/export function locksSelectionFor(pointerType: string): boolean {return pointerType !== 'mouse';diff --git a/packages/core/src/utils/touchPresentation.ts b/packages/core/src/utils/touchPresentation.tsindex 94a32ae7f5..9fc3fa7f46 100644--- a/packages/core/src/utils/touchPresentation.ts+++ b/packages/core/src/utils/touchPresentation.ts@@ -4,62 +4,40 @@/*** @file touchPresentation.ts- * @input Uses the SSR-safe useMediaQuery hook, window.matchMedia, and- * TOUCH_QUERY from touchQueries.ts (which loads without React or the theme)- * @output The one definition of when a component presents itself the touch- * way: TOUCH_QUERY, COMPACT_QUERY, COMPACT_TOUCH_QUERY, the iOS style gate- * (IOS_SUPPORTS_QUERY and its StyleX keys); the hook useTouchPresentation;- * readTouchPresentation for a decision taken at one moment- * @position Internal shared resolver beside interactionModality.ts- *- * Two questions, answered once:- *- * - TOUCH behaviours (the press model, gesture recognizers, UIKit springs and- * timings) key on the PRIMARY pointer being coarse: a finger. A touchscreen- * laptop reports its trackpad (fine) and keeps pointer behaviours; a tablet- * reports coarse and gets touch ones at any width. Not `hover: none` (some- * touch browsers report hover) and not `any-pointer` (a laptop's touch- * screen is not how it is driven).- * - LAYOUT behaviours key on the available size, whatever the pointer:- * the theme's one compact definition (`spec:AST-012` FR9), width below the- * `md` point or height below 500, the same numbers on every platform. A- * phone in landscape is compact by its height; no platform size class is- * consulted.- * - A presentation that needs both (a bottom sheet in place of a popover, a- * drilled-in sub-menu in place of a flyout) asks for both.- *- * Touch behaviour is one model on every touch device, iOS and Android alike;- * nothing here chooses a platform. Touch motion plays the measured table,- * through the internal motion roles where a value is one.- *- * CSS first: a style that changes with these conditions writes the same- * query as a StyleX media key, spelled exactly as here (`@media` followed by- * the constant's text), so the right rule paints before hydration. The iOS- * gate is two nested keys, the media query outside and the supports query- * inside (IOS_TOUCH_STYLE_KEYS):- *- * '@media (pointer: coarse)': {- * '@supports (-webkit-touch-callout: none)': value,- * },- *- * One `@supports (-webkit-touch-callout: none) and (pointer: coarse)` never- * matches anywhere (`pointer` is not a property), so it is not written. A- * test keeps core's compact-touch keys identical to COMPACT_TOUCH_QUERY and- * every touch-callout key spelled and nested as above. The iOS style gate- * is only for a style iOS WebKit itself requires (core's 16px input floor);- * it never selects a behaviour. Core spells the keys literally: an imported- * `defineConsts` key compiles to a different StyleX priority than the same- * literal, which would reorder the cascade. `touchKeys`- * (touchPresentation.stylex.ts, internal to core) holds the same keys, and a- * test keeps every literal equal to them. The hook is for behaviour. It answers the server default- * (not touch, not compact) until hydrated unless the caller passes a server- * hint, and follows the pointer and size when they change (a tablet docking- * a mouse).+ * @input useMediaQuery, window.matchMedia, and TOUCH_QUERY from touchQueries.ts+ * @output TOUCH_QUERY, COMPACT_QUERY, COMPACT_TOUCH_QUERY, the iOS style gate+ * (IOS_SUPPORTS_QUERY and its StyleX keys), useTouchPresentation, and+ * readTouchPresentation+ * @position Internal shared resolver beside interactionModality.ts; the one+ * definition of when a component presents itself the touch way** SYNC: When modified, update touchPresentation.test.ts and every StyleX* media key that spells these queries.*/+// - Touch behaviors key on a coarse primary pointer: a finger. A touchscreen+// laptop reports its trackpad and keeps pointer behaviors. Not+// `hover: none` (some touch browsers report hover), and not `any-pointer`.+// - Layout behaviors key on the available size: the theme's compact+// definition (AST-012, and its AST-012 FR9). A phone in landscape is+// compact by its height.+// - A presentation that needs both asks for both. No platform is chosen.+//+// A style that changes with these conditions uses the same query as a StyleX+// media key, so the right rule paints before hydration. The iOS gate is two+// nested keys, the media query outside and the supports query inside:+//+// '@media (pointer: coarse)': {+// '@supports (-webkit-touch-callout: none)': value,+// },+//+// One combined `@supports` never matches, because `pointer` is not a+// property. The iOS gate is only for a style that iOS WebKit requires (the+// 16px input floor). Core spells the keys literally, because an imported+// `defineConsts` key gets a different StyleX priority. Tests keep the+// literals equal to these queries and to `touchKeys`. The hook answers the+// server default until hydrated, unless the caller passes a hint.+import {useMemo} from 'react';import {useMediaQuery} from '../hooks/useMediaQuery';import {@@ -75,8 +53,8 @@ import {IOS_SUPPORTS_QUERY, TOUCH_QUERY} from './touchQueries';export {TOUCH_QUERY};/**- * The viewport is compact at the default width points: layout behaviours- * (`spec:AST-012` FR9). A StyleX media key, which cannot read the theme,+ * The viewport is compact at the default width points: layout behaviours.+ * A StyleX media key, which cannot read the theme,* spells this; behaviour reads the active theme's definition* (useCompactDefinition), so a theme that moves `md` moves compact with it.*/@@ -107,7 +85,7 @@ export interface TouchPresentation {}/**- * The active theme's compact definition (`spec:AST-012` FR9): width below the+ * The active theme's compact definition: width below the* theme's effective `md` point, or height below 500.*/export function useCompactDefinition(): CompactDefinition {@@ -139,7 +117,7 @@ export function useTouchPresentation(* The touch presentation at this moment, for a decision taken once (a menu* deciding how it presents as it opens). `compact` is the active theme's* definition (`useCompactDefinition()`, read while rendering), required so a- * theme that moves `md` is never ignored (spec:AST-012 FR9). Not touch and+ * theme that moves `md` is never ignored. Not touch and* not compact where there is no window.*/export function readTouchPresentation(