feat: WASM Font Preloading Support

doc/articles/features/custom-fonts.md

@@ -41,49 +41,114 @@ The format is the same as Windows, as follows:
 ```xml
 <Setter Property="FontFamily" Value="/Assets/Fonts/yourfont.ttf#Your Font Name" />
 ```
-    or
+or
 
 ```xml
 <Setter Property="FontFamily" Value="ms-appx:///Assets/Fonts/yourfont.ttf#Your Font Name" />
 ```
 
 ## Custom fonts on WebAssembly
 
-Adding a custom font is done through the use of WebFonts, using a data-URI:
+There is 3 ways to use fonts on WebAssembly platform:
+
+1. Referencing a **font defined in CSS**: Use a font defined using a `@font-face` CSS clause.
+
+   > [!NOTE]
+   > This was the only available way to define and use a custom font before Uno.UI v4.4. This is useful if the application is using externally referenced CSS as those commonly available on a CDN.
+
+2. Referencing a **font file in application assets**: Use a font file (any web comptatible file format, such as `.ttf`, `.woff`, etc...). This can also be used to reference a font hosted elsewhere using http address.
+
+### Adding a custom font defined in CSS
+
+First, the font needs to be defined in CSS.
 
 ```css
+/* First way: defined locally using data uri */
 @font-face {
-  font-family: "Symbols";
-  /* winjs-symbols.woff2: https://github.com/Microsoft/fonts/tree/master/Symbols */
+  font-family: "RobotoAsBase64"; /* XAML: <FontFamily>RobotoAsBase64</FontFamily> */
   src: url(data:application/x-font-woff;charset=utf-8;base64,d09GMgABAAA...) format('woff');
 }
+
+/* Second way: defined locally using external uri targetting the font file */
+@font-face {
+  font-family: "Roboto"; /* XAML: <FontFamily>CssRoboto</FontFamily> */
+  src: url(/Roboto.woff) format('woff');
+}
+
+/* Third way: Use an external font definition, optionally hosted on a CDN. */
+@import url('http://fonts.cdnfonts.com/css/antikythera'); /* XAML: <FontFamily>Antikythera</FontFamily> + others available */
+```
+
+Second, you can use it in XAML in this way:
+
+``` xml
+<!-- XAML usage of CSS defined font -->
+
+<TextBlock FontFamily="MyCustomFontAsBase64">This text should be rendered using the font defined as base64 in CSS.</TextBlock>
+
+<TextBlock FontFamily="CssRoboto">This text should be rendered using the roboto.woff font referenced in CSS.</TextBlock>
+
+<TextBlock FontFamily="Antikythera">This text should be rendered using the Antikythera font hosted on a CDN.</TextBlock>
 ```
 
-This type of declaration is required to avoid measuring errors if the font requested by a `TextBlock` or a `FontIcon` needs to be downloaded first. Specifying it using a data-URI ensures the font is readily available.
+> [!NOTE]
+> This approach is nice and pretty flexible, but not friendly for multi-targetting. Until Uno.UI v4.4, it was the only way to defined custom fonts on this platform.
+
+### Added a custom font from a file defined as application assets
 
-The font names are referenced based on the `#` name, so:
+When the application is multi-targetted, this approach is simpler because no CSS manipulation is required.
 
+1. Add font file as `Content` build action in the application's head project.
+
+2. Reference it using the format is the same as Windows:
+
+   ```xml
+   <Setter Property="FontFamily" Value="/Assets/Fonts/yourfont01.ttf#Roboto" />
+   ```
 ```xml
 <Setter Property="FontFamily"
         Value="ms-appx:///Assets/Fonts/yourfont.ttf#Your Font Name" />
 ```
 
-Will match the following `@font-face`:
+   or
 
-```css
-@font-face {
-  font-family: "Roboto";
-  ...
-}
-```
+   ```xml
+   <Setter Property="FontFamily" Value="ms-appx:///Assets/Fonts/yourfont01.ttf#Roboto" />
+   ```
 
-In case your `FontFamily` value does not contain `#`, Uno falls back to the font file name. Hence for:
+   or
 
+   ```xml
+   <!-- This is exclusive to Wasm platform -->
+   <Setter Property="FontFamily" Value="https://fonts.cdnfonts.com/s/71084/antikythera.woff#Antikythera" />
+   ```
 ```xml
 <Setter Property="FontFamily"
         Value="ms-appx:///Assets/Fonts/yourfont.ttf" />
 ```
 
+
+> [!NOTE]
+> The `#` part is optional and is there for cross-platform compatibilty. It is completely ignored on Uno WASM and can be omitted.
+
+### Fonts preloading
+
+On Wasm platform, fonts files are loaded by the browser and can take time to load, resulting in a performance degradation and potential flicking when the font is actually available for rendering. In order to prevent this, it is possible to instruct the browser to preload the font before the rendering:
+
+``` csharp
+// Preloading of font families on Wasm. Add this before the Application.Start() in the Program.cs
+
+public static void main(string[] orgs)
+{
+    // Add this in your application to preload a font.
+    // You can add more than one, but preload too much fonts could hurt user experience.
+    // IMPORTANT: The string parameter should be exactly the same string (including casing)
+    //            used as FontFamily in the application.
+    Windows.UI.Xaml.Media.FontFamily.Preload("ms-appx:///Assets/Fonts/yourfont01.ttf#ApplicationFont01");
+    Windows.UI.Xaml.Media.FontFamily.Preload("https://fonts.cdnfonts.com/s/71084/antikythera.woff#Antikythera");
+    Windows.UI.Xaml.Media.FontFamily.Preload("Roboto");
+
+    Windows.UI.Xaml.Application.Start(_ => _app = new App());
 Will match:
 
 ```css
@@ -92,6 +157,10 @@ Will match:
   ...
 }
 ```
+
+> [!TIP]
+> Even if the font is defined in CSS, it could still be useful to preload it, since the browser won't parse the font file until is it actually used by the content. Preloading it will force the browser to do this sooner, resulting in a better user experience. This will also prevent the application from doing a new _measure_ phase once the font is loaded.
+
 ## Custom Fonts on macOS
 
 Fonts must be placed in the `Resources/Fonts` folder of the head project, be marked as

src/SamplesApp/UITests.Shared/UITests.Shared.projitems

@@ -4041,6 +4041,10 @@
       <SubType>Designer</SubType>
       <Generator>MSBuild:Compile</Generator>
     </Page>
+    <Page Include="$(MSBuildThisFileDirectory)Windows_UI_Xaml_Media\FontTests\DynamicFont.xaml">
+      <SubType>Designer</SubType>
+      <Generator>MSBuild:Compile</Generator>
+    </Page>
     <Page Include="$(MSBuildThisFileDirectory)Windows_UI_Xaml_Media\Geometry\ClosedFigurePage.xaml">
       <SubType>Designer</SubType>
       <Generator>MSBuild:Compile</Generator>
@@ -7242,6 +7246,9 @@
     <Compile Include="$(MSBuildThisFileDirectory)Windows_UI_Xaml_Media\BrushesTests\SolidColorBrush_Color_Changed.xaml.cs">
       <DependentUpon>SolidColorBrush_Color_Changed.xaml</DependentUpon>
     </Compile>
+    <Compile Include="$(MSBuildThisFileDirectory)Windows_UI_Xaml_Media\FontTests\DynamicFont.xaml.cs">
+      <DependentUpon>DynamicFont.xaml</DependentUpon>
+    </Compile>
     <Compile Include="$(MSBuildThisFileDirectory)Windows_UI_Xaml_Media\Geometry\ClosedFigurePage.xaml.cs">
       <DependentUpon>ClosedFigurePage.xaml</DependentUpon>
     </Compile>
@@ -8481,6 +8488,11 @@
     <Content Include="$(MSBuildThisFileDirectory)Assets\Diagnostics\movie_type_dbox.png" />
     <Content Include="$(MSBuildThisFileDirectory)Assets\DropdownButton.png" />
     <Content Include="$(MSBuildThisFileDirectory)Assets\FlipView.png" />
+    <Content Include="$(MSBuildThisFileDirectory)Assets\Fonts\Even Badder Mofo.ttf" />
+    <Content Include="$(MSBuildThisFileDirectory)Assets\Fonts\FamilyGuy-4grW.ttf" />
+    <Content Include="$(MSBuildThisFileDirectory)Assets\Fonts\Nillambari-K7y1W.ttf" />
+    <Content Include="$(MSBuildThisFileDirectory)Assets\Fonts\Renaiss-Italic.ttf" />
+    <Content Include="$(MSBuildThisFileDirectory)Assets\Fonts\RoteFlora.ttf" />
     <Content Include="$(MSBuildThisFileDirectory)Assets\Fonts\uno-fluentui-assets.ttf" />
     <Content Include="$(MSBuildThisFileDirectory)Assets\Formats\animated.gif" />
     <Content Include="$(MSBuildThisFileDirectory)Assets\Formats\uno-overalls.bmp" />

src/SamplesApp/UITests.Shared/Windows_UI_Xaml_Media/FontTests/DynamicFont.xaml

@@ -0,0 +1,35 @@
+<Page
+    x:Class="UITests.Windows_UI_Xaml_Media.FontTests.DynamicFont"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:local="using:UITests.Windows_UI_Xaml_Media.FontTests"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d"
+    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
+
+    <StackPanel Spacing="20">
+		<Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="msappx:///Assets/Fonts/Even Badder Mofo.ttf#EvenBadderMofo">(ms-appx) This is a test</TextBlock>
+		</Border>
+		<Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="msappx:///Assets/Fonts/FamilyGuy-4grW.ttf">(ms-appx) This is a test</TextBlock>
+	    </Border>
+		<Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="msappx:///Assets/Fonts/Nillambari-K7y1W.ttf">(ms-appx) This is a test</TextBlock>
+	    </Border>
+		<Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="https://fonts.cdnfonts.com/s/71084/antikythera.woff">(https) This is a test rendering a string using external uri. [WASM ONLY]</TextBlock>
+	    </Border>
+		<Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="https://fonts.cdnfonts.com/s/71084/antikytheraoutlineital.woff">(https) This is a test rendering a string using external uri. [WASM ONLY]</TextBlock>
+	    </Border>
+		<Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="https://fonts.cdnfonts.com/s/71084/antikytheraoutline.woff">(https) This is a test rendering a string using external uri. [WASM ONLY]</TextBlock>
+	    </Border>
+	    <Border BorderBrush="Blue" BorderThickness="3" HorizontalAlignment="Left">
+			<TextBlock FontSize="20" FontFamily="https://fonts.cdnfonts.com/s/73485/GALACTIC%20VANGUARDIAN%20NCV.woff">(https) This is a test rendering a string using external uri. [WASM ONLY]</TextBlock>
+	    </Border>
+
+    </StackPanel>
+</Page>

src/SamplesApp/UITests.Shared/Windows_UI_Xaml_Media/FontTests/DynamicFont.xaml.cs

@@ -0,0 +1,14 @@
+using Windows.UI.Xaml.Controls;
+using Uno.UI.Samples.Controls;
+
+namespace UITests.Windows_UI_Xaml_Media.FontTests
+{
+	[Sample]
+	public partial class DynamicFont : Page
+	{
+		public DynamicFont()
+		{
+			this.InitializeComponent();
+		}
+	}
+}

src/Uno.UI.RuntimeTests/Tests/Windows_UI_Xaml_Media/Given_FontFamily.cs

@@ -12,7 +12,7 @@ public void With_Pure_Name()
 		{
 			var fontName = "My happy font";
 			var fontFamily = new FontFamily(fontName);
-			Assert.AreEqual(fontName, fontFamily.ParsedSource);
+			Assert.AreEqual(fontName, fontFamily.CssFontName);
 		}
 
 		[TestMethod]
@@ -21,7 +21,7 @@ public void With_Path_And_Hash()
 			var fontName = "My font name";
 			var fontFamilyPath = $"/Assets/Data/Fonts/MyFont.ttf#{fontName}";
 			var fontFamily = new FontFamily(fontFamilyPath);
-			Assert.AreEqual(fontName, fontFamily.ParsedSource);
+			Assert.AreEqual(fontName, fontFamily.CssFontName);
 		}
 
 		[TestMethod]
@@ -30,7 +30,7 @@ public void With_Path_Without_Hash()
 			var fontName = "FontName";
 			var fontFamilyPath = $"/Assets/Data/Fonts/{fontName}.ttf";			
 			var fontFamily = new FontFamily(fontFamilyPath);
-			Assert.AreEqual(fontName, fontFamily.ParsedSource);
+			Assert.AreEqual(fontName, fontFamily.CssFontName);
 		}
 
 		[TestMethod]
@@ -39,7 +39,7 @@ public void With_Msappx()
 			var fontName = "Msappx font name";
 			var fontFamilyPath = $"ms-appx:///Assets/Data/Fonts/MyFont.ttf#{fontName}";
 			var fontFamily = new FontFamily(fontFamilyPath);
-			Assert.AreEqual(fontName, fontFamily.ParsedSource);
+			Assert.AreEqual(fontName, fontFamily.CssFontName);
 		}
 
 		[TestMethod]
@@ -48,7 +48,7 @@ public void Without_Path_With_Hash()
 			var fontName = "Font name";
 			var fontFamilyPath = $"SomeFont.woff2#{fontName}";
 			var fontFamily = new FontFamily(fontFamilyPath);
-			Assert.AreEqual(fontName, fontFamily.ParsedSource);
+			Assert.AreEqual(fontName, fontFamily.CssFontName);
 		}
 	}
 }