Take control over what Icons and Emojis are available and get deployed on publishing!

[vnbaaij]

Introduction

For version 2.1 I'm adding a new <FluentEmoji> component to the family (see https://brave-cliff-0c0c93310-259.centralus.azurestaticapps.net/Emoji for examples)! Good news I think, but...it also introduces a new challenge.

The Fluent Emoji are a (still growing) collection of familiar, friendly, and modern emoji from Microsoft. At the moment there are over 1500 distinct emoji available in color, flat and high contrast styles and 6 different skin tones (where applicable) divided in 9 groups. At the moment, the collections consist of just over 7.5k emoji in SVG format in total.
Combined with the ~13k Fluent System Icons that are already available through the <FluentIcon> component, this means a significant number of static assets get pushed to a server when publishing an application that uses the library. In fact, with Azure Static Web Apps (which we are using for hosting the demo site) I'm not able to publish everything as there currently exists a maximum of 15000 files per application.

I therefore needed a way to limit the number of static assets that gets included in a publish action and I'm happy to report I've found a way to do that! As an added bonus you, as the developer using the library in an application, can now control what icons and emojis (yes, emojis is valid for indicating plural) will be available to the application. I'll do a blog pot on how I made it work on the project and package side later. For now, I want to focus on how you can configure things.

Options to filter Icons and Emojis

The icon collection is set up such a way that an icon is made available in different sizes and then for each size there are usually 2 variants ('Filled', 'Regular'). The sizes available are '10', '12', '16', '20', '24', '28', '32', and '48'. Not every icon is available in all sizes and/or all variants.

The emoji collection is, like mentioned above, divided into 9 groups where each emoji is made available in 3 styles ('Color', 'Flat', 'High Contrast'). The groups available are 'Activities', 'Animals & Nature', 'Flags', "Food & Drink', 'Objects', 'People & Body', 'Smileys & Emotion', 'Symbols' and 'Travel & Places'. I think every emoji is available in every style but not 100% sure. For a lot of emoji in the 'People & Body' category there are also 6 different skin tone variants available per style

Due to the way the project file needs to be altered to make this mechanism work, the number of filters you can use is limited. For icons this means you can specify a combination of sizes and variants. For emoji you can specify a combination of groups and styles.

Configuring the application project

You can specify which combination to use by defining <PropertyGroup> elements in the .csproj file for the application you are using the library in. The elements you can use for icons are:

• <FluentIconSizes>
• <FluentIconVariants>

For emoji you can use:

• <FluentEmojiGroups>
• <FluentEmojiStyles>

In each element you specify one or more values (no spaces, separated by semicolon (;)). The combination of the <FluentIcon...> elements determines the icon assets published, the <FluentEmoji...> elements combination determines the emoji assets published.

The possible values per element are:

• <FluentIconSizes>: 10;12;16;20;24;28;32;48
• <FluentIconVariants>: filled;regular
• <FluentEmojiGroups>: activities;animals_nature;flags;food_drink;objects;people_body;smileys_emotion;symbols;travel_places
• <FluentEmojiStyles>: color;flat;high-contrast

For the current demo site the elements look like this:

<PropertyGroup>
	<!-- Choose one or more from the options below (no spaces, separate with ;) -->
	<!--activities;animals_nature;flags;food_drink;objects;people_body;smileys_emotion;symbols;travel_places-->
	<FluentEmojiGroups>activities;animals_nature;flags;food_drink;objects;smileys_emotion;symbols;travel_places</FluentEmojiGroups>

	<!-- Choose one or more from the options below (no spaces, separate with ;) -->
	<!-- color;flat;high-contrast -->
	<FluentEmojiStyles>color;</FluentEmojiStyles>

	<!-- Choose one or more from the options below (no spaces, separate with ;) -->
	<!-- 10;12;16;20;24;28;32;48 -->
	<FluentIconSizes>10;12;16;20;24;48</FluentIconSizes>

	<!-- Choose one or more from the options below (no spaces, separate with ;) -->
	<!-- filled;regular -->
	<FluentIconVariants>filled;regular</FluentIconVariants>
</PropertyGroup>

This translates to 'all color emoji EXCEPT People & Body group' and 'all icons EXCEPT size 32' will be published as static assets.

If you don't specify an element in the project file, by default all possible options for that element will be included in the publish action

Configuring the AddFluentUIComponents service collection extension

To get runtime checks on <FluentIcon> and <FluentEmoji> using actual available assets, you need to configure the AddFluentUIComponents service collection extension. To enable this a couple of service and configuration classed have been added to the library. In anormal situation, you'd make sure the settings for the configuration here mimic the settings made in the project file.

The classes added for configuration are: IconConfiguration with properties Sizes and Variants and EmojiConfiguration with properties Groups and Styles. All properties are arrays of enumerations which contain all possible options for that specific element.

The services added are IconService and EmojiService both classes only contain a (get-only) Configuration property of their respective configuration type. The services are added in the AddFluentUIComponents code.

You can manipulate the configuration by adding code to the AddFluentUIComponents call you make when configuring the SeviceCollection. Usually this is done in Program.cs. When using top-level statements, you should see multiple builder.Services...
lines in that file. In general such a manipulation looks like this:

builder.Services.AddFluentUIComponents(configuration =>
{
    configuration!.{Icon or Emoji}Configuration.{Property} = new[]
    {
        :
        {property specific enum values}
        :
    }
}

For the demo site it looks like this:

builder.Services.AddFluentUIComponents(configuration =>
{
    configuration!.EmojiConfiguration.Groups = new[]
    {
        EmojiGroup.Activities,
        EmojiGroup.Animals_Nature,
        EmojiGroup.Flags,
        EmojiGroup.Food_Drink,
        EmojiGroup.Objects,
        EmojiGroup.Smileys_Emotion,
        EmojiGroup.Symbols,
        EmojiGroup.Travel_Places,
    };
    configuration!.EmojiConfiguration.Styles = new[]
    {
        EmojiStyle.Color
    };
    configuration!.IconConfiguration.Sizes = new[]
    {
        IconSize.Size10,
        IconSize.Size12,
        IconSize.Size16,
        IconSize.Size20,
        IconSize.Size24,
        IconSize.Size48
    };
    configuration!.IconConfiguration.Variants = new[]
    {
        IconVariant.Regular,
        IconVariant.Filled
    };
});

Using this configuration, I can for example change the Search functionality in the EmojiPage to only show the groups (no 'People & Body') and style (just 'Color') for which the assets are actually published:

See https://github.com/microsoft/fast-blazor/blob/emojis/examples/FluentUI.Demo.Shared/Pages/Emoji/EmojiPage.razor#L48-L56 (and line 72-79) in the demo site for how this is done.

When not specifying any configuration options, that same goes as with the project settings. Everything will be available.

Try it out!

To test this functionality, you need version 2.1.0-beta-1 of the package which is available on GitHub now. If you do try this out, please let us know if it works as expected (or not).

[baywet]

An aspect of the configuration that could be improved would be to easily identify duplicate entries. Hashsets or flaggable enums could be used instead of arrays, it'd probably make the comparison at publish time faster as well.

builder.Services.AddFluentUIComponents(configuration =>
{
    configuration!.IconConfiguration.Variants = 
        IconVariant.Regular |
        IconVariant.Filled;
});

Also as far as I understand this are projection rules, meaning that if I specify IconConfiguration Regular & Filled as well as Sie 12 & 14 I'll get 4 variants at least of each icon group that gets imported. Having a matching rule engine instead with lambdas would help trim it down further.

builder.Services.AddFluentUIComponents(configuration =>
{
    configuration!.IconsMatchingRules.Add((size, group, variant, style) => size == IconSize.Size10 && style == EmojiStyle.Color  && variant == IconVariant.Regular && group == EmojiGroup.Activities):
});

Although I'm not sure how that would translate in csproj, maybe it's a capability that can only be used in CSharp?

[baywet]

Thanks for the quick reply. I was under the impression that configuration was either needed in the services or in the csproj, but not both. Did I misunderstand that aspect?

[vnbaaij]

Yes, you did... sorry🤷‍♀️
The .csproj part orchestrates the handling of the right .target files from the NuGet packagage. i.e. what gets pulishedin the end. The services configuration enables runtime checks,

[baywet]

Thanks, after adding things to the csproj, I can confirm that the result of a release publication is reduced by ~75% (19k files to 5k). In my case we could probably drive that reduction further if there was an additional option to specify the icons names in use (I probably only need 10 of them).
The assets worker is also positively impacted by that change.

[vnbaaij]

So as far as you are concerned this could be released (with a bunch of necessary readme additions)?

[baywet]

ideally I'd also be able to filter on icon groups (I don't think groups exist today) or icon names, and I'd be able to know which component is using which icons. But that's a set of improvements that can be done in a second phase.

[vnbaaij]

Update

I've made available a 2.1 RC1 package with some changes on how this works. In short, you still to need to add settings to the project file of the project you are using the library in, and you need to change the .AddFluentUIComponents() call in Program.cs a bit.

Longer explanation

Most important change: 2 new properties have been added:

• PublishFluentEmojiAssets
• PublishFLuentIconAssets

As you can probably guess from their names, these enable completely turning off or on publishing icons and/or emoji assets. The default value for BOTH properties is false. This means that if you do not add the property (with a value of 'true') in your project file, NO ICON/EMOJI ASSETS WILL GET PUBLISHED (except for the icons the library is using itself)

The other properties are still there but the values for the options have changed a bit. The mechanism of specifying sizes/variant and groups/styles has not changed. Only thing is the values now need to be separated by commas (','). Any additional leading/trailing spaces will be trimmed when processing the values.

The possible (updated) values per element are:

• <FluentIconSizes>: 10,12,16,20,24,28,32,48
• <FluentIconVariants>: Filled, Regular
• <FluentEmojiGroups>: Activities, Animals_Nature, Flags, Food_Drink, Objects, People_Body, Smileys_Emotion, Symbols, Travel_Places
• <FluentEmojiStyles>: Color, Flat, HighContrast

If publishing icons/emoji is enabled and a property is not given a value/left out of the project file, ALL possible options for that value will be used.

For the current demo site the elements look like this:

<PropertyGroup>
	<!-- 
		The icon component is part of the library. By default, NO icons (static assets) will be included when publishing the project. 
			 
		Setting the property 'PublishFluentIconAssets' to false (default), or leaving the property out completely, will disable publishing of the 
		icon static assets (with exception of the icons that are being used by the library itself). 
			
		Setting the property 'PublishFluentIconAssets' to 'true' will enable publishing of the icon static assets. You can limit what icon assets 
		get published by specifying icon sizes and variants in the 'FluentIconSizes' and 'FluentIconVariants' properties respectively.
			
		To determine what icons will be published, the specified options for sizes and variants are combined. Specifying sizes '10' and '16' and 
		variants 'Filled' and 'Regular' means all '10/Filled', all '10/Regular', all '16/Filled' and all '16/Regular' icons assets will be published. 
		It is not posible to specify multiple individual combinations like '10/Filled' and '16/Regular' in the same set. 
			
		When no icon sizes are specified in the 'FluentIconSizes' property, ALL sizes will be included(*)  
		When no icon variant are specified in the 'FluentIconVariants' property, ALL variants will be included(*)  
		(*)when publishing of icon assets is enabled 
	-->
	<PublishFluentIconAssets>true</PublishFluentIconAssets>

	<!-- 
		Specify at least one (or more) size(s) from the following options (separated by ','):
			10,12,16,20,24,28,32,48 
		Or leave out the property to have all sizes included.
	-->
	<FluentIconSizes>10,12,16,20,24,48</FluentIconSizes>

	<!-- 
		Specify at least one (or more) variant(s) from the following options (separated by ','):
			Filled,Regular 
		Or leave out the property to have all variants included.
	-->
	<FluentIconVariants>Filled,Regular</FluentIconVariants>

	<!-- 
		The emoji component is part of the library. By default, NO emojis (static assets) will be included when publishing the project. 
			 
		Setting the property 'PublishFluentEmoji' to false (default), or leaving the property out completely, will disable publishing of the 
		emoji static assets. 
			
		Setting the property 'PublishFluentEmojiAssets' to 'true' will enable publishing of the emoji static assets. You can limit what emoji assets 
		get published by specifying emoji groups and styles in the 'FluentEmojiGroups' and 'FluentEmojiStyles' properties respectively.
			
		To determine what emojis will be published, the specified options for sizes and variants are combined. Specifying emoji groups 'Activities' and 
		'Flags' and emoji styles 'Color' and 'Flat' means all 'Activities/Color', all 'Activities/Flat', all 'Flags/Color' and all 'Flags/Flat' emoji 
		assets will be published.
			
		It is not posible to specify multiple individual combinations like 'Activities/Color' and 'Flags/Flat' in the same published set
			
		When no emoji groups are specified in the 'FluentEmojiGroups' property, ALL groups will be included (*)  
		When no emoji variant are specified in the 'FluentEmojiStyles' property, ALL styles will be included (*)  
		(*) when publishing of emoji assets is enabled 
	-->
	<PublishFluentEmojiAssets>true</PublishFluentEmojiAssets>

	<!-- 
		Specify at least one (or more) group(s) from the following options (separated by ','):
			Activities,Animals_Nature,Flags,Food_Drink,Objects,People_Body,Smileys_Emotion,Symbols,Travel_Places 
		Or leave out the property to have all groups included.
	-->
	<FluentEmojiGroups>Activities,Animals_Nature,Flags,Food_Drink,Objects,Smileys_Emotion,Symbols,Travel_Places</FluentEmojiGroups>

	<!-- 
		Specify at least one (or more) style(s) from the following options: (separated by ',':) 
			Color,Flat,HighContrast
		Or leave out the property to have all styles included.
	-->
	<FluentEmojiStyles>Color,</FluentEmojiStyles>
</PropertyGroup>

This translates to 'all icons EXCEPT size 32' and 'all color emoji EXCEPT People & Body group' will be published as static assets (i.e. copied to the wwwroot folder) when publishing the application/site.

Configuring the AddFluentUIComponents() service collection extension

This has become a lot simpler with this update. The only two lines you need to add to your Program.cs from this version onwards are:

LibraryConfiguration config = new(ConfigurationGenerator.GetIconConfiguration(), ConfigurationGenerator.GetEmojiConfiguration());
builder.Services.AddFluentUIComponents(config);

The actual needed configuration information is now being delivered by a Source Generator I've written and which has been added to the library package. The source generator reads the settings described above from the .csproj file and does its thing when compiling your application.

The RC1 package is available on NuGet now

[vnbaaij]

This has been followed up by an RC2 release. There was a bug in the RC1 package and that one has been unlisted from NuGet