@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/MultiSelector/MultiSelector.tsx

@@ -905,7 +905,7 @@ export interface MultiSelectorProps<
    * Not called when nothing is selected — the placeholder shows instead — and
    * not called for triggerDisplay 'badges', which renders Badge elements
    * rather than text.
-   * @default items => `${items.length} selected` for 'count', "A, B, C, +N" for 'labels'
+   * @default the translated `@astryx.multiSelector.selectedCount` message ("2 selected") for 'count', "A, B, C, +N" for 'labels'
    */
   formatValue?: (items: MultiSelectorSelectedItem[]) => string;
 
@@ -1215,11 +1215,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the trigger container (which already exists)
-  // and the trigger button stays perceivable via aria-disabled instead of the
-  // disabled attribute. Activation is blocked by the isDisabled guards in
-  // useMultiCombobox (onTriggerClick / onKeyDown).
+  // Disabled-reason tooltip listeners attach to the existing trigger container.
+  // The trigger stays focusable via aria-disabled. Trigger guards and the value
+  // commit guards below block activation, including from an already-open panel.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1450,6 +1448,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    isFocusReturnAlways: hasExternalTrigger,
     popoverOptions: {
       hasLightDismiss: true,
       hasCloseButton: false,
@@ -1546,21 +1545,27 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Announce the filtered result count from the query-change handler (matching
   // BaseTypeahead) rather than a reactive effect: computing the count for the
   // next query here fires the announcement exactly once per keystroke and does
-  // not re-speak on unrelated re-renders. Reuses the announce instance shared
-  // with the selection-count announcements above.
+  // not re-speak on unrelated re-renders. The count, the create row and the
+  // empty panel's message state one thing, how the search ended, so they go
+  // through the search's own `hasReplace` announcer: one the next keystroke
+  // replaces before it is exposed is withdrawn rather than joined
+  // (`spec:AST-086` FR9, FR13), and keystrokes arriving within one frame,
+  // from a scanner, dictation or automation, say only the last query's.
+  // Selection changes keep the plain announcer above, so they still join.
+  const announceSearch = useAnnounce({hasReplace: true});
   const handleSearchChange = useCallback(
     (nextQuery: string) => {
       setSearchQuery(nextQuery);
       if (nextQuery.length === 0) {
         // Emptying the query clears the region rather than announcing a count.
-        announce('');
+        announceSearch('');
         return;
       }
       // While isLoading the panel deliberately shows nothing, so announcing a
       // result would put a claim in the one channel the screen has gone quiet
       // for.
       if (isLoading) {
-        announce('');
+        announceSearch('');
         return;
       }
       const count = filterOptionsByQuery(selectableItems, nextQuery).length;
@@ -1570,7 +1575,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           // The create row is the one result on screen, so the panel is not
           // empty and the rendered-message route below stays silent; say the
           // row.
-          announce(
+          announceSearch(
             t('@astryx.multiSelector.createOption', {query: nextCreateQuery}),
           );
           return;
@@ -1581,9 +1586,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         // keystroke — an async load landing with nothing that matches.
         return;
       }
-      announce(t('@astryx.multiSelector.resultCount', {count}));
+      announceSearch(t('@astryx.multiSelector.resultCount', {count}));
     },
-    [announce, isLoading, selectableItems, getCreateQuery, t],
+    [announceSearch, isLoading, selectableItems, getCreateQuery, t],
   );
 
   // The panel's empty message is role="presentation" — role="listbox" permits
@@ -1608,12 +1613,20 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const realItemCount = sortedItems.length - leadingCount;
   const isPanelEmpty =
     surface.isOpen && !isLoading && realItemCount === 0 && !hasCreateRow;
-  useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
+  // Through the search's announcer: the empty panel is how the search ended,
+  // so it and the count replace each other while not yet exposed
+  // (`spec:AST-086` FR13).
+  useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery, {
+    announce: announceSearch,
+  });
 
   // Handle toggle
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
   const clearValues = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     onChange([]);
     announceSelection([]);
     if (changeAction) {
@@ -1623,6 +1636,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     onChange,
     changeAction,
     startTransition,
@@ -1651,6 +1665,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
 
   const handleToggle = useCallback(
     (itemValue: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(itemValue)
         ? optimisticValue.filter(v => v !== itemValue)
         : [...optimisticValue, itemValue];
@@ -1665,6 +1682,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1699,6 +1717,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       : false;
 
   const handleSelectAll = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     let newValue: string[];
     if (allEnabledSelected) {
       // Deselect all enabled items, keep disabled items that are selected
@@ -1724,6 +1745,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     allEnabledSelected,
     enabledItems,
     optimisticValue,
@@ -1740,6 +1762,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // the option the caller adds is visible.
   const commitCreate = useCallback(
     (query: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(query)
         ? optimisticValue
         : [...optimisticValue, query];
@@ -1754,6 +1779,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1890,7 +1916,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         return (
           <span {...stylex.props(styles.triggerText)}>
             {formatValue?.(selectedItems) ??
-              `${optimisticValue.length} selected`}
+              t('@astryx.multiSelector.selectedCount', {
+                count: optimisticValue.length,
+              })}
           </span>
         );
 
@@ -1933,6 +1961,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     placeholder,
     formatValue,
     maxBadges,
+    t,
   ]);
 
   // Render search input

package/src/NavMenu/NavHeadingMenu.spec.md

@@ -44,7 +44,7 @@ system_specs: [spec:AST-005/DEC-1, spec:AST-020, spec:AST-085]
 | Behavior                | A `role="menu"` list of `menuitem` rows inside a heading popover, with arrow, Home, End, typeahead, Enter, Space, and Escape support. Selecting an enabled item runs it and, where the host heading supplies a close action, closes the heading menu.                 |
 | End-user impact         | Users switch products or accounts from the heading menu by pointer or keyboard; disabled rows are skipped by keyboard and typeahead.                                                                                                                                  |
 | Builder impact          | None.                                                                                                                                                                                                                                                                 |
-| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact).                                                                                                                                                                       |
+| Compatibility/readiness | Records shipped behavior; no public change. Five implementation gaps (see Current-state impact).                                                                                                                                                                       |
 | Review checks           | Reject losing `menu`/`menuitem` roles to caller props, keyboard focus landing on a disabled item, or a caller `onKeyDown` that silently disables the keyboard model.                                                                                                  |
 | Governing rules         | `family:navigation-destinations` FR7; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:layer-runtime`.                                                                                                                    |
 
@@ -81,10 +81,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   `role="menu"` sits directly inside the heading's own `role="menu"` wrapper.
   WAI-ARIA 1.2 allows a `menu` to own only `menuitem`-family items and groups,
   so assistive technology meets a menu nested in a menu.
-- **Inside a heading, arrow keys move twice.** Inside SideNavHeading or
-  TopNavHeading, the heading's own list handler also moves focus over every
-  `menuitem`, so one ArrowDown moves two items, and in a two-item menu ArrowDown
-  never moves focus. The APG menu pattern moves focus one item per arrow press.
 - **The menu has no name of its own.** NavHeadingMenu's `menu` carries no
   accessible name unless the caller passes `aria-label`; inside a heading only
   the heading's wrapper `menu` is named. The APG menu pattern, which

package/src/NavMenu/NavHeadingMenuItem.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/NavMenu/index.ts
  */
 
-import React, {useCallback, useRef, type ReactNode} from 'react';
+import React, {useCallback, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Text} from '../Text';
@@ -23,7 +23,8 @@ import {
   typeScaleVars,
   radiusVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
+import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';
 import type {BaseProps} from '../BaseProps';
 import {useNavHeadingMenuContext} from './NavMenuContext';
 import {useLinkComponent} from '../Link/useLinkComponent';
@@ -156,43 +157,8 @@ export function NavHeadingMenuItem({
   const Element = href ? (isDisabled ? 'a' : LinkComponent) : 'div';
 
   // The element type above changes when `isDisabled` flips, so React replaces
-  // the row. Carry focus over to the replacement when the outgoing node held it
-  // (spec:AST-085 FR4). The ref cleanup runs before the old node is removed, so
-  // `activeElement` is still readable there. Only a different node replacing a
-  // removed one takes focus, and only if focus has fallen to the page: React
-  // also detaches and re-attaches the same node (for example when an <Activity>
-  // boundary hides and reveals the row), and neither case may pull focus back
-  // after the person has moved elsewhere.
-  const focusedNodeRef = useRef<HTMLElement | null>(null);
-  const itemRef = useCallback(
-    (node: HTMLElement | null) => {
-      if (node === null) {
-        return;
-      }
-      const outgoing = focusedNodeRef.current;
-      focusedNodeRef.current = null;
-      // Focus only follows the swap when it has fallen to the page. If the
-      // person moved focus elsewhere in the meantime (for example while an
-      // <Activity> boundary kept the row hidden), leave it alone.
-      const focusFell =
-        document.activeElement === null ||
-        document.activeElement === document.body;
-      if (
-        outgoing !== null &&
-        outgoing !== node &&
-        !outgoing.isConnected &&
-        focusFell
-      ) {
-        node.focus();
-      }
-      const release = mergeRefs<HTMLElement>(ref)(node);
-      return () => {
-        focusedNodeRef.current = document.activeElement === node ? node : null;
-        release?.();
-      };
-    },
-    [ref],
-  );
+  // the row; focus follows to the replacement (spec:AST-085 FR4).
+  const itemRef = useFocusAcrossSwap<HTMLElement>(ref);
 
   return (
     <Element

package/src/NumberInput/NumberInput.doc.mjs

@@ -160,7 +160,7 @@ export const docs = {
       name: 'hasNumberSteppers',
       type: 'boolean',
       description:
-        'Shows increment and decrement buttons at the end of the input.',
+        'Shows increment and decrement buttons at the end of the input on fine pointers. Hidden on coarse pointers (such as touch screens); text entry and keyboard stepping remain available.',
       default: 'false',
     },
     {
@@ -226,12 +226,14 @@ export const docs = {
     {
       name: 'containerClassName',
       type: 'string',
-      description: 'Class name for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Class name for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'containerStyle',
       type: 'CSSProperties',
-      description: 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Inline styles for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'controlXstyle',
@@ -474,7 +476,8 @@ export const docsZh = {
     {
       name: 'hasNumberSteppers',
       type: 'boolean',
-      description: '是否在输入框末尾显示递增和递减按钮。',
+      description:
+        '在精细指针设备上于输入框末尾显示递增和递减按钮。粗指针设备（例如触摸屏）上隐藏按钮；仍可直接输入数值或使用键盘步进。',
       default: 'false',
     },
     {
@@ -720,10 +723,12 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    containerXstyle: 'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
+    containerXstyle:
+      'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
     containerClassName: 'Class name for the field container.',
     containerStyle: 'Inline styles for the field container.',
-    controlXstyle: 'StyleX styles for the visual control box (border, background, icons); not the native input.',
+    controlXstyle:
+      'StyleX styles for the visual control box (border, background, icons); not the native input.',
     controlClassName: 'Class name for the visual control box.',
     controlStyle: 'Inline styles for the visual control box.',
     label: 'Label text (always rendered for accessibility).',
@@ -754,7 +759,8 @@ export const docsDense = {
       'Formats committed value at rest; raw number is shown while editing.',
     isWheelEnabled:
       'Allow focused wheel gestures to step value. Defaults to true.',
-    hasNumberSteppers: 'Show increment + decrement buttons. Defaults to false.',
+    hasNumberSteppers:
+      'Show increment + decrement buttons on fine pointers; hidden on coarse pointers. Defaults to false.',
     units: 'Units suffix (e.g. "%" or "GB").',
     isIntegerOnly: 'Only allow integer values.',
     hasClear:

package/src/NumberInput/NumberInput.spec.md

@@ -6,8 +6,8 @@ id: component:NumberInput
 authority: current
 archive_reason: null
 superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-26
+approved_by: imdreamrunner
+approved_at: 2026-10-29
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
@@ -19,6 +19,7 @@ verified_by:
     packages/core/src/NumberInput/numberParser.docblock.test.ts,
     packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx,
     packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts,
+    packages/core/src/NumberInput/__tests__/NumberInput.coarse-pointer.a11y.chromium.spec.ts,
     packages/core/src/InputGroup/InputGroup.test.tsx,
   ]
 modules: []
@@ -40,15 +41,15 @@ system_specs: [spec:AST-085, spec:AST-086, spec:AST-102]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. NumberInput is a controlled numeric field with Field props, size, status, `min`, `max`, `step`, `isIntegerOnly`, `formatValue`, `units`, steppers, wheel stepping, clear, disabled and read-only states, and the input-family part props. |
-| Behavior                | A text-backed `spinbutton`. Typing edits a draft that commits only on blur or Enter, parsed for the locale and clamped to the range. Arrow keys, the wheel, and the steppers step on a grid and commit at once.                                         |
-| End-user impact         | People can type or paste numbers the way their locale and spreadsheets write them, and get told at once when an entry is invalid. Keyboard and screen-reader users can reach a disabled field. Read-only is not announced.                              |
-| Builder impact          | None.                                                                                                                                                                                                                                                   |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The read-only state is not exposed to assistive technology, and the clear button scales under reduced motion; both are listed under Current-state impact.                                     |
-| Review checks           | Reject an `onChange` for every keystroke, a commit of an unparsable draft, a step off the grid or past a bound, a disabled field that leaves the tab order or submits, or arrows that step during IME composition.                                      |
-| Governing rules         | `family:input-fields` FR3, FR4, FR8–FR11; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR3, FR4; `architecture:internationalization`; `design:reduced-motion` DR1.                                                                                       |
+| Area                    | Contract                                                                                                                                                                                                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | NumberInput is a controlled numeric field with Field props, size, status, `min`, `max`, `step`, `isIntegerOnly`, `formatValue`, `units`, steppers, wheel stepping, clear, disabled and read-only states, and input-family part props.                            |
+| Behavior                | A text-backed `spinbutton`; a typed draft commits on blur or Enter, parsed for the locale and clamped to the range. Arrow keys, the wheel, and available non-coarse-pointer steppers step on a grid and commit at once.                                          |
+| End-user impact         | Coarse-pointer users enter numbers directly instead of using compact steppers. Keyboard stepping remains available. Invalid entries are announced; disabled fields remain reachable; read-only is not announced.                                                 |
+| Builder impact          | Public prop types and numeric callbacks remain unchanged; existing NumberInput calls need no source or configuration migration.                                                                                                                                  |
+| Compatibility/readiness | Coarse-pointer adaptation is non-breaking: numeric values, validation, direct entry, and keyboard stepping remain supported. The read-only exposure and reduced-motion clear-button gaps remain listed under Current-state impact.                               |
+| Review checks           | Reject coarse-pointer steppers, loss of non-coarse-pointer steppers when requested, per-keystroke `onChange`, an unparsable commit, an off-grid or out-of-range step, a disabled field that leaves the tab order or submits, or stepping during IME composition. |
+| Governing rules         | FR5 and AR4 own pointer-conditioned stepper availability; `family:input-fields` FR3, FR4, FR8–FR11; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR3, FR4; `spec:AST-017` FR1, FR3, FR7; `architecture:internationalization`; `design:reduced-motion` DR1.        |
 
 This table is a review projection; the body below is authoritative.
 
@@ -63,12 +64,16 @@ Consumer usage lives in `NumberInput.doc.mjs`.
 
 - Released default preserved: `yes`; `step={1}`, wheel stepping on, no
   steppers, no clear, `size="md"`, `statusVariant="attached"`
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
+- Compatibility class: non-breaking presentation adaptation; public prop
+  names, types, exports, numeric values and callbacks, validation, direct entry,
+  and keyboard stepping remain unchanged under `spec:AST-017` FR3's numeric-stepper
+  presentation rule
 - Controlled/uncontrolled behavior: controlled only; `value` (`number`, `null`,
   or `undefined`) is the committed value, and NumberInput keeps only an
   uncommitted text draft of its own
-- Migration decision: none
+- Migration decision: no caller source or configuration migration; numeric
+  input functionality remains available through direct entry and keyboard
+  stepping while compact visual stepper aids adapt to pointer precision
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -118,7 +123,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR2  | Typing changes only a draft; `onChange` is not called while typing. A draft is valid when it parses for the active locale (grouping, decimal separator, digit script, and sign) and, for validity display, lies within the range and meets integer-only. An invalid draft colors the text secondary, sets `aria-invalid`, and fills a persistent assertive region with the localized invalid-number message.                                                                                                                                                                                                                                                                                                                                                                                      | `spec:AST-086` FR3; `architecture:internationalization`; current tests |
 | FR3  | On blur the draft resolves once and ends: an empty draft clears (`onChange(null)` when clearable and a value exists) or reverts; an unparsable or wrong-kind draft reverts; otherwise the number clamps to the range and commits with `onChange(number)` when it differs from `value`. Enter resolves a valid draft the same way and clears an empty draft when clearable. Enter commits nothing for an empty draft without `hasClear`, which stays in the field and is not marked invalid, or for an unparsable or wrong-kind draft, which stays in the field and stays invalid. Enter ends the draft only when its commit clamped. In a field that is not disabled, every Enter outside composition then calls `onEnter`, whatever it committed.                                                | Current tests                                                          |
 | FR4  | ArrowUp and ArrowDown without modifiers, the wheel over the focused input (when `isWheelEnabled`), and the steppers step by one grid position and commit at once. The grid starts at `min` (when it suits integer-only) or 0. From an empty field or an emptied draft, up goes to `min` or 0 and down to `max` or 0. Results round to the finer of the step's and the grid start's precision (at most 12 decimal places), clamp to the range, and never leave integer-only; a stepper that cannot move does nothing, while an arrow or wheel step that cannot move still ends the draft, committing a valid draft's number and dropping an unparsable one. A caller `onKeyDown` that prevents an arrow cancels that step. A wheel step stops the page from scrolling; otherwise the page scrolls. | Current tests                                                          |
-| FR5  | With `hasNumberSteppers`, increment and decrement buttons render at the end of the control. They are outside the tab order, are named with the localized increment and decrement phrases and the label, keep focus on the input when pressed, and expose `aria-disabled` when stepping that way cannot move or the field is disabled or read-only.                                                                                                                                                                                                                                                                                                                                                                                                                                                | `spec:AST-085` FR1, FR2; current tests                                 |
+| FR5  | With `hasNumberSteppers`, increment and decrement buttons render at the end of the control unless the primary pointer is coarse. On coarse primary pointers the buttons are hidden from layout and the accessibility tree at every viewport width, with no opt-out; the control restores its normal themed end padding. Direct numeric entry and keyboard stepping remain available. When shown, the buttons are outside the tab order, are named with the localized increment and decrement phrases and the label, keep focus on the input when pressed, and expose `aria-disabled` when stepping that way cannot move or the field is disabled or read-only.                                                                                                                                    | `spec:AST-085` FR1, FR2; current tests                                 |
 | FR6  | With `formatValue`, the input shows the formatted committed value at rest and the plain locale-formatted number while focused. The form value is then submitted from a hidden input carrying the raw number, and the visible input has no `name`; without `formatValue` the visible input carries `name`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current tests                                                          |
 | FR7  | `units` renders as secondary text after the input and is part of the input's description.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current tests                                                          |
 | FR8  | With `hasClear`, a clear button shows while `value` is not `null` and the field is editable. Activating it calls `onChange(null)`, drops the draft, and focuses the input as TextInput's clear does. The clear button is a ghost small `component:Button`, so its press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it still scales under reduced motion.                                                                                                                                                                                                                                                                                                                                                                                        | `family:input-fields` FR11; current tests                              |
@@ -168,19 +173,20 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **AR2 — Invalid entry.** FR2's assertive region announces an invalid draft,
   since an invalid draft reverts silently on blur (WCAG 3.3.1).
 - **AR3 — Disabled.** FR9 satisfies `spec:AST-085` FR1, FR5, and FR6.
-- **AR4 — Steppers.** Pointer-only aids; the arrow keys give keyboard users the
-  same stepping (FR4, FR5).
+- **AR4 — Steppers.** Compact pointer-only aids are hidden on coarse primary
+  pointers at every viewport width. Direct numeric entry remains available, and
+  arrow keys provide keyboard stepping on every pointer type (FR4, FR5).
 - **AR5 — Read-only exposure.** A read-only NumberInput MUST expose its
   read-only state to assistive technology (WCAG 2.2 4.1.2). Implementation gap:
   the spinbutton exposes no read-only state.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                        | Representation authority | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Input            | Numeric text; secondary color while the draft is invalid. | Current source and tests | Prominent      | FR2                |
-| Units            | Secondary text after the number.                          | Current source and tests | Supporting     | FR7                |
-| Steppers         | Stacked increment and decrement at the end.               | Current source and tests | Supporting     | FR5, FR13          |
+| Anatomy or state | Design requirement                                                                                            | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Input            | Numeric text; secondary color while the draft is invalid.                                                     | Current source and tests | Prominent      | FR2                |
+| Units            | Secondary text after the number.                                                                              | Current source and tests | Supporting     | FR7                |
+| Steppers         | Stacked at the end on non-coarse pointers; hidden on coarse primary pointers, with normal themed end padding. | FR5; DEC-1               | Supporting     | FR5, FR13          |
 
 `design:reduced-motion` governs the clear button's press scale (FR8); no other
 design record governs NumberInput. The control box carries `number-input`;
@@ -201,19 +207,20 @@ anatomy-theming map.
 
 ## Verification map
 
-| Contract                 | Verification                                                                                                                              | Representative states                           | Mutation or failure expectation                                                                                             | Audit section                     |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1, AR1                 | `NumberInput.test.tsx` spinbutton-attribute suite; `NumberInput.a11y.chromium.spec.ts`                                                    | Bounded, unbounded, formatted                   | A missing role or ARIA value fails.                                                                                         | `audit:NumberInput/accessibility` |
-| FR2, AR2                 | `numberParser.test.ts`; `numberParser.docblock.test.ts`; `NumberInput.test.tsx` invalid-feedback suite                                    | Locales, grouping, invalid text                 | A misparse, a commit of a guess, or a missing announcement fails.                                                           | `audit:NumberInput/behavior`      |
-| FR3, ORD1                | `numberInputCommit.test.ts`; `NumberInput.test.tsx` validation, commit-policy, clamping, keyboard-clearing suites                         | Blur, Enter, empty, clamp, inverted range       | A per-keystroke `onChange`, an unclamped commit, or a wrong clear fails.                                                    | `audit:NumberInput/behavior`      |
-| FR4, FR5, ORD2, AR4, PR1 | `NumberInput.test.tsx` stepping and steppers suites; wheel-listener cases                                                                 | Keys, wheel, steppers; bounds; empty; precision | A step off the grid, past a bound, or with modifiers fails. Evidence gap: no test steps from an emptied draft over a value. | `audit:NumberInput/behavior`      |
-| FR6, FR7                 | `NumberInput.test.tsx` formatted-display, form, and units suites                                                                          | Rest and focus; form submission                 | A formatted value submitted, or units not described, fails.                                                                 | `audit:NumberInput/behavior`      |
-| FR8                      | `NumberInput.test.tsx` hasClear suite                                                                                                     | Clear; disabled; read-only                      | A clear on a disabled field, or no `null`, fails. Evidence gap: no test presses the clear button under reduced motion.      | `audit:NumberInput/behavior`      |
-| FR9, FR10, ORD3, AR3     | `NumberInput.test.tsx` disabled, disabledMessage, read-only, and form suites; `InputGroup.test.tsx` disabled-propagation cases            | Disabled, reason, read-only                     | A lost tab stop, a submitted disabled value, or stepping while read-only fails.                                             | `audit:NumberInput/accessibility` |
-| FR12                     | `NumberInput.fr10.test.tsx`; `NumberInput.test.tsx` status and click-to-focus suites                                                      | Standalone and grouped                          | A base prop off the input, or styling on the wrong part, fails.                                                             | `audit:NumberInput/api`           |
-| FR13                     | `NumberInput.test.tsx` theme-state and stepper-padding suites                                                                             | Each padding spelling                           | Steppers that ignore the theme padding fail.                                                                                | `audit:NumberInput/theming`       |
-| AR5                      | `NumberInput.a11y.chromium.spec.ts` with its recorded known failure                                                                       | Read-only                                       | The known failure stops matching when the gap closes.                                                                       | `audit:NumberInput/accessibility` |
-| FR11                     | `NumberInput.test.tsx` "does not step or commit on a composing keydown (IME)" and "waits for IME composition to finish before committing" | Composing arrows and Enter                      | A step or commit during composition fails.                                                                                  | `audit:NumberInput/behavior`      |
+| Contract                 | Verification                                                                                                                              | Representative states                                                                  | Mutation or failure expectation                                                                                             | Audit section                     |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1, AR1                 | `NumberInput.test.tsx` spinbutton-attribute suite; `NumberInput.a11y.chromium.spec.ts`                                                    | Bounded, unbounded, formatted                                                          | A missing role or ARIA value fails.                                                                                         | `audit:NumberInput/accessibility` |
+| FR2, AR2                 | `numberParser.test.ts`; `numberParser.docblock.test.ts`; `NumberInput.test.tsx` invalid-feedback suite                                    | Locales, grouping, invalid text                                                        | A misparse, a commit of a guess, or a missing announcement fails.                                                           | `audit:NumberInput/behavior`      |
+| FR3, ORD1                | `numberInputCommit.test.ts`; `NumberInput.test.tsx` validation, commit-policy, clamping, keyboard-clearing suites                         | Blur, Enter, empty, clamp, inverted range                                              | A per-keystroke `onChange`, an unclamped commit, or a wrong clear fails.                                                    | `audit:NumberInput/behavior`      |
+| FR4, FR5, ORD2, AR4, PR1 | `NumberInput.test.tsx` stepping and steppers suites; wheel-listener cases                                                                 | Keys, wheel, steppers; bounds; empty; precision                                        | A step off the grid, past a bound, or with modifiers fails. Evidence gap: no test steps from an emptied draft over a value. | `audit:NumberInput/behavior`      |
+| FR6, FR7                 | `NumberInput.test.tsx` formatted-display, form, and units suites                                                                          | Rest and focus; form submission                                                        | A formatted value submitted, or units not described, fails.                                                                 | `audit:NumberInput/behavior`      |
+| FR8                      | `NumberInput.test.tsx` hasClear suite                                                                                                     | Clear; disabled; read-only                                                             | A clear on a disabled field, or no `null`, fails. Evidence gap: no test presses the clear button under reduced motion.      | `audit:NumberInput/behavior`      |
+| FR9, FR10, ORD3, AR3     | `NumberInput.test.tsx` disabled, disabledMessage, read-only, and form suites; `InputGroup.test.tsx` disabled-propagation cases            | Disabled, reason, read-only                                                            | A lost tab stop, a submitted disabled value, or stepping while read-only fails.                                             | `audit:NumberInput/accessibility` |
+| FR12                     | `NumberInput.fr10.test.tsx`; `NumberInput.test.tsx` status and click-to-focus suites                                                      | Standalone and grouped                                                                 | A base prop off the input, or styling on the wrong part, fails.                                                             | `audit:NumberInput/api`           |
+| FR13                     | `NumberInput.test.tsx` theme-state and stepper-padding suites                                                                             | Each padding spelling                                                                  | Steppers that ignore the theme padding fail.                                                                                | `audit:NumberInput/theming`       |
+| AR5                      | `NumberInput.a11y.chromium.spec.ts` with its recorded known failure                                                                       | Read-only                                                                              | The known failure stops matching when the gap closes.                                                                       | `audit:NumberInput/accessibility` |
+| FR11                     | `NumberInput.test.tsx` "does not step or commit on a composing keydown (IME)" and "waits for IME composition to finish before committing" | Composing arrows and Enter                                                             | A step or commit during composition fails.                                                                                  | `audit:NumberInput/behavior`      |
+| FR5, FR13, AR4           | `NumberInput.coarse-pointer.a11y.chromium.spec.ts`                                                                                        | Coarse/non-coarse pointers at 390 and 1280 px, LTR/RTL, non-default themed end padding | Visible coarse-pointer steppers, hidden fine-pointer steppers, wrong end padding, or lost direct/keyboard entry fail.       | `audit:NumberInput/behavior`      |
 
 ## Current-state impact
 
@@ -235,8 +242,23 @@ anatomy-theming map.
 
 ## Decision log
 
-No component-local decision. NumberInput applies `family:input-fields` and
-`spec:AST-085`.
+NumberInput applies `family:input-fields` and `spec:AST-085`.
+
+### DEC-1 — Compact steppers follow primary-pointer precision
+
+**Reference:** `component:NumberInput/DEC-1`
+**Decider:** `imdreamrunner`, `2026-10-29`
+
+Coarse-primary-pointer presentation uses direct numeric entry rather than
+compact steppers, independently of viewport width and without an opt-out.
+Non-coarse-pointer steppers and keyboard stepping retain their contracts.
+The compact buttons are presentation aids: the numeric value, validation,
+callback, direct-entry, and keyboard-stepping contracts do not depend on their
+visibility. Adapting those aids requires no caller source or configuration
+migration.
+
+Rejected: width-based activation, because pointer precision governs this
+control affordance rather than the available layout width.
 
 ## Open questions
 

package/src/NumberInput/NumberInput.tsx

@@ -5,7 +5,7 @@
 /**
  * @file NumberInput.tsx
  * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon, InputGroupContext
- * @output Exports NumberInput component, NumberInputProps
+ * @output Exports NumberInput component, NumberInputProps; optional steppers are hidden on coarse pointers
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -29,6 +29,7 @@ import {
   type KeyboardEvent,
   type ReactNode,
 } from 'react';
+import {flushSync} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -100,7 +101,10 @@ const styles = stylex.create({
     paddingInlineEnd: padInlineEnd,
   },
   wrapperWithNumberSteppers: {
-    paddingInlineEnd: 0,
+    paddingInlineEnd: {
+      default: 0,
+      '@media (pointer: coarse)': padInlineEnd,
+    },
   },
   input: {
     display: 'block',
@@ -142,7 +146,12 @@ const styles = stylex.create({
   },
   numberSteppers: {
     alignSelf: 'stretch',
-    display: 'flex',
+    // These compact buttons are a fine-pointer affordance. Touch users can
+    // enter a value directly; keyboard stepping remains available.
+    display: {
+      default: 'flex',
+      '@media (pointer: coarse)': 'none',
+    },
     flexDirection: 'column',
     flexShrink: 0,
     width: spacingVars['--spacing-4'],
@@ -385,6 +394,8 @@ interface NumberInputPropsBase extends Omit<
   isWheelEnabled?: boolean;
   /**
    * Whether to show increment and decrement buttons at the end of the input.
+   * The buttons are hidden on coarse pointers (such as touch screens).
+   * Direct text entry and keyboard stepping remain available.
    * @default false
    */
   hasNumberSteppers?: boolean;
@@ -708,12 +719,34 @@ export function NumberInput({
   );
 
   // Handle focus
+  // Tab into the field selects its text so typing replaces it. With
+  // `formatValue` the text at rest differs from the editable text, and putting
+  // the editable text in the input after focus collapses that selection to the
+  // end, so typing would append. When focus arrives with the text selected,
+  // the focus handler commits the swap and selects the swapped-in text itself:
+  // the work one event causes stays in its handler
+  // (architecture:react-component-runtime/INV2).
   const handleFocus = useCallback(
     (e: FocusEvent<HTMLInputElement>) => {
+      const input = e.currentTarget;
+      const editableText =
+        pendingInput ??
+        (value == null ? '' : formatEditableNumber(value, locale));
+      const shouldReselect =
+        input.value.length > 0 &&
+        input.value !== editableText &&
+        input.selectionStart === 0 &&
+        input.selectionEnd === input.value.length;
       setIsFocused(true);
       onFocus?.(e);
+      if (shouldReselect) {
+        // Commit the swap now, so the editable text is in the input to select.
+        // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the editable text must be in the input before the focus event selects it
+        flushSync(() => {});
+        input.setSelectionRange(0, input.value.length);
+      }
     },
-    [onFocus],
+    [onFocus, pendingInput, value, locale],
   );
 
   const commitPendingInput = useCallback(