Accessibility automation peers

[wieslawsoltes]

PR Summary: Dock Avalonia Accessibility and UI Automation

Branch

• Source branch: feature/accessibility-automation-peers
• Base branch: master

Goal

Implement a full UI automation/accessibility layer for Dock Avalonia controls, including dedicated automation peers, provider contracts, runtime state/event exposure, keyboard selector validation, leak safety, and end-user documentation.

Commit Breakdown

1) 20edc83b8 feat(avalonia): add UI automation peers for dock controls

Added automation peer layer

Created dedicated peers under src/Dock.Avalonia/Automation/Peers/ for Dock surfaces, including:

• Host/layout controls: DockControl, RootDockControl, DockCommandBarHost
• Dock targets: DockTarget / GlobalDockTarget
• Document/tool/MDI hosts: DocumentControl, ToolControl, MdiDocumentControl
• Tabs and items: DocumentTabStrip, ToolTabStrip, DocumentTabStripItem, ToolTabStripItem
• Tool chrome/pinned surfaces: ToolChromeControl, PinnedDockControl, ToolPinnedControl, ToolPinItemControl
• Window surfaces: HostWindow, HostWindowTitleBar, PinnedDockWindow, MdiDocumentWindow
• Drag visuals and overlay: DragPreviewControl, DragPreviewWindow, DockAdornerWindow, DockSelectorOverlay
• Shared helper: DockAutomationPeerHelper for name/id/state/activation behavior

Control wiring and provider behavior

Added OnCreateAutomationPeer() overrides in all relevant controls so each control returns a dedicated Dock peer.

Implemented and exposed patterns where applicable:

• IInvokeProvider
• ISelectionProvider
• ISelectionItemProvider
• IExpandCollapseProvider
• IScrollProvider
• IValueProvider (read-only where appropriate)

Runtime event propagation

Hooked control property changes to peer notifications for:

• Tab item IsSelected
• Selector overlay IsOpen, SelectedItem, Items, Mode
• Drag preview Status

This ensures automation clients receive state-change events when interactive state updates.

Overlay template automation support

Updated fluent selector template (src/Dock.Avalonia.Themes.Fluent/Controls/DockSelectorOverlay.axaml) to include:

• PART_ItemsList

This enables automation delegation for overlay selection and scrolling.

Reliability/leak-related cleanup in controls

Included lifecycle safety fixes in touched controls to prevent duplicate handlers/subscriptions and improve detach behavior:

• DocumentTabStrip window-drag attach/detach consistency
• ToolTabStrip template/container observable cleanup
• ToolChromeControl template/handler detachment correctness
• ToolControl pointer handler detach on visual-tree removal
• RootDockControl template handler cleanup across re-apply/detach
• DragPreviewControl property owner registration fix for ContentTemplateProperty

2) 50b86eaac test(avalonia): cover automation peers, reader flows, and leaks

Added comprehensive automated coverage:

• tests/Dock.Avalonia.HeadlessTests/AutomationPeersTests.cs

  • Verifies control type/class/name/id/help text contracts
  • Verifies provider availability and invoke/selection/expand-collapse/value behavior
  • Verifies non-interactive decorative surfaces are not exposed as control/content elements

• tests/Dock.Avalonia.HeadlessTests/AutomationReaderCompatibilityTests.cs

  • Simulates automation-reader traversal over peer trees
  • Validates pattern usage via discovered peers (selection/invoke/scroll/value)
  • Verifies overlay automation property/children change events

• tests/Dock.Avalonia.HeadlessTests/DockSelectorKeyboardNavigationTests.cs

  • Validates keyboard-only selector workflows (Ctrl+Tab, Ctrl+Alt+Tab, arrows/tab, Enter, Esc, modifier release)

• tests/Dock.Avalonia.LeakTests/AutomationPeerLeakTests.cs

  • Release-mode leak test covering new automation paths, subscriptions, and event wiring

3) df23ead75 docs(docfx): document dock accessibility automation model

Documentation updates in docfx/articles:

• Added new article: dock-accessibility.md

  • Control-to-peer/provider matrix
  • Provider behavior contract
  • Name/ID resolution and customization with AutomationProperties
  • State/event/action contracts
  • Template requirements (PART_ItemsList)
  • Testing guidance and coverage references

• Updated dock-controls-reference.md

  • Added accessibility automation peers section and integration notes
  • Documented selector template part requirements

• Updated dock-selector-overlay.md

  • Added automation behavior details and explicit event contract
  • Added reader compatibility notes

• Updated toc.yml

  • Added "Accessibility and UI automation" article entry

Validation Performed

Headless automation tests

• Command: dotnet test tests/Dock.Avalonia.HeadlessTests/Dock.Avalonia.HeadlessTests.csproj
• Result: Passed (503 passed, 0 failed)

Release leak test for automation peers

• Command: dotnet test tests/Dock.Avalonia.LeakTests/Dock.Avalonia.LeakTests.csproj -c Release --filter "AutomationPeerLeakTests"
• Result: Passed (1 passed, 0 failed)
• Notes: Existing warnings in leak test project only (no failures)

Compatibility / Behavior Notes

• Decorative preview/adorner windows are intentionally non-interactive in automation trees.
• Overlay selection/scroll automation requires PART_ItemsList in control templates.
• ISelectionItemProvider.Select for tab items now follows the same activation path as invoke behavior.
• Automation metadata can be overridden through AutomationProperties.Name and AutomationProperties.AutomationId.

Files Changed (high-level)

• Core implementation: src/Dock.Avalonia/Automation/Peers/* and related control wiring in src/Dock.Avalonia/Controls/*
• Theme template: src/Dock.Avalonia.Themes.Fluent/Controls/DockSelectorOverlay.axaml
• Tests: tests/Dock.Avalonia.HeadlessTests/*, tests/Dock.Avalonia.LeakTests/AutomationPeerLeakTests.cs
• Docs: docfx/articles/dock-accessibility.md, docfx/articles/dock-controls-reference.md, docfx/articles/dock-selector-overlay.md, docfx/articles/toc.yml