pass 3

Author: Jay-o-Way

specs/DateTimePicker-Visual-Updates-Spec.md

@@ -10,9 +10,9 @@ This allows the element to appear to be an overlay on top of the other element.
 
 `MonochromaticOverlayPresenter` element is similar to several precedents:
 
-* [CompositionMaskBrush](https://learn.microsoft.com/uwp/api/Windows.UI.Composition.CompositionMaskBrush),
+- [CompositionMaskBrush](https://learn.microsoft.com/uwp/api/Windows.UI.Composition.CompositionMaskBrush),
 which  is a brush that gets its content from another (source) brush.
-* WPF's [VisualBrush](https://learn.microsoft.com/dotnet/api/System.Windows.Media.VisualBrush),
+- WPF's [VisualBrush](https://learn.microsoft.com/dotnet/api/System.Windows.Media.VisualBrush),
 which uses an element's rendering to draw a brush.
 
 A key difference in this new type is that it only renders the portion of the source
@@ -70,12 +70,12 @@ The following example puts a `MonochromaticOverlayPresenter` on top of (z-ordere
 some scrolling text, causing the center of the text to be highlighted, even as it's scrolling.
 Things to note:
 
-* The `MonochromaticOverlayPresenter` is sourcing from the `TextBlock`, it's also z-ordered above
+- The `MonochromaticOverlayPresenter` is sourcing from the `TextBlock`, it's also z-ordered above
 the same `TextBlock`. If the `Background` and `SourceElement` properties weren't set,
 it would have no effect; it would render the `TextBlock` exactly on top of itself.
-* The `MonochromaticOverlayPresenter` is positioned and given a height such that it's a black band
+- The `MonochromaticOverlayPresenter` is positioned and given a height such that it's a black band
 across the center of the scrolling text.
-* The `MonochromaticOverlayPresenter.IsHitTestVisible` property is set to False, so that input
+- The `MonochromaticOverlayPresenter.IsHitTestVisible` property is set to False, so that input
 still goes to the ScrollViewer that is z-ordered behind it.
 
 ```xml

specs/Popup-AdditionalLayoutProperties-Spec.md

@@ -8,9 +8,9 @@ and
 [flyouts](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Primitives.FlyoutBase)
 in XAML are given two modes of display:
 
-* They can either appear as part of the rest of XAML,
+- They can either appear as part of the rest of XAML,
 in which case they're confined to the bounds of the XAML root,
-* Or they can appear in their own HWND, which
+- Or they can appear in their own HWND, which
 allows them to escape the bounds of the XAML root. This is common for elements such as context menus.
 
 [CommandBarFlyout](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.CommandBarFlyout)

specs/SystemBackdropElement_Spec.md

@@ -4,25 +4,25 @@ SystemBackdropElement
 # Background
 
 There are backdrop materials provided in WinUI such as Mica, Acrylic that are subclass of
-[Microsoft.UI.Xaml.Media.SystemBackdrop](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.systembackdrop). Currently, it is possible to add a system backdrop only at the window level or on flyouts, but not in a specific area in the visual tree. This has been a major limitation on WinUI 3 compared to WinUI2 in achieving the acrylic / mica effects, especially for achieving various animations.
+[Microsoft.UI.Xaml.Media.SystemBackdrop](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.systembackdrop). Currently, it is possible to add a system backdrop only at the window level or on flyouts, but not in a specific area in the visual tree. This has been a major limitation on WinUI 3 compared to WinUI 2 in achieving the acrylic / mica effects, especially for achieving various animations.
 
 `SystemBackdropElement` is a lightweight `FrameworkElement` that bridges between the XAML tree and the composition
 infrastructure required by `SystemBackdrop`. It creates the required composition components to add the systembackdrop on a specific area, resizes the systembackdrop to fill the given area, and applies the clip on the backdrop visual based on `CornerRadius` values applied on `SystemBackdropElement` which helps for rounded corners to
 appear as expected. This control abstracts lot of details for the composition layer and hence make it easy
 for WinUI 3 developers to implement the acrylic effect in the applications.
 
-In WinUI2, it was possible to achieve the backdrop using `BackgroundSource` property of [AcrylicBrush](https://learn.microsoft.com/uwp/api/windows.ui.xaml.media.acrylicbrush?view=winrt-26100), However in WinUI 3, [AcrylicBrush](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) doesn't provide `BackgroundSource` property leaving it capable of achieving only in-app acrylic. This is due to the limitation of WinUI 3 compositor which is running in-proc, and so can't fetch buffers outside the application window. In this design, the solution is to leverage the [ContentExternalBackdropLink](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.content.contentexternalbackdroplink) API. It provides `PlacementVisual` that would be used for rendering the backdrop in the WinUI 3 visual tree. `SystemBackdropElement` control takes care of resizing and positioning this `PlacementVisual` as per the position, size and Z-order of the control.
+In WinUI 2, it was possible to achieve the backdrop using `BackgroundSource` property of [AcrylicBrush](https://learn.microsoft.com/uwp/api/windows.ui.xaml.media.acrylicbrush?view=winrt-26100), However in WinUI 3, [AcrylicBrush](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) doesn't provide `BackgroundSource` property leaving it capable of achieving only in-app acrylic. This is due to the limitation of WinUI 3 compositor which is running in-proc, and so can't fetch buffers outside the application window. In this design, the solution is to leverage the [ContentExternalBackdropLink](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.content.contentexternalbackdroplink) API. It provides `PlacementVisual` that would be used for rendering the backdrop in the WinUI 3 visual tree. `SystemBackdropElement` control takes care of resizing and positioning this `PlacementVisual` as per the position, size and Z-order of the control.
 
 ## Goals
 
-* Provide an intuitive, XAML-friendly way to place a system backdrop anywhere inside application's visual tree.
-* Handle connection, disconnection, and sizing so application only have to set a backdrop and position the element.
-* Allow to put rounded corners on the backdrop without writing custom composition code.
+- Provide an intuitive, XAML-friendly way to place a system backdrop anywhere inside application's visual tree.
+- Handle connection, disconnection, and sizing so application only have to set a backdrop and position the element.
+- Allow to put rounded corners on the backdrop without writing custom composition code.
 
 ## Non-goals
 
-* Adding a SystemBackdrop property independently on all controls.
-* Provide a content container; `SystemBackdropElement` is purely a visual effect surface and is not a container.
+- Adding a SystemBackdrop property independently on all controls.
+- Provide a content container; `SystemBackdropElement` is purely a visual effect surface and is not a container.
 
 # Conceptual pages (How To)
 
@@ -76,7 +76,7 @@ Keep the `SystemBackdropElement` in the bottom of the stack below other contents
 
 The same pattern works from code:
 
-* C#:
+- C#:
 
 ```csharp
 var backdropElement = new SystemBackdropElement
@@ -87,7 +87,7 @@ var backdropElement = new SystemBackdropElement
 rootGrid.Children.Add(backdropElement);
 ```
 
-* C++:
+- C++:
 
 ```cpp
 winrt::Microsoft::UI::Xaml::Controls::SystemBackdropElement backdropElement;
@@ -101,27 +101,27 @@ If a `CornerRadius` is applied on the parent `rootGrid`, that would clip the `Sy
 
 ### Remarks
 
-* _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._
-* It is recommended to be used as first element for background effect to work appropriately, for example as the first child inside a
+- _Spec note: This API is currently `experimental`; the API surface may still change before it is finalized._
+- It is recommended to be used as first element for background effect to work appropriately, for example as the first child inside a
     panel. (First element added to tree gets rendered first and goes in the bottom of stack)
-* The `SystemBackdropElement` only connects to a backdrop while it has a `XamlRoot`. If the element is not in the live tree, the backdrop
+- The `SystemBackdropElement` only connects to a backdrop while it has a `XamlRoot`. If the element is not in the live tree, the backdrop
     remains disconnected until it is loaded.
-* As `SystemBackdropElement` control punches a hole in the layout to show the SystemBackdrop, properties like Shadow, Lights, Clip & Transform may not behave as intended.
+- As `SystemBackdropElement` control punches a hole in the layout to show the SystemBackdrop, properties like Shadow, Lights, Clip & Transform may not behave as intended.
 
 ## SystemBackdropElement.SystemBackdrop property
 
 Gets or sets the `SystemBackdrop` instance that renders in the `SystemBackdropElement` area. The default value is `null`.
 
-* You can data bind this property. Typical values include `MicaBackdrop`, `DesktopAcrylicBackdrop`, or a
+- You can data bind this property. Typical values include `MicaBackdrop`, `DesktopAcrylicBackdrop`, or a
     custom subclass of `SystemBackdrop`.
-* If the `SystemBackdropElement` does not yet have a `XamlRoot`, the connection is postponed until one becomes available.
+- If the `SystemBackdropElement` does not yet have a `XamlRoot`, the connection is postponed until one becomes available.
 
 ## SystemBackdropElement.CornerRadius property
 
 Gets or sets the `CornerRadius` applied to the backdrop surface. The default value of `CornerRadius` is 0.
 
-* The `SystemBackdropElement` applies a `RectangleClip` on the composition visual of SystemBackdrop to achieve the rounded corners.
-* Default `CornerRadius` value will be 0 aligning with [control templates](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.cornerradius#remarks) behavior.
+- The `SystemBackdropElement` applies a `RectangleClip` on the composition visual of SystemBackdrop to achieve the rounded corners.
+- Default `CornerRadius` value will be 0 aligning with [control templates](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.control.cornerradius#remarks) behavior.
 
 # API Details
 

specs/appwindow-spec.md

@@ -19,7 +19,7 @@ expose AppWindow object directly to app developer through an API. Instead of wri
 code everywhere, app developer can use this API, reducing code bloat, and making AppWindow APIs easily
 accessible from WinUI 3 code.
 
-These *before* and *after* C# code examples illustrate how this API simplifies integrating AppWindow APIs in WinUI 3 codebase.
+These _before_ and _after_ C# code examples illustrate how this API simplifies integrating AppWindow APIs in WinUI 3 codebase.
 
 - Before
 

specs/xaml-backdrop-api.md

@@ -80,7 +80,7 @@ Use this class to set a backdrop on a
 [Popup](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Controls.Primitives.Popup)\*,
 or [FlyoutBase](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Xaml.Controls.Primitives.FlyoutBase)\* (such as a `Flyout` or `MenuFlyout`).
 
-* `Popup`/`MenuFlyout` `SystemBackdrop` support is not available in WinAppSDK 1.3.0, but is expected to light up in a subsequent release. Note also `SystemBackdrop` will only work in "windowed" popups, i.e. those with _ShouldConstrainToRootBounds=False_.
+- `Popup`/`MenuFlyout` `SystemBackdrop` support is not available in WinAppSDK 1.3.0, but is expected to light up in a subsequent release. Note also `SystemBackdrop` will only work in "windowed" popups, i.e. those with _ShouldConstrainToRootBounds=False_.
 
 For example:
 
@@ -103,8 +103,8 @@ You don't create this class directly, but subclass it to add your custom support
 
 Generally, the custom material overrides `OnTargetConnected` to create and configure a backing [ISystemBackdropController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.isystembackdropcontroller?view=windows-app-sdk-1.3), which will manage the [CompositionBrush](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositionbrush?view=windows-app-sdk-1.3) used to fill the backdrop region. The brush's ultimate pixel rendering is affected by the environment/policy (set via [SystemBackdropConfiguration](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration?view=windows-app-sdk-1.3)) and material's appearance parameters, exposed via general (eg `ICompositionControllerWithTargets.SystemBackdropState` ∈ { _`Active` / `Fallback` / `HighContast`_ }) and material-specfic (eg `MicaController.Kind` ∈ { _`Base` / `BaseAlt`_} _SystemBackdropController_ properties.
 
-* The controllers available today (`MicaController` and `DesktopAcrylicController`) support the following parameters for customizing their appearance: [FallbackColor](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.fallbackcolor?view=windows-app-sdk-1.3), [LuminosityOpacity](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.luminosityopacity?view=windows-app-sdk-1.3), [TintColor](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintcolor?view=windows-app-sdk-1.3), and [TintOpacity](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintopacity?view=windows-app-sdk-1.3).
-* The provided XAML backdrop materials `MicaBackdrop` and `DesktopAcrylicBackdrop` currently do not expose `FallbackColor` or the material customization properties (`TintOpacity`, etc), instead relying on the default Light/Dark configurations of the underlying `MicaController` and `DesktopAcrylicController`. To customize these properties, createa a custom material class deriving from SystemBackdrop that exposes the desired properties.
+- The controllers available today (`MicaController` and `DesktopAcrylicController`) support the following parameters for customizing their appearance: [FallbackColor](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.fallbackcolor?view=windows-app-sdk-1.3), [LuminosityOpacity](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller.luminosityopacity?view=windows-app-sdk-1.3), [TintColor](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintcolor?view=windows-app-sdk-1.3), and [TintOpacity](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller.tintopacity?view=windows-app-sdk-1.3).
+- The provided XAML backdrop materials `MicaBackdrop` and `DesktopAcrylicBackdrop` currently do not expose `FallbackColor` or the material customization properties (`TintOpacity`, etc), instead relying on the default Light/Dark configurations of the underlying `MicaController` and `DesktopAcrylicController`. To customize these properties, createa a custom material class deriving from SystemBackdrop that exposes the desired properties.
 
 The following example shows a simple custom system backdrop class that's implemented using
 [MicaController](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.Composition.SystemBackdrops.MicaController).
@@ -166,18 +166,18 @@ object that is set and maintained automatically for each `SystemBackdrop` usage
 
 The properties on `SystemBackdropConfiguration` you receive may change over time:
 
-* `Theme`: set based on [ElementTheme](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.ElementTheme) of the target element (obtained from xamlRoot.Content)
-  * If `FallbackColor`, `LuminosityOpacity`, `TintColor`, or `TintOpacity` are modified by the material's implementation, changes to associated [SystemBackdropConfiguration.Theme](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration.theme?view=windows-app-sdk-1.3) will no longer automatically toggle the controller's theme (since  default Dark and Light configurations are no longer appropriate). In this case, the material's appearance properties need to be manually updated to match the new Theme in `SystemBackdrop.OnDefaultSystemBackdropConfigurationChanged`.
+- `Theme`: set based on [ElementTheme](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.ElementTheme) of the target element (obtained from xamlRoot.Content)
+  - If `FallbackColor`, `LuminosityOpacity`, `TintColor`, or `TintOpacity` are modified by the material's implementation, changes to associated [SystemBackdropConfiguration.Theme](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.systembackdropconfiguration.theme?view=windows-app-sdk-1.3) will no longer automatically toggle the controller's theme (since  default Dark and Light configurations are no longer appropriate). In this case, the material's appearance properties need to be manually updated to match the new Theme in `SystemBackdrop.OnDefaultSystemBackdropConfigurationChanged`.
 
-* `IsInputActive`: true if the target of the `SystemBackdrop` is in the active window.
+- `IsInputActive`: true if the target of the `SystemBackdrop` is in the active window.
 
-* `IsHighContrast`: true if the target of the `SystemBackdrop` is in high contrast mode.
+- `IsHighContrast`: true if the target of the `SystemBackdrop` is in high contrast mode.
 
 ## SystemBackdrop.OnDefaultSystemBackdropConfigurationChanged virtual protected method
 
 Override this method to be called when one of the properties (described above) on the object returned by `GetDefaultSystemBackdropConfiguration` has changed.
 
-* This is useful when implementing a custom `SystemBackdropConfiguration` that incorporates some of the tracked property states but is different in some way from the default policy. First, obtain a  `SystemBackdropConfiguration` object from `GetDefaultSystemBackdropConfiguration` as usual, but do not apply it via `CompositionController.SetSystemBackdropConfiguration`. Instead  create an additional `SystemBackdropConfiguration` object that is updated on `OnDefaultSystemBackdropConfigurationChanged` by applying custom logic to the tracked property (eg ignoring Theme change). The second `SystemBackdropConfiguration` object is hooked up to `CompositionController.SetSystemBackdropConfiguration`, applying the custom policy.
+- This is useful when implementing a custom `SystemBackdropConfiguration` that incorporates some of the tracked property states but is different in some way from the default policy. First, obtain a  `SystemBackdropConfiguration` object from `GetDefaultSystemBackdropConfiguration` as usual, but do not apply it via `CompositionController.SetSystemBackdropConfiguration`. Instead  create an additional `SystemBackdropConfiguration` object that is updated on `OnDefaultSystemBackdropConfigurationChanged` by applying custom logic to the tracked property (eg ignoring Theme change). The second `SystemBackdropConfiguration` object is hooked up to `CompositionController.SetSystemBackdropConfiguration`, applying the custom policy.
 
 ## Other `SystemBackdrop` members