feat: add native number field hold stepping

Author: Roy Lin

README.md

@@ -48,8 +48,7 @@ object graph at the host boundary.
   IME/dead-key conformance, measured overlay collision/arrow conformance and
   scroll locking, remaining native focus conformance, message catalogs,
   currency/unit parsing and formatting, date-range/time-zone formatting,
-  continuous NumberField press stepping, and NumberField live announcements
-  are still in progress.
+  and NumberField live announcements are still in progress.
 - `.rsx` component source modules with imports, local Rust types, hook
   registrations, Rust selector/reducer expressions, and a final `rsx!(...)`
   view.

docs/architecture.md

@@ -485,9 +485,15 @@ shared interaction profile marks handled keys and wheels on AppKit, GTK4, and
 WinUI so a toolkit-native numeric control cannot apply a second change. A
 mouse stepper `PressStart` resolves the marked sibling input and requests
 native focus after the platform press, while touch and virtual focus remain on
-their native target. Read-only and disabled fields retain focus semantics but
-do not produce step changes. Continuous press stepping remains a separate
-interaction contract.
+their native target. Marked stepper buttons share a cancellable hold state
+machine across AppKit, GTK4, and WinUI. Mouse and pen presses step immediately,
+start repeating after 400 milliseconds, and repeat every 60 milliseconds.
+Touch defers its first repeat for 600 milliseconds and emits a short tap only
+on release. Leaving the button, pointer cancellation, disabled/read-only state,
+or a step boundary stops the active timer; re-entry starts a fresh cycle.
+Native terminal button activation is consumed so it cannot duplicate the
+portable step. Read-only and disabled fields retain focus semantics but do not
+produce step changes.
 AppKit keeps logical item identity separate from the collection selection
 target: a row button is registered as the ListBoxItem or TreeItem responder,
 while activation reports the selected value to the owning collection.

docs/react-aria-native.md

@@ -288,9 +288,14 @@ The first shared interaction milestone is available in the portable runtime:
   model-space stepping, rejects horizontal-dominant trackpad gestures and
   control-wheel zoom, and can be disabled independently with
   `isWheelDisabled`. Mouse presses on either stepper restore focus to the input.
+  Mouse and pen steppers fire immediately, repeat after a 400-millisecond
+  delay, and continue every 60 milliseconds. Touch steppers defer repeating
+  for 600 milliseconds and preserve short-tap activation on release. Leaving,
+  cancellation, disabled/read-only updates, and step boundaries stop the
+  current cycle; re-entry starts a new one.
   AppKit, GTK4, and WinUI claim handled keys and wheels before the toolkit
-  default runs, preventing native numeric controls from applying a duplicate
-  change.
+  default runs and consume terminal stepper activation, preventing native
+  controls from applying a duplicate change.
 - Native IR capabilities are versioned. Every host exposes a feature manifest
   with unsupported, portable, or native support levels, role-specific
   overrides, and auditable capability issues. Protocol render responses carry
@@ -330,7 +335,7 @@ existence of a platform object:
 | Complete press lifecycle | Button, disclosure summary, link, image-map area, ListBoxItem, and TreeItem on AppKit, GTK4, and WinUI; WinUI menu items also use the complete lifecycle. |
 | Long press | Shared AppKit, GTK4, and WinUI press sources emit start/end and recognize terminal long press after the configured threshold. `NSTimer`, GTK main-loop timeout, and `DispatcherQueueTimer` provide threshold-time delivery, and release-time evaluation is the fallback. |
 | Move | AppKit mouse/pen drag events, GTK4 `GestureDrag`, and WinUI mouse/touch/pen pointer capture use one incremental move state machine. All three normalize Arrow keys to a complete keyboard lifecycle and prevent the underlying native default. |
-| NumberField stepping | The shared runtime maps ArrowUp/ArrowDown/PageUp/PageDown, Home/End, and focused vertical wheels to model-space `Change` events. Wheel input rejects horizontal-dominant gestures and control-wheel zoom, honors `isWheelDisabled`, and AppKit, GTK4, and WinUI suppress handled toolkit defaults. Built-in decrement and increment buttons expose the same next values and boundary/read-only state through native Button controls, and mouse presses preserve input focus. Continuous pointer-hold stepping, automatic localized button messages, and live value announcements remain incomplete. |
+| NumberField stepping | The shared runtime maps ArrowUp/ArrowDown/PageUp/PageDown, Home/End, focused vertical wheels, and stepper presses to model-space `Change` events. Wheel input rejects horizontal-dominant gestures and control-wheel zoom and honors `isWheelDisabled`. Built-in decrement and increment buttons expose the same next values and boundary/read-only state through native Button controls, and mouse presses preserve input focus. AppKit, GTK4, and WinUI share cancellable pointer-hold stepping with immediate mouse/pen activation, delayed touch activation, and 60-millisecond repeats; handled toolkit defaults and terminal native clicks are suppressed. Automatic localized button messages and live value announcements remain incomplete. |
 | Native menu activation | AppKit and GTK4 menu items emit terminal press only because their menu models do not expose a mounted generic view event source. |
 | Hover and typed modality | View-backed widgets; explicit exceptions are reported for AppKit non-view wrappers/items, GTK4 menu items, and the WinUI window wrapper. |
 | Focus within | Portable runtime routing on AppKit, GTK4, WinUI, and headless hosts. Native blur/focus batches are linked with `relatedTarget`; direct focus callbacks remain target-only while focus-within callbacks run only when a subtree boundary is crossed. |
@@ -410,7 +415,7 @@ props:
 | P1 | Event propagation | Add platform-run conformance fixtures for conditional `Stop`/`Continue` across nested native controls. |
 | P1 | Focus management | Add platform-run conformance fixtures for post-mount `autoFocus`, nested containment, and restoration. |
 | P1 | Collections and selection | Complete IME/dead-key typeahead conformance and add real-platform fixtures for layout-aware page navigation. |
-| P1 | NumberField interaction | Add continuous press-and-hold stepping, automatic localized stepper labels, and live value announcements. Group/input/button anatomy, minimum-anchored button stepping, Arrow/Page/Home/End keyboard semantics, focused vertical-wheel stepping with horizontal/zoom rejection and `isWheelDisabled`, mouse input-focus preservation, decimal-noise cleanup, boundary disabling, and native-default suppression are implemented. |
+| P1 | NumberField interaction | Add automatic localized stepper labels and live value announcements. Group/input/button anatomy, minimum-anchored button and continuous press-and-hold stepping, Arrow/Page/Home/End keyboard semantics, focused vertical-wheel stepping with horizontal/zoom rejection and `isWheelDisabled`, mouse input-focus preservation, decimal-noise cleanup, boundary disabling, cancellation/re-entry, and native-default suppression are implemented. |
 | P1 | Internationalization | Add message formatting, currency/unit parsing and formatting, and date ranges/time zones. Reusable decimal/percent parsing and formatting, partial-input validation, locale-aware filtering, and localized NumberField model/display conversion now build on inherited locale/direction. |
 | P1 | Accessibility conformance | Complete OS accessibility API projection, relationships, live regions, value announcements, and role-specific native adapter coverage. |
 | P2 | Overlays | Complete measured boundary-driven collision and arrow projection, native scroll locking, configurable outside-interaction filters, multi-window layer coordination, and real-platform positioning conformance fixtures. |

docs/roadmap.md

@@ -79,8 +79,9 @@ The following foundations are implemented and are not roadmap placeholders:
   localized decimal/percent parsing and partial-input validation, NumberField
   model/display normalization, grouped native stepper controls,
   minimum-anchored button, Arrow/Page/Home/End, and focus-gated vertical-wheel
-  stepping with platform-default suppression, horizontal/zoom rejection, and
-  decimal/percent/date/time formatting
+  stepping, cancellable cross-platform pointer-hold repetition, platform-default
+  suppression, horizontal/zoom rejection, and decimal/percent/date/time
+  formatting
 - an activation-ordered mounted overlay stack with topmost Escape/outside
   dismissal, modal background inertness, portaled foreground layers, and
   shared focus containment, autofocus, and restoration

docs/rsx.md

@@ -1504,8 +1504,13 @@ The accessible-label overrides are optional. Without them, the built-in
 English labels include the field label. Applications should provide localized
 overrides until automatic message catalogs are implemented.
 `isWheelDisabled={true}` disables wheel changes without disabling keyboard or
-button stepping. Mouse stepper presses preserve input focus. Continuous
-press-and-hold and live value announcements are not yet part of this contract.
+button stepping. Mouse stepper presses preserve input focus. Mouse and pen
+steppers fire immediately, begin repeating after 400 milliseconds, and repeat
+every 60 milliseconds. Touch steppers begin repeating after 600 milliseconds;
+a shorter touch activates once on release. Leaving, cancellation, a disabled
+or read-only update, and reaching a step boundary stop repetition. Automatic
+localized stepper labels and live value announcements are not yet part of this
+contract.
 
 - `UiButton`
 - `UiBadge`

src/appkit_native/interaction.rs

@@ -1,7 +1,7 @@
 use super::*;
 use crate::event::{
-    keyboard_move_events, NativeInteractionProfile, NativeLongPressTimer, PointerMoveState,
-    PointerPressState,
+    keyboard_move_events, NativeInteractionProfile, NativeLongPressTimer,
+    NumberFieldStepperPressState, NumberFieldStepperTimer, PointerMoveState, PointerPressState,
 };
 use crate::input::{NativeEventContext, NativeInputModality, NativeKeyModifiers};
 
@@ -66,6 +66,49 @@ impl AppKitLongPressTarget {
     }
 }
 
+#[derive(Debug, Clone)]
+struct AppKitNumberFieldStepperTargetIvars {
+    timer: NumberFieldStepperTimer,
+    events: Rc<RefCell<Vec<NativeEvent>>>,
+}
+
+define_class!(
+    #[unsafe(super(NSObject))]
+    #[thread_kind = MainThreadOnly]
+    #[ivars = AppKitNumberFieldStepperTargetIvars]
+    #[derive(Debug)]
+    struct AppKitNumberFieldStepperTarget;
+
+    impl AppKitNumberFieldStepperTarget {
+        #[unsafe(method(a3sGuiNumberFieldStep:))]
+        fn fire(&self, native_timer: &NSTimer) {
+            if let Some(event) = self.ivars().timer.try_fire(true) {
+                self.ivars().events.borrow_mut().push(event);
+            } else {
+                native_timer.invalidate();
+            }
+        }
+    }
+
+    unsafe impl NSObjectProtocol for AppKitNumberFieldStepperTarget {}
+);
+
+impl AppKitNumberFieldStepperTarget {
+    fn new(
+        timer: NumberFieldStepperTimer,
+        events: Rc<RefCell<Vec<NativeEvent>>>,
+        mtm: MainThreadMarker,
+    ) -> Retained<Self> {
+        let this =
+            Self::alloc(mtm).set_ivars(AppKitNumberFieldStepperTargetIvars { timer, events });
+        unsafe { msg_send![super(this), init] }
+    }
+
+    fn as_any_object(&self) -> &AnyObject {
+        self.as_super().as_super()
+    }
+}
+
 #[derive(Debug, Clone, Copy)]
 pub(super) struct AppKitInteractionRegistration {
     profile: NativeInteractionProfile,
@@ -83,16 +126,33 @@ impl AppKitInteractionRegistration {
     pub(super) fn apply_setter(&mut self, setter: &NativeWidgetSetter) {
         self.profile.apply_setter(setter);
     }
+
+    pub(super) fn is_number_field_stepper(self) -> bool {
+        self.profile.is_number_field_stepper()
+    }
+
+    pub(super) fn tracks_number_field_stepper(self) -> bool {
+        self.profile.tracks_number_field_stepper()
+    }
 }
 
 #[derive(Debug)]
 pub(super) struct AppKitPointerPress {
     pub(super) node: HostNodeId,
     view: Retained<NSView>,
     press_state: Option<PointerPressState>,
+    number_field_stepper: Option<NumberFieldStepperPressState>,
     move_state: PointerMoveState,
 }
 
+impl AppKitPointerPress {
+    pub(super) fn cancel_number_field_stepper(&mut self) {
+        if let Some(state) = self.number_field_stepper.as_mut() {
+            state.cancel();
+        }
+    }
+}
+
 #[derive(Debug)]
 pub(super) struct AppKitHoverTarget {
     pub(super) node: HostNodeId,
@@ -282,6 +342,9 @@ impl AppKitNativeSurface {
             if let Some(state) = previous.press_state.as_mut() {
                 events.extend(state.cancel(previous.node, context));
             }
+            if let Some(state) = previous.number_field_stepper.as_mut() {
+                state.cancel();
+            }
         }
 
         let context = pointer_context(event, &target.view);
@@ -299,18 +362,37 @@ impl AppKitNativeSurface {
         } else {
             (Vec::new(), None)
         };
+        let mut number_field_stepper = target
+            .registration
+            .tracks_number_field_stepper()
+            .then(NumberFieldStepperPressState::default);
+        let (stepper_events, stepper_timer) = if let Some(state) = number_field_stepper.as_mut() {
+            let pending = state.begin(target.node, context);
+            let timer = state.take_timer(target.node, context);
+            (pending, timer)
+        } else {
+            (Vec::new(), None)
+        };
         let mut move_state = PointerMoveState::default();
         if target.registration.profile.tracks_movement() {
             move_state.begin(context);
         }
-        self.events.borrow_mut().extend(pending);
+        {
+            let mut events = self.events.borrow_mut();
+            events.extend(pending);
+            events.extend(stepper_events);
+        }
         if let Some(timer) = timer {
             self.schedule_long_press(timer);
         }
+        if let Some(timer) = stepper_timer {
+            self.schedule_number_field_stepper(timer);
+        }
         *self.pointer_press.borrow_mut() = Some(AppKitPointerPress {
             node: target.node,
             view: target.view,
             press_state,
+            number_field_stepper,
             move_state,
         });
     }
@@ -334,10 +416,22 @@ impl AppKitNativeSurface {
             };
             events.extend(pending);
         }
+        let mut stepper_timer = None;
+        if let Some(state) = active.number_field_stepper.as_mut() {
+            if point_is_inside(&active.view, context) {
+                events.extend(state.enter(active.node, context));
+                stepper_timer = state.take_timer(active.node, context);
+            } else {
+                state.leave();
+            }
+        }
         drop(events);
         if let Some(timer) = timer {
             self.schedule_long_press(timer);
         }
+        if let Some(timer) = stepper_timer {
+            self.schedule_number_field_stepper(timer);
+        }
     }
 
     fn end_pointer_press(&self, event: &NSEvent) {
@@ -371,12 +465,24 @@ impl AppKitNativeSurface {
                     .any(|event| event.kind == NativeEventKind::LongPress);
             self.events.borrow_mut().extend(pending);
         }
+        if let Some(state) = active.number_field_stepper.as_mut() {
+            if over_target {
+                let boundary = state.enter(active.node, context);
+                self.events.borrow_mut().extend(boundary);
+            } else {
+                state.leave();
+            }
+            let pending = state.release(active.node, context);
+            self.events.borrow_mut().extend(pending);
+        }
 
         if over_target && registration.is_some_and(|registration| registration.native_press_action)
         {
+            let handled =
+                long_pressed || registration.is_some_and(|value| value.is_number_field_stepper());
             self.activation_contexts
                 .borrow_mut()
-                .insert(active.node, context.handled_activation(long_pressed));
+                .insert(active.node, context.handled_activation(handled));
         } else {
             self.activation_contexts.borrow_mut().remove(&active.node);
         }
@@ -393,6 +499,9 @@ impl AppKitNativeSurface {
         if let Some(state) = active.press_state.as_mut() {
             events.extend(state.cancel(active.node, context));
         }
+        if let Some(state) = active.number_field_stepper.as_mut() {
+            state.cancel();
+        }
     }
 
     fn schedule_long_press(&self, timer: NativeLongPressTimer) {
@@ -417,6 +526,25 @@ impl AppKitNativeSurface {
         }
     }
 
+    fn schedule_number_field_stepper(&self, timer: NumberFieldStepperTimer) {
+        let initial_delay = timer.initial_delay().as_secs_f64();
+        let interval = timer.repeat_interval().as_secs_f64();
+        let target = AppKitNumberFieldStepperTarget::new(timer, Rc::clone(&self.events), self.mtm);
+        let native_timer = unsafe {
+            NSTimer::timerWithTimeInterval_target_selector_userInfo_repeats(
+                interval,
+                target.as_any_object(),
+                sel!(a3sGuiNumberFieldStep:),
+                None,
+                true,
+            )
+        };
+        native_timer.setFireDate(&NSDate::dateWithTimeIntervalSinceNow(initial_delay));
+        unsafe {
+            NSRunLoop::mainRunLoop().addTimer_forMode(&native_timer, NSRunLoopCommonModes);
+        }
+    }
+
     fn update_hover(&self, event: &NSEvent) {
         let target = self.interaction_target_at_event(event, |registration| {
             registration.profile.subscriptions.hover

src/appkit_native/update.rs

@@ -7,8 +7,22 @@ impl AppKitNativeSurface {
         handle: &AppKitOsHandle,
         setter: &NativeWidgetSetter,
     ) -> GuiResult<()> {
-        if let Some(registration) = self.interaction_nodes.get_mut(&id) {
-            registration.apply_setter(setter);
+        let cancel_number_field_stepper =
+            if let Some(registration) = self.interaction_nodes.get_mut(&id) {
+                registration.apply_setter(setter);
+                !registration.tracks_number_field_stepper()
+            } else {
+                false
+            };
+        if cancel_number_field_stepper {
+            if let Some(active) = self
+                .pointer_press
+                .borrow_mut()
+                .as_mut()
+                .filter(|active| active.node == id)
+            {
+                active.cancel_number_field_stepper();
+            }
         }
         if let Some(config) = self.text_input_configs.get_mut(&id) {
             apply_widget_setter(config, setter);

src/event.rs

@@ -21,7 +21,7 @@ pub(crate) use move_interaction::{keyboard_move_events, PointerMoveState};
 pub(crate) use press::{
     virtual_press_events, KeyboardPressState, NativeInteractionProfile,
     NativeInteractionSubscriptions, NativeLongPressConfig, NativeLongPressMode,
-    NativeLongPressTimer, PointerPressState,
+    NativeLongPressTimer, NumberFieldStepperPressState, NumberFieldStepperTimer, PointerPressState,
 };
 
 /// Maximum number of successful action invocations retained for diagnostics by default.