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

package/README.md

@@ -1,3 +1,460 @@
-# 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 />
+
+## 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 />
+
+### 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 />
+
+### 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>

package/dist/catalog-BVw1r_SG.js

@@ -0,0 +1,183 @@
+import { n as isRecord, t as isDefined } from "./utils-BV38iODp.js";
+import { c as logger, l as pluginName, n as parseWeights, t as parseCatalog } from "./catalog-KAqAIjzw.js";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+* Resolves symbolic links in a path, so a package linked into `node_modules` matches its real location.
+*
+* @param file - The path.
+* @returns The real path, or the path unchanged when it doesn't exist.
+*/
+function resolveRealPath(file) {
+	try {
+		return realpathSync(file);
+	} catch {
+		return file;
+	}
+}
+/**
+* Path of the placeholder catalog module the Studio imports, which the build step replaces. The build step's own code
+* is published next to it, so the path is found from this file's location.
+*/
+const catalogModulePath = resolveRealPath(fileURLToPath(new URL("catalog.js", import.meta.url)));
+/**
+* Checks whether a module the bundler is loading is the placeholder catalog.
+*
+* @param id - The module's path, possibly followed by a query.
+* @returns Whether it's the placeholder.
+*/
+function isCatalogModule(id) {
+	let [file] = id.split("?");
+	return isDefined(file) && resolveRealPath(file) === catalogModulePath;
+}
+/**
+* Writes the module that replaces the placeholder catalog, which imports the catalog only when a picker opens.
+*
+* @param specifier - What the bundler imports the catalog from, or undefined when there's no catalog to import.
+* @returns The module's code.
+*/
+function createCatalogModule(specifier) {
+	return isDefined(specifier) ? `export const fontCatalog = { ready: true, load: () => import(${JSON.stringify(specifier)}) };` : "export const fontCatalog = { ready: true };";
+}
+/** Types file the plugin reads family names from, published next to the placeholder catalog. */
+const namesFile = path.join(path.dirname(catalogModulePath), "names.d.ts");
+/**
+* Writes the catalog's family names into the plugin's own types, so options that list families are checked against
+* them. The file is replaced rather than edited, because pnpm shares a package's files between projects.
+*
+* @param families - Every family name in the catalog.
+*/
+async function writeFontNames(families) {
+	let union = [...new Set(families)].toSorted().map((name) => JSON.stringify(name)), content = [
+		`// Written by ${pluginName}'s build step from the Google Fonts catalog.`,
+		`export type SanityFontNames = ${isDefined(union) ? union.join(" | ") : "never"};`,
+		""
+	].join("\n");
+	if (await readFile(namesFile, "utf8").catch(() => "") === content) return;
+	let temporary = `${namesFile}.${process.pid}.tmp`;
+	await writeFile(temporary, content), await rename(temporary, namesFile);
+}
+/** Google Fonts' own list of families, which only Node can read because it sends no CORS header. */
+const categories = {
+	"Sans Serif": "sans-serif",
+	Serif: "serif",
+	Display: "display",
+	Handwriting: "handwriting",
+	Monospace: "monospace"
+};
+/**
+* Converts one family from Google's list, keeping only what the picker filters and previews by.
+*
+* @param value - The family from Google's list.
+* @returns The family and its rank in popularity, or undefined when it can't be read or has no weight a font field can
+*   load.
+*/
+function convertFamily(value) {
+	if (!isRecord(value)) return;
+	let { family, category, fonts, axes, subsets, trending, dateAdded, popularity } = value, mapped = typeof category == "string" ? categories[category] : void 0;
+	if (typeof family != "string" || !isDefined(mapped) || !isRecord(fonts) || !Array.isArray(subsets)) return;
+	let variants = Object.keys(fonts), weights = parseWeights(variants.filter((key) => !key.endsWith("i")).map(Number)), italics = parseWeights(variants.filter((key) => key.endsWith("i")).map((key) => Number(key.slice(0, -1))));
+	if (isDefined(weights) || isDefined(italics)) return {
+		converted: {
+			family,
+			category: mapped,
+			weights,
+			italics,
+			variable: Array.isArray(axes) && isDefined(axes),
+			subsets: subsets.filter((subset) => typeof subset == "string" && subset !== "menu"),
+			trending: typeof trending == "number" ? trending : 2 ** 53 - 1,
+			added: typeof dateAdded == "string" ? dateAdded : ""
+		},
+		popularity: typeof popularity == "number" ? popularity : Infinity
+	};
+}
+/**
+* Downloads Google's list of families and converts it.
+*
+* @returns Every family, most popular first, or undefined when Google couldn't be reached or the list couldn't be read.
+*/
+async function downloadCatalog() {
+	try {
+		let response = await fetch("https://fonts.google.com/metadata/fonts", { signal: AbortSignal.timeout(2e4) });
+		if (!response.ok) return;
+		let metadata = await response.json();
+		return !isRecord(metadata) || !Array.isArray(metadata.familyMetadataList) ? void 0 : metadata.familyMetadataList.flatMap((entry) => {
+			let family = convertFamily(entry);
+			return isDefined(family) ? [family] : [];
+		}).toSorted((first, second) => first.popularity - second.popularity).map(({ converted }) => converted);
+	} catch {
+		return;
+	}
+}
+/**
+* Reads the catalog an earlier build wrote.
+*
+* @param file - Path of the file.
+* @returns The families and how long ago they were written, or undefined when there's no usable file.
+*/
+async function readCachedCatalog(file) {
+	try {
+		let [content, details] = await Promise.all([readFile(file, "utf8"), stat(file)]), families = parseCatalog(JSON.parse(content));
+		return isDefined(families) ? {
+			families,
+			written: details.mtime
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Downloads the catalog unless a recent one is cached, and writes it where the bundler can import it. If Google can't
+* be reached, the last download is used instead.
+*
+* @param root - The project folder.
+* @returns The catalog, or undefined when there's neither a download nor an earlier one to use.
+*/
+async function writeCatalogOnce(root) {
+	let file = path.join(root, "node_modules", ".cache", "driftime-font", "catalog.json"), cached = await readCachedCatalog(file);
+	if (isDefined(cached) && Date.now() - cached.written.getTime() < 864e5) return {
+		file,
+		families: cached.families
+	};
+	let families = await downloadCatalog();
+	if (isDefined(families)) {
+		let temporary = `${file}.${randomUUID()}.tmp`;
+		return await mkdir(path.dirname(file), { recursive: !0 }), await writeFile(temporary, JSON.stringify(families)), await rename(temporary, file), logger.info(`Downloaded ${families.length.toLocaleString("en-US")} Google Fonts families.`), {
+			file,
+			families
+		};
+	}
+	if (isDefined(cached)) return logger.warn(`Couldn't reach Google Fonts, so the picker lists the families downloaded on ${cached.written.toLocaleDateString("en-US", { dateStyle: "long" })}.`), {
+		file,
+		families: cached.families
+	};
+	logger.error("Couldn't reach Google Fonts, and there's no earlier download to use. Restart once it can be reached.");
+}
+/**
+* Writes the catalog, then the family names the plugin's types check options against.
+*
+* @param root - The project folder.
+* @returns The catalog, or undefined when there's neither a download nor an earlier one to use.
+*/
+async function prepareCatalog(root) {
+	let catalog = await writeCatalogOnce(root);
+	return isDefined(catalog) && await writeFontNames(catalog.families.map(({ family }) => family)), catalog;
+}
+/** Catalog writes in progress, keyed by project folder, so one process downloads the catalog once. */
+const catalogWrites = /* @__PURE__ */ new Map();
+/**
+* Writes the catalog for a project, reusing a write already in progress.
+*
+* @param root - The project folder.
+* @returns The catalog, or undefined when there's neither a download nor an earlier one to use.
+*/
+async function writeFontCatalog(root) {
+	let write = catalogWrites.get(root);
+	return isDefined(write) || (write = prepareCatalog(root), catalogWrites.set(root, write)), await write;
+}
+export { isCatalogModule as i, catalogModulePath as n, createCatalogModule as r, writeFontCatalog as t };
+
+//# sourceMappingURL=catalog-BVw1r_SG.js.map