docs/architecture/UNCERTAINTIES.md
This document collects areas where the architecture documentation is incomplete or uncertain based on the analysis. These items require further investigation or are subject to change.
Area: tests/ directory (outside analysis scope)
Cannot determine exact test coverage. Given 77+ controls with complex state management (NavigationView journal, ContentDialog async lifecycle), the testability of static managers (ApplicationThemeManager, SystemThemeWatcher) is limited. Service interfaces (INavigationService, IContentDialogService, etc.) are testable through mock implementations.
Current unit test coverage is minimal (6 tests covering Animations and Extensions only).
Area: src/Wpf.Ui/Controls/Window/WindowBackdrop.cs
WindowBackdrop class is referenced in FluentWindow and WindowBackgroundManager (ApplyBackdrop, RemoveBackdrop, RemoveBackground, RemoveTitlebarBackground) but was not directly examined. Likely located in Controls/Window/ directory and provides Mica/Acrylic/Tabbed backdrop effects via DWM APIs.
Area: src/Wpf.Ui/Controls/NavigationView/NavigationCache.cs and NavigationCacheMode.cs
These files exist but were not deeply examined. The caching strategy for navigation pages includes Required, Enabled, and Disabled modes but the exact implementation details need further investigation.
Area: Central Package Management in Directory.Packages.props
PolySharp is referenced in core library csproj via PolySharpExcludeGeneratedTypes but the actual package reference appears to come from Directory.Packages.props (central package management) which was not fully examined. The exact polyfill configuration and version require verification.
Module: Wpf.Ui.ToastNotifications
It is unclear whether this library has any concrete implementation plans or if it is purely a placeholder for future work. The Toast.Show() method throws NotImplementedException. The library has no dependency on Wpf.Ui core despite being a WPF-targeting project.
Module: Wpf.Ui.FlaUI
The FlaUI library has no project reference to Wpf.Ui, yet it exists under the Wpf.Ui namespace. It only depends on FlaUI.Core. Currently contains only an AutoSuggestBox automation element wrapper. It is unclear whether additional automation elements for other WPF UI controls will be added.
Module: Wpf.Ui.FontMapper
The FontMapper generates enum files for the core library but has no project reference to it. The generated output path uses a relative 'generated/' directory. The exact integration workflow (how generated files reach the core library) is not evident from the project analysis alone.
Additional Issue: FetchVersion() returns a hardcoded version '1.1.316' instead of actually fetching from GitHub API (the API call code is commented out).
Module: Wpf.Ui.SyntaxHighlight
The SyntaxHighlight.xaml references a FontFamily with key 'FiraCode' using pack URI pointing to Wpf.Ui (not Wpf.Ui.SyntaxHighlight), suggesting the font may need to also exist in the core library.
Additional Issue: The CodeBlock.cs is also listed as an EmbeddedResource in the csproj, which is unusual for a source file.
WIP Status: Highlighter class is marked as work in progress. The autodetect language feature defaults to XAML, and C# and XAML use identical regex patterns.
Module: Wpf.Ui.Gallery.Package
A .wapproj (Windows Application Packaging) project is referenced in Wpf.Ui.Gallery.slnf but not directly analyzed. This likely creates an MSIX package for the Gallery app. The packaging configuration and deployment process need clarification.
Area: src/Wpf.Ui.Gallery/ControlsLookup/
Referenced as GalleryAssembly.Asssembly (note triple 's') in DependencyModel and ControlsLookup. The actual GalleryAssembly class was not directly read. It likely provides the Gallery assembly reference for reflection-based page discovery.
Package: ReflectionEventing and ReflectionEventing.DependencyInjection
These packages are referenced in the Gallery csproj but their usage was not traced to specific event handling code within the analyzed files. The purpose and integration point of these packages require investigation.
Module: src/Wpf.Ui.Extension
The VS2022 extension project (.vsix) is built for x64 and arm64 platforms but was not analyzed. The extension capabilities and integration points with Visual Studio are unknown.
Area: build.ps1
The build script references .NET SDK 8 for installation (winget install Microsoft.DotNet.SDK.8) but the project now targets .NET 10. The build script may be outdated.
Area: .github/dependabot.yml
The Dependabot configuration targets the 'development' branch, not 'main'. The branch strategy and merge workflow from development to main are not documented.
Area: .github/workflows/wpf-ui-pr-validator.yaml
The PR validator workflow only builds the Gallery app and does not run any tests (unit or integration). The rationale for not including test execution in CI is unclear.
Area: GitHub Actions secrets and certificate management
The CD pipeline fetches a strong-name certificate from GitHub secrets (${{ secrets.WPF_UI_CERTIFICATE_BASE64 }}). The certificate generation, storage, and rotation procedures are not documented.
Area: Directory.Build.props vs actual package versions
The Version property is set to 4.2.0, but the synchronization mechanism between this central version, individual package versions, and changelog updates is not documented.
Area: Deprecated APIs and migration paths
Several APIs are marked [Obsolete] (ContentDialog legacy constructors, WindowBackgroundManager.UpdateBackground with forceBackground parameter). The deprecation timeline and migration strategy for consumers are not documented.
Area: src/Wpf.Ui/AutomationPeers/
Only 4 automation peers exist for 77+ controls:
Many interactive controls (Button, NavigationView base, TextBox, etc.) may lack custom automation peer implementations. The strategy for expanding accessibility support is unclear. This potentially affects screen reader compatibility and UI automation testing.
Area: Dynamic resource naming and contracts
20+ accent-related dynamic resources are updated programmatically by ApplicationAccentColorManager:
The complete list of dynamic resources and their contracts (expected types, update triggers) is not centrally documented. Third-party theme authors may struggle to determine which resources must be provided.
Area: Cross-framework API compatibility
Various conditional compilation symbols are used:
NET5_0_OR_GREATERNET6_0_OR_GREATERNET8_0_OR_GREATERNET48_OR_GREATER_or_NETCOREAPP3_0_OR_GREATERThe decision matrix for when to use each symbol and the feature availability across frameworks is not documented in a single location.
Area: Minimum Windows version and feature matrix
The library supports Windows 7 through Windows 11, but feature availability varies:
A comprehensive feature compatibility matrix by Windows version is not documented.