reactor-wrapping

# Reactor — Wrapping Arbitrary Controls (source generator) Use this skill when the app needs a control Reactor has **no built-in factory for** — a Windows Community Toolkit control, a third-party vendor control, or the app's own custom `Control` subclass. The `Reactor.Wrappers.Generator` source generator turns the control into a first-class declarative element (init-props + `ControlDescriptor` + Pattern-A registration + a parameterized factory named after the control) from a single annotated partial record. **No hand-written wrapper, handler, or registration code.** > Canonical worked example: `samples/apps/wct-controls/` (declarations in > `WctControls.cs`, usage in `Program.cs`). Design spec: `docs/specs/058-control-wrapper-generator.md`. > For controls the generator still can't express, drop to the hand-written > `ControlDescriptor` / `IElementHandler` path in `docs/guide/extending-reactor-controls.md`. ## The whole feature in one example ```csharp using Microsoft.UI.Reactor.Wrappers; // the [Wrap*] authoring attributes namespace MyApp; // 1. Declare an empty partial record, annotated with the control to wrap. [GenerateReactorWrapper(typeof(CommunityToolkit.WinUI.Controls.SettingsCard))] public partial record SettingsCardElement; ``` ```csharp // 2. Consume the generated factory via `using static` (named after the control). using static MyApp.SettingsCardElement; SettingsCard( header: "Wi-Fi", description: wifiOn ? "Connected" : "Disconnected", content: ToggleSwitch(isOn: wifiOn, onIsOnChanged: setWifiOn)) // a Reactor child INSIDE a WCT control ``` The generator fills the rest of that partial: one init-property per surfaced control property, the single-content/children slot, `On{Event}` callbacks, the `ControlDescriptor`, the trim-rooting `static` cctor registration, and the `SettingsCard(...)` factory. `Setters` is always emitted as an escape hatch (`.Set(c => c.Foo = …)`) for anything not surfaced. **You never call `ReactorApp.RegisterControlAssembly` yourself** — the generator emits it in the element's static constructor, so a control library's `Themes/Generic.xaml` resolves before first realization (avoids the `0xC000027B` crash, spec 058 §9a). ## Requirements & setup - Reference `Microsoft.UI.Reactor` (carries the generator in `analyzers/dotnet/cs/` and the authoring attributes in `Reactor.Wrappers.Abstractions.dll`). - Reference the control's own package (e.g. the WCT `CommunityToolkit.WinUI.Controls.*` packages). - The target must be a **non-static `FrameworkElement`** with a **public parameterless constructor** (else `REACTORGEN001`). - Keep the record `partial` (the generator fills the other half) and in a namespace you control. ## What is auto-inferred (zero config) The generator walks members from the most-derived type **up to but excluding** `Control`/`FrameworkElement` (Reactor already models that layout plumbing via generic modifiers like `.Margin()`, `.Width()`): | Control shape | Becomes | |---|---| | Settable value prop (`string`/`object`→text, `bool`/`int`/`double`/enum, structs like `Thickness`/`Color`, `Brush`/`FontFamily`, `bool?`/`DateTimeOffset?` tri-state) | a nullable / `Optional<T>` **one-way** init-prop (skipped when unset) | | Value prop `P` **paired with** a `{P}Changed` event | a **two-way controlled** `Optional<T>` prop + `On{P}Changed` callback, with echo suppression | | The control's `[ContentProperty]` (a `UIElement` child, or `object` named exactly `Content`) | the single **`content:`** child slot | | A public `Children` of `UIElementCollection` (a `Panel`) | a `params Element[]` children slot | | A public `Items` whose type is/implements `IList<object>` (an `ItemsControl`) | a `params object[] items` slot | | A fire-and-forget `RoutedEventHandler` / `TypedEventHandler<,>` / `EventHandler<A>` event | an `On{Event}` callback (typed events auto-surface the whole args as `Action<A>`) | Two-way auto-pairing keys **strictly on the `{P}Changed` name**. Controls whose change event breaks that convention (`ToggleSwitch.IsOn`↔`Toggled`, `Segmented.SelectedIndex`↔`SelectionChanged`) stay one-way until you add `[WrapControlled]`. ## Annotation cheat-sheet (opt-in, when inference isn't enough) All live in `Microsoft.UI.Reactor.Wrappers`. All are repeatable unless noted. | Attribute | Use it to… | |---|---| | `[GenerateReactorWrapper(typeof(T), Exclude/Include/AutoDiscover)]` | wrap `T`; prune noisy inherited props (`Exclude = new[]{ "CommandParameter" }`) or switch to explicit opt-in (`AutoDiscover = false, Include = new[]{ … }`). | | `[WrapControlled("P", ChangedEvent = "…")]` | make `P` two-way when its event isn't `{P}Changed`. Use `Events = new[]{ "Checked","Unchecked" }` for multi-event values (read back after any fire). `Deferred = true` for deferred/coercing string boxes (`PasswordBox.Password`, `AutoSuggestBox.Text`). A control has **one** controlled slot — two `[WrapControlled]` on one control warns `REACTORGEN012`. | | `[WrapOneWay("P")]` | opt a prop **out** of two-way auto-pairing (display-only despite a `{P}Changed`, e.g. `ProgressBar.Value`). | | `[WrapAlias("FriendlyName", "ControlProperty")]` | surface a control prop under a nicer name (`"Min"`→`"Minimum"`). Aliasing the content property turns it into a string value prop (no child slot). | | `[WrapContent("Prop")]` | override which property is the `content:` child slot. | | `[WrapConvert("Prop")]` | surface a struct prop (`CornerRadius`, `Thickness`) as an ergonomic scalar via its single-arg constructor (`double?` → `new CornerRadius(v)`). | | `[WrapEvent("Foo", Arg = "ErrorMessage")]` | project event args into a typed `On{Event}(args.Arg)` callback; `Args = new[]{ … }` for multi-param. | | `[WrapLifecycle(nameof(Start), OnUnmounted = nameof(Stop))]` | run a `static void M(TControl)` on mount/unmount for imperative controls (`CameraPreview.StartAsync`) — **no call-site boilerplate**. | | `[WrapPanelChildren(PerChild = …)]` | wire per-child attached props (`Grid.SetRow`, `Canvas.SetLeft`) onto a panel; `AfterAll` for two-pass (RelativePanel). | | `[WrapManual("P")]` + `static partial Customize(d)` | hand-chain one entry the generator can't infer while it still generates the rest. | | `[WrapElementSlot("Prop", ControlProperty = "…")]` | auto-wire a **secondary single-element slot** that writes a dedicated control property (`TabView.TabStripHeader`, `SettingsCard.HeaderIcon`) — mounts via `ctx.MountChild`, updates via state-preserving `ctx.ReconcileChild`. Use `ControlProperty=` when the element-facing name differs from the control property. The control property must be public-settable and `object`/`UIElement`-typed. For the **primary** child use `[WrapContent]`; for a slot that shares a control prop with a string fallback (`Expander.Header`) stay manual. | | `[WrapPolymorphic(nameof(Resolve))]` / `[WrapDecorator(nameof(Create))]` | controls whose concrete type is chosen at runtime, or that need a fully custom mount/update/unmount lifecycle (emit an `IDecoratorElementHandler`, not a descriptor). | ### Imperative control (lifecycle) — paste-ready ```csharp // CameraPreview must be StartAsync'd after mount and Stop'd on unmount. Declared // ONCE here, so every call site is a plain declarative `CameraPreview(...)`. [GenerateReactorWrapper(typeof(CommunityToolkit.WinUI.Controls.CameraPreview))] [WrapEvent("PreviewFailed", Arg = "Error")] [WrapLifecycle(nameof(StartPreview), OnUnmounted = nameof(StopPreview))] public partial record CameraPreviewElement { private static async void StartPreview(CommunityToolkit.WinUI.Controls.CameraPreview cp) { try { await cp.StartAsync(cp.CameraHelper); } catch { /* surfaced via PreviewFailed */ } } private static void StopPreview(CommunityToolkit.WinUI.Controls.CameraPreview cp) { try { cp.Stop(); } catch { /* already torn down */ } } } ``` ### Non-conventional two-way event ```csharp // SelectedIndex changes through SelectionChanged, not SelectedIndexChanged. [GenerateReactorWrapper(typeof(CommunityToolkit.WinUI.Controls.Segmented))] [WrapControlled("SelectedIndex", ChangedEvent = "SelectionChanged")] public partial record SegmentedElement; // → Segmented(selectedIndex: idx, onSelectedIndexChanged: setIdx, items: …) ``` ## Hand-tuning a single generated member Write the member yourself in your half of the partial; the generator skips any member you declare. Example — treat `Header` as templated Reactor content instead of plain text: ```csharp public partial record SettingsCardElement { public Element? Header { get; init; } } ``` ## Diagnostics `REACTORGEN001` (target isn't a non-static `FrameworkElement` with a public parameterless ctor) · `…002` (bad Include/Exclude name) · `…003`/`…004` (WrapControlled property / change-event) · `…005` (WrapAlias control property) · `…006` (WrapOneWay) · `…007` (WrapContent) · `…008` (WrapConvert) · `…009`/`…010` (WrapEvent target / arg) · `…011` (WrapLifecycle method) · `…012` (two controlled props share one control) · `…013` (WrapElementSlot control property missing/not-settable — set `ControlProperty=`) · `…014` (WrapElementSlot control property not `UIElement`-assignable) · `…015` (WrapElementSlot slot name not a valid identifier). Run `mur check <path>` — it surfaces these with skill pointers. ## When to drop to a hand-written descriptor The generator targets the common case. Reach for the manual `ControlDescriptor` / `IElementHandler` path (`docs/guide/extending-reactor-controls.md`, registered via `ControlRegistry.RegisterHandler`) only when a control's contract is something the attributes above can't yet express — and prefer adding a reusable `[Wrap*]` capability over a one-off handler when the shape is general.