Merge pull request #17423 from unoplatform/mergify/bp/release/stable/…

…5.3/pr-17374

docs(WCT): Add additional details for non-Windows platform compatibility and troubleshooting for Windows Community Toolkit (backport #17374)

doc/articles/uno-community-toolkit-v7.md

@@ -4,7 +4,9 @@ uid: Uno.Development.CommunityToolkit.v7
 
 # How to use Windows Community Toolkit - Version 7.x
 
-This tutorial will walk you through adding and implementing the `DataGrid` control but the same steps can be followed for any of the Uno ported Windows Community Toolkit controls versions 7.x.
+This tutorial will walk you through adding and implementing the `DataGrid` control but the same steps can be followed for **other\*** Uno ported Windows Community Toolkit controls versions 7.x.
+
+**\* See the [non-Windows platform compatibility](xref:Uno.Development.CommunityToolkit#non-windows-platform-compatibility) section for more details.**
 
 > [!NOTE]
 > The complete source code that goes along with this guide is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [`DataGrid` Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-7.x/UnoWCTDataGridSample).

doc/articles/uno-community-toolkit-v8.md

@@ -4,7 +4,9 @@ uid: Uno.Development.CommunityToolkit.v8
 
 # How to use Windows Community Toolkit - Version 8.x
 
-This tutorial will walk you through adding and implementing the `SettingsCard` control but the same steps can be followed for any of the Windows Community Toolkit controls version 8.x.
+This tutorial will walk you through adding and implementing the `SettingsCard` control but the same steps can be followed for **other\*** Windows Community Toolkit controls version 8.x.
+
+**\* See the [non-Windows platform compatibility](xref:Uno.Development.CommunityToolkit#non-windows-platform-compatibility) section for more details.**
 
 > [!NOTE]
 > The complete source code that goes along with this guide is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [`SettingsCard` Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-8.x/UnoWCTSettingsCardSample)

doc/articles/uno-community-toolkit.md

@@ -8,8 +8,10 @@ The [Windows Community Toolkit](https://learn.microsoft.com/windows/communitytoo
 
 Depending on the version of the Windows Community Toolkit that you want to use, these tutorials below will walk you through adding and implementing:
 
-- **[For WCT version 8.x](xref:Uno.Development.CommunityToolkit.v8):** The `SettingsCard` control, but the same steps can be followed for any of the Windows Community Toolkit components supported out of the box.
-- **[For WCT version 7.x](xref:Uno.Development.CommunityToolkit.v7):** The `DataGrid` control, but the same steps can be followed for any of the Uno ported Windows Community Toolkit components.
+- **[For WCT version 8.x](xref:Uno.Development.CommunityToolkit.v8):** The `SettingsCard` control, but the same steps can be followed for **other\*** Windows Community Toolkit components supported out of the box.
+- **[For WCT version 7.x](xref:Uno.Development.CommunityToolkit.v7):** The `DataGrid` control, but the same steps can be followed for **other\*** Uno ported Windows Community Toolkit components.
+
+**\* See the [non-Windows platform compatibility](#non-windows-platform-compatibility) section below for more details.**
 
 > [!IMPORTANT]
 > **Here is the [Migration Guide from v7 to v8 for Windows Community Toolkit](https://github.com/CommunityToolkit/Windows/wiki/Migration-Guide-from-v7-to-v8) for additional information on what changed lately between these versions.**
@@ -20,3 +22,31 @@ Depending on the version of the Windows Community Toolkit that you want to use,
 >
 > - [Release notes for version 7.x](https://github.com/CommunityToolkit/WindowsCommunityToolkit/releases)
 > - [Release notes for version 8.x](https://github.com/CommunityToolkit/Windows/releases)
+
+## Non-Windows platform compatibility
+
+### Overview
+
+While all Windows Community Toolkit packages are supported for UWP and WinAppSDK, this is not the case for the other platforms Uno Platform supports.
+
+### Unsupported Components
+
+Some components, like [Media](https://github.com/CommunityToolkit/Windows/tree/main/components/Media/src), rely heavily on Composition APIs that are not yet supported by Uno Platform on all platforms. As a result, the Media package does not have the Uno-powered [MultiTargets](https://github.com/CommunityToolkit/Windows/blob/main/components/Media/src/MultiTarget.props) enabled, as the component would be non-functional out of the box.
+
+In such cases, the Windows Community Toolkit prefers to disable the package for Uno Platform rather than enable it and have it not work. To address these functional gaps, we encourage contributing to Uno Platform to bridge the gaps for the missing supported APIs or to the [Windows Community Toolkit](https://github.com/CommunityToolkit/Windows) by seeking or helping to build Uno-compatible alternatives.
+
+### Partial Support
+
+In limited cases, WCT packages may have partial support for Uno Platform where the TargetFramework is enabled, but not all Toolkit code works out of the box. Currently, the only package in this scenario is Animations. It has a special FrameworkLayer abstraction that enables `AnimationBuilder` and `CustomAnimation` on Uno-powered MultiTargets but does not extend to `ImplicitAnimationSet` or Connected Animations.
+See [CommunityToolkit/Windows #319](https://github.com/CommunityToolkit/Windows/issues/319) for tracking.
+
+### Majority Support
+
+The majority of controls are supported on all platforms by default.
+If you find a package that doesn't work as expected on Uno Platform, please open an [issue](https://github.com/unoplatform/uno/issues/new/choose) or [discussion](https://github.com/unoplatform/uno/discussions) to let us know.
+
+## Troubleshooting
+
+The features and support for Uno Platform and Windows Community Toolkit components are constantly evolving. Therefore, you may encounter some issues while building your application. We encourage you to report these [issues](https://github.com/unoplatform/uno/issues/new/choose) and engage in [discussions](https://github.com/unoplatform/uno/discussions) to help improve the platform.
+
+[!include[getting-help](includes/getting-help.md)]