Statamic Fontsource Variable Dictionary

A Statamic addon that automatically discovers installed @fontsource-variable fonts and makes them available as a Statamic Dictionary.

Instead of maintaining a separate list of fonts in your Statamic project, this addon reads the font metadata from installed npm packages and exposes it to Statamic's Control Panel.

This means your font list is derived directly from your installed packages rather than being maintained manually. Hence, adding (or removing) a font is as simple as changing your installed npm dependencies:

    npm install @fontsource-variable/ubuntu-sans

There following are also available, for more specialised needs:

• The vite plugin used by this package
• The underlying javascript as a library/cli

This package was developed to support a project of GUNET.

Features

• Automatically discovers installed @fontsource-variable/* packages from your package.json.
• Generates font metadata as part of your existing Vite workflow.
• Makes discovered fonts available through a Statamic Dictionary.
• Provides built-in font categories for use as Control Panel filters.
• Supports custom font categories by extending the dictionary class.

How it works

The addon consists of two parts:

1. Vite font discovery

The Vite plugin scans your application's package.json for installed @fontsource-variable/* packages.

For each discovered font, it reads the package's metadata.json and generates

• a CSS file which you can @import from your main site.css, for making the fonts available to your CSS,
• a JSON file containing the font metadata (key-value, font family, category).

The underlying discovery library @gpits/fontsource-variable-discover can also be used independently when Vite integration isn't required.

2. Statamic Dictionary

The PHP addon reads the generated JSON file and exposes the fonts through a FontsourceVariableFonts Statamic Dictionary.

The fields of the dictionary are the following:

• key: the id of the font in fontsource (i.e. the part after @fontsource-variable/ in your package.json)
• name: the name of the font
• family: the font family to use in CSS to refer to the font
• category: the category characterisation of each font by fontsource.

In particular, the dictionary has been configured so that categories can be used for filtering the available fonts in the Statamic Control Panel. For example, monospace can be useful for a font selector where you want to only include monospace fonts.

If you do not need the categories mechanism, you can alternatively use the JSON file as a File dictionary with these options:

    dictionary:
      type: file
      filename: fonts.json
      value: key
      label: name

Installation

Install the php part of the addon through Composer:

    composer require gpits/statamic-fontsource-variable-dictionary

If you want to customise settings (json path), publish the configuration file:

php artisan vendor:publish --provider="Gpits\StatamicFontsourceVariableDictionary\ServiceProvider" --tag=config

Also, install the Vite font discovery plugin

    npm install @gpits/statamic-fontsource-variable-dictionary

add the font discovery plugin to your Vite configuration.

    import fontsourceVariableDiscover from "@gpits/statamic-fontsource-variable-dictionary";

    export default defineConfig({
        plugins: [
            fontsourceVariableDiscover(),
            ...
        ],
    });

and add @import "./fonts"; (or the correct path, if you use a custom one) to your site.css.

Of course, you also have to install the variable fonts you want to make available to Statamic. For example:

    npm install @fontsource-variable/inter
    npm install @fontsource-variable/roboto-mono

Now, your templates can use the selected font of a Fonts field. For example, assuming you have a body_font field, you may add this in your layout:

<style>
  :root {
    {{ if body_font }}
      font-family: "{{ body_font:family }}", system-ui, sans;
    {{ /if }}
  }
</style>

Configuration

Read devDependencies

By default, only fonts listed in dependencies are discovered. If you also want to discover fonts installed as devDependencies, enable includeDevDependencies in the vite configuration:

    fontsourceVariableDiscover({
        includeDevDependencies: true,
    })

Custom paths

The addon writes the generated files at the following paths by default:

• resources/css/fonts.css
• resources/dictionaries/fonts.json

You can change the CSS path from the vite configuration

    fontsourceVariableDiscover({
        cssPath: "resources/css/variable-fonts.css",
    })

You can also change the JSON path (e.g. to storage/app/fonts.json), but you need to edit it both in vite

    fontsourceVariableDiscover({
        jsonPath: "storage/app/fonts.json",
    })

and in the php config file fontsource-variable-dictionary.php:

    "json_path" => \storage_path("app/fonts.json"),

Custom font categories

If the built-in categories don't fit your project, you can extend Gpits\StatamicFontsourceVariableDictionary\Dictionaries\FontsourceVariableFonts class and define your own dictionary categories.

This allows you to build categories that are specific to your application's design system.

For example, you could create additional categories such as:

• headings
• body while only keeping 'monospace' of the default ones:

namespace App\Dictionaries\MyFonts;

use Gpits\StatamicFontsourceVariableDictionary\Dictionaries\FontsourceVariableFonts;

class MyFonts extends FontsourceVariableFonts
{

    protected function customFontCategories(): array
    {
        return ['body', 'headings', 'monospace'];
    }

    protected function isOfCategory(array $font, string $category): bool
    {
        return match ($category) {
            'body' => $font['category'] == 'sans-serif',
            'headings' => \in_array($font['name'], ['Ysabeau SC', 'Climate Crisis']),
            'monospace' => parent::isOfCategory($font, 'monospace') ?? false,
            default => null,
        };
    }
}

Or you must just want to include more fonts in some category

    protected function isOfCategory(array $font, string $category): bool
    {
        return match ($category) {
            'monospace' => parent::isOfCategory($font, $category) || \in_array('Mono', \explode(' ', $font['name'])),
            default => parent::isOfCategory($font, $category),
        };
    }

By default, Fonts@isOfCategory($font, $category) returns

• true if $category matches exactly the one specified by fontsource,
• false otherwise

Of course, you can also add more ways to filter fonts:

namespace App\Dictionaries\MyFonts;

use Gpits\StatamicFontsourceVariableDictionary\Dictionaries\FontsourceVariableFonts;

class MyFonts extends FontsourceVariableFonts
{
    protected function fieldItems(): array
    {
        return [
            ...parent::fieldItems(),
            'my-filter' [
                //define here
            ],
        ];
    }

    protected function getItems(): array
    {
        $fonts = parent::getItems();

        // apply 'my-filter' to the fonts, which have already been filtered by category

        return \array_values($fonts);
    }
}

Issue tracker

At https://todo.sr.ht/~giorgio93p/fontsource-variable-discover.

Please specify that your issue is related to gpits/statamic-fontsource-variable-dictionary.

License

European Union Public Licence 1.2