feat: resolve native accessibility relationships

Author: Roy Lin

Cargo.lock

@@ -109,6 +109,7 @@ winui = []
 winui-native = [
     "winui",
     "dep:windows",
+    "dep:windows-collections",
     "dep:windows-core",
     "dep:winui3",
 ]
@@ -207,6 +208,7 @@ windows = { version = "0.62.0", optional = true, features = [
     "Win32_UI_Shell",
     "Win32_UI_WindowsAndMessaging",
 ] }
+windows-collections = { version = "0.3.2", optional = true }
 windows-core = { version = "0.62.0", optional = true }
 winui3 = { package = "winio-winui3", version = "0.4.2", optional = true, features = [
     "UI_Composition",

Cargo.toml

@@ -34,8 +34,10 @@ object graph at the host boundary.
   and WAI-ARIA live-region updates through native assistive-technology APIs,
   independent visible and accessible labels with native `aria-label`
   projection, native descriptive accessibility metadata with field-level
-  capability reporting, validated ARIA state tokens with field-level native
-  capability reporting and exact AppKit/GTK4 projection where supported,
+  capability reporting, resolvable accessibility ID-reference relationships
+  with exact GTK4 and supported AppKit/WinUI projection, validated ARIA state
+  tokens with field-level native capability reporting and exact AppKit/GTK4
+  projection where supported,
   decimal/percent/date/time formatting, versioned
   capability reporting, shared native event-source state machines, and
   accessibility conformance checks. Versioned
@@ -54,7 +56,7 @@ object graph at the host boundary.
   IME/dead-key conformance, measured overlay collision/arrow conformance and
   scroll locking, remaining native focus conformance, broader message catalogs,
   currency/unit parsing and formatting, date-range/time-zone formatting,
-  complete native accessibility relationship and remaining state/role-edge
+  remaining AppKit/WinUI accessibility relationship and state/role-edge
   projection,
   and real-platform assistive-technology fixtures are still in progress.
 - `.rsx` component source modules with imports, local Rust types, hook

README.md

@@ -271,7 +271,15 @@ rerender updates, and when native change events arrive.
 ARIA relationship attributes including `aria-labelledby`, `aria-describedby`,
 `aria-details`, `aria-controls`, `aria-owns`, `aria-flowto`,
 `aria-errormessage`, and `aria-activedescendant` project into structured
-native accessibility relationship hints and stay available in metadata.
+native accessibility relationship hints and stay available in metadata. A
+shared native registry resolves their ID-reference lists against mounted node
+`id` metadata, including forward references, id changes, removal, and
+duplicate-id ambiguity. GTK4 projects all eight relationships through
+`GtkAccessible`. WinUI projects described-by, controls, and flow-to lists plus
+a single labelled-by target through UI Automation. AppKit projects a single
+static-text labelled-by target as its title UI element. Remaining
+backend/field combinations and non-accessible wrappers retain portable
+semantics and report field-level capability issues.
 ARIA description and value attributes including `aria-description`,
 `aria-roledescription`, `aria-keyshortcuts`, and `aria-valuetext` project into
 structured native accessibility description hints and stay available in metadata.

docs/architecture.md

@@ -331,6 +331,17 @@ The first shared interaction milestone is available in the portable runtime:
   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.
+- Accessibility relationship ID references resolve to mounted host nodes through
+  one shared registry. Forward references bind when their target mounts; target
+  id changes and removal rebind or clear dependents; duplicate ids stay
+  unresolved instead of selecting an arbitrary node. GTK4 projects
+  `aria-labelledby`, `aria-describedby`, `aria-details`, `aria-controls`,
+  `aria-owns`, `aria-flowto`, `aria-errormessage`, and
+  `aria-activedescendant`. WinUI projects complete description, control, and
+  flow-to lists plus a single label target. AppKit projects a single resolved
+  static-text label through its title UI element. Every relationship field has
+  an independent capability entry, including explicit portable exceptions for
+  logical GTK4 menu items and the WinUI window wrapper.
 - Accessibility state fields remain independent through native props, setter
   diffs, recording, accessibility-tree projection, and capability audits.
   AppKit projects `aria-hidden` and `aria-modal` through `NSAccessibility`.
@@ -348,11 +359,11 @@ The first shared interaction milestone is available in the portable runtime:
 - Accessibility conformance validates names, focus uniqueness, selection and
   checked states, exclusive-container selection, relationships, and duplicate
   node identity. Invalid `aria-autocomplete`, `aria-current`, `aria-haspopup`,
-  `aria-pressed`, `aria-live`, and `aria-relevant` values are reported as
-  errors rather than silently changing state or announcement behavior. The
-  same semantic tree assertions run against AppKit, GTK4, and WinUI planning
-  adapters. Mounted selection is the source of truth for accessible
-  selected/checked state.
+  `aria-pressed`, `aria-live`, and `aria-relevant` values, plus a
+  multi-reference `aria-activedescendant`, are reported as errors rather than
+  silently changing state or announcement behavior. The same semantic tree
+  assertions run against AppKit, GTK4, and WinUI planning adapters. Mounted
+  selection is the source of truth for accessible selected/checked state.
 - AppKit, GTK4, and WinUI use the same press and keyboard state machines. Their
   view-backed widgets emit pointer press/re-entry/cancellation, hover, focus,
   key, modality, modifier, repeat, and local-position data through one portable
@@ -387,6 +398,7 @@ existence of a platform object:
 | 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. |
+| Accessible relationships | A shared registry resolves ID-reference lists across forward mounting, id changes, removal, and duplicate-id ambiguity. GTK4 projects all eight relationship fields. WinUI projects description, controls, and flow-to lists plus single-target labels; AppKit projects single static-text labels. Remaining backend/field combinations and non-accessible wrappers retain portable semantics and produce field-level capability issues. |
 | Accessible states | Hidden, autocomplete, multiline, current, popup, pressed, live-region, busy, and modal semantics have independent executable capabilities. AppKit projects hidden and modal; GTK4 projects hidden, autocomplete, multiline, popup presence, pressed, busy, and modal. Live-region policy is evaluated by the shared runtime and delivered through each backend's native announcement channel. WinUI direct-state gaps, `aria-current`, the GTK4 popup subtype, and logical wrapper exceptions remain portable and auditable instead of being silently dropped. |
 | 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. |
@@ -472,7 +484,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 projection, add exact native mappings for remaining state gaps such as `aria-current` and direct AppKit/WinUI autocomplete, multiline, popup, pressed, and busy semantics where platform APIs permit, close the documented logical-item/window name, description, state, and announcement exceptions, fill the remaining AppKit shortcut and WinUI role-description/value-text gaps, and add real assistive-technology fixtures. Independent `aria-label`, descriptive metadata, and state-field capability reporting, exact AppKit/GTK4 state projection where supported, validated ARIA state tokens, the typed announcement channel, WAI-ARIA live-region diff policy, and focused NumberField value announcements are implemented. |
+| P1 | Accessibility conformance | Complete multi-label projection on AppKit and WinUI; add AppKit description/details/control/ownership/flow/error/active-descendant mappings and WinUI details/ownership/error/active-descendant mappings where platform APIs permit; add exact native mappings for remaining state gaps such as `aria-current` and direct AppKit/WinUI autocomplete, multiline, popup, pressed, and busy semantics; close the documented logical-item/window name, description, relationship, state, and announcement exceptions; fill the remaining AppKit shortcut and WinUI role-description/value-text gaps; and add real assistive-technology fixtures. Shared lifecycle-aware relationship resolution, all GTK4 relationship mappings, supported AppKit/WinUI relationship mappings, independent `aria-label`, descriptive metadata, state-field capabilities, exact AppKit/GTK4 state projection where supported, validated ARIA tokens, the typed announcement channel, WAI-ARIA live-region diff policy, and focused NumberField value announcements are implemented. |
 | 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/react-aria-native.md

@@ -4,6 +4,13 @@ use serde::{Deserialize, Serialize};
 
 mod conformance;
 mod live_region;
+#[cfg(any(
+    test,
+    all(target_os = "macos", feature = "appkit-native"),
+    all(target_os = "linux", feature = "gtk4-native"),
+    all(target_os = "windows", feature = "winui-native")
+))]
+pub(crate) mod relationship_registry;
 pub use conformance::{
     AccessibilityConformanceIssue, AccessibilityConformanceReport, AccessibilityIssueCode,
     AccessibilityIssueSeverity,

src/accessibility.rs

@@ -23,6 +23,7 @@ pub enum AccessibilityIssueCode {
     InvalidMultipleState,
     MultipleSelectedItems,
     EmptyRelationship,
+    InvalidActiveDescendant,
     InvalidAutocomplete,
     InvalidCurrent,
     InvalidHasPopup,
@@ -159,6 +160,19 @@ fn validate_node<'a>(
             });
         }
     }
+    if node
+        .relationships
+        .active_descendant
+        .as_deref()
+        .is_some_and(|value| value.split_whitespace().count() > 1)
+    {
+        push_error(
+            issues,
+            node,
+            AccessibilityIssueCode::InvalidActiveDescendant,
+            "aria-activedescendant must reference exactly one element".to_string(),
+        );
+    }
     if node
         .state
         .autocomplete

src/accessibility/conformance.rs

@@ -120,3 +120,18 @@ fn conformance_rejects_invalid_accessibility_state_tokens() {
         assert!(report.issues.iter().any(|issue| issue.code == code));
     }
 }
+
+#[test]
+fn conformance_rejects_multiple_active_descendant_references() {
+    let mut list = node(AccessibilityRole::ListBox);
+    list.label = Some("Results".to_string());
+    list.relationships.active_descendant = Some("first second".to_string());
+
+    let report = AccessibilityConformanceReport::validate(&list);
+
+    assert!(!report.is_conformant());
+    assert!(report
+        .issues
+        .iter()
+        .any(|issue| issue.code == AccessibilityIssueCode::InvalidActiveDescendant));
+}