refactor(framework): ship @ui5/webcomponents-base/dist/FontFace.css

docs/2-advanced/14-fonts.md

@@ -1,31 +1,75 @@
-# Custom Fonts
+# Fonts
 
-During boot, the UI5 Web Components framework loads the necessary fonts to achieve the desired design of its components.
+This article explains how fonts are handled in UI5 Web Components and the options available for customization.
 
-**Important:** These fonts are fetched via network requests.
+## Default Font Loading
 
-## Customizing Fonts
+During boot, the UI5 Web Components framework automatically loads the necessary fonts to achieve the SAP Fiori design. The fonts are fetched from a CDN (`cdn.jsdelivr.net`) via network requests.
+
+This default behavior requires no configuration - fonts are loaded automatically when you use UI5 Web Components.
+
+
+## Custom (Manual) Font Loading
 
 There are several reasons why you might need to customize fonts:
-- To specify different paths for fonts (e.g., due to restrictions on public internet access).
-- To include additional declarations within `@font-face`.
-- To download additional fonts, such as `72-Light`.
-- To prevent the default fonts from being fetched.
+- To specify different paths for fonts (e.g., due to restrictions on public internet access)
+- To include additional declarations within `@font-face` (e.g., `font-display`)
+- To download additional fonts, such as `72-Light`
+- To prevent the default fonts from being fetched
+
+
+### 1. Disable Default Fonts
+
+You can disable the default fonts by either creating a `style` tag with `data-ui5-font-face` attribute, or via the `defaultFontLoading` configuration option.
+
+- via `<style data-ui5-font-face>`
+
+The framework checks for the presense of this element with this specific attribute and skips the font loading when present.
+
+```html
+<style type="text/css" data-ui5-font-face>
+    @font-face {
+        font-family: "72";
+        font-style: normal;
+        font-weight: 200;
+        font-display: swap;
+        src: local("72-Light"),
+        url({path_to_your_font});
+    }
+</style>
+```
+
+- via `defaultFontLoading` in your HTML
+
+
+```html
+<script data-ui5-config type="application/json">
+{
+	"defaultFontLoading": false
+}
+</script>
+```
+
+- via `setDefaultFontLoading` JS API
 
-To achieve this, you can prevent the fetching of default fonts by configuring `setDefaultFontLoading (@ui5/webcomponents-base/dist/config/Fonts.js)` to `false`:
 
 ```ts
-import { getDefaultFontLoading, setDefaultFontLoading } from "@ui5/webcomponents-base/dist/config/Fonts.js";
+import { setDefaultFontLoading } from "@ui5/webcomponents-base/dist/config/Fonts.js";
 
 setDefaultFontLoading(false);
 ```
 
-Then, specify the custom font you intend to use. When the UI5 Web Components framework initializes, it will refrain from fetching default fonts and instead use the ones you have provided.
+When the UI5 Web Components framework initializes, it will refrain from fetching default fonts and instead use the ones you have provided.
+
+
+### 2. Provide Custom Font Definitions
+
+After disabling the default fonts, specify the custom fonts you intend to use.
 
-To use the `72-Light` font in your application and specify the `font-display` setting, you should define the font in your application's styles. 
+For example, to use the `72-Light` font with a custom `font-display` setting:
 
 ```html
-<style type="text/css">
+<style type="text/css" data-ui5-font-face>
     @font-face {
         font-family: "72";
         font-style: normal;

packages/base/lib/css-processors/css-processor-font-face.mjs

@@ -1,16 +1,18 @@
 import * as esbuild from 'esbuild'
 import * as path from "path";
-import { readFile, writeFile } from "fs/promises";
+import { readFile, writeFile, mkdir } from "fs/promises";
 import { fileURLToPath, pathToFileURL } from "url";
 
 const generate = async () => {
     const themeBasePackage = JSON.parse(await readFile(fileURLToPath(import.meta.resolve("@sap-theming/theming-base-content/package.json", "utf-8"))));
+	const CDN_URL = `https://cdn.jsdelivr.net/npm/@sap-theming/theming-base-content@${themeBasePackage.version}/content/Base/baseLib/baseTheme/fonts`;
+	const NPM_URL = `@sap-theming/theming-base-content/content/Base/baseLib/baseTheme/fonts`;
 
     const processFontFace = (text) => {
         const declarationExpr = /@font-face\s*{[^}]*}/g;
 
         // change font-face src
-        text = text.replaceAll("../baseTheme/fonts", `https://cdn.jsdelivr.net/npm/@sap-theming/theming-base-content@${themeBasePackage.version}/content/Base/baseLib/baseTheme/fonts`);
+        text = text.replaceAll("../baseTheme/fonts", CDN_URL);
 
         // extract declarations for separate usage
         let fontFaceDeclarations = [...text.matchAll(declarationExpr)].map(x => x[0]);
@@ -35,10 +37,17 @@ const generate = async () => {
 
             build.onEnd(result => {
                 result.outputFiles.forEach(async f => {
-                    let newText = processFontFace(f.text);
                     const tsPath = path.join(process.cwd(), "src/generated/css/FontFace.css.ts");
-                    const tsContent = `export default \`${newText}\``;
+                    const tsText = processFontFace(f.text);
+                    const tsContent = `export default \`${tsText}\``;
+
+                    const distPath = path.join(process.cwd(), "dist");
+                    const cssPath = path.join(distPath, "FontFace.css");
+                    const cssContent = tsText.replaceAll(CDN_URL, NPM_URL);
+
+                    await mkdir(distPath, { recursive: true });
                     await writeFile(tsPath, tsContent);
+                    await writeFile(cssPath, cssContent);
                 });
             })
         },