From 98804e5d4ed290d6ed370b0affa0dea8375bbfe4 Mon Sep 17 00:00:00 2001
From: DerZade <DerZade@gmail.com>
Date: Tue, 9 Jul 2024 20:07:14 +0200
Subject: [PATCH] docs: :memo: add advanced configuration

---
 README.md      | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++
 build/index.js |  4 ++--
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f698481..3caf987 100644
--- a/README.md
+++ b/README.md
@@ -30,3 +30,67 @@ h6 {
   font-family: 'Raleway', 'Raleway Fallback', sans-serif; /* Make sure to include the fallback font to reduce layout shift */
 }
 ```
+
+### Advanced usage
+
+When you are using [SASS](https://sass-lang.com/) (or SCSS) you can also import the `index.scss`, which allows configuration which font families, Unicode ranges and styles should be included as well as from where the font files are loaded.
+
+<!-- prettier-ignore -->
+```scss
+// NOTE: omit the variable entirely to keep the default value
+
+@use '@arma-events/web-fonts/dist/index.scss' with (
+  // no trailing slash;
+  // would attempt to load '~my/font/files/Raleway/italic.latin.woff2'
+  //                        ^^^^^^^^^^^^^^ ^^^^^^^ ^^^^^^ ^^^^^
+  //                        Your Path      Family  Style  Range
+  $base-path: '~my/font/files',
+
+  // only include Source Sans 3 and Raleway in the italic-style
+  // and latin as well as latin-ext ranges
+  $families: ('Source Sans 3', 'Raleway'),
+  $styles: ('italic'),
+  $ranges: ('latin', 'latin-ext'),
+);
+```
+
+#### Variables
+
+> [!IMPORTANT]
+> All "Allowed Values" below might be outdated. Check the `dist/_build_info.scss` file in your package directory for the correct values.
+
+##### `$base-path`
+
+| Name           | Value                                                         |
+| :------------- | :------------------------------------------------------------ |
+| Description    | Base path of woff files to load (without a trailing slash)    |
+| Default Value  | `@arma-events/web-fonts/dist/woff2`                           |
+| Type           | [String](https://sass-lang.com/documentation/values/strings/) |
+| Allowed Values | -                                                             |
+
+##### `$families`
+
+| Name           | Value                                                            |
+| :------------- | :--------------------------------------------------------------- |
+| Description    | Font families to include                                         |
+| Default Value  | All families                                                     |
+| Type           | [List](https://sass-lang.com/documentation/values/lists/)        |
+| Allowed Values | one or multiple of `Source Sans 3`, `Source Code Pro`, `Raleway` |
+
+##### `$styles`
+
+| Name           | Value                                                     |
+| :------------- | :-------------------------------------------------------- |
+| Description    | Font styles to include                                    |
+| Default Value  | All styles                                                |
+| Type           | [List](https://sass-lang.com/documentation/values/lists/) |
+| Allowed Values | one or multiple of `normal`, `italic`                     |
+
+##### `$ranges`
+
+| Name           | Value                                                                                                   |
+| :------------- | :------------------------------------------------------------------------------------------------------ |
+| Description    | Unicode ranges to include                                                                               |
+| Default Value  | All built ranges                                                                                        |
+| Type           | [List](https://sass-lang.com/documentation/values/lists/)                                               |
+| Allowed Values | one or multiple of `cyrillic-ext`, `cyrillic`, `greek-ext`, `greek`, `vietnamese`, `latin-ext`, `latin` |
diff --git a/build/index.js b/build/index.js
index 373af76..4ee80e5 100644
--- a/build/index.js
+++ b/build/index.js
@@ -49,12 +49,12 @@ console.log('');
   await writeFile(
     path,
     [
-      `@use 'sass:map';`,
       `$families: ${arrayToScssList(Object.keys(CONFIGS))};`,
       `$styles: ${arrayToScssList(STYLES)};`,
+      `$ranges: ${arrayToScssList(Object.keys(UNICODE_RANGES))};`,
+      '',
       `$weights: ${objToScssMap(Object.fromEntries(Object.entries(CONFIGS).map(([k, v]) => [k, v.weight])))};`,
       `$unicode-ranges: ${objToScssMap(UNICODE_RANGES)};`,
-      `$ranges: map.keys($unicode-ranges)`,
     ].join('\n'),
   );
   console.log('📝 Wrote build infos to', coloredPath(path));