Dock Capability Policy Integration

[wieslawsoltes]

PR Summary: Dock Capability Policy Integration

Branch

• feature/capability-policy-integration

Goal

Implement a full capability-policy system for Dock, including:

• root-level policy defaults,
• per-dock policy overrides,
• per-dockable explicit overrides,
• runtime capability enforcement in Avalonia interaction paths,
• theme binding updates so UI reactively follows effective capabilities,
• complete model/headless test coverage,
• docs and sample UX for policy exploration.

Commit Breakdown

1. bf2246b00 feat(model): add dock capability policy contracts and resolver
2. 9b8e78c19 feat(avalonia): enforce capability policy in controls and themes
3. 710b32f68 test: add capability policy coverage across model and headless suites
4. 8e530f8f6 docs(samples): add capability policy guidance and reactive sample editor

Detailed Changes

1) Model/Core capability contract and precedence

Added new capability abstraction and evaluation model:

• src/Dock.Model/Core/DockCapability.cs
• src/Dock.Model/Core/DockCapabilityValueSource.cs
• src/Dock.Model/Core/DockCapabilityEvaluation.cs
• src/Dock.Model/Core/IDockCapabilityPolicy.cs
• src/Dock.Model/Core/DockCapabilityPolicy.cs
• src/Dock.Model/Core/DockCapabilityOverrides.cs
• src/Dock.Model/DockCapabilityResolver.cs

Extended key model contracts:

• src/Dock.Model/Core/IDockable.cs
• src/Dock.Model/Core/IDock.cs
• src/Dock.Model/Core/IDockManager.cs
• src/Dock.Model/Controls/IRootDock.cs

Integrated policy state into all model variants (Avalonia/INPC/MVVM/Prism/ReactiveProperty/ReactiveUI/Caliburn):

• DockBase gets dock-level policy property.
• DockableBase gets dockable override property.
• RootDock gets root policy property.

Factory and manager integration:

• src/Dock.Model/FactoryBase.Dockable.cs
• src/Dock.Model/DockManager.cs
• src/Dock.Model/DockService.cs

Effective capability resolution precedence implemented as:

1. Dockable intrinsic flag (CanClose, CanPin, etc.)
2. Root dock policy
3. Dock policy
4. Dockable overrides

The resolver returns diagnostics (DockCapabilityEvaluation) explaining both effective value and source.

2) Avalonia runtime enforcement and reactive UI capability behavior

Added capability converter support:

• src/Dock.Avalonia/Converters/DockCapabilityConverters.cs
• Supports both IValueConverter and IMultiValueConverter usage.
• Exposes dedicated *MultiConverter singletons for MultiBinding scenarios.

Runtime interaction paths now enforce effective capabilities instead of only raw flags:

• src/Dock.Avalonia/Controls/DocumentTabStripItem.axaml.cs
• src/Dock.Avalonia/Controls/ToolTabStripItem.axaml.cs
• src/Dock.Avalonia/Controls/MdiDocumentWindow.axaml.cs
• src/Dock.Avalonia/Controls/ManagedDockableBase.cs
• src/Dock.Avalonia/Controls/ManagedWindowDock.cs
• src/Dock.Avalonia/Internal/DockControlState.cs
• src/Dock.Avalonia/Internal/DockManagerState.cs
• src/Dock.Avalonia/Internal/HostWindowState.cs
• src/Dock.Avalonia/Internal/ManagedHostWindowState.cs

Automation peers updated to surface capability-constrained behavior in automation interactions:

• src/Dock.Avalonia/Automation/Peers/DocumentTabStripItemAutomationPeer.cs
• src/Dock.Avalonia/Automation/Peers/ToolTabStripItemAutomationPeer.cs
• src/Dock.Avalonia/Automation/Peers/ToolPinItemControlAutomationPeer.cs
• src/Dock.Avalonia/Automation/Peers/ToolChromeControlAutomationPeer.cs
• src/Dock.Avalonia/Automation/Peers/MdiDocumentWindowAutomationPeer.cs

3) Fluent theme capability binding overhaul

Updated Fluent control templates/menus to bind visibility/drag/drop behavior through effective capability multi-bindings:

• src/Dock.Avalonia.Themes.Fluent/Controls/DocumentControl.axaml
• src/Dock.Avalonia.Themes.Fluent/Controls/DocumentTabStripItem.axaml
• src/Dock.Avalonia.Themes.Fluent/Controls/MdiDocumentWindow.axaml
• src/Dock.Avalonia.Themes.Fluent/Controls/ToolChromeControl.axaml
• src/Dock.Avalonia.Themes.Fluent/Controls/ToolPinItemControl.axaml
• src/Dock.Avalonia.Themes.Fluent/Controls/ToolTabStripItem.axaml

Important fix included:

• ToolChromeControl drag/drop policy trigger paths now observe IToolDock policy context (not root owner policy), matching resolver semantics and ensuring reactive updates track the correct policy object.

4) Test coverage

Model tests added:

• tests/Dock.Model.UnitTests/DockCapabilityPolicyTests.cs
• tests/Dock.Model.UnitTests/DockCapabilityResolverTests.cs
• tests/Dock.Model.UnitTests/DockManagerCapabilityPolicyTests.cs
• tests/Dock.Model.UnitTests/DockServiceCapabilityPolicyTests.cs
• tests/Dock.Model.UnitTests/DockGroupValidationTests.cs (updated)

Avalonia headless tests added:

• tests/Dock.Avalonia.HeadlessTests/DockCapabilityConvertersTests.cs
• tests/Dock.Avalonia.HeadlessTests/DockCapabilityBindingUpdateTests.cs
• tests/Dock.Avalonia.HeadlessTests/CapabilityPolicyFactoryTests.cs
• tests/Dock.Avalonia.HeadlessTests/CapabilityPolicyThemeBindingTests.cs
• tests/Dock.Avalonia.HeadlessTests/ManagedWindowParityTests.cs (updated)

CapabilityPolicyThemeBindingTests validates all new theme binding additions across both themes:

• DockFluentTheme
• DockSimpleTheme (linked controls)

Covered controls include:

• DocumentControl
• DocumentTabStripItem
• MdiDocumentWindow
• ToolTabStripItem
• ToolPinItemControl
• ToolChromeControl

The tests verify policy transition behavior:

• baseline enabled,
• dock policy disable,
• dockable override re-enable,
• fallback to dockable flags when policies/overrides are removed.

5) Sample updates

Enhanced reactive sample to exercise policy features:

• samples/DockXamlReactiveUISample/ViewModels/CapabilityPolicyEditor.cs
• samples/DockXamlReactiveUISample/ViewModels/MainWindowViewModel.cs
• samples/DockXamlReactiveUISample/Views/MainWindow.axaml
• samples/DockXamlReactiveUISample/Infrastructure/SampleDockItemContainerGenerator.cs
• samples/DockXamlReactiveUISample/Models/DocumentItem.cs
• samples/DockXamlReactiveUISample/Models/ToolItem.cs

Sample now exposes and edits root/dock/dockable capability policy state to validate precedence in UI.

6) Documentation updates

Added new policy-focused article and linked into docs navigation:

• docfx/articles/dock-capability-policies.md
• docfx/articles/dock-dockable-properties.md
• docfx/articles/dock-docking-constraints.md
• docfx/articles/dock-itemssource.md
• docfx/articles/dock-manager-guide.md
• docfx/articles/toc.yml

Docs now explain:

• policy object model,
• precedence rules,
• practical enforcement points,
• migration/usage guidance.

Validation Run

Executed and passed:

• dotnet test tests/Dock.Avalonia.HeadlessTests/Dock.Avalonia.HeadlessTests.csproj -v minimal
• dotnet test tests/Dock.Model.UnitTests/Dock.Model.UnitTests.csproj -v minimal
• dotnet test Dock.slnx --no-build -v minimal

Compatibility Notes

• Existing raw capability flags remain supported.
• New policy layers are opt-in via nullable policy/override properties.
• Converter API remains backward-compatible via existing IValueConverter fields, with additional dedicated multi-binding fields.