Skip to content

Add native SettingsCard and SettingsExpander (spec 065) - #1531

Draft
Niels Laute (niels9001) wants to merge 11 commits into
niels9001-theme-high-contrastfrom
niels9001-settings-card
Draft

Niels Laute (niels9001) wants to merge 11 commits into
niels9001-theme-high-contrastfrom
niels9001-settings-card

Conversation

@niels9001

@niels9001 Niels Laute (niels9001) commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Native Reactor ports of the Windows Community Toolkit's SettingsCard and SettingsExpander (spec 065). They have the same look in light, dark and contrast themes, the same narrow layout and the same keyboard and UI Automation behavior, with no CommunityToolkit.* dependency. The PR also adds a guide page, rebuilds the settings-page recipe on the cards, adds two gallery pages, and includes tests (unit, selftest, E2E) and the spec.

Stacked on #1509 (theme tokens in high contrast). The base is niels9001-theme-high-contrast, so the diff shows only the port. Retarget to main after #1509 merges.

Reference pages. samples/apps/wct-controls gets two pages with the same nine samples: "Settings reference" (Toolkit controls) and "Settings port" (this port). docs/specs/065/capture.ps1 captures both the same way for the side-by-side screenshots. Whether these pages stay in the PR is open for the draft review.

Screenshots. Spec §3.1 shows 38 Toolkit/port pairs side by side: wide, narrow and extra-narrow windows, light and dark, rest, disabled, expanded, hover and keyboard focus, all captured by docs/specs/065/capture.ps1 in one run at 150% scale. 10 pairs are identical. The others differ in at most 699 pixels, by at most 6 of 255 per color channel: anti-aliasing next to the left and right borders and in some text. Pressed is not captured (winapp ui has no press-and-hold), and high contrast is checked by hand.

Linked issue / spec

Fixes #1505. Implements docs/specs/065-settings-card.md.

Test plan

  • dotnet restore Reactor.slnx, then dotnet build Reactor.slnx --no-restore -c Release: passed, 0 errors (only the existing Win2D AnyCPU and NU1902/NU1903 warnings).
  • dotnet test tests/Reactor.Tests: 15,774 total, 15,756 passed, 0 failed, 18 skipped. New: tests/Reactor.Tests/SettingsCardTests.cs (27).
  • dotnet run --project tests/Reactor.AppTests.Host --no-build -c Debug -p:Platform=x64 -- --self-test --filter "Settings": 62/62 checks passed (new SettingsCardFixtures.cs, 6 fixtures).
  • dotnet test tests/Reactor.SelfTests -p:Platform=x64: 2,077 total, 1,998 passed, 77 skipped, 2 failed outside this change. AutoSuggestBoxCollectedStateTick passes when run alone (timing). DockSplitter_L06_DeepNested_Innermost needs wider panes than this 540-DIP display gives: its comment expects about 84 DIPs per pane, and the 60-DIP clamp absorbs the drag.
  • dotnet test tests/Reactor.AppTests -p:Platform=x64 --filter "ClassName=Microsoft.UI.Reactor.AppTests.Tests.SettingsCardInteractionTests": 4/4 passed with real input (click, Tab, Enter, Space, expander toggle, UIA roles and names).
  • Doc apps settings-cards and recipe-settings-page: dotnet build docs/_pipeline/apps/<app>/<app>.csproj --no-incremental -c Debug -p:Platform=x64 -p:TreatWarningsAsErrors=true -p:WarningsNotAsErrors=NU1900: 0 warnings.
  • dotnet run --project tools/Reactor.DocPipeline -- compile --topic <topic> for settings-cards, recipes/settings-page, controls and index: compiled, and the two pages' screenshots were captured.
  • dotnet run --project tools/Reactor.SearchIndex (108 controls) and the API index regeneration (mur --regen-api): both reactor.api.txt copies identical.
  • dotnet build samples/apps/wct-controls -p:Platform=x64 -p:RuntimeIdentifier=win-x64 and dotnet build samples/ReactorGallery -p:Platform=x64: passed.
  • winapp ui inspect of both reference pages: identical trees (spec §3.2). winapp ui invoke on a clickable card fails on the Toolkit and works on the port.
  • Side-by-side screenshot set: docs/specs/065/capture.ps1 on both reference pages, on a 2496 × 1664 display at 150%: 38 pairs, 10 identical, the others at most 699 pixels by at most 6 of 255 (spec §3.1).
  • By hand: high contrast (turn a contrast theme on and off while the app runs) and Narrator (names, roles, Invoke, expand and collapse).

Risk / breaking changes

  • New public API only: the SettingsCard(...) and SettingsExpander(...) factories, SettingsCardElement, SettingsExpanderElement, SettingsCardContentAlignment and their modifiers.
  • An app that wraps the Toolkit's SettingsCard with [GenerateReactorWrapper] and imports both factories will now bind SettingsCard("…", …) to the built-in, because string beats the wrapper's Optional<object> header. The wct-controls sample shows the alias fix, and the reactor-wrapping skill now warns about it.
  • Reconciler: ApplyThemeBindings and ClearThemeBindings honor a new internal IReactorBaseStyleHost. Only the new card implements it; other controls are unchanged.
  • Ports MIT-licensed code from CommunityToolkit/Windows at a2fa47ad; attribution is in cgmanifest.json and ThirdPartyNoticeText.txt. The NuGet packages do not include ThirdPartyNoticeText.txt yet; that existing gap is tracked in [Bug] NuGet packages don't include the third-party license notices #1535.

…ttingsExpander

Reference captures of the real Windows Community Toolkit controls, taken
before the native Reactor port so its screenshots can be compared side by
side.

- samples/apps/wct-controls: a "Settings reference" page with six fixed
  SettingsCard / SettingsExpander samples (stable AutomationIds, solid page
  background) and a light/dark switch that sets RequestedTheme on the app
  root. SettingsExpander's wrapper gains HeaderIcon and Content element slots
  so the expander header can show an icon and a ComboBox.
- docs/specs/065/capture.ps1: drives the page with `winapp ui`, crops each
  sample (UIA bounds + 8 px) from a viewport capture, uses a fresh app
  instance per theme, and fails if a hover or focus capture equals the rest
  state.
- docs/specs/065/capture-runbook.md: content, steps, window sizes, file list.
- docs/specs/065/toolkit/: 28 PNGs (light and dark; rest, hover, keyboard
  focus, disabled; expander collapsed and expanded; wide, narrow, extra
  narrow).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A native port of the Windows Community Toolkit's SettingsCard and SettingsExpander
(issue #1505), with no dependency on the Toolkit:

- SettingsCard(header, description, icon, content, onClick), an Element overload for
  rich header/description content, and SettingsCard(Command).
- SettingsExpander(header, description, icon, content, isExpanded,
  onIsExpandedChanged, items), with .ItemsHeader / .ItemsFooter.
- .ContentAlignment, .ActionIcon, .ActionIconToolTip, .ActionIconVisible.
- The Toolkit's templates and styles, loaded with XamlReader; the card's states,
  wrap thresholds, content naming and automation peers ported to C#. A clickable
  card is a Button with a working Invoke; other cards are unnamed groups; the
  expander is a group named after its header.
- Theme bindings on a control with an explicit base style build on that style
  (IReactorBaseStyleHost), so theme-token modifiers restyle the cards.
- wct-controls: a "Settings port" page renders the reference content with the
  port; the Toolkit wrappers are called through aliases.

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

- Guide page docs/guide/settings-cards.md (template + doc app + captures), catalog
  and index entries, and the settings-page recipe rebuilt on SettingsCard.
- ReactorGallery SettingsCard and SettingsExpander pages; search index and API
  indexes regenerated.
- .Click(...) and .IsExpandedChanged(...) callback fluents for the new elements.
- E2E tests: real click, Tab/Enter/Space, expander toggle, UIA roles and names.
- wct-controls: three more reference samples on both pages (Left alignment,
  custom action icon, expander items header/footer and clickable item).
- reactor-wrapping skill: wrap HeaderedContentControl in the example, and warn
  that a wrapper named like a built-in factory loses overload resolution.
- Spec 065 draft and capture runbook updates; CHANGELOG, cgmanifest and
  third-party notice entries for the ported Toolkit code.

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

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build metrics

Artifact sizes for cb0ad46 vs the base branch (500ca22).

Packages (compressed .nupkg)

Artifact base PR Δ
Microsoft.UI.Reactor.nupkg 2.06 MB 2.10 MB +43.9 KB (+2.08%) ⚠️
Microsoft.UI.Reactor.Advanced.nupkg 521.7 KB 521.7 KB +10 B (0.00%) ≈
Microsoft.UI.Reactor.Devtools.nupkg 287.8 KB 287.8 KB +4 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor

Artifact base PR Δ
Reactor.Analyzers.dll 411.0 KB 411.0 KB +0 B (0.00%) ≈
Reactor.dll 2.79 MB 3.30 MB +516.0 KB (+18.03%) ⚠️
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 145.5 KB 145.5 KB +0 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor.Advanced

Artifact base PR Δ
Reactor.Advanced.dll 1.06 MB 1.06 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.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

🧪 Merged coverage

Coverage for cb0ad46 vs the base branch (6889229) — unit + selftest merged.

Metric base PR Δ
Line 88.59% 88.66% +0.07 pp ≈
Branch 46.38% (18059/38935) 46.07% (18146/39391) -0.31 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.

- Command cards: a command that cannot run now blocks the card in the control,
  so an unchanged .IsEnabled(false) modifier is no longer overwritten on later
  renders and a disabled command wins over .IsEnabled(true).
- Header/description elements with styling ShallowEquals ignores (MaxLines,
  selection, wrapping, decorations, setters, extras) stay rich content.
- Expander chevron: retry the AnimatedIcon state hook on size changes, so an
  expander mounted (or restyled) while hidden still animates its chevron.
- Base-style host: keep the cache key with the chosen base style.
- Docs: expander restyling scope (as in the Toolkit), content naming for check
  boxes and element headers, Command accelerator/access key, narrow Left; the
  Left samples name their check box. CHANGELOG migration note, DSL reference,
  mkdocs nav, threat-model OSS inventory, capture script cleanup.
- Tests: non-tautological command/enabled, naming, disabled-state, RTL and
  hover-reset checks; chevron state, uncontrolled expander, collapse from
  state, mirrored properties, theme token across contrast and on items,
  contrast re-parenting; null-clear tests for the new fluents.

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

- Spec 065 §3.1: light/dark, top/bottom whole-page pairs of both reference
  pages with measured pixel differences (only the page title and scroll
  indicator differ above the fold; 11-22 pixels by one color step below).
- §3.3: a disabled toggle keeps the outline color of the theme it was disabled
  in, in both controls; captures use a fresh app instance per page and theme.
- capture.ps1: per-monitor DPI aware (window sizes were scaled twice above
  100%), -WindowHeight, opens a hidden navigation pane, scrolls samples that
  are out of view into view. Runbook updated (new files, page captures).
- Selftests: toggle outline colors per state, including a card disabled from
  mount.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Bring in the high-contrast fix branch, now up to date with main. CHANGELOG.md
merged cleanly: the port's Added and Changed entries plus both Fixed entries
(#1268, #1506).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Capture the Toolkit and Reactor sets in one run at 150% scale (wide, narrow and
extra-narrow windows; rest, disabled, expanded, hover and keyboard focus). The new
Toolkit set replaces the earlier 100% one, so both images of a pair have the same
scale. Section 3.1 now shows the 38 pairs side by side and describes the
differences: 10 pairs are identical, the others differ in at most 699 pixels by at
most 6 of 255 (border-edge and text anti-aliasing). Section 7 links #1534.

capture.ps1: bring samples into view with scroll-into-view plus one step instead of
scrolling to the page end (near the end the viewport's UI Automation bounds grow
past the window and the capture comes back clipped), wait for scrolling to settle,
stop when Windows shrinks the window or a capture is blank, and add -Themes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Brings the #1509 fix that follows contrast switches once WinUI applies them.

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

# Conflicts:
#	tests/Reactor.AppTests.Host/SelfTest/SelfTestFixtureRegistry.cs
Brings the #1509 follow-up: a theme probe counts only while its root is in the live tree.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Brings the #1509 follow-up: a live theme probe hands over on a root swap.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Brings the #1509 fix that keeps the theme probe off the root's Loaded and Unloaded events.

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

This branch has not been deployed

No deployments
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.

1 participant