@astryxdesign/core 0.7.4 → 0.7.5-canary.04434e7

package/src/Icon/Icon.spec.md

@@ -27,7 +27,7 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-087]
 ---
 
 # Icon component contract
@@ -53,6 +53,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Owns**
 
 - Accepting a semantic icon key or a supplied icon component as the glyph source.
+- Passing the resolved size and a variant the entry can receive to a registry entry.
 - Resolving explicit, component-owned contextual, and standalone size defaults.
 - Applying Icon's size, color, theming target, and accessibility semantics to
   the rendered glyph.
@@ -71,12 +72,13 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default                                         | Owner            | Stability | Invalid-value behavior                                 |
-| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------- | --------- | ------------------------------------------------------ |
-| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required                                        | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
-| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | nearest component-owned default; otherwise `md` | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`                                       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative                                      | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
+| Concept       | Closed values or states                                   | Meaning                                                    | Availability by variant/orientation/state        | Default                                         | Owner            | Stability | Invalid-value behavior                                                            |
+| ------------- | --------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------- | --------- | --------------------------------------------------------------------------------- |
+| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                 | Every render                                     | Required                                        | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values.                            |
+| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                 | Every rendered glyph                             | nearest component-owned default; otherwise `md` | `component:Icon` | Stable    | TypeScript rejects unsupported values.                                            |
+| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.       | Every rendered glyph                             | `inherit`                                       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                                            |
+| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph.  | Every rendered glyph                             | Decorative                                      | `component:Icon` | Stable    | Empty labels use the decorative behavior.                                         |
+| Variant       | names in `IconVariantMap`; the active theme lists its own | Requests a theme's alternate artwork for a registry glyph. | Registry glyphs only; never a supplied component | None                                            | `component:Icon` | Stable    | TypeScript rejects unknown names; an unlisted variant renders the normal artwork. |
 
 A namespaced key that does not resolve currently renders nothing. This is
 existing behavior, not an intentional fallback promise.
@@ -86,13 +88,15 @@ existing behavior, not an intentional fallback promise.
 Requirements identify their basis so observed code is not mistaken for an
 intentional decision.
 
-| ID  | Candidate invariant                                                                                                                                                                               | Basis                                                 | Draft review state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
-| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.                 | Settled intent.                                         |
-| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data.                                                                     | Current source, docs, and theming tests.              | Settled intent.                                         |
-| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests.            | Settled intent.                                         |
-| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.                  | Current compatibility behavior; verify before changing. |
-| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`. | Component-size precedence and Button sizing decision. | Settled intent.                                         |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                           | Basis                                                 | Draft review state                                      |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                                                                                                                                                                                                                                                                        | Documented promise and current tests.                 | Settled intent.                                         |
+| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data.                                                                                                                                                                                                                                                                                                                 | Current source, docs, and theming tests.              | Settled intent.                                         |
+| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type.                                                                                                                                                                                                                                             | Human decision, current source, and tests.            | Settled intent.                                         |
+| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                                                                                                                                                                                                                                                                           | Current source and regression tests.                  | Current compatibility behavior; verify before changing. |
+| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`.                                                                                                                                                                                                                                             | Component-size precedence and Button sizing decision. | Settled intent.                                         |
+| FR6 | In registry mode, Icon MUST pass `{size, variant}` to the selected entry, where `size` is the size resolved by ORD1 and `variant` is the requested variant when the active theme lists it and, for a theme-supplied entry, the theme that defined the entry lists it too, otherwise `undefined`. A supplied icon component MUST NOT receive `variant`, Icon MUST NOT forward `variant` to the DOM, and the `icon` target MUST NOT reflect it. | `spec:AST-087` FR1–FR5 and FR9.                       | Settled intent.                                         |
+| FR7 | The `icon` target MUST guarantee `width` and `height` on its `size:*` selectors as reviewed target-specific additions, so a theme sets each size's dimension. Without theme styles, sizes are 12, 16, 20, and 24px at a 16px root and scale with the root font size.                                                                                                                                                                          | `spec:AST-087` FR10.                                  | Settled intent.                                         |
 
 ### Allowed variation
 
@@ -109,15 +113,18 @@ intentional decision.
 
 ### Representative states
 
-| State                            | Required invariant                                       | Allowed variation                              |
-| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
-| Semantic key                     | One resolved glyph carries the `icon` target.            | Theme, registry, or built-in artwork.          |
-| Namespaced extension key         | A resolved extension glyph carries the `icon` target.    | Consumer- or library-owned artwork.            |
-| Supplied icon component          | The supplied glyph carries the `icon` target.            | Component implementation and SVG internals.    |
-| Standalone Icon without `size`   | The resolved size is `md`.                               | Glyph source and color.                        |
-| Owned icon slot without `size`   | The nearest documented component default is used.        | The owning component's declared size mapping.  |
-| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default. | Any supported Icon size.                       |
-| Unresolved namespaced key        | No glyph is currently rendered.                          | No fallback behavior is established by intent. |
+| State                            | Required invariant                                                                 | Allowed variation                              |
+| -------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------- |
+| Semantic key                     | One resolved glyph carries the `icon` target.                                      | Theme, registry, or built-in artwork.          |
+| Namespaced extension key         | A resolved extension glyph carries the `icon` target.                              | Consumer- or library-owned artwork.            |
+| Supplied icon component          | The supplied glyph carries the `icon` target.                                      | Component implementation and SVG internals.    |
+| Standalone Icon without `size`   | The resolved size is `md`.                                                         | Glyph source and color.                        |
+| Owned icon slot without `size`   | The nearest documented component default is used.                                  | The owning component's declared size mapping.  |
+| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default.                           | Any supported Icon size.                       |
+| Unresolved namespaced key        | No glyph is currently rendered.                                                    | No fallback behavior is established by intent. |
+| Listed variant                   | The entry receives the size and the variant when its defining theme also lists it. | The theme's artwork for that request.          |
+| Unlisted or omitted variant      | The entry receives `variant: undefined`.                                           | The theme's normal artwork.                    |
+| Variant on a supplied component  | The component renders as given without `variant`.                                  | Component implementation.                      |
 
 ### Transformation and precedence order
 
@@ -172,6 +179,8 @@ not promise a `span`, `svg`, or other element type.
   rules for the `icon` target.
 - `architecture:icon-resolution-and-component-slots` owns semantic-key and
   component-slot resolution before Icon renders the selected source.
+- `spec:AST-087` decides the `variant` request, theme-listed variant names, and
+  theme-set size dimensions.
 - `architecture:public-component-api` owns admission and compatibility rules for
   Icon's public props and observable defaults.
 - The owning component or family specifies each contextual Icon-size mapping.
@@ -181,12 +190,14 @@ not promise a `span`, `svg`, or other element type.
 
 ## Verification map
 
-| Contract            | Verification                                                                   | Representative states                                           | Mutation or failure expectation                                                                                                             | Audit section              |
-| ------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3, FR5       | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions.             | `audit:Icon/behavior`      |
-| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection                   | Both source modes; size and color variants                      | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming`       |
-| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                                         | Decorative, labelled, explicit ARIA override                    | Changing default or labelled semantics fails accessibility assertions.                                                                      | `audit:Icon/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical consumer anatomy and current target                   | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                     | `audit:Icon/theming`       |
+| Contract            | Verification                                                                   | Representative states                                                                                            | Mutation or failure expectation                                                                                                               | Audit section              |
+| ------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3, FR5       | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes                                                  | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions.               | `audit:Icon/behavior`      |
+| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection                   | Both source modes; size and color variants                                                                       | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions.   | `audit:Icon/theming`       |
+| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                                         | Decorative, labelled, explicit ARIA override                                                                     | Changing default or labelled semantics fails accessibility assertions.                                                                        | `audit:Icon/accessibility` |
+| FR6                 | `Icon.test.tsx` variant suites (pending)                                       | listed, unlisted, and omitted variant; no active list; inherited entry under a replaced list; supplied component | An unlisted variant, or one the entry's defining theme does not list, reaches an entry, or `variant` reaches a supplied component or the DOM. | `audit:Icon/behavior`      |
+| FR7                 | Theme styling tests for each size (pending)                                    | each size with and without theme styles                                                                          | A themed size does not change the glyph dimension, or an unstyled size changes.                                                               | `audit:Icon/theming`       |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical consumer anatomy and current target                                                                    | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                       | `audit:Icon/theming`       |
 
 Focused coverage for `data-color` on both glyph source modes is a checkable test
 gap; source inspection is the current evidence for that part of FR2.

package/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts

@@ -0,0 +1,199 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TouchTrigger.a11y.chromium.spec.ts
+ * @input The `Core/Tooltip` and `Core/HoverCard` Touch Triggers stories in a
+ *   built Storybook, driven by real Chromium touch input (CDP) in a phone-sized
+ *   viewport.
+ * @output Real-engine proof that a hover layer answers a touch only once it is
+ *   a tap: it opens when the finger lifts, stays shut while a finger rests on
+ *   the trigger, never opens for a touch that turns into a scroll, and a
+ *   tap-opened layer closes when a tap outside lifts or a scroll starts
+ *   outside.
+ * @position Run with `pnpm test:a11y-contract`. Only a real engine decides
+ *   whether a touch is a tap, a scroll or a long press, so these outcomes
+ *   cannot be shown in jsdom; the unit suites (Tooltip.test.tsx,
+ *   HoverCard.test.tsx) cover the same rules on synthetic events.
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+test.use({hasTouch: true, isMobile: true, viewport: {width: 390, height: 844}});
+
+interface Finger {
+  down(x: number, y: number): Promise<void>;
+  move(x: number, y: number): Promise<void>;
+  up(): Promise<void>;
+}
+
+async function openStory(page: Page, id: string): Promise<Finger> {
+  await page.goto(`${storybook.origin}/iframe.html?id=${id}&viewMode=story`);
+  // Room to scroll, so a drag is a page scroll the browser takes from us.
+  await page.evaluate(() => {
+    const spacer = document.createElement('div');
+    spacer.style.height = '2000px';
+    document.body.append(spacer);
+  });
+  const cdp: CDPSession = await page.context().newCDPSession(page);
+  return {
+    down: async (x, y) => {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchStart',
+        touchPoints: [{x, y}],
+      });
+    },
+    move: async (x, y) => {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchMove',
+        touchPoints: [{x, y}],
+      });
+    },
+    up: async () => {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchEnd',
+        touchPoints: [],
+      });
+    },
+  };
+}
+
+async function centerOf(target: Locator): Promise<[number, number]> {
+  const box = await target.boundingBox();
+  if (box == null) {
+    throw new Error('the trigger has no layout box');
+  }
+  return [
+    Math.round(box.x + box.width / 2),
+    Math.round(box.y + box.height / 2),
+  ];
+}
+
+/** A blank point of the page, away from every trigger. */
+const OUTSIDE: [number, number] = [360, 700];
+
+const cases = [
+  {
+    name: 'Tooltip',
+    story: 'core-tooltip--touch-triggers',
+    trigger: (page: Page) => page.getByText('hover-able term', {exact: true}),
+    action: (page: Page) => page.getByRole('button', {name: 'Save'}),
+    layer: '.astryx-tooltip:popover-open',
+  },
+  {
+    name: 'HoverCard',
+    story: 'core-hovercard--touch-triggers',
+    trigger: (page: Page) => page.getByText('Jane Doe', {exact: true}),
+    action: (page: Page) => page.getByRole('button', {name: 'Open profile'}),
+    layer: '.astryx-hover-card:popover-open',
+  },
+];
+
+for (const {name, story, trigger, action, layer} of cases) {
+  test.describe(`${name} under a finger`, () => {
+    test('opens when the tap lifts, not when the finger lands', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await page.waitForTimeout(150);
+      // The finger is still down: it may yet be starting a scroll.
+      await expect(page.locator(layer)).toHaveCount(0);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(1);
+    });
+
+    test('never opens for a touch that turns into a scroll', async ({page}) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      for (let step = 1; step <= 8; step += 1) {
+        await finger.move(x, y - step * 10);
+        await page.waitForTimeout(16);
+      }
+      await finger.up();
+      await page.waitForTimeout(300);
+      await expect(page.locator(layer)).toHaveCount(0);
+    });
+
+    test('stays shut while a finger rests on the trigger', async ({page}) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await page.waitForTimeout(900);
+      // Nothing is decided until the finger lifts; whether a long hold still
+      // counts as a tap then is the engine's call (UIKit's own tap allows a
+      // hold of up to 1.5 s).
+      await expect(page.locator(layer)).toHaveCount(0);
+      await finger.up();
+    });
+
+    test('closes when a tap outside lifts, not when it lands', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(1);
+
+      await finger.down(...OUTSIDE);
+      await page.waitForTimeout(150);
+      await expect(page.locator(layer)).toHaveCount(1);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(0);
+    });
+
+    test('closes as soon as a scroll that starts outside takes the touch', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(trigger(page));
+      await finger.down(x, y);
+      await finger.up();
+      await expect(page.locator(layer)).toHaveCount(1);
+
+      const [ox, oy] = OUTSIDE;
+      await finger.down(ox, oy);
+      for (let step = 1; step <= 8; step += 1) {
+        await finger.move(ox, oy - step * 10);
+        await page.waitForTimeout(16);
+      }
+      // Still down: the scroll took the touch, which is the dismissal.
+      await expect(page.locator(layer)).toHaveCount(0);
+      await finger.up();
+    });
+
+    test('leaves a tap on a trigger that acts to that trigger', async ({
+      page,
+    }) => {
+      const finger = await openStory(page, story);
+      const [x, y] = await centerOf(action(page));
+      await finger.down(x, y);
+      await finger.up();
+      await page.waitForTimeout(300);
+      await expect(page.locator(layer)).toHaveCount(0);
+    });
+  });
+}

package/src/Layer/modalOutlet.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file modalOutlet.ts
- * @input The open Dialog `<dialog>` elements
+ * @input The open Dialog and scrim BottomSheet `<dialog>` elements
  * @output Exports useModalOutlet (a modal supplies its outlet),
  *   getActiveModalOutlet, and subscribeModalOutlets (a global host follows
  *   the latest one)

package/src/Layer/useTouchTrigger.ts

@@ -24,9 +24,21 @@
  * lose, so the tap opens the layer and the next tap outside dismisses it. That
  * is `auto`; `tap` and `none` state the choice outright, which is what an
  * icon-button whose only job is to reveal the layer needs.
+ *
+ * A touch decides nothing until it is a tap. A finger landing on the trigger
+ * may be starting a scroll, a pinch or a long press, and only the browser
+ * knows which once the finger moves or lifts. Its `click` is that verdict (on
+ * iOS it comes from UIKit's own tap recognizer), so the press only records
+ * itself and the tap's `click` opens or closes the layer; a press the browser
+ * takes for scrolling ends in `pointercancel` and never gets there. That is
+ * how a UIKit tap behaves: it recognizes when the finger lifts and fails once
+ * the scroll view claims the touch. The tap outside that closes a tap-opened
+ * layer counts when the finger lifts too, or when a scroll takes the touch,
+ * which is when UIKit dismisses a popover.
  */
 
 import {useCallback, useEffect, useRef, type RefObject} from 'react';
+import {currentGesture} from './gestureCounter';
 import {
   getInteractionModality,
   useInteractionModalityTracking,
@@ -175,7 +187,9 @@ export interface UseTouchTriggerReturn {
   /**
    * Attach to the trigger. Returns true when the press was a touch one and
    * this hook has dealt with it, meaning the caller's own pointer-down
-   * behavior must not also run.
+   * behavior must not also run. A touch press opens or closes nothing by
+   * itself: the hook waits for that press's tap (the `click` the browser
+   * fires when the finger lifts without scrolling) on the same element.
    */
   handlePointerDown: (event: PointerEvent) => boolean;
 
@@ -234,6 +248,9 @@ export function useTouchTrigger(
   const outsideListenerRef = useRef<((event: PointerEvent) => void) | null>(
     null,
   );
+  // A touch press on the trigger still waiting for its tap: calling it stops
+  // waiting. The next press, a cancel, the tap itself or unmounting calls it.
+  const forgetPendingTapRef = useRef<(() => void) | null>(null);
 
   useInteractionModalityTracking();
 
@@ -244,23 +261,30 @@ export function useTouchTrigger(
       return;
     }
     outsideListenerRef.current = null;
-    document.removeEventListener('pointerdown', listener, true);
+    document.removeEventListener('pointerup', listener, true);
+    document.removeEventListener('pointercancel', listener, true);
   }, []);
 
   // Capture phase, so a trigger that stops propagation cannot strand an open
-  // layer. The opening tap's own capture phase at the document has already
-  // passed by the time this runs, so the listener never sees it.
+  // layer. It is armed by the opening tap's `click`, after that tap's own
+  // `pointerup`, so the listener never sees the tap that opened the layer.
+  // A tap outside counts when it lifts (`pointerup`); a scroll or pinch that
+  // starts outside counts as soon as the browser takes it (`pointercancel`).
   const armOutsideDismiss = useCallback(() => {
     isTapOpenRef.current = true;
     if (outsideListenerRef.current != null) {
       return;
     }
 
-    const handleOutsidePointerDown = (event: PointerEvent) => {
+    const handleOutsidePointerEnd = (event: PointerEvent) => {
       const target = event.target as Node | null;
       if (target != null) {
-        // The trigger's own handler owns the toggle.
-        if (triggerRef.current?.contains(target) === true) {
+        // A tap on the trigger is the trigger's to toggle. A scroll that
+        // starts there is a scroll outside the layer, and it does close it.
+        if (
+          event.type === 'pointerup' &&
+          triggerRef.current?.contains(target) === true
+        ) {
           return;
         }
         // Hover card content is interactive; a tap inside it is not a dismiss.
@@ -274,11 +298,13 @@ export function useTouchTrigger(
       hideRef.current();
     };
 
-    outsideListenerRef.current = handleOutsidePointerDown;
-    document.addEventListener('pointerdown', handleOutsidePointerDown, true);
+    outsideListenerRef.current = handleOutsidePointerEnd;
+    document.addEventListener('pointerup', handleOutsidePointerEnd, true);
+    document.addEventListener('pointercancel', handleOutsidePointerEnd, true);
   }, [triggerRef, disarmOutsideDismiss]);
 
   useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+  useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(
     () => isTouchPointerRef.current && getInteractionModality() === 'pointer',
@@ -293,52 +319,80 @@ export function useTouchTrigger(
     isTouchPointerRef.current = event.pointerType === 'touch';
   }, []);
 
+  // What a tap on the trigger does. It runs from the tap's `click`, after the
+  // render that armed it, so it reads the latest props through this ref.
+  const answerTapRef = useRef<() => void>(() => {});
+  answerTapRef.current = () => {
+    const trigger = triggerRef.current;
+    const mode =
+      touchTrigger === 'auto'
+        ? trigger != null && isActionTrigger(trigger)
+          ? 'none'
+          : 'tap'
+        : touchTrigger;
+
+    if (mode === 'none' || !isEnabled) {
+      // A layer left open by an earlier tap must not survive the next one.
+      disarmOutsideDismiss();
+      hide();
+      return;
+    }
+
+    // A lazily mounted layer reports `isOpen` a tick after `show()`, so the
+    // tap's own bookkeeping is what makes the second tap a close.
+    if (isOpenRef.current || isTapOpenRef.current) {
+      disarmOutsideDismiss();
+      hide();
+      return;
+    }
+
+    armOutsideDismiss();
+    show();
+  };
+
   const handlePointerDown = useCallback(
     (event: PointerEvent): boolean => {
       const isTouch = TOUCH_POINTER_TYPES.has(event.pointerType);
       isTouchPointerRef.current = isTouch;
+      // A new press replaces one that never became a tap.
+      forgetPendingTapRef.current?.();
 
       if (!isTouch || isControlled) {
         return false;
       }
 
-      const trigger = triggerRef.current;
-      const mode =
-        touchTrigger === 'auto'
-          ? trigger != null && isActionTrigger(trigger)
-            ? 'none'
-            : 'tap'
-          : touchTrigger;
-
-      if (mode === 'none' || !isEnabled) {
-        // A layer left open by an earlier tap must not survive the next one.
-        disarmOutsideDismiss();
-        hide();
+      const trigger =
+        event.currentTarget instanceof Element
+          ? event.currentTarget
+          : triggerRef.current;
+      if (trigger == null) {
         return true;
       }
 
-      // A lazily mounted layer reports `isOpen` a tick after `show()`, so the
-      // tap's own bookkeeping is what makes the second tap a close.
-      if (isOpenRef.current || isTapOpenRef.current) {
-        disarmOutsideDismiss();
-        hide();
-        return true;
-      }
-
-      armOutsideDismiss();
-      show();
+      // The tap must belong to this press. A key press or a new pointer press
+      // advances the gesture, so a keyboard activation that later fires
+      // `click` on the trigger (Enter on a button) is not mistaken for it.
+      const gesture = currentGesture();
+      const forget = () => {
+        trigger.removeEventListener('click', handleTap);
+        trigger.removeEventListener('pointercancel', forget);
+        if (forgetPendingTapRef.current === forget) {
+          forgetPendingTapRef.current = null;
+        }
+      };
+      const handleTap = () => {
+        forget();
+        if (currentGesture() === gesture) {
+          answerTapRef.current();
+        }
+      };
+      trigger.addEventListener('click', handleTap);
+      // The browser took the touch for a scroll or a pinch: no tap is coming.
+      trigger.addEventListener('pointercancel', forget);
+      forgetPendingTapRef.current = forget;
       return true;
     },
-    [
-      touchTrigger,
-      isEnabled,
-      isControlled,
-      triggerRef,
-      show,
-      hide,
-      armOutsideDismiss,
-      disarmOutsideDismiss,
-    ],
+    [isControlled, triggerRef],
   );
 
   // A layer closed by any other path (Escape, a consumer, the browser) leaves

package/src/NumberInput/NumberInput.doc.mjs

@@ -81,7 +81,7 @@ export const docs = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. Stepping is off in every form while read-only: arrow keys, the wheel, and the number steppers. isDisabled takes precedence when both are set.',
+        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and keeps its form value. Stepping is off in every form while read-only: arrow keys, the wheel, and the number steppers. isDisabled takes precedence when both are set.',
       default: 'false',
     },
     {
@@ -308,7 +308,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
     anatomy: [
@@ -401,7 +401,7 @@ export const docsZh = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留在 Tab 顺序中。只读时所有步进方式均被禁用：方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。',
+        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留其表单值。只读时所有步进方式均被禁用：方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。',
       default: 'false',
     },
     {
@@ -613,7 +613,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
     anatomy: [
@@ -687,7 +687,7 @@ export const docsDense = {
       {
         guidance: false,
         description:
-          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
     anatomy: [
@@ -737,7 +737,7 @@ export const docsDense = {
     isRequired: 'Field required (mutually exclusive w/ isOptional).',
     isDisabled: 'Input disabled.',
     isReadOnly:
-      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed.',
     disabledMessage:
       'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled NumberInput in Tooltip.',
     placeholder: 'Placeholder text.',