feat: add native number field stepping

Author: Roy Lin

README.md

@@ -27,7 +27,9 @@ object graph at the host boundary.
   background inertness, nested focus containment/restoration, typed anchored
   overlay placement, inherited locale/direction, locale-aware collation and
   filtering, decimal and percent parsing with localized NumberField
-  model/display conversion, decimal/percent/date/time formatting, versioned
+  model/display conversion, minimum-anchored step normalization, grouped
+  decrement/input/increment controls, portable ArrowUp/ArrowDown stepping,
+  decimal/percent/date/time formatting, versioned
   capability reporting, shared native event-source state machines, and
   accessibility conformance checks. Versioned
   native-input manifests expand every role marked
@@ -44,7 +46,8 @@ object graph at the host boundary.
   role-edge input parity, real-platform layout-aware page-navigation fixtures,
   IME/dead-key conformance, measured overlay collision/arrow conformance and
   scroll locking, remaining native focus conformance, message catalogs,
-  currency/unit parsing and formatting, and date-range/time-zone formatting are
+  currency/unit parsing and formatting, date-range/time-zone formatting,
+  continuous NumberField press stepping, and NumberField wheel stepping are
   still in progress.
 - `.rsx` component source modules with imports, local Rust types, hook
   registrations, Rust selector/reducer expressions, and a final `rsx!(...)`

docs/architecture.md

@@ -472,6 +472,15 @@ uses the same public collator filter. Native number text fields use the cached
 parser and formatter for localized display, range/step normalization, and
 model-space change events, so interactive behavior and application-level
 locale rules cannot drift.
+NumberField is represented as a native group with separate decrement button,
+numeric text input, and increment button nodes. The semantic hook computes
+button action values and `canIncrement`/`canDecrement` from the same
+minimum-anchored step grid used by runtime ArrowUp/ArrowDown handling. The
+shared interaction profile marks these keys as handled on AppKit, GTK4, and
+WinUI so a toolkit-native numeric control cannot apply a second increment.
+Read-only and disabled fields retain focus semantics but do not produce step
+changes. Continuous press and wheel stepping are intentionally separate
+remaining interaction contracts.
 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

@@ -272,6 +272,16 @@ The first shared interaction milestone is available in the portable runtime:
   covers localized short through full styles, seconds, calendar,
   numbering-system, and hour-cycle locale extensions. Collection typeahead
   reuses the public collator filter.
+- `use_number_field` exposes separate group, input, increment-button, and
+  decrement-button prop contracts. `UiNumberField` projects that anatomy as a
+  native group instead of collapsing it into one text field. Buttons are
+  excluded from sequential focus, carry the next model-space value, use
+  field-aware accessible labels (or explicit `incrementAriaLabel` and
+  `decrementAriaLabel` overrides), and disable at step boundaries or for
+  disabled/read-only fields. ArrowUp and ArrowDown use the same
+  minimum-anchored step algorithm, including decimal-noise cleanup. AppKit,
+  GTK4, and WinUI claim those keys before the toolkit default runs, preventing
+  GTK4 `SpinButton` from emitting 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
@@ -311,6 +321,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 to model-space `Change` events on the next minimum-anchored step boundary. AppKit, GTK4, and WinUI suppress their underlying key default for marked NumberField inputs. Built-in decrement and increment buttons expose the same next values and boundary/read-only state through native Button controls. Continuous pointer-hold stepping, wheel stepping, 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. |
@@ -390,6 +401,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, focused vertical-wheel stepping with horizontal-trackpad rejection, automatic localized stepper labels, input-focus preservation on pointer press, and live value announcements. Group/input/button anatomy, minimum-anchored button stepping, ArrowUp/ArrowDown stepping, decimal-noise cleanup, boundary disabling, 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

@@ -77,7 +77,9 @@ The following foundations are implemented and are not roadmap placeholders:
   transactional runtime projection for interaction and typed state variants
 - inherited BCP 47 locale/direction, thread-safe ICU4X collation and filtering,
   localized decimal/percent parsing and partial-input validation, NumberField
-  model/display normalization, and decimal/percent/date/time formatting
+  model/display normalization, grouped native stepper controls,
+  minimum-anchored button and ArrowUp/ArrowDown stepping with platform-default
+  suppression, 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

@@ -1477,6 +1477,31 @@ card parts are under `src/rsx_ui/components/card/`, checkbox parts are under
 `src/rsx_ui/components/file/`, and layout semantics are under
 `src/rsx_ui/components/layout/`.
 
+`UiNumberField` renders a label plus a native control group containing
+decrement, numeric-input, and increment controls. Button presses and
+ArrowUp/ArrowDown deliver the next canonical model-space value to `onChange`;
+step boundaries are anchored at `minValue`. Percent fields default to a `0.01`
+step.
+
+```xml
+<UiNumberField
+  key="tax-rate"
+  label="Tax rate"
+  valueNumber={state.taxRate}
+  minValue="0"
+  maxValue="1"
+  formatStyle="percent"
+  incrementAriaLabel="Increase tax rate"
+  decrementAriaLabel="Decrease tax rate"
+  onChange={setTaxRate}
+/>
+```
+
+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. Continuous
+press-and-hold and wheel stepping are not yet part of this contract.
+
 - `UiButton`
 - `UiBadge`
 - `UiAutocomplete`

src/appkit_native/interaction.rs

@@ -199,6 +199,9 @@ impl AppKitNativeSurface {
                 .push(NativeEvent::new(node, kind).value(key).context(context));
             return false;
         };
+        let number_field_step_handled = registration
+            .profile
+            .handles_number_field_step_key(kind, &key);
         let mut pending =
             if kind == NativeEventKind::KeyDown && registration.profile.tracks_movement() {
                 keyboard_move_events(node, &key, context)
@@ -227,7 +230,7 @@ impl AppKitNativeSurface {
                 .borrow_mut()
                 .insert(node, activation_context);
         }
-        movement_handled
+        movement_handled || number_field_step_handled
     }
 
     fn begin_pointer_press(&self, event: &NSEvent) {

src/compiler.rs

@@ -2295,7 +2295,12 @@ fn props_scope_value(props: &CompiledProps) -> JsonValue {
             &mut scope,
             "numberField",
             number_field,
-            &["numberFieldProps", "numberFieldInputProps"],
+            &[
+                "numberFieldProps",
+                "numberFieldInputProps",
+                "incrementButtonProps",
+                "decrementButtonProps",
+            ],
             &[
                 "label",
                 "valueNumber",
@@ -2310,6 +2315,8 @@ fn props_scope_value(props: &CompiledProps) -> JsonValue {
                 "isRequired",
                 "isInvalid",
                 "isReadOnly",
+                "canIncrement",
+                "canDecrement",
             ],
         );
     }
@@ -4165,6 +4172,14 @@ fn number_field_scope_value(props: &CompiledProps) -> GuiResult<JsonValue> {
                 non_empty_prop_action(props.events.get("onChange"))
                     .or_else(|| non_empty_prop_action(props.events.get("onInput"))),
             )
+            .increment_aria_label(non_empty_attribute(
+                props,
+                &["incrementAriaLabel", "increment-aria-label"],
+            ))
+            .decrement_aria_label(non_empty_attribute(
+                props,
+                &["decrementAriaLabel", "decrement-aria-label"],
+            ))
             .disabled(props.is_disabled)
             .required(props.is_required)
             .invalid(props.is_invalid)

src/event/press.rs

@@ -6,7 +6,7 @@ use std::time::{Duration, Instant};
 use crate::event::{NativeEvent, NativeEventKind};
 use crate::host::HostNodeId;
 use crate::input::{NativeEventContext, NativeInputModality};
-use crate::native::NativeRole;
+use crate::native::{is_number_input_type, NativeRole, NUMBER_FIELD_INPUT_METADATA_KEY};
 use crate::platform::{NativeWidgetBlueprint, NativeWidgetSetter};
 
 use super::move_interaction::PointerMoveState;
@@ -227,6 +227,8 @@ pub(crate) struct NativeInteractionProfile {
     has_terminal_event: bool,
     has_long_press_event: bool,
     has_collection_action: bool,
+    number_field_input: bool,
+    number_input: bool,
     enabled: bool,
     long_press_threshold: Duration,
 }
@@ -243,6 +245,11 @@ impl NativeInteractionProfile {
             &["onLongPressStart", "onLongPressEnd", "onLongPress"],
         );
         let has_collection_action = has_collection_action(blueprint);
+        let number_field_input = blueprint
+            .metadata
+            .get(NUMBER_FIELD_INPUT_METADATA_KEY)
+            .is_some_and(|value| value.eq_ignore_ascii_case("true"));
+        let number_input = is_number_input_type(blueprint.control_state.input_type.as_deref());
         let event_subscriptions = NativeInteractionSubscriptions::from_events(
             &blueprint.events,
             has_action || has_collection_action,
@@ -261,6 +268,8 @@ impl NativeInteractionProfile {
             has_terminal_event,
             has_long_press_event,
             has_collection_action,
+            number_field_input,
+            number_input,
             enabled: !blueprint.control_state.disabled,
             long_press_threshold: long_press_threshold(&blueprint.metadata),
         };
@@ -293,10 +302,16 @@ impl NativeInteractionProfile {
                     .get(crate::selection::COLLECTION_ACTION_METADATA_KEY)
                     .is_some_and(|value| value.eq_ignore_ascii_case("true"));
                 self.long_press_threshold = long_press_threshold(metadata);
+                self.number_field_input = metadata
+                    .get(NUMBER_FIELD_INPUT_METADATA_KEY)
+                    .is_some_and(|value| value.eq_ignore_ascii_case("true"));
                 self.overlay_subscriptions =
                     NativeInteractionSubscriptions::from_metadata(metadata);
                 self.refresh_subscriptions();
             }
+            NativeWidgetSetter::SetInputType(input_type) => {
+                self.number_input = is_number_input_type(input_type.as_deref());
+            }
             NativeWidgetSetter::SetPortableStyle(style) => {
                 self.style_subscriptions = NativeInteractionSubscriptions::from_style(style);
                 self.refresh_subscriptions();
@@ -340,6 +355,17 @@ impl NativeInteractionProfile {
         self.enabled && self.subscriptions.movement
     }
 
+    pub(crate) fn handles_number_field_step_key(self, kind: NativeEventKind, key: &str) -> bool {
+        self.enabled
+            && self.number_field_input
+            && self.number_input
+            && kind == NativeEventKind::KeyDown
+            && matches!(
+                super::native_key_value(key).as_str(),
+                "ArrowUp" | "ArrowDown"
+            )
+    }
+
     fn refresh_subscriptions(&mut self) {
         self.event_subscriptions.terminal_press =
             self.has_action || self.has_terminal_event || self.has_collection_action;
@@ -1169,6 +1195,30 @@ mod tests {
         assert!(profile.normalizes_keyboard_press());
     }
 
+    #[test]
+    fn number_field_profiles_claim_only_the_portable_arrow_step_keys() {
+        let element = NativeElement::new("quantity", NativeRole::TextField).with_props(
+            NativeProps::new()
+                .input_type("number")
+                .metadata(NUMBER_FIELD_INPUT_METADATA_KEY, "true"),
+        );
+        let blueprint = AppKitAdapter.blueprint(&element);
+        let mut profile = NativeInteractionProfile::from_blueprint(&blueprint);
+
+        assert!(profile.handles_number_field_step_key(NativeEventKind::KeyDown, "ArrowUp"));
+        assert!(profile.handles_number_field_step_key(NativeEventKind::KeyDown, "Down"));
+        assert!(!profile.handles_number_field_step_key(NativeEventKind::KeyUp, "ArrowUp"));
+        assert!(!profile.handles_number_field_step_key(NativeEventKind::KeyDown, "ArrowLeft"));
+
+        profile.apply_setter(&NativeWidgetSetter::SetInputType(Some("text".to_string())));
+        assert!(!profile.handles_number_field_step_key(NativeEventKind::KeyDown, "ArrowUp"));
+        profile.apply_setter(&NativeWidgetSetter::SetInputType(Some(
+            "number".to_string(),
+        )));
+        profile.apply_setter(&NativeWidgetSetter::SetMetadata(BTreeMap::new()));
+        assert!(!profile.handles_number_field_step_key(NativeEventKind::KeyDown, "ArrowUp"));
+    }
+
     #[test]
     fn collection_action_marker_subscribes_items_without_copying_the_callback() {
         let element = NativeElement::new("ada", NativeRole::ListBoxItem).with_props(

src/gtk4_native/interaction.rs

@@ -136,6 +136,9 @@ fn register_key_events(
         let repeat = down_presses.borrow().target_for_key(&key).is_some();
         let context = keyboard_context(modifiers, repeat);
         let current = down_registration.get();
+        let number_field_step_handled = current
+            .profile
+            .handles_number_field_step_key(NativeEventKind::KeyDown, &key);
         if current.native_button {
             remember_activation_context(&down_contexts, id, context);
         }
@@ -154,7 +157,7 @@ fn register_key_events(
             current.profile.subscriptions.tracks_press(),
         ));
         push_events(&down_events, &down_suppressed, pending);
-        if movement_handled {
+        if movement_handled || number_field_step_handled {
             gtk::glib::Propagation::Stop
         } else {
             gtk::glib::Propagation::Proceed

src/lib.rs

@@ -404,8 +404,8 @@ pub use semantic_ui::{
 };
 pub use semantic_ui::{use_form, use_form_value, FormProps, UseFormProps, UseFormResult};
 pub use semantic_ui::{
-    use_number_field, use_number_field_value, NumberFieldInputProps, NumberFieldProps,
-    UseNumberFieldProps, UseNumberFieldResult,
+    use_number_field, use_number_field_value, NumberFieldButtonProps, NumberFieldInputProps,
+    NumberFieldProps, UseNumberFieldProps, UseNumberFieldResult,
 };
 pub use semantic_ui::{
     use_slider_fill, use_slider_fill_value, use_slider_output, use_slider_output_value,