ItemsSource Container Lookup + Unregister Policy

[wieslawsoltes]

PR Summary: ItemsSource Container Lookup + Unregister Policy

Branch

• feature/item-container-lookup-unregister-policy

Commits

1. abd15c753 feat(itemsource): add container lookup and unregister update policy
2. 8fa6ffb87 test(itemsource): cover lookup, unregister policy, and serializer behavior
3. 0d72b6aea feat(sample): add itemsource unregister policy and container lookup demo
4. 1447aa962 docs(itemsource): document lookup API and unregister policy controls

Problem Statement

Dock supported source-backed document/tool generation via ItemsSource, but lacked:

• a direct factory API to resolve generated container by source item,
• a configurable unregister/remove policy beyond default close->remove behavior,
• explicit parity for tool/document behavior and policy propagation across dock cloning/splitting paths.

Scope of This PR

This PR fully implements feature 5 from the parity plan:

• Add item-to-container lookup API on factory.
• Add global and per-dock unregister update policy.
• Keep behavior symmetric for documents and tools.
• Ensure policy is copied in dock duplication/splitting/windowing flows.
• Extend tests, sample app, and docfx docs.

API Changes

New IFactory API

• IDockable? GetContainerFromItem(object item)
• File: src/Dock.Model/Core/IFactory.cs

New per-dock policy property

• bool? CanUpdateItemsSourceOnUnregister { get; set; }
• Added to:
  • IItemsSourceDock (src/Dock.Model/Core/IItemsSourceDock.cs)
  • IToolItemsSourceDock (src/Dock.Model/Core/IToolItemsSourceDock.cs)
• Implemented on:
  • DocumentDock (src/Dock.Model.Avalonia/Controls/DocumentDock.cs)
  • ToolDock (src/Dock.Model.Avalonia/Controls/ToolDock.cs)

New global setting

• DockSettings.UpdateItemsSourceOnUnregister (default true)
• Files:
  • src/Dock.Settings/DockSettings.cs
  • src/Dock.Settings/DockSettingsOptions.cs
  • src/Dock.Settings/AppBuilderExtensions.cs
• New builder extension:
  • .UpdateItemsSourceOnUnregister(bool update = true)

Implementation Details

Factory item tracking and lookup

• FactoryBase now tracks generated source-item associations in addition to owner mapping.
• Added item->dockable bookkeeping with duplicate-item support.
• GetContainerFromItem returns the first still-tracked generated container for the item and prunes stale entries.
• Files:
  • src/Dock.Model/FactoryBase.cs

Registration / unregistration wiring

• DocumentDock and ToolDock now register generated dockables with both owner and source item.
• Existing untrack paths clean owner and item associations.
• Files:
  • src/Dock.Model.Avalonia/Controls/DocumentDock.cs
  • src/Dock.Model.Avalonia/Controls/ToolDock.cs

Unregister/remove policy behavior

• RemoveItemFromSource in both docks now evaluates effective policy:
  • Per-dock CanUpdateItemsSourceOnUnregister when set.
  • Otherwise fallback to global DockSettings.UpdateItemsSourceOnUnregister.
• If updates are disabled, generated containers are still untracked/removed from dock UI without mutating backing source collection.

Policy propagation across dock operations

• Copies policy metadata when creating/splitting/moving dock structures so behavior remains consistent after layout transforms.
• Files:
  • src/Dock.Model/DockService.cs
  • src/Dock.Model/FactoryBase.cs
  • src/Dock.Model/FactoryBase.Dockable.cs

Serializer alignment

• Added CanUpdateItemsSourceOnUnregister to serializer allow-lists for DocumentDock and ToolDock.
• File:
  • src/Dock.Model.Avalonia/Json/AvaloniaDockSerializer.cs

Tests Added/Updated

Model/Avalonia tests

• tests/Dock.Model.Avalonia.UnitTests/Controls/DocumentDockItemsSourceSampleTests.cs
• tests/Dock.Model.Avalonia.UnitTests/Controls/ToolDockItemsSourceTests.cs
• Coverage includes:
  • GetContainerFromItem lookup for docs/tools.
  • Tracking/untracking on close.
  • ItemsSource reload/reset semantics.
  • Duplicate source item behavior (remaining container lookup correctness).
  • Global disabled policy behavior.
  • Per-dock override precedence over global setting.

Serializer tests

• tests/Dock.Model.Avalonia.UnitTests/AvaloniaDockSerializerTests.cs
• Verifies serialize/deserialize of CanUpdateItemsSourceOnUnregister for both DocumentDock and ToolDock.

Settings tests

• tests/Dock.Settings.UnitTests/AppBuilderExtensionsTests.cs
• Verifies options and fluent extension update DockSettings.UpdateItemsSourceOnUnregister.

Sample App Updates

• Sample: samples/DockXamlReactiveUISample
• Added runtime controls to test:
  • global UpdateItemsSourceOnUnregister,
  • per-document/per-tool override (bool? via three-state checkbox),
  • lookup buttons using Factory.GetContainerFromItem.
• Composition improved:
  • MainWindowViewModel now receives IFactory via constructor.
  • Factory wiring moved to App.axaml.cs (composition root).

Documentation Updates

• docfx/articles/dock-itemssource.md
• docfx/articles/dock-reference.md
• docfx/articles/dock-model-controls.md
• docfx/articles/dock-settings.md

Docs now include:

• IFactory.GetContainerFromItem usage,
• global/per-dock unregister policy behavior and precedence,
• app-builder/options support.

Validation

Executed and passed:

• dotnet test Dock.slnx -c Release --no-restore --no-build
• dotnet build samples/DockXamlReactiveUISample/DockXamlReactiveUISample.csproj -c Release --no-restore

Additional focused passes were run for:

• Dock.Model.Avalonia.UnitTests
• Dock.Settings.UnitTests
• serializer-specific test subset

Behavior Notes

• Default behavior remains backward compatible (UpdateItemsSourceOnUnregister = true), so close->remove stays on by default.
• Per-dock nullable override enables precise opt-in/opt-out without forcing global behavior.
• No model-layer dependency was introduced from Dock.Model to Dock.Settings; policy resolution remains in Avalonia dock control layer.

Breaking Changes

• None intended.
• API surface additions only; existing behavior preserved by default.