feat: add localized number field announcements

Author: Roy Lin

Cargo.toml

@@ -139,6 +139,7 @@ objc2-app-kit = { version = "0.3.2", default-features = false, features = [
     "objc2-core-foundation",
     "objc2-core-graphics",
     "objc2-quartz-core",
+    "NSAccessibilityConstants",
     "NSApplication",
     "NSBox",
     "NSButton",
@@ -177,6 +178,7 @@ objc2-foundation = { version = "0.3.2", default-features = false, features = [
     "std",
     "NSDate",
     "NSGeometry",
+    "NSValue",
     "NSObject",
     "NSRunLoop",
     "NSString",
@@ -189,7 +191,7 @@ objc2-quartz-core = { version = "0.3.2", default-features = false, features = [
 ], optional = true }
 
 [target.'cfg(target_os = "linux")'.dependencies]
-gtk4_crate = { package = "gtk4", version = "0.11.4", optional = true }
+gtk4_crate = { package = "gtk4", version = "0.11.4", features = ["v4_14"], optional = true }
 
 [target.'cfg(target_os = "windows")'.dependencies]
 windows = { version = "0.62.0", optional = true, features = [

README.md

@@ -30,6 +30,8 @@ object graph at the host boundary.
   model/display conversion, minimum-anchored step normalization, grouped
   decrement/input/increment controls, portable Arrow/Page/Home/End and
   focus-gated wheel stepping with native default suppression,
+  34-locale NumberField accessibility messages, focused value announcements
+  through native assistive-technology APIs,
   decimal/percent/date/time formatting, versioned
   capability reporting, shared native event-source state machines, and
   accessibility conformance checks. Versioned
@@ -46,9 +48,9 @@ object graph at the host boundary.
   Populating the AppKit and GTK4 manifests with real platform automation,
   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,
+  scroll locking, remaining native focus conformance, broader message catalogs,
   currency/unit parsing and formatting, date-range/time-zone formatting,
-  and NumberField live announcements are still in progress.
+  and complete native accessibility-property projection 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

@@ -453,8 +453,8 @@ prefers the GDK Unicode scalar over its symbolic key name, and WinUI uses
 falling back to a stable virtual-key name. Full IME and dead-key composition
 remains an adapter conformance gap.
 `I18nManager` also resolves that inherited locale for reusable
-`LocaleCollator`, `LocaleNumberParser`, `LocaleNumberFormatter`, and
-`LocaleDateFormatter` objects.
+`LocaleCollator`, `LocaleNumberParser`, `LocaleNumberFormatter`,
+`LocaleDateFormatter`, and `LocaleMessageFormatter` objects.
 The public collator exposes search/sort usage, ECMA-402 sensitivity,
 case-first, numeric ordering, and locale-equivalent starts-with, ends-with, and
 contains filters. Decimal parsing exposes complete parsing, partial-input
@@ -472,6 +472,11 @@ 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.
+`LocaleMessageFormatter` owns the small accessibility-message layer that must
+follow inherited locale even though no Web runtime exists. Its NumberField
+catalog contains the same decrease, increase, numeric-role, and empty-value
+messages for 34 React Aria locales. Language fallback is deterministic, with
+separate Portuguese regions and simplified/traditional Chinese resolution.
 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
@@ -494,6 +499,16 @@ 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.
+Automatic stepper labels and the numeric-input role description are projected
+after locale inheritance, so custom labels remain untouched while native
+buttons receive localized defaults. A focused marked numeric input compares
+its previous and current normalized accessible value after reconciliation.
+Changes emit an assertive `AccessibilityAnnouncement`; empty values use the
+effective locale's message and ASCII minus signs are normalized to U+2212.
+`AccessibilityAnnouncementHost` is an optional host capability. The planning
+host serializes it, headless records it, and the native command stack forwards
+it to AppKit accessibility notifications, GTK4 accessible announcements, or
+WinUI UI Automation notifications.
 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.
@@ -839,6 +854,13 @@ to execute:
 - `{"type": "insertChild", "parent": ..., "child": ..., "index": ...}`
 - `{"type": "remove", "id": ...}`
 - `{"type": "setRoot", "id": ...}`
+- `{"type": "requestFocus", "id": ...}`
+- `{"type": "positionOverlay", "overlay": ..., "anchor": ..., "request": ...}`
+- `{"type": "accessibilityAnnouncement", "announcement": {"node": ..., "message": ..., "priority": "assertive"}}`
+
+Strict protocol v1 flattens the same announcement payload beside its command
+type (`node`, `message`, and `priority`) and validates a non-zero target plus a
+non-empty message during decoding.
 
 The planning host's command vector is a pending delivery queue, not cumulative
 diagnostic history. `take_commands()` moves all commands produced since the
@@ -937,6 +959,9 @@ before native handles or recorded backend objects are replaced.
 - `insert_child(parent, child, index)`
 - `remove_widget(id)`
 - `set_root_widget(id)`
+- `request_focus(id)`
+- `position_overlay(overlay, anchor, request)`
+- `announce_accessibility(announcement)`
 
 If the platform layer owns event callbacks, it also implements
 `NativeEventSource::take_native_events()` and queues `NativeEvent` records such
@@ -1162,8 +1187,9 @@ Feature-gated platform executor surfaces:
   `autoCapitalize`, `autoCorrect`,
   `virtualKeyboardPolicy`, and `spellCheck` into GTK input purpose and input
   hint flags. It is a Linux-only feature so macOS and Windows builds can enable
-  all portable features without linking GTK. Linux builds require GTK4
-  development libraries and `pkg-config`.
+  all portable features without linking GTK. Linux builds require GTK 4.14 or
+  newer development libraries and `pkg-config`; 4.14 provides the native
+  accessible announcement API used by the typed announcement command.
   GTK callbacks enqueue press, text change, focus, blur, toggle, and
   selection-change events through the same `NativeEventSource` and action
   routing path as AppKit. GTK widgets also attach `EventControllerKey`

docs/packaging.md

@@ -92,7 +92,8 @@ The crate does not currently generate a `.dmg` or `.pkg`.
 
 Prerequisites:
 
-- GTK4 development libraries.
+- GTK 4.14 or newer development libraries. The native accessibility
+  announcement API is part of the required backend contract.
 - `pkg-config`.
 - A Linux package toolchain only when producing distro packages.
 

docs/react-aria-native.md

@@ -260,8 +260,11 @@ The first shared interaction milestone is available in the portable runtime:
   keyed native tree. Scoped overrides and default locale changes are preserved
   across rerenders, and BCP 47 language/script subtags provide deterministic
   RTL inference. It creates reusable, thread-safe `LocaleCollator`,
-  `LocaleNumberParser`, `LocaleNumberFormatter`, and `LocaleDateFormatter`
-  values from the effective node locale. Collation covers search/sort
+  `LocaleNumberParser`, `LocaleNumberFormatter`, `LocaleDateFormatter`, and
+  `LocaleMessageFormatter` values from the effective node locale. The message
+  formatter includes React Aria-compatible NumberField labels, role
+  descriptions, and empty-value text for 34 locales with deterministic
+  language/script/region fallback. Collation covers search/sort
   sensitivity, case-first, numeric ordering, and locale-equivalent prefix,
   suffix, and substring filtering. Stable ICU4X decimal parsing covers
   localized signs and separators, partial-input validation, and automatic
@@ -296,6 +299,14 @@ The first shared interaction milestone is available in the portable runtime:
   AppKit, GTK4, and WinUI claim handled keys and wheels before the toolkit
   default runs and consume terminal stepper activation, preventing native
   controls from applying a duplicate change.
+  Default stepper labels and the numeric-input role description are localized
+  from the inherited locale; explicit stepper-label overrides remain
+  authoritative. When the focused input's normalized accessible value changes,
+  the runtime emits an assertive typed announcement. AppKit posts
+  `NSAccessibilityAnnouncementRequestedNotification`, GTK4 calls
+  `gtk_accessible_announce`, and WinUI raises a UI Automation notification.
+  Empty values use the same locale catalog, and negative announcements use the
+  screen-reader-friendly Unicode minus sign.
 - 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
@@ -335,7 +346,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, 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. |
+| 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. Default stepper labels, the role description, and empty-value text follow a 34-locale catalog. Focused value changes emit assertive native accessibility announcements on all three backends. |
 | 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. |
@@ -415,9 +426,9 @@ 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 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. |
+| P1 | NumberField interaction | Add real-platform assistive-technology fixtures for localized labels and focused announcements. Group/input/button anatomy, localized stepper labels and role descriptions, focused native value announcements, 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 | Expand message formatting beyond NumberField, and add currency/unit parsing and formatting plus date ranges/time zones. Reusable decimal/percent parsing and formatting, partial-input validation, locale-aware filtering, localized NumberField model/display conversion, and a 34-locale NumberField message catalog now build on inherited locale/direction. |
+| P1 | Accessibility conformance | Complete OS accessibility-property projection, relationships, general live regions, and role-specific native adapter coverage. The typed announcement channel and focused NumberField value announcements are implemented on AppKit, GTK4, and WinUI. |
 | 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. |
 | P2 | Capability enforcement | Turn reported capability gaps into adapter policy and conformance gates where portable fallback is not sufficient. |
 | P2 | Environment style variants | Add native environment and ancestry evaluators for responsive/container, theme, group, peer, and structural selector variants. These remain preserved in the style IR but inactive at runtime today. |

docs/roadmap.md

@@ -80,8 +80,9 @@ The following foundations are implemented and are not roadmap placeholders:
   model/display normalization, grouped native stepper controls,
   minimum-anchored button, Arrow/Page/Home/End, and focus-gated vertical-wheel
   stepping, cancellable cross-platform pointer-hold repetition, platform-default
-  suppression, horizontal/zoom rejection, and decimal/percent/date/time
-  formatting
+  suppression, horizontal/zoom rejection, a 34-locale NumberField accessibility
+  catalog, assertive focused-value announcements on AppKit/GTK4/WinUI, 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

@@ -1500,17 +1500,19 @@ and control-wheel zoom are ignored. Step boundaries are anchored at
 />
 ```
 
-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.
+The accessible-label overrides are optional. Without them, the built-in labels
+include the field label and follow the inherited locale through the 34-locale
+NumberField message catalog. Explicit overrides are never replaced.
 `isWheelDisabled={true}` disables wheel changes without disabling keyboard or
 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.
+or read-only update, and reaching a step boundary stop repetition. The numeric
+input also receives a localized role description. While it is focused,
+normalized value changes are announced assertively through AppKit, GTK4, or
+WinUI's native assistive-technology channel; empty values are localized as
+well.
 
 - `UiButton`
 - `UiBadge`

src/accessibility.rs

@@ -10,6 +10,40 @@ pub use conformance::{
 #[cfg(test)]
 mod conformance_tests;
 
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum AccessibilityAnnouncementPriority {
+    #[default]
+    Polite,
+    Assertive,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccessibilityAnnouncement {
+    pub node: HostNodeId,
+    pub message: String,
+    pub priority: AccessibilityAnnouncementPriority,
+}
+
+impl AccessibilityAnnouncement {
+    pub fn new(
+        node: HostNodeId,
+        message: impl Into<String>,
+        priority: AccessibilityAnnouncementPriority,
+    ) -> Self {
+        Self {
+            node,
+            message: message.into(),
+            priority,
+        }
+    }
+
+    pub fn assertive(node: HostNodeId, message: impl Into<String>) -> Self {
+        Self::new(node, message, AccessibilityAnnouncementPriority::Assertive)
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub enum AccessibilityRole {