Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/packages/core/src/utils/clickGuard.ts b/packages/core/src/utils/clickGuard.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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(