Skip to content

Fix ThemeRef PaneBackground, InteractionStates restore, author Style and key quoting on the Style path - #1636

Merged
Alexandre Zollinger Chohfi (azchohfi) merged 6 commits into
mainfrom
azchohfi-themeref-stable-sdk-fixes
Nov 20, 2026
Merged

Alexandre Zollinger Chohfi (azchohfi) merged 6 commits into
mainfrom
azchohfi-themeref-stable-sdk-fixes

Conversation

@azchohfi

@azchohfi Alexandre Zollinger Chohfi (azchohfi) commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Lands the ThemeRef fixes from #1618 that don't need SetThemeResourceBinding, on the stable Windows App SDK, keeping Reconciler.ApplyThemeBindings' XamlReader {ThemeResource} Style. #1618 stays the later API swap. ThemeRef.Resolve and the probe in #1633 are untouched.

  • SplitView.PaneBackground(ThemeRef) was a silent no-op. GetDependencyPropertyName and GetStyleTargetType now map it, and the descriptor entry is the Optional-backed OneWay(..., dp:), so a removed .PaneBackground(brush) is cleared. Found along the way: a loaded SplitView throws E_INVALIDARG on any Style write (even an empty Style, or ClearValue) unless the new Style is BasedOn DefaultSplitViewStyle. That already crashes on main when a ThemeRef is added to or removed from a mounted SplitView. The themed Style for a SplitView is now built on DefaultSplitViewStyle.
  • InteractionStates no longer freezes a ThemeRef Background or Foreground. The normal value is captured when a state first writes over the property, and captured again if a re-render replaced the state's brush while the state was active. On exit nothing happens unless the property still holds the state's brush. A captured local brush is written back, and no local value means ClearValue, so the {ThemeResource} setter takes over again. Opacity-only states no longer touch brushes.
  • The author's Style is kept. This covers .Set(c => c.Style = s), .ApplyStyle, .AccentButton(), .SubtleButton(), .TextLink(), Title(...) and the other typography factories. The themed Style is built BasedOn it and targets the control's own WinUI type.
    • On re-render the base is read back from the themed Style's BasedOn, so styles don't chain.
    • Cache entries are keyed by an id stamped on the base Style through an attached DP. The cache starts over when it hits its cap.
    • Re-applying toggles through the base instead of null, so a custom Template isn't rebuilt.
    • ClearThemeBindings restores the base. This is the same idea as draft Add native SettingsCard and SettingsExpander (spec 065) #1531's IReactorBaseStyleHost, done generically.
    • A Style that targets a third-party control type can't be a BasedOn of the WinUI type. In that case the themed Style replaces it, as before this PR, and a warning is logged once. Later renders skip straight to that path instead of failing each time.
  • Keys are quoted and escaped in the setter value, using the same rules as Resolve ThemeRef through WinUI instead of reading theme dictionaries #1633's probe, so the two can share one helper later. The XML character check is done by hand, which keeps System.Xml out of ThemeRef apps. A key that can't be written skips only that setter and logs a bounded DiagnosticLog.Warning that names the property. The themed-Style cache key now escapes |, = and \, so such keys can't collide with a different binding set.

Linked issue / spec

Part of #1618 (stable-SDK half). Related: #1633, #1531, #522.

Test plan

  • New selftests ThemeRefStyleFixtures (12 fixtures, 98 checks). They cover:

    • SplitView: themed, update and skip re-renders, removal
    • InteractionStates: hover and press sequences, a mid-hover re-render, opacity only
    • author Style, named styles, a derived TargetType, a custom template, and the third-party Style fallback
    • quoted keys, an unrepresentable key with its warning, and a cache-key collision

    Each fixture fails on the pre-fix code. Targeted mutations also redden their oracle: toggling through null, the loose TargetType, no DefaultSplitViewStyle base, no recapture, capture on every state, no key escape, return instead of continue for a bad key, and no fallback retry.

  • Unit tests for FormatThemeResourceReference and the BuildCacheKey escaping (ReconcilerCacheKeyTests). ModifierTableIntegrityTests exempts the element-specific PaneBackground.

  • dotnet test tests/Reactor.Tests: passed (16058 passed, 18 skipped).

  • dotnet test tests/Reactor.SelfTests -p:Platform=x64: passed on the first commit. After the review fixes, the --self-test --filter groups for ThemeRefStyle, Issue522, PanelBorder, ThemeBindings, InterState, Theme, SplitView, NamedStyle, Interaction, Pool and Issue142 all pass.

  • dotnet build src/Reactor/Reactor.csproj -c Release: passed. dotnet restore Reactor.slnx, then dotnet build Reactor.slnx --no-restore -c Release -p:SkipSignaturesGen=true with NuGetAudit=false: 0 errors. Locally the network blocks nuget.org's vulnerability feed (NU1900), and SignaturesGen's nested restore can't skip it. CI isn't affected.

  • Docs: compiled only the styling topic.

Risk / breaking changes

  • Behaviour change: a ThemeRef no longer replaces an explicit Style that targets a WinUI type. It layers on top of it. This was the intended behaviour, and the old one dropped named styles.
  • Removing .PaneBackground(brush) now restores the default pane background instead of keeping the last brush.
  • An InteractionStates exit on a property with no local value now clears it instead of writing back a captured brush.
  • Perf: themed Styles built on a base are cached per base id. A base Style created on every render rebuilds the themed Style with XamlReader on each render, and the cache resets when it reaches its 256-entry cap.

…and key quoting on the Style path

Port the #1618 ThemeRef fixes that don't need SetThemeResourceBinding, keeping the
XamlReader {ThemeResource} Style:

- SplitView.PaneBackground(ThemeRef) maps to the pane background, and the descriptor
  clears a removed brush. A loaded SplitView rejects any Style not BasedOn
  DefaultSplitViewStyle (E_INVALIDARG), so the themed Style is built on it.
- InteractionStates captures the normal brush lazily and, on restore, clears a property
  that had no local value instead of writing back a brush captured at setup.
- The themed Style is built BasedOn the control's own Style (setter, ApplyStyle, named
  styles), targeting the control's exact type, cached per stamped base id, and
  ClearThemeBindings restores the base.
- ThemeRef keys are quoted and escaped in the setter value.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build metrics

Artifact sizes for a571157 vs the base branch (34953e5).

Packages (compressed .nupkg)

Artifact base PR Δ
Microsoft.UI.Reactor.nupkg 2.08 MB 2.09 MB +4.00 KB (+0.19%) ⚠️
Microsoft.UI.Reactor.Advanced.nupkg 523.7 KB 523.7 KB -10 B (0.00%) ≈
Microsoft.UI.Reactor.Devtools.nupkg 287.8 KB 287.8 KB -2 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor

Artifact base PR Δ
Reactor.Analyzers.dll 422.5 KB 422.5 KB +0 B (0.00%) ≈
Reactor.dll 2.82 MB 2.83 MB +5.00 KB (+0.17%) ⚠️
Reactor.Localization.Generator.dll 16.0 KB 16.0 KB +0 B (0.00%) ≈
Reactor.Wrappers.Abstractions.dll 10.5 KB 10.5 KB +0 B (0.00%) ≈
Reactor.Wrappers.Generator.dll 164.0 KB 164.0 KB +0 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor.Advanced

Artifact base PR Δ
Reactor.Advanced.dll 1.07 MB 1.07 MB +0 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor.Devtools

Artifact base PR Δ
Microsoft.UI.Reactor.Devtools.dll 787.0 KB 787.0 KB +0 B (0.00%) ≈

✅ smaller / ⚠️ larger / ≈ within noise. Sizes come from a Release dotnet pack on the CI runner: packages are the compressed .nupkg download size, assemblies the uncompressed DLL inside it.
workflow run.

Comment thread src/Reactor/Core/Reconciler.cs Fixed
Comment thread src/Reactor/Core/Reconciler.cs Fixed
Comment thread src/Reactor/Core/Reconciler.cs Fixed
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

🧪 Merged coverage

Coverage for a571157 vs the base branch (34953e5) — unit + selftest merged.

Metric base PR Δ
Line 88.79% 88.83% +0.04 pp ≈
Branch 46.08% (18281/39669) 45.98% (18314/39827) -0.10 pp ⚠️

✅ higher / ⚠️ lower / ≈ within noise. Δ is in percentage points; coverage is unit + selftest merged (Debug x64) on the CI runner. Cobertura reports attached to the workflow run as artifacts.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved theming defects can leave stale styles installed, reuse incorrect setters through cache-key collisions, and prevent ThemeRefs from applying to custom controls with author styles.

3 open issues
What changed in this PR

This PR improves Reactor’s Style-based ThemeRef handling on the stable Windows App SDK, bringing over fixes from #1618 without adopting the experimental binding API or changing ThemeRef.Resolve.

Changes:

  • Add SplitView pane theming and clear removed explicit pane brushes.
  • Preserve author Styles and restore interaction-state brushes without freezing themed values.
  • Quote resource keys and add regression coverage, documentation, and release notes.
File Description
tests/​Reactor.Tests/​ReconcilerCacheKeyTests.cs Tests resource-key quoting, escaping, and rejection.
tests/​Reactor.Tests/​AnalyzerTests/​ModifierTableIntegrityTests.cs Accounts for the element-specific PaneBackground mapping.
tests/​Reactor.AppTests.Host/​SelfTest/​SelfTestFixtureRegistry.cs Registers nine ThemeRef Style fixtures.
tests/​Reactor.AppTests.Host/​SelfTest/​Fixtures/​ThemeRefStyleFixtures.cs Covers pane theming, brush restoration, author Styles, templates, and quoted keys.
src/​Reactor/​Core/​Reconciler.cs Updates themed Style construction, caching, ownership, and interaction-brush restoration.
src/​Reactor/​Core/​Element.cs Clears removed SplitView pane brushes through the descriptor.
docs/​guide/​styling.md Documents ThemeRef layering over author Styles.
docs/​_pipeline/​templates/​styling.md.dt Updates the source template for the styling guide.
CHANGELOG.md Records the ThemeRef behavior fixes.

Review effort: Balanced

Comment thread src/Reactor/Core/Reconciler.cs Resolved
Comment thread src/Reactor/Core/Reconciler.cs Resolved
Comment thread src/Reactor/Core/Reconciler.cs Resolved
- Escape '|', '=' and '\' in the themed-Style cache key so a resource key containing
  them can't share a cached Style with a different binding set.
- InteractionStates recapture the normal brush when a re-render replaced the state's
  brush mid-state, so a later press/release restores the current brush.
- Guard the TryApplyBasedStyle rollback so nothing escapes into reconcile, and fall
  back to the unbased themed Style (warning once) when an app Style can't be a
  BasedOn of the control's WinUI type, instead of failing on every render.
- Reset the based-Style cache at its cap instead of freezing it.
- Read the base from the themed Style's BasedOn instead of an extra attached DP.
- Check XML characters by hand rather than with XmlConvert (keeps System.Xml out of
  ThemeRef apps); bound, escape and name the property in the bad-key warning.
- Filter the new catch clauses (OutOfMemory/StackOverflow pass through).
- Tests: Pressed sequences, mid-hover re-render, SplitView update/skip re-renders,
  unrepresentable key, cache-key collision, third-party Style fallback.
- Docs: CHANGELOG cites PR #1636, notes PaneBackground removal and the fallback;
  styling guide narrows the BasedOn claim.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

ThemeRef updates can leave stale themed styles installed, and resource-parsing failures can incorrectly mark shared author styles incompatible, causing later renders to lose setters or templates.

3 open issues
1 resolved since last review

Review effort: Balanced

Comment thread src/Reactor/Core/Reconciler.cs Resolved
- A ThemeRef whose key becomes unrepresentable now takes off the themed Style a
  previous render applied, restoring the app's Style, instead of keeping the old brush.
- A XamlReader parse failure (such as a missing resource key) no longer marks the
  app's base Style incompatible; only a failed apply does.
- Skip ThemeRefStyle_ThirdPartyStyleFallsBack under NativeAOT, like the Issue142
  fixtures that mount the same third-party control (no XAML metadata provider).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Hover/press exit clears captured Background or Foreground bindings instead of restoring them, causing controls to display style/default brushes rather than their bound brushes.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Restore bound brushes after hover or press state changes

src/​Reactor/​Core/​Reconciler.cs:6365

When Background or Foreground is set through .Set(c => c.SetBinding(...)), this branch clears the captured binding expression on hover/press exit, so the control shows its style/default brush instead of the bound brush. Capture the binding's ParentBinding (WinUI default-branch source) before overriding it and restore it with SetBinding, retaining the ownership check. Add a selftest checking both the restored brush and subsequent source updates.

3 resolved since last review

Review effort: Balanced

Restore a binding an InteractionStates brush wrote over: on exit, re-apply the
captured BindingExpression's ParentBinding instead of clearing the property, so a
bound Background/Foreground keeps following its source.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the ThemeRef rendering changes.

No open issues 🎉

Review effort: Balanced

Under NativeAOT the raw ReadLocalValue object for a bound property doesn't project as
a BindingExpression, so the InteractionStates restore cleared the binding there
(AOT Selftests: ThemeRefStyle_Bound_Restored). Capture the Binding through the typed
FrameworkElement.GetBindingExpression when the state takes the property over, and
restore it with SetBinding. Verified with a local NativeAOT publish.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because pooled controls reused without ThemeRefs can retain a previous component’s styles and templates through an uncleared theme ownership marker.

No open issues 🎉

Review effort: Balanced

Clear Reactor's themed-Style ownership marker when a control returns to the pool
(ElementPool.CleanElement now calls ClearThemeBindings), so a pooled control holds no
reference to the previous renter's themed Style.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block approval of the ThemeRef styling changes.

No open issues 🎉

Review effort: Balanced

@azchohfi Alexandre Zollinger Chohfi (azchohfi) added ready-for-review Agent work and technical checks complete; awaiting review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Nov 20, 2026
@azchohfi
Alexandre Zollinger Chohfi (azchohfi) merged commit 9569c46 into main Nov 20, 2026
65 of 66 checks passed
@azchohfi
Alexandre Zollinger Chohfi (azchohfi) deleted the azchohfi-themeref-stable-sdk-fixes branch November 20, 2026 21:50
@azchohfi Alexandre Zollinger Chohfi (azchohfi) removed the ready-for-review Agent work and technical checks complete; awaiting review, not approval or merge label Nov 20, 2026
Alexandre Zollinger Chohfi (azchohfi) added a commit that referenced this pull request Nov 20, 2026
Keeps both CHANGELOG Fixed entries. ThemeResourceProbe now builds its markup with
Reconciler.FormatThemeResourceReference, which #1636 added with the same quoting and
escaping rules, instead of its own copy.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Alexandre Zollinger Chohfi (azchohfi) added a commit that referenced this pull request Nov 21, 2026
…rsed Style

ApplyThemeBindings now binds each mapped property (Background, Foreground,
BorderBrush, SplitView.PaneBackground) with FrameworkElement.SetThemeResourceBinding,
the code equivalent of {ThemeResource}, instead of building a Style from a XAML
string. Ownership is tracked per property in ReactorState.ThemeResourceBindings, so
a dropped ThemeRef or a pooled control clears only what Reactor bound, and the
precedence the old Style had (explicit brush modifiers, setters and element
properties win) is kept at local-value precedence.

This replaces the Style path PR #1636 shipped on the stable SDK and keeps its
behavior checks (ThemeRefStyleFixtures). Removed with it: the themed-Style caches,
the ownership marker, the BasedOn base-style stamping and fallback, the
DefaultSplitViewStyle workaround and the unrepresentable-key warning, since no
Style is written and a key needs no quoting. FormatThemeResourceReference stays
for ThemeResourceProbe. InteractionStates keeps main's restore and also puts back
a theme binding the state wrote over, instead of its resolved brush. A key that
changes to one WinUI can't find now releases the property instead of keeping the
previous key's brush.

Stacks on #1125 (experimental Windows App SDK).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants