@driftime/sanity-plugin-font 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,493 @@
-# Temporary Holding Version
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/icon-dark.svg" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/icon-light.svg" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/icon-light.svg" alt="Font plugin logo" width="48" />
+  </picture>
+  <h1>Font</h1>
+  <p><strong>A Sanity Studio plugin by Driftime®</strong></p>
+  <p>Fonts for Sanity Studio, from the Google Fonts catalog or a brand's own files.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@driftime/sanity-plugin-font"><img src="https://img.shields.io/npm/v/@driftime/sanity-plugin-font?style=flat-square&labelColor=1a1a1a&color=666666" alt="npm version" /></a>
+    <a href="https://github.com/driftime/sanity-plugins/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@driftime/sanity-plugin-font?style=flat-square&labelColor=1a1a1a&color=666666" alt="License: MIT" /></a>
+  </p>
+</div>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<br />
+
+## Overview
+
+Font brings typography into the content model. Authors can browse the whole Google Fonts catalog, with every family shown in its own typeface, and choose one as they would any other value. When a brand has its own typeface, they upload the files instead, and the plugin reads the weight and style from each one, so there's nothing to fill in by hand.
+
+The design still has the final say. A field can require the weights, styles, and languages the site depends on, and only fonts that have all of them are offered, so whatever an author picks, the headings still get a real bold.
+
+On the site, a font chosen in Sanity is used much like one from `next/font`, whether it came from Google or an upload, and whether it's set for the whole site, a single page, or one block.
+
+<br />
+
+<figure>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-picker-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-picker-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-picker-light.png" alt="The font picker open in Sanity Studio on the Google Fonts tab, showing a search field, menus for kind and sort order, and a grid of popular families, each set in its own typeface" />
+  </picture>
+  <p align="center"><sub><em>The font picker, with every Google Fonts family set in its own typeface.</em></sub></p>
+</figure>
+
+<br />
+
+## Installation
+
+Font is built for Sanity Studio 6.10 and React 19 and declares both as peer dependencies, so the Studio needs to be on those versions already. Node 20.19 or later is required, or 22.12 or later on Node 22.
+
+```bash
+bun add -E @driftime/sanity-plugin-font
+```
+
+<br />
+
+## Studio
+
+In the Studio, the plugin registers a `font` type, and a step added to the Studio's build brings in the Google Fonts catalog.
+
+<br />
+
+### Adding the Build Step
+
+The build step brings Google's list of font families into the Studio as it builds. It's added to the configuration of whichever bundler builds the Studio.
+
+<br />
+
+#### Standalone Studio
+
+A standalone Studio is built with Vite, and `withFonts` extends the `vite` option in its `sanity.cli.ts`.
+
+```typescript
+import { withFonts } from "@driftime/sanity-plugin-font/vite";
+import { defineCliConfig } from "sanity/cli";
+
+export default defineCliConfig({
+  // ...
+  vite: withFonts(),
+});
+```
+
+<br />
+
+#### Next.js
+
+For a Studio embedded in a Next.js app, `withFonts` wraps the app's configuration in `next.config.ts` and works with both Turbopack and webpack.
+
+```typescript
+import { withFonts } from "@driftime/sanity-plugin-font/next";
+import type { NextConfig } from "next";
+
+const config: NextConfig = {
+  // ...
+};
+
+export default withFonts()(config);
+```
+
+`withFonts` returns an async configuration function rather than an object, so when other plugins also wrap the configuration, it needs to be applied last.
+
+<br />
+
+#### Other Vite Frameworks
+
+A Studio embedded in another Vite-based framework, such as React Router, TanStack Start, or Astro, adds `googleFonts` to that framework's Vite plugins.
+
+```typescript
+import { googleFonts } from "@driftime/sanity-plugin-font/vite";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    // ...
+    googleFonts(),
+  ],
+});
+```
+
+<br />
+
+### Registering the Plugin
+
+The plugin works without any configuration, and the options it's given apply to every font field that doesn't set its own.
+
+```typescript
+import { fontPlugin } from "@driftime/sanity-plugin-font";
+import { defineConfig } from "sanity";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    // ...
+    fontPlugin(),
+  ],
+});
+```
+
+| Option       | Type                   | Default                | Purpose                                                                                             |
+| ------------ | ---------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `sources`    | `SanityFontSource[]`   | `["google", "upload"]` | Where fonts come from. See [Choosing the Sources](#choosing-the-sources).                           |
+| `categories` | `SanityFontCategory[]` | every kind             | Kinds of typeface a font can be. See [Restricting the Fonts](#restricting-the-fonts).               |
+| `families`   | `SanityFontFamily[]`   | every family           | Google families on offer, in the order listed. See [Restricting the Fonts](#restricting-the-fonts). |
+| `weights`    | `SanityFontWeight[]`   | `[400, 600]`           | Weights a font must have. See [Setting the Requirements](#setting-the-requirements).                |
+| `styles`     | `SanityFontStyle[]`    | `["normal"]`           | Styles a font must have in every weight. See [Setting the Requirements](#setting-the-requirements). |
+| `subsets`    | `string[]`             | `["latin"]`            | Character sets a Google font must cover. See [Setting the Requirements](#setting-the-requirements). |
+| `preview`    | `SanityFontPreview`    | `"Aa"`                 | Text used to preview a chosen font. See [Previewing the Font](#previewing-the-font).                |
+
+<br />
+
+### Adding a Font Field
+
+A field of type `font` is defined like any other, and takes the same options as the plugin. Each option a field sets replaces the plugin's.
+
+```typescript
+defineField({
+  name: "headingFont",
+  type: "font",
+  description: "Typeface for headings.",
+});
+```
+
+The plugin registers types named `font` and `fontFile`, so a Studio that already has a type by either name needs to rename it before installing.
+
+<br />
+
+### Setting the Requirements
+
+A design is usually set in a handful of weights and styles, and every font an author picks needs to have them. A field lists them, and the picker only offers Google families that have every one, in every character set listed in `subsets`.
+
+```typescript
+defineField({
+  name: "bodyFont",
+  type: "font",
+  description: "Typeface for body text.",
+  options: { weights: [400, 700], styles: ["normal", "italic"], subsets: ["latin", "latin-ext"] },
+});
+```
+
+Every weight is required in every style, so this field asks for regular, italic, bold, and bold italic. Subsets take Google's own names, such as `cyrillic` or `greek`. Uploaded fonts are held to the same requirements.
+
+<br />
+
+### Restricting the Fonts
+
+`categories` limits the kinds of typeface on offer, and `families` names the exact Google families a field offers, in the order they're listed.
+
+```typescript
+defineField({
+  name: "headingFont",
+  type: "font",
+  description: "Typeface for headings.",
+  options: { categories: ["serif"], families: ["Playfair Display", "Lora", "Fraunces"] },
+});
+```
+
+Family names are checked against the Google Fonts catalog once the build step has run, so the editor autocompletes them and a misspelling is a type error. A list shared between fields is typed with `SanityFontFamily`.
+
+<br />
+
+### Choosing the Sources
+
+A field offers Google Fonts and uploads, each in its own tab. Either can be left out, for example for a logo that's always set in the brand's own typeface.
+
+```typescript
+defineField({
+  name: "brandFont",
+  type: "font",
+  description: "Typeface for the logo.",
+  options: { sources: ["upload"] },
+});
+```
+
+<br />
+
+### Uploading Fonts
+
+An uploaded font is a set of WOFF2 or WOFF files, either one for each weight and style or a single variable font. Authors just add the files, and the plugin works out what each one holds.
+
+Uploaded files are served from the Sanity CDN, which only sends fonts to the origins in the project's CORS settings. **Every domain the site runs on needs to be added to the project's CORS origins** at [sanity.io/manage](https://www.sanity.io/manage), or the site shows the fallback instead. Uploaded files are public, like every Sanity asset, so the font's license is worth checking before it's uploaded.
+
+<br />
+
+<figure>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-upload-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-upload-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-upload-light.png" alt="The font picker on the Upload tab, with the family Landour, the category Display, and one uploaded ExtraBold file above a drop zone for more" />
+  </picture>
+  <p align="center"><sub><em>An uploaded font, with each file's weight and style read from the file itself.</em></sub></p>
+</figure>
+
+<br />
+
+### Previewing the Font
+
+Once a font is chosen, the field shows "Aa" in each of its weights and styles, and `preview.text` replaces it with the site's own text.
+
+```typescript
+defineField({
+  name: "headingFont",
+  type: "font",
+  description: "Typeface for headings.",
+  options: { preview: { text: "Welcome to Acme Inc." } },
+});
+```
+
+<br />
+
+<figure>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-field-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-field-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/font/assets/font-field-light.png" alt="A Body Font field in Sanity Studio set to Spectral, previewing Aa in Regular, Italic, SemiBold, and SemiBold Italic" />
+  </picture>
+  <p align="center"><sub><em>A chosen font, previewed in each weight and style the field requires.</em></sub></p>
+</figure>
+
+<br />
+
+### Document Previews
+
+`createFontPreview` shows a chosen font in a document's preview, in place of the icon its type was given in the schema. It's called in `prepare` with the stored value.
+
+```typescript
+import { createFontPreview } from "@driftime/sanity-plugin-font";
+
+defineType({
+  // ...
+  preview: {
+    select: { title: "title", font: "headingFont" },
+    prepare({ title, font }) {
+      return { title, media: createFontPreview(font) };
+    },
+  },
+});
+```
+
+When no font is stored, it returns `undefined` and the preview keeps the type's icon.
+
+<br />
+
+## Site
+
+On the site, a font from Sanity is used much like one from `next/font`. `resolveFont` turns a stored font into classes and a style, `FontStyles` adds the rules behind them to the page, and `fontFragment` expands an uploaded font's files in a query. All three come from `@driftime/sanity-plugin-font/render`, which contains no Studio code.
+
+<br />
+
+### Querying
+
+An uploaded font's files are references to assets, so a query needs to expand them. `fontFragment` does that, and goes in the font field's projection wherever the field is.
+
+```typescript
+import { fontFragment } from "@driftime/sanity-plugin-font/render";
+
+const settingsQuery = `*[_type == "settings"][0] {
+  headingFont { ${fontFragment} }
+}`;
+```
+
+It leaves a Google font unchanged, so it's safe to use on every font field.
+
+<br />
+
+### Resolving Fonts
+
+`resolveFont` takes a stored font and returns the same three things a `next/font` font does: a `className` that sets it, a `style` that does the same inline, and, when it's given a CSS variable to define, a `variable` class.
+
+```typescript
+import { resolveFont } from "@driftime/sanity-plugin-font/render";
+
+const heading = resolveFont(settings.headingFont, { variable: "--font-heading" });
+```
+
+| Option     | Type                | Default                  | Purpose                                                                      |
+| ---------- | ------------------- | ------------------------ | ---------------------------------------------------------------------------- |
+| `display`  | `SanityFontDisplay` | `"swap"`                 | How the font is shown while it loads, as CSS's `font-display` names it.      |
+| `preload`  | `boolean`           | `true`                   | Whether the page hints that the font's files should start downloading early. |
+| `fallback` | `string[]`          | one for the kind of font | Fonts shown in its place while it loads, such as `["Geist", "sans-serif"]`.  |
+| `variable` | `string`            | none                     | The CSS variable the `variable` class defines, such as `--font-heading`.     |
+
+| Value       | Type                     | Purpose                                                    |
+| ----------- | ------------------------ | ---------------------------------------------------------- |
+| `className` | `string`                 | A class that sets the font.                                |
+| `style`     | `{ fontFamily: string }` | An inline style that sets the font.                        |
+| `variable`  | `string \| undefined`    | A class that defines the CSS variable, when one was named. |
+
+It returns `undefined` when no font is stored.
+
+<br />
+
+### Adding the Styles
+
+`next/font` writes its rules at build time, but a font from Sanity isn't known until the page renders, so `FontStyles` adds its rules then. It takes one resolved font or several.
+
+```tsx
+<FontStyles font={heading} />
+<FontStyles font={[heading, body]} />
+```
+
+It can go in a layout, a page, or the component that uses the font, because React 19 moves its links and styles into the document's head. A font added twice is only added once.
+
+<br />
+
+### Applying Fonts
+
+A resolved font is applied with its classes. The `variable` class defines the variable for the element it's on and everything inside it, so on the root element it covers the whole site, and the site's own CSS can use it with a default for when no font is chosen.
+
+```tsx
+import { FontStyles, resolveFont } from "@driftime/sanity-plugin-font/render";
+
+export default async function Layout({ children }: LayoutProps) {
+  const settings = await getSettings();
+  const heading = resolveFont(settings.headingFont, { variable: "--font-heading" });
+
+  return (
+    <html lang="en" className={heading?.variable}>
+      <body>
+        <FontStyles font={heading} />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+```css
+h1,
+h2 {
+  font-family: var(--font-heading, ui-serif, serif);
+}
+```
+
+A font stored on a page or a block goes on the element that should use it, through its `variable` class or simply its `className`, so it only affects that part of the page.
+
+```tsx
+export function Hero({ font, heading }: HeroProps) {
+  const resolved = resolveFont(font);
+
+  return (
+    <section className={resolved?.className}>
+      <FontStyles font={resolved} />
+      <h1>{heading}</h1>
+    </section>
+  );
+}
+```
+
+A site that doesn't use React adds the font to its head itself. Each resolved font also carries `stylesheet` and `css` for that, along with `preconnect` and `preload` hints.
+
+<br />
+
+## Reference
+
+The rest of this document covers the shape of a stored font and everything the package exports.
+
+<br />
+
+### Stored Fonts
+
+`SanityFont` is the type of a stored font. A Google font holds its family and the weights and styles to load.
+
+```json
+{
+  "_type": "font",
+  "source": "google",
+  "family": "Playfair Display",
+  "category": "serif",
+  "weights": [400, 700],
+  "styles": ["normal", "italic"]
+}
+```
+
+| Field      | Type                 | Purpose                                                                                |
+| ---------- | -------------------- | -------------------------------------------------------------------------------------- |
+| `_type`    | `string`             | Always `font`.                                                                         |
+| `source`   | `SanityFontSource`   | Where the font comes from: `google` or `upload`.                                       |
+| `family`   | `string`             | The name the font is used under.                                                       |
+| `category` | `SanityFontCategory` | The kind of typeface: `sans-serif`, `serif`, `display`, `handwriting`, or `monospace`. |
+| `weights`  | `SanityFontWeight[]` | The weights to load, for a Google font.                                                |
+| `styles`   | `SanityFontStyle[]`  | The styles to load, for a Google font.                                                 |
+| `files`    | `SanityFontFile[]`   | The files, for an uploaded font.                                                       |
+
+An uploaded font holds `files` in place of `weights` and `styles`, each with its asset and the weight and style it holds.
+
+<br />
+
+### API
+
+| Export                         | Import from                           | Purpose                                                  |
+| ------------------------------ | ------------------------------------- | -------------------------------------------------------- |
+| `fontPlugin(config?)`          | `@driftime/sanity-plugin-font`        | Registers the `font` type.                               |
+| `createFontPreview(value)`     | `@driftime/sanity-plugin-font`        | Builds preview media from a stored font.                 |
+| `withFonts()`                  | `@driftime/sanity-plugin-font/vite`   | Adds the build step to the `vite` option of a Studio.    |
+| `googleFonts()`                | `@driftime/sanity-plugin-font/vite`   | The build step as a Vite plugin, for a framework's list. |
+| `withFonts()`                  | `@driftime/sanity-plugin-font/next`   | Adds the build step to a Next.js configuration.          |
+| `resolveFont(value, options?)` | `@driftime/sanity-plugin-font/render` | Resolves a stored font into classes and a style.         |
+| `FontStyles`                   | `@driftime/sanity-plugin-font/render` | Adds resolved fonts to the page.                         |
+| `fontFragment`                 | `@driftime/sanity-plugin-font/render` | GROQ projection that expands an uploaded font's files.   |
+
+<br />
+
+### Types
+
+| Type                          | Import from                           | Purpose                                                         |
+| ----------------------------- | ------------------------------------- | --------------------------------------------------------------- |
+| `SanityFontConfig`            | `@driftime/sanity-plugin-font`        | Everything `fontPlugin` accepts.                                |
+| `SanityFontPreview`           | `@driftime/sanity-plugin-font`        | Settings for the preview below a font field.                    |
+| `SanityFontOptions`           | `@driftime/sanity-plugin-font`        | The `options` a font field accepts.                             |
+| `SanityFontDefinition`        | `@driftime/sanity-plugin-font`        | A field or array member of type `font`.                         |
+| `SanityFontFamily`            | `@driftime/sanity-plugin-font`        | The name of a Google Fonts family, checked against the catalog. |
+| `SanityFontVitePlugin`        | `@driftime/sanity-plugin-font/vite`   | What `googleFonts` returns.                                     |
+| `SanityFontNextConfig`        | `@driftime/sanity-plugin-font/next`   | The parts of a Next.js configuration the build step extends.    |
+| `SanityFontWebpackConfig`     | `@driftime/sanity-plugin-font/next`   | The parts of a webpack configuration the build step extends.    |
+| `SanityFontWebpackCustomizer` | `@driftime/sanity-plugin-font/next`   | A Next.js `webpack` option the build step runs first.           |
+| `SanityFont`                  | `@driftime/sanity-plugin-font/render` | A stored font, from Google Fonts or uploaded.                   |
+| `SanityFontFile`              | `@driftime/sanity-plugin-font/render` | One uploaded file, with the weight and style it holds.          |
+| `SanityFontAsset`             | `@driftime/sanity-plugin-font/render` | A file's asset reference, or the asset with its `url`.          |
+| `SanityFontSource`            | `@driftime/sanity-plugin-font/render` | Where a font comes from: `google` or `upload`.                  |
+| `SanityFontCategory`          | `@driftime/sanity-plugin-font/render` | A kind of typeface.                                             |
+| `SanityFontDisplay`           | `@driftime/sanity-plugin-font/render` | How a font is shown while it loads.                             |
+| `SanityFontWeight`            | `@driftime/sanity-plugin-font/render` | A weight from 100 to 900.                                       |
+| `SanityFontStyle`             | `@driftime/sanity-plugin-font/render` | A style: `normal` or `italic`.                                  |
+| `SanityResolveFontOptions`    | `@driftime/sanity-plugin-font/render` | Everything `resolveFont` accepts besides the stored font.       |
+| `SanityResolvedFont`          | `@driftime/sanity-plugin-font/render` | What `resolveFont` returns.                                     |
+| `SanityFontPreconnect`        | `@driftime/sanity-plugin-font/render` | An origin to connect to early.                                  |
+| `SanityFontPreload`           | `@driftime/sanity-plugin-font/render` | A file to preload.                                              |
+| `SanityFontStylesProps`       | `@driftime/sanity-plugin-font/render` | Everything `FontStyles` accepts.                                |
+
+<br />
+
+## License
+
+MIT © [Driftime®](https://driftime.com). See [LICENSE](https://github.com/driftime/sanity-plugins/blob/main/LICENSE).
+
+<br />
+
+## Acknowledgements
+
+The plugin ships no fonts. Families chosen from [Google Fonts](https://fonts.google.com) are served by Google under their own open licenses, mostly the SIL Open Font License, and uploaded fonts under whatever license the project holds. WOFF2 files are read with the help of [brotli.js](https://github.com/devongovett/brotli.js), under the MIT License. Icons for the Studio's own controls come from `@sanity/icons`, so they match the rest of the Studio. The plugin's own Studio icon is based on [Lucide](https://lucide.dev), distributed under the [ISC License](https://github.com/lucide-icons/lucide/blob/main/LICENSE), and its logo comes from [Central Icon System](https://iconists.co/central), used under its license.
+
+<br />
+<br />
+
+<div align="center">
+  <p><strong>Built alongside <a href="https://cairn.driftime.com">Cairn</a>, a starting point for responsible web experiences.</strong></p>
+  <p>Part of a suite of Sanity Studio plugins by Driftime®</p>
+  <p><a href="https://github.com/driftime/sanity-plugins#readme">Sanity Plugins</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/handbook#readme">Handbook</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/icon#readme">Icon</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/color#readme">Color</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/link#readme">Link</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/font#readme">Font</a></p>
+</div>
+
+<br />
+
+<div align="center">
+  <a href="https://driftime.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://driftime.com/driftime-github-logo-dark.svg" />
+      <source media="(prefers-color-scheme: light)" srcset="https://driftime.com/driftime-github-logo.svg" />
+      <img src="https://driftime.com/driftime-github-logo.svg" alt="Driftime® Logo" width="100" />
+    </picture>
+  </a>
+</div>