Update workflows to build when md files change

Update docs

.github/workflows/cicd_publish.yml

@@ -4,23 +4,20 @@ on:
     branches: 
       - main
     paths-ignore:
-      - '**/*.md'
       - '**/*.gitignore'
       - '**/*.gitattributes'
 
   pull_request:
     types: [opened, synchronize, reopened, closed]
     branches: [ main ]
     paths-ignore:
-      - '**/*.md'
       - '**/*.gitignore'
       - '**/*.gitattributes'
 
   workflow_dispatch:
     branches:
       - main
     paths-ignore:
-      - '**/*.md'
       - '**/*.gitignore'
       - '**/*.gitattributes'
 

.github/workflows/deploy_preview.yml

@@ -6,7 +6,6 @@ on:
       - dev
       - archives/v2
     paths-ignore:
-      - '**/*.md'
       - '**/*.gitignore'
       - '**/*.gitattributes'
 
@@ -16,7 +15,6 @@ on:
       - dev
       - archives/v2
     paths-ignore:
-      - '**/*.md'
       - '**/*.gitignore'
       - '**/*.gitattributes'
 
@@ -25,7 +23,6 @@ on:
       - dev
       - archives/v2
     paths-ignore:
-      - '**/*.md'
       - '**/*.gitignore'
       - '**/*.gitattributes'
 

examples/Demo/Shared/Pages/Icon/IconPage.razor

@@ -13,6 +13,21 @@
     contains all these icons, which you can access directly in your projects.
     To use them, simply reference this package in your project.
 </p>
+<p>
+    During the DotNet Publication process, the unused icons are automatically removed from the final library.
+    You can configure this behavior by setting the <code>PublishTrimmed</code> property in your project file.
+    More details on <a href="https://learn.microsoft.com/aspnet/core/blazor/host-and-deploy/configure-trimmer" target="_blank">this page</a>.
+</p>
+<p>
+    You can create your own icons by adding a class like this one:
+
+    <CodeSnippet Language="language-csharp">
+        public static class MyIcons
+        {
+        public class SettingsEmail : Icon { public SettingsEmail() : base("SettingsEmail", IconVariant.Regular, IconSize.Size20, "&lt;svg width=\"20\" height=\"19\" viewBox=\"0 0 20 19\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">&lt;path d=\"M15.6251 2.5H4.37508L4.2214 2.50428C2.79712 2.58396 1.66675 3.76414 1.66675 5.20833V13.125L1.67103 13.2787C1.75071 14.7029 2.93089 15.8333 4.37508 15.8333H9.76425C9.91725 15.4818 10.1354 15.1606 10.4087 14.8873L10.7126 14.5833H4.37508L4.25547 14.5785C3.50601 14.5177 2.91675 13.8902 2.91675 13.125V6.97833L9.709 10.5531L9.78908 10.5883C9.95267 10.647 10.135 10.6353 10.2912 10.5531L17.0834 6.9775V9.17258C17.5072 9.14483 17.9362 9.21517 18.3334 9.38358V5.20833L18.3292 5.05465C18.2494 3.63038 17.0693 2.5 15.6251 2.5ZM4.37508 3.75H15.6251L15.7447 3.75483C16.4942 3.81568 17.0834 4.44319 17.0834 5.20833V5.565L10.0001 9.29375L2.91675 5.56583V5.20833L2.92158 5.08873C2.98242 4.33926 3.60994 3.75 4.37508 3.75ZM15.9167 10.5579L10.9979 15.4766C10.7112 15.7633 10.5077 16.1227 10.4093 16.5162L10.0279 18.0418C9.86208 18.7052 10.4631 19.3062 11.1265 19.1403L12.6521 18.7588C13.0455 18.6605 13.4048 18.4571 13.6917 18.1703L18.6103 13.2516C19.3542 12.5078 19.3542 11.3018 18.6103 10.5579C17.8665 9.814 16.6605 9.814 15.9167 10.5579Z\" fill=\"#212121\" />&lt;/svg>") { } }
+        }
+    </CodeSnippet>
+</p>
 <p>
     You can use any of these icons by levaraging the <code>&lt;FluentIcon&gt;</code>&nbsp;component. See below for the parameters and examples. 
     There is also a search capability available on this page wich allows you to browse to all the different icons.

examples/Demo/Shared/Pages/IconsAndEmoji.razor

@@ -0,0 +1,18 @@
+@page "/IconsAndEmoji"
+
+<PageTitle>Icons and Emoji</PageTitle>
+
+<h1>Using Icons and Emoji</h1>
+
+<MarkdownSection FromAsset="./_content/FluentUI.Demo.Shared/docs/IconsAndEmoji.md" OnContentConverted="RefreshTableOfContents" />
+
+@code {
+
+    [CascadingParameter]
+    public EventCallback OnRefreshTableOfContents { get; set; }
+
+    private async Task RefreshTableOfContents()
+    {
+        await OnRefreshTableOfContents.InvokeAsync();
+    }
+}

examples/Demo/Shared/Shared/DemoNavMenuTree.razor

@@ -12,9 +12,10 @@
             <FluentNavMenuLink Href="/CodeSetup" Icon="@(new Icons.Regular.Size20.DocumentOnePageSparkle())" Text="Code setup" />
             <FluentNavMenuLink Href="/DesignTokens" Icon="@(new Icons.Regular.Size20.DesignIdeas())" Text="Design tokens" />
             <FluentNavMenuLink Href="/Reboot" Icon="@(new Icons.Regular.Size20.ArrowReset())" Text="Reboot" />
-            <FluentNavMenuLink Href="/Templates" Icon="@(new Icons.Regular.Size20.Classification())" Text="Project templates" />
+            <FluentNavMenuLink Href="/IconsAndEmoji" Icon="@(new Icons.Regular.Size20.Symbols())" Text="Icons and Emoji" />
             <FluentNavMenuLink Href="/DialogService" Icon="@(new Icons.Regular.Size20.AppGeneric())" Text="DialogService" />
             <FluentNavMenuLink Href="/ToastService" Icon="@(new Icons.Regular.Size20.FoodToast())" Text="ToastService" />
+            <FluentNavMenuLink Href="/Templates" Icon="@(new Icons.Regular.Size20.Classification())" Text="Project templates" />
             <FluentNavMenuLink Href="/basicform-fluentui-components" Icon="@(new Icons.Regular.Size20.Form())" Text="Fluent UI Form" />
             <FluentNavMenuLink Href="/basicform-blazor-components" Icon="@(new Icons.Regular.Size20.Form())" Text="Blazor Form" />
         </FluentNavMenuGroup>

examples/Demo/Shared/wwwroot/docs/IconsAndEmoji.md

@@ -0,0 +1,72 @@
+Starting with v3, the assets for the icons and emoji are removed from the library package and are provided through additional (separate) packages for 
+both the icon and emoji resources. The components, and icons that are used by the library itself, are still part of the package. 
+Adding the [Microsoft.Fast.Components.FluentUI.Icons package](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI.Icons) and/or [Microsoft.Fast.Components.FluentUI.Emojis package](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI.Emojis) 
+is enough to make the resources available to your code.
+
+We use the [.NET trimming capabilities](https://learn.microsoft.com/aspnet/core/blazor/host-and-deploy/configure-trimmer) to publish only those assests that are actually being used in your program. Usually this results in some very small DLL's that only contain the resources that are actually being used in your application.
+
+We still have support for both the **complete** [Fluent UI System Icons](https://github.com/microsoft/fluentui-system-icons) and the [Fluent Emoji](https://github.com/microsoft/fluentui-emoji) libraries.
+
+## Getting Started
+
+To use the **Fluent UI System Icons** in your application, you will need to install the [Microsoft.Fast.Components.FluentUI.Icons](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI.Icons/) NuGet package in the project are using the main library. 
+
+
+To use the **Fluent UI Emoji** in your application, you need to install the [Microsoft.Fast.Components.FluentUI.Emojis](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI.Emojis/) NuGet package in the project are using the main library.
+
+#### `FluentIcon` component
+
+To use the icons, you add a `FluentIcon` component in your code like this:
+
+```razor
+<FluentIcon Icon="Icons.Regular.Size24.Save" />
+```
+
+> **Note:** Icon names are structured like this: `Icons.[IconVariant].[IconSize].[IconName]`
+
+Following this structure in combination with Visual Studio's IntelliSense makes it easier to find the icon you need.
+
+There are several other ways of using the `FluentIcon` component with the `Icon` class:
+
+- Using an icon instance.
+
+    ```razor
+    <FluentIcon Value="@(new Icons.Regular.Size24.Save())" />
+    ```
+- Using the `Icon.FromImageUrl` method to use your ow images as icons.
+
+    ```razor
+    <FluentIcon Value="@(Icon.FromImageUrl("/Blazor.png"))" />
+    ```
+- Using the `ToMarkup` method. This generates the SVG code without using the `FluentIcon` features.
+
+#### Custom Icons
+You can even use your own set of custom SVG files as icons. Start by creating a class with you Icons like this:
+
+```csharp
+public static class MyIcons
+{
+    public class SettingsEmail : Icon { public SettingsEmail() : base("SettingsEmail", IconVariant.Regular, IconSize.Size20, "<svg width=\"20\" height=\"19\" viewBox=\"0 0 20 19\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M15.6251 2.5H4.37508L4.2214 2.50428C2.79712 2.58396 1.66675 3.76414 1.66675 5.20833V13.125L1.67103 13.2787C1.75071 14.7029 2.93089 15.8333 4.37508 15.8333H9.76425C9.91725 15.4818 10.1354 15.1606 10.4087 14.8873L10.7126 14.5833H4.37508L4.25547 14.5785C3.50601 14.5177 2.91675 13.8902 2.91675 13.125V6.97833L9.709 10.5531L9.78908 10.5883C9.95267 10.647 10.135 10.6353 10.2912 10.5531L17.0834 6.9775V9.17258C17.5072 9.14483 17.9362 9.21517 18.3334 9.38358V5.20833L18.3292 5.05465C18.2494 3.63038 17.0693 2.5 15.6251 2.5ZM4.37508 3.75H15.6251L15.7447 3.75483C16.4942 3.81568 17.0834 4.44319 17.0834 5.20833V5.565L10.0001 9.29375L2.91675 5.56583V5.20833L2.92158 5.08873C2.98242 4.33926 3.60994 3.75 4.37508 3.75ZM15.9167 10.5579L10.9979 15.4766C10.7112 15.7633 10.5077 16.1227 10.4093 16.5162L10.0279 18.0418C9.86208 18.7052 10.4631 19.3062 11.1265 19.1403L12.6521 18.7588C13.0455 18.6605 13.4048 18.4571 13.6917 18.1703L18.6103 13.2516C19.3542 12.5078 19.3542 11.3018 18.6103 10.5579C17.8665 9.814 16.6605 9.814 15.9167 10.5579Z\" fill=\"#212121\"/></svg>") { } }
+}
+```
+
+The `Icon` class and enumerations are in the Fluent UI library itself (so, you can be independant of the Fluent UI Icons library)
+
+After adding the class, you can start using this custom icon like a "normal" Fluent UI Icon:
+
+```razor
+<FluentIcon Icon="MyIcons.SettingsEmail" />
+```
+
+#### `FluentEmoji` component
+
+To use the emoji, you add a `FleuntEmoji` component in your code like this:
+
+```razor
+<FluentSystemEmoji Emoji="Emojis.PeopleBody.Color.Default.Artist" />
+```
+
+> **Note:** Names are structured like this: `Emojis.[EmojiGroup].[EmojiStyle].[EmojiSkintone].[EmojiName]`
+
+
+

examples/Demo/Shared/wwwroot/docs/UpgradeGuide.md

@@ -1,4 +1,4 @@
-## `FluentDataGrid` Breaking changes
+## Breaking changes
  The `FluentDataGrid` component is, as you may know, a `QuickGrid` in disguise. We 
  aligned the underlying code even more to the productized version that will ship with 
  .NET 8. Where we previously aligned parameter names to the `fluent-datagrid` Web 
@@ -10,17 +10,35 @@
 * RowsDataSize -> ItemSize 
 * RowsDataKey -> ItemKey	
 
-## `FluentComponentBase` changes
+Another breaking change is found in the `Align` enumeration. Where we previously used the values `Left` and `Right`, these have now been changed to `Start` and `End`. This to make working with those easier/more consistent in an RTL-based application.
+
+`FluentBadge` now uses a `Color` \ `BackgroundColor` combination to determine the fill values.
+
+`FluentCalendar` no longer wraps the `fluent-calendar` web component. It's functionality was too limited. Not all parameters are supported in the updated version.
+
+`StackHorizontalAlignment`/`StackVerticalAlignment` have been renamed to just `HorizontalAlignment`/`VerticalAlignment` as there are now more components using these enumarations.
+
+## FluentComponentBase changes
 The `FluentComponentBase` class now has an `Id` parameter. This has been lifted from the `FluentInputBase` class. 
 The `Id` parameter is used to set the `id` attribute on the root element of the component. 
 Previously, in the `FluentInputBase` class, a value was always created for the `Id`. This is no longer the case and 
 a value is now only created for components that need to have an id. If needed, you can assign an value to the `Id` 
 parameter yourself which will then be used as the 'id' on the root element.
 
 ## When using icons or emoji in version 2
+We have changed the way icons and emoji are used in version 3. We published a [Icons](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI.Icons) NuGet package
+and a [Emoji](https://www.nuget.org/packages/Microsoft.Fast.Components.FluentUI.Emojis) NuGet package.   
+The Fluent UI System Icons are a (still growing) collection of familiar, friendly and modern icons from Microsoft.
+At the moment there are more than 2200 distinct icons available in both filled and outlined versions and in various sizes. In total the collections consists of well over 11k icons in SVG format.
+
+After the following changes, usage is very simple:
+```xml
+<FluentIcon Icon="Icons.Regular.Size24.Save" />
+```
+
 There are a couple of changes that need to be done to upgrade from v2 to v3 when using icons/emoji:
 
-### Changes in `.csproj` file
+### 1. Changes in `.csproj` file
 For version 2 you needed to add a `<ProjectGroup>` similar to below to your project file:
 ```xml
 <PropertyGroup>
@@ -35,7 +53,7 @@ For version 2 you needed to add a `<ProjectGroup>` similar to below to your proj
 This whole group should be **removed** from your project file. See the [Project setup](https://www.fluentui-blazor.net/ProjectSetup)
 for instructions on how to work with icons and emoji in version 3.
 
-### Changes in `Program.cs`
+### 2. Changes in `Program.cs`
 The `AddFluentUIComponents()` service collection extension needs to be changed. 
 The `options.IconConfiguration` and `options.EmojiConfiguration` lines are no longer necessary and should be removed.
 
@@ -48,8 +66,8 @@ builder.Services.AddFluentUIComponents(options =>
 
 The `options.HostingModel` setting is used to determine the type of project you are building. Choose a value from the `BlazorHostingModel` enumeration which reflects your type of project.
 
-### Changes in code
-**ALL** occurences of <`<FluentIcon>` and `<FluentEmoji>` should be checked and changed to work with the new format.
+### 3. Changes in code
+**ALL** occurences of `<FluentIcon>` and `<FluentEmoji>` should be checked and changed to work with the new format.
 
 For icons the new format is like:
 
@@ -67,6 +85,19 @@ For emoji the new format is:
 
 > Names are structured as follows: `Emojis.[EmojiGroup].[EmojiStyle].[EmojiSkintone].[EmojiName]`.
 
+📢 You can automate the changes by using the [Visual Studio Find and Replace functionality](https://learn.microsoft.com/en-us/visualstudio/ide/using-regular-expressions-in-visual-studio).
+
+> Before to use **Find and Replace in Files**, you have to backup your project.
+> The following steps are provided as an example and may not work in your case.
+> You have to adapt them to your project.
+
+- To search: `<FluentIcon Name="?@?FluentIcons\.(?<name>[^"]+)"? Size="?@?IconSize\.(?<size>[^"]+)"? Variant="?@?IconVariant\.(?<variant>[^"]+)"? Color="?@?Color\.(?<color>[^"]+)"? Slot="?(?<slot>[^"]+)"? />`
+- To replace by: `<FluentIcon Icon="Icons.${variant}.${size}.${name}" Color="@Color.${color}" Slot="${slot}" />`
+
+![Find and Replace](./_content/FluentUI.Demo.Shared/images/Icons-FindReplace-RegEx.png)
+
+The preceding expressions are defined to search for attributes in this order: Name, Size, Variant, Color, Slot.
+You may need to change or delete some attributes, depending on how you've coded them (and relaunch the process).
 
 ## Using the library from a RCL
 For version 2 you had to add the following to your project file:
@@ -77,5 +108,4 @@ For version 2 you had to add the following to your project file:
 	</ItemGroup>
 </Target>
 ```
-This is no longer necessary. The code should be **removed** from your project file
-```xml
+This is no longer necessary. The code should be **removed** from your project file