feat: project native accessibility descriptions

Author: Roy Lin

README.md

@@ -33,7 +33,8 @@ object graph at the host boundary.
   34-locale NumberField accessibility messages, focused value announcements
   and WAI-ARIA live-region updates through native assistive-technology APIs,
   independent visible and accessible labels with native `aria-label`
-  projection,
+  projection, native descriptive accessibility metadata with field-level
+  capability reporting,
   decimal/percent/date/time formatting, versioned
   capability reporting, shared native event-source state machines, and
   accessibility conformance checks. Versioned

docs/react-aria-native.md

@@ -322,6 +322,15 @@ The first shared interaction milestone is available in the portable runtime:
   accessible name; otherwise the visible label is the fallback. AppKit applies
   `setAccessibilityLabel`, GTK4 updates the `GtkAccessible` label property, and
   WinUI calls `AutomationProperties.SetName`.
+- `aria-description`, `aria-roledescription`, `aria-keyshortcuts`, and
+  `aria-valuetext` remain distinct through the same IR and setter path. GTK4
+  projects all four through `GtkAccessible`. AppKit projects description, role
+  description, and value text through `NSAccessibility`; its missing generic
+  shortcut property remains portable. WinUI projects description and shortcuts
+  through UI Automation `HelpText` and `AcceleratorKey`; role description and
+  generic value-text overrides remain portable. Logical AppKit collection/tab
+  items, GTK4 menu-model items, and the WinUI window wrapper report portable
+  coverage instead of silently dropping unsupported native properties.
 - 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
@@ -366,6 +375,7 @@ existence of a platform object:
 | 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. |
 | Live regions | Stable keyed updates implement WAI-ARIA `polite`/`assertive`, `atomic`, `relevant`, and ancestor `busy` semantics in the shared runtime. Implicit alert/status/log/output policies and nested boundaries are honored. AppKit, GTK4, and WinUI deliver the resulting typed message through their native assistive-technology APIs; headless and protocol hosts retain the same ordered command. |
 | Accessible names | `aria-label` is independent from visible native text and is projected through AppKit accessibility labels, GTK4 accessible label properties, and WinUI UI Automation names. Headless and protocol output retain the same computed name. The capability manifest conservatively reports portable-only coverage for AppKit logical list/tree and tab items, GTK4 `gio::MenuItem`, and the WinUI window wrapper. |
+| Accessible descriptions | Description, role-description, shortcut, and value-text metadata have independent executable capabilities. GTK4 projects all four. AppKit projects description, role description, and value text; WinUI projects description and shortcuts. Unsupported field/backend combinations and non-accessible logical wrappers remain available to headless/protocol consumers and produce explicit portable capability issues. |
 | 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. |
@@ -450,7 +460,7 @@ props:
 | P1 | Collections and selection | Complete IME/dead-key typeahead conformance and add real-platform fixtures for layout-aware page navigation. |
 | 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 native relationship, state, and role-specific property projection, close the documented logical-item/window accessible-name exceptions, and add real assistive-technology fixtures. Independent `aria-label` projection, the typed announcement channel, WAI-ARIA live-region diff policy, and focused NumberField value announcements are implemented on AppKit, GTK4, and WinUI. |
+| P1 | Accessibility conformance | Complete native relationship and state projection, close the documented logical-item/window accessible-name and description exceptions, fill the remaining AppKit shortcut and WinUI role-description/value-text gaps, and add real assistive-technology fixtures. Independent `aria-label` and field-level descriptive metadata projection, the typed announcement channel, WAI-ARIA live-region diff policy, and focused NumberField value announcements are implemented with explicit per-backend capabilities. |
 | 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. |

src/appkit_native/update.rs

@@ -72,6 +72,9 @@ impl AppKitNativeSurface {
             NativeWidgetSetter::SetAccessibilityLabel(value) => {
                 set_appkit_accessibility_label(&handle.widget, value.as_deref());
             }
+            NativeWidgetSetter::SetAccessibilityDescription(value) => {
+                set_appkit_accessibility_description(&handle.widget, value);
+            }
             NativeWidgetSetter::SetWindowResizable(value) => {
                 if let AppKitOsWidget::Window(window) = &handle.widget {
                     let mut style = window.styleMask();
@@ -606,7 +609,6 @@ impl AppKitNativeSurface {
             | NativeWidgetSetter::SetHtmlFormAssociation(_)
             | NativeWidgetSetter::SetHtmlCollection(_)
             | NativeWidgetSetter::SetAccessibilityRelationships(_)
-            | NativeWidgetSetter::SetAccessibilityDescription(_)
             | NativeWidgetSetter::SetAccessibilityStructure(_)
             | NativeWidgetSetter::SetAccessibilityState(_)
             | NativeWidgetSetter::SetWebStyle(_)
@@ -634,3 +636,35 @@ fn set_appkit_accessibility_label(widget: &AppKitOsWidget, value: Option<&str>)
         }
     }
 }
+
+fn set_appkit_accessibility_description(
+    widget: &AppKitOsWidget,
+    value: &crate::accessibility::AccessibilityDescriptionProps,
+) {
+    let description = value.description.as_deref().map(ns_string);
+    let role_description = value.role_description.as_deref().map(ns_string);
+    let value_text = value.value_text.as_deref().map(ns_string);
+
+    macro_rules! apply {
+        ($target:expr) => {{
+            let target = $target;
+            target.setAccessibilityHelp(description.as_deref());
+            target.setAccessibilityRoleDescription(role_description.as_deref());
+            target.setAccessibilityValueDescription(value_text.as_deref());
+        }};
+    }
+
+    match widget {
+        AppKitOsWidget::Window(window) => apply!(window),
+        AppKitOsWidget::Panel(panel) => apply!(panel),
+        AppKitOsWidget::Popover(state) => apply!(&state.popover),
+        AppKitOsWidget::Menu(menu) => apply!(menu),
+        AppKitOsWidget::MenuItem(item) => apply!(item),
+        AppKitOsWidget::ComboBoxItem(_) | AppKitOsWidget::TabViewItem(_) => {}
+        _ => {
+            if let Some(view) = widget.as_view() {
+                apply!(view);
+            }
+        }
+    }
+}

src/capability.rs

@@ -27,6 +27,10 @@ pub enum NativeCapabilityFeature {
     AnchoredOverlayPosition,
     AccessibilityRole,
     AccessibilityName,
+    AccessibilityDescription,
+    AccessibilityRoleDescription,
+    AccessibilityKeyShortcuts,
+    AccessibilityValueText,
     AccessibilityRelationships,
     AccessibilityState,
     AccessibilityAnnouncements,
@@ -257,6 +261,87 @@ impl NativeCapabilities {
                     "computed names use the backend's native accessibility-name property"
                 }),
             ),
+            NativeFeatureCapability::new(
+                Feature::AccessibilityDescription,
+                if headless { Portable } else { Native },
+                Some(match backend {
+                    NativeBackendKind::AppKit => {
+                        "descriptions use the native NSAccessibility help property"
+                    }
+                    NativeBackendKind::Gtk4 => {
+                        "descriptions use the native GtkAccessible description property"
+                    }
+                    NativeBackendKind::WinUI => {
+                        "descriptions use the native UI Automation help-text property"
+                    }
+                    NativeBackendKind::Headless => {
+                        "headless mode retains descriptions without an OS accessibility object"
+                    }
+                }),
+            ),
+            NativeFeatureCapability::new(
+                Feature::AccessibilityRoleDescription,
+                match backend {
+                    NativeBackendKind::AppKit | NativeBackendKind::Gtk4 => Native,
+                    NativeBackendKind::WinUI | NativeBackendKind::Headless => Portable,
+                },
+                Some(match backend {
+                    NativeBackendKind::AppKit => {
+                        "role descriptions use the native NSAccessibility role-description property"
+                    }
+                    NativeBackendKind::Gtk4 => {
+                        "role descriptions use the native GtkAccessible role-description property"
+                    }
+                    NativeBackendKind::WinUI => {
+                        "role descriptions remain in portable accessibility output because the current WinUI binding has no exact attached-property setter"
+                    }
+                    NativeBackendKind::Headless => {
+                        "headless mode retains role descriptions without an OS accessibility object"
+                    }
+                }),
+            ),
+            NativeFeatureCapability::new(
+                Feature::AccessibilityKeyShortcuts,
+                match backend {
+                    NativeBackendKind::Gtk4 | NativeBackendKind::WinUI => Native,
+                    NativeBackendKind::AppKit | NativeBackendKind::Headless => Portable,
+                },
+                Some(match backend {
+                    NativeBackendKind::AppKit => {
+                        "key shortcuts remain in portable accessibility output because NSAccessibility has no equivalent setter"
+                    }
+                    NativeBackendKind::Gtk4 => {
+                        "key shortcuts use the native GtkAccessible key-shortcuts property"
+                    }
+                    NativeBackendKind::WinUI => {
+                        "key shortcuts use the native UI Automation accelerator-key property"
+                    }
+                    NativeBackendKind::Headless => {
+                        "headless mode retains key shortcuts without an OS accessibility object"
+                    }
+                }),
+            ),
+            NativeFeatureCapability::new(
+                Feature::AccessibilityValueText,
+                match backend {
+                    NativeBackendKind::AppKit | NativeBackendKind::Gtk4 => Native,
+                    NativeBackendKind::WinUI | NativeBackendKind::Headless => Portable,
+                },
+                Some(match backend {
+                    NativeBackendKind::AppKit => {
+                        "value text uses the native NSAccessibility value-description property"
+                    }
+                    NativeBackendKind::Gtk4 => {
+                        "value text uses the native GtkAccessible value-text property"
+                    }
+                    NativeBackendKind::WinUI => {
+                        "value text remains in portable accessibility output because WinUI has no generic attached-property override for a control pattern value"
+                    }
+                    NativeBackendKind::Headless => {
+                        "headless mode retains value text without an OS accessibility object"
+                    }
+                }),
+            ),
             NativeFeatureCapability::new(
                 Feature::AccessibilityRelationships,
                 Portable,
@@ -399,6 +484,22 @@ impl NativeCapabilities {
                                 "AppKit logical combo-box/list and tab items retain the computed name in portable accessibility output but do not expose an independent native accessibility-label setter",
                             ),
                         );
+                        for feature in [
+                            Feature::AccessibilityDescription,
+                            Feature::AccessibilityRoleDescription,
+                            Feature::AccessibilityKeyShortcuts,
+                            Feature::AccessibilityValueText,
+                        ] {
+                            set_role_capability(
+                                &mut role_overrides,
+                                role,
+                                feature,
+                                Portable,
+                                Some(
+                                    "AppKit logical combo-box/list and tab items retain descriptive accessibility metadata in portable output but do not expose an independent native accessibility-property setter",
+                                ),
+                            );
+                        }
                     }
                 }
                 NativeBackendKind::Gtk4 => {
@@ -411,6 +512,22 @@ impl NativeCapabilities {
                             "GTK4 gio::MenuItem retains the computed name in portable accessibility output but has no independent GtkAccessible label property",
                         ),
                     );
+                    for feature in [
+                        Feature::AccessibilityDescription,
+                        Feature::AccessibilityRoleDescription,
+                        Feature::AccessibilityKeyShortcuts,
+                        Feature::AccessibilityValueText,
+                    ] {
+                        set_role_capability(
+                            &mut role_overrides,
+                            NativeRole::MenuItem,
+                            feature,
+                            Portable,
+                            Some(
+                                "GTK4 gio::MenuItem retains descriptive accessibility metadata in portable output but has no independent GtkAccessible property",
+                            ),
+                        );
+                    }
                 }
                 NativeBackendKind::WinUI => {
                     set_role_capability(
@@ -422,6 +539,22 @@ impl NativeCapabilities {
                             "the WinUI Window wrapper retains the computed name in portable accessibility output but is not a UIElement AutomationProperties target",
                         ),
                     );
+                    for feature in [
+                        Feature::AccessibilityDescription,
+                        Feature::AccessibilityRoleDescription,
+                        Feature::AccessibilityKeyShortcuts,
+                        Feature::AccessibilityValueText,
+                    ] {
+                        set_role_capability(
+                            &mut role_overrides,
+                            NativeRole::Window,
+                            feature,
+                            Portable,
+                            Some(
+                                "the WinUI Window wrapper retains descriptive accessibility metadata in portable output but is not a UIElement AutomationProperties target",
+                            ),
+                        );
+                    }
                 }
                 NativeBackendKind::Headless => {}
             }
@@ -658,6 +791,18 @@ fn requested_features(role: NativeRole, props: &NativeProps) -> Vec<NativeCapabi
     if props.accessibility_label.is_some() && props.accessibility_label != props.label {
         features.push(Feature::AccessibilityName);
     }
+    if props.accessibility_description.description.is_some() {
+        features.push(Feature::AccessibilityDescription);
+    }
+    if props.accessibility_description.role_description.is_some() {
+        features.push(Feature::AccessibilityRoleDescription);
+    }
+    if props.accessibility_description.key_shortcuts.is_some() {
+        features.push(Feature::AccessibilityKeyShortcuts);
+    }
+    if props.accessibility_description.value_text.is_some() {
+        features.push(Feature::AccessibilityValueText);
+    }
     if props.accessibility_relationships != Default::default() {
         features.push(Feature::AccessibilityRelationships);
     }