@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/fonts/font-picker.d.ts

@@ -0,0 +1,70 @@
+import * as React from "react";
+import { type LabelsProp } from "../lib/labels.js";
+import { type FontCategory, type GoogleFont } from "./catalog.js";
+export declare const fontPickerLabels: {
+    placeholder: string;
+    search: string;
+    searchPlaceholder: string;
+    categories: string;
+    all: string;
+    list: string;
+    empty: string;
+    results: string;
+    variable: string;
+    italic: string;
+    weights: string;
+};
+export type FontPickerLabels = typeof fontPickerLabels;
+export interface FontPickerListProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Selected family name. */
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (family: string, font: GoogleFont) => void;
+    /** Families to offer. Default: the 59-family catalog. */
+    fonts?: GoogleFont[];
+    /** Only these categories (e.g. `["mono"]` for a code font field). */
+    categories?: FontCategory[];
+    /** Sample line under each family. */
+    previewText?: string;
+    /** Load glyph-subset previews from Google Fonts. Default `true`. Turn off when fonts are self-hosted. */
+    loadPreviews?: boolean;
+    /** Show the large specimen of the active option. Default `true`. */
+    specimen?: boolean;
+    /** Focus the search field on mount. */
+    autoFocus?: boolean;
+    /** Max height of the list (CSS length). Default `"18rem"`. */
+    listHeight?: string;
+    labels?: LabelsProp<FontPickerLabels>;
+}
+/**
+ * Searchable, categorised list of font families with live previews. ARIA combobox + listbox:
+ * focus stays in the search field; ↑/↓, PageUp/PageDown, Home/End (with Ctrl) move, Enter selects.
+ * Use it inline (settings pages) or through `FontPicker` (popover).
+ */
+export declare const FontPickerList: React.ForwardRefExoticComponent<FontPickerListProps & React.RefAttributes<HTMLDivElement>>;
+export interface FontPickerProps extends Omit<FontPickerListProps, "autoFocus" | "className" | "onChange" | "id"> {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    size?: "sm" | "md" | "lg";
+    placeholder?: string;
+    disabled?: boolean;
+    /** Show the category under the family name in the trigger. Default `true`. */
+    showCategory?: boolean;
+    align?: "start" | "center" | "end";
+    id?: string;
+    name?: string;
+    required?: boolean;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: boolean | "true" | "false";
+    className?: string;
+    /** Class for the popover panel. */
+    contentClassName?: string;
+}
+/**
+ * A select-like trigger that opens the searchable font list in a popover. Closes on selection.
+ * Inside a `Field` it picks up the id, description and invalid state.
+ */
+export declare const FontPicker: React.ForwardRefExoticComponent<FontPickerProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/fonts/font-picker.js

@@ -0,0 +1,225 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, ChevronsUpDown, Search } from "lucide-react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { cn } from "../lib/cn.js";
+import { controlVariants } from "../lib/variants.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useFieldControl, FieldContextReset } from "../lib/field-context.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { Layer } from "../lib/layer.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { highlightParts, matchText } from "../lib/text.js";
+import { fontCategories, fontGroupOf, fontGroups, fontStack, getFont, googleFonts, isVariableFont } from "./catalog.js";
+import { FONT_PREVIEW_TEXT, loadFontPreviews } from "./loader.js";
+export const fontPickerLabels = {
+    placeholder: "Choose a font",
+    search: "Search fonts",
+    searchPlaceholder: "Search by name, style or use",
+    categories: "Category",
+    all: "All",
+    list: "Fonts",
+    empty: "No fonts match “{query}”.",
+    results: "{count, plural, one {# family} other {# families}}",
+    variable: "Variable",
+    italic: "Italic",
+    weights: "{count, plural, one {# weight} other {# weights}}",
+};
+/* ------------------------------------------------------------------ */
+/* Preview font visibility                                             */
+/* ------------------------------------------------------------------ */
+/** Applies a family's face only once its row has scrolled into view, so only visible previews download. */
+function useSeen(root) {
+    const [seen, setSeen] = React.useState(() => new Set());
+    const observer = React.useRef(null);
+    const pending = React.useRef(new Map());
+    React.useEffect(() => {
+        if (typeof IntersectionObserver === "undefined")
+            return;
+        const io = new IntersectionObserver((entries) => {
+            const add = [];
+            for (const e of entries) {
+                if (!e.isIntersecting)
+                    continue;
+                const id = pending.current.get(e.target);
+                if (id)
+                    add.push(id);
+                io.unobserve(e.target);
+            }
+            if (add.length)
+                setSeen((s) => new Set([...s, ...add]));
+        }, { root: root.current, rootMargin: "120px 0px" });
+        observer.current = io;
+        for (const el of pending.current.keys())
+            io.observe(el);
+        return () => io.disconnect();
+    }, [root]);
+    const observe = React.useCallback((id) => (el) => {
+        if (!el)
+            return;
+        if (typeof IntersectionObserver === "undefined") {
+            setSeen((s) => (s.has(id) ? s : new Set(s).add(id)));
+            return;
+        }
+        pending.current.set(el, id);
+        observer.current?.observe(el);
+    }, []);
+    return { seen, observe };
+}
+/**
+ * Searchable, categorised list of font families with live previews. ARIA combobox + listbox:
+ * focus stays in the search field; ↑/↓, PageUp/PageDown, Home/End (with Ctrl) move, Enter selects.
+ * Use it inline (settings pages) or through `FontPicker` (popover).
+ */
+export const FontPickerList = React.forwardRef(function FontPickerList({ value: valueProp, defaultValue, onValueChange, fonts = googleFonts, categories, previewText = FONT_PREVIEW_TEXT, loadPreviews = true, specimen = true, autoFocus, listHeight = "18rem", labels, className, ...props }, ref) {
+    const t = useLabels("fontPicker", fontPickerLabels, labels);
+    const { locale } = useLocale();
+    const uid = React.useId();
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? null, name: "FontPickerList" });
+    const [query, setQuery] = React.useState("");
+    const pool = React.useMemo(() => (categories?.length ? fonts.filter((f) => categories.includes(f.category)) : fonts), [fonts, categories]);
+    const cats = React.useMemo(() => fontCategories.filter((c) => pool.some((f) => f.category === c.id)), [pool]);
+    const [cat, setCat] = React.useState("all");
+    const rows = React.useMemo(() => {
+        const out = [];
+        for (const g of fontGroups) {
+            for (const f of pool) {
+                if (fontGroupOf(f).id !== g.id)
+                    continue;
+                if (cat !== "all" && f.category !== cat)
+                    continue;
+                if (query && !matchText(`${f.family} ${g.label} ${f.use}`, query, locale))
+                    continue;
+                out.push({ font: f, group: g.id });
+            }
+        }
+        if (query) {
+            // Name matches first, keep group order otherwise.
+            const byName = (r) => (matchText(r.font.family, query, locale) ? 0 : 1);
+            out.sort((a, b) => byName(a) - byName(b));
+        }
+        return out;
+    }, [pool, cat, query, locale]);
+    const [active, setActive] = React.useState(null);
+    const activeIndex = Math.max(0, rows.findIndex((r) => r.font.family === active));
+    const activeRow = rows.length ? rows[activeIndex] : undefined;
+    // Keep the active option on the selection when the list changes.
+    React.useEffect(() => {
+        if (rows.length === 0)
+            return setActive(null);
+        if (active && rows.some((r) => r.font.family === active))
+            return;
+        setActive(rows.find((r) => r.font.family === value)?.font.family ?? rows[0].font.family);
+    }, [rows, value, active]);
+    const listRef = React.useRef(null);
+    const { seen, observe } = useSeen(listRef);
+    React.useEffect(() => {
+        if (loadPreviews)
+            void loadFontPreviews(pool.map((f) => f.family), { extraText: previewText });
+    }, [loadPreviews, pool, previewText]);
+    const optionId = (f) => `${uid}-opt-${f.id}`;
+    React.useEffect(() => {
+        if (!activeRow)
+            return;
+        const el = listRef.current?.querySelector(`[id="${optionId(activeRow.font)}"]`);
+        el?.scrollIntoView?.({ block: "nearest" });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeRow?.font.id]);
+    const select = (f) => {
+        setValue(f.family);
+        onValueChange?.(f.family, f);
+    };
+    const move = (to) => {
+        if (!rows.length)
+            return;
+        const i = Math.min(rows.length - 1, Math.max(0, to));
+        setActive(rows[i].font.family);
+    };
+    const onKeyDown = (e) => {
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                move(activeIndex + 1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                move(activeIndex - 1);
+                break;
+            case "PageDown":
+                e.preventDefault();
+                move(activeIndex + 8);
+                break;
+            case "PageUp":
+                e.preventDefault();
+                move(activeIndex - 8);
+                break;
+            case "Home":
+                if (e.ctrlKey || e.metaKey) {
+                    e.preventDefault();
+                    move(0);
+                }
+                break;
+            case "End":
+                if (e.ctrlKey || e.metaKey) {
+                    e.preventDefault();
+                    move(rows.length - 1);
+                }
+                break;
+            case "Enter":
+                if (activeRow) {
+                    e.preventDefault();
+                    select(activeRow.font);
+                }
+                break;
+        }
+    };
+    const face = (f) => (seen.has(f.id) || !loadPreviews ? { fontFamily: fontStack(f.family) } : undefined);
+    const listId = `${uid}-list`;
+    const sections = React.useMemo(() => {
+        const m = new Map();
+        for (const r of rows)
+            m.set(r.group, [...(m.get(r.group) ?? []), r]);
+        return [...m.entries()];
+    }, [rows]);
+    const renderOption = (r) => {
+        const g = fontGroups.find((x) => x.id === r.group);
+        const selected = r.font.family === value;
+        const isActive = r.font.family === activeRow?.font.family;
+        return (_jsxs("div", { ref: observe(r.font.id), id: optionId(r.font), role: "option", "aria-selected": selected, "data-active": isActive || undefined, onPointerMove: () => !isActive && setActive(r.font.family), onMouseDown: (e) => e.preventDefault(), onClick: () => select(r.font), className: "relative grid cursor-default grid-cols-[minmax(0,1fr)_auto] items-baseline gap-x-3 rounded-ui-sm px-2.5 py-1.5 data-active:bg-hover", children: [_jsx("span", { className: "truncate text-[15.5px] leading-snug text-fg", style: face(r.font), children: query
+                        ? highlightParts(r.font.family, query, locale).map((p, i) => (p.match ? _jsx("mark", { className: "rounded-[2px] bg-accent-soft text-fg", children: p.text }, i) : _jsx(React.Fragment, { children: p.text }, i)))
+                        : r.font.family }), _jsxs("span", { className: "flex items-center gap-1.5 text-[11px] text-fg-subtle", children: [query ? _jsx("span", { children: g.label }) : null, isVariableFont(r.font) ? _jsx("span", { className: "font-mono uppercase tracking-wide", children: "var" }) : _jsxs("span", { className: "tabular-nums", children: [r.font.weights.length, "w"] }), _jsx(Check, { "aria-hidden": true, className: cn("size-3.5 text-accent-ink", !selected && "invisible") })] }), _jsx("span", { "aria-hidden": true, className: "col-span-2 truncate text-[12.5px] leading-snug text-fg-muted", style: face(r.font), children: previewText })] }, r.font.id));
+    };
+    return (_jsxs("div", { ref: ref, "data-slot": "font-picker-list", className: cn("grid min-w-0 gap-2.5", className), ...props, children: [_jsxs("div", { className: cn(controlVariants({ size: "md" }), "ps-2.5"), children: [_jsx(Search, { "aria-hidden": true, className: "text-fg-subtle" }), _jsx("input", { role: "combobox", "aria-label": t("search"), "aria-expanded": true, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": activeRow ? optionId(activeRow.font) : undefined, autoFocus: autoFocus, autoComplete: "off", spellCheck: false, value: query, placeholder: t("searchPlaceholder"), onChange: (e) => setQuery(e.target.value), onKeyDown: onKeyDown, className: "h-full min-w-0 flex-1 bg-transparent text-fg outline-none placeholder:text-fg-subtle" }), _jsx("span", { "aria-live": "polite", className: "shrink-0 text-[11.5px] tabular-nums text-fg-subtle", children: t("results", { count: rows.length }) })] }), cats.length > 1 ? (_jsx("div", { role: "group", "aria-label": t("categories"), className: "-mx-0.5 flex flex-wrap gap-1 px-0.5", children: [{ id: "all", label: t("all") }, ...cats].map((c) => (_jsx("button", { type: "button", "aria-pressed": cat === c.id, onClick: () => setCat(c.id), className: cn("h-6 rounded-full border px-2.5 text-[11.5px] font-medium transition-colors focus-ring", cat === c.id ? "border-transparent bg-fg text-scene" : "border-line text-fg-muted hover:border-field-border-hover hover:text-fg"), children: c.label }, c.id))) })) : null, _jsx("div", { ref: listRef, id: listId, role: "listbox", "aria-label": t("list"), tabIndex: -1, style: { maxHeight: listHeight }, className: "-mx-1 overflow-y-auto overscroll-contain px-1", children: rows.length === 0 ? (_jsx("p", { className: "px-2 py-8 text-center text-[13px] text-fg-muted", children: t("empty", { query }) })) : query ? (rows.map((r) => renderOption(r))) : (sections.map(([gid, items]) => {
+                    const g = fontGroups.find((x) => x.id === gid);
+                    const hid = `${uid}-grp-${gid}`;
+                    return (_jsxs("div", { role: "group", "aria-labelledby": hid, className: "pb-1", children: [_jsx("div", { id: hid, className: "px-2.5 pb-1 pt-2.5 font-mono text-[10.5px] uppercase tracking-[0.08em] text-fg-subtle", children: g.label }), items.map((r) => renderOption(r))] }, gid));
+                })) }), specimen && activeRow ? (_jsxs("div", { "aria-hidden": true, className: "relative -mx-(--popover-p,0px) -mb-(--popover-p,0px) overflow-hidden border-t border-line bg-surface-2 px-(--popover-p,0.75rem) py-3", children: [_jsx("div", { className: "truncate text-[28px] leading-[1.1] text-fg", style: { fontFamily: fontStack(activeRow.font.family) }, children: "A\u011Fa\u00E7 i\u015F\u00E7ili\u011Fi" }), _jsxs("div", { className: "mt-1.5 flex items-baseline justify-between gap-3 text-[11.5px]", children: [_jsx("span", { className: "min-w-0 truncate text-fg-muted", children: activeRow.font.use }), _jsxs("span", { className: "shrink-0 font-mono text-[10.5px] uppercase tracking-[0.06em] text-fg-subtle", children: [isVariableFont(activeRow.font) ? t("variable") : t("weights", { count: activeRow.font.weights.length }), activeRow.font.italics ? ` · ${t("italic")}` : ""] })] })] })) : null] }));
+});
+/**
+ * A select-like trigger that opens the searchable font list in a popover. Closes on selection.
+ * Inside a `Field` it picks up the id, description and invalid state.
+ */
+export const FontPicker = React.forwardRef(function FontPicker(rawProps, ref) {
+    const props = useFieldControl(rawProps);
+    const { open: openProp, defaultOpen, onOpenChange, size = "md", placeholder, disabled, showCategory = true, align = "start", id, name, required, className, contentClassName, value: valueProp, defaultValue, onValueChange, labels, loadPreviews = true, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, "aria-invalid": ariaInvalid, ...listProps } = props;
+    delete listProps.readOnly;
+    const t = useLabels("fontPicker", fontPickerLabels, labels);
+    const [open, setOpen] = useControllableState({ value: openProp, defaultValue: defaultOpen ?? false, onChange: onOpenChange, name: "FontPicker" });
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? null, name: "FontPicker" });
+    const font = value ? getFont(value) : undefined;
+    const container = usePortalContainer();
+    React.useEffect(() => {
+        if (loadPreviews && value)
+            void loadFontPreviews([value]);
+    }, [loadPreviews, value]);
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, disabled: disabled, children: _jsxs("button", { ref: ref, type: "button", id: id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, "aria-invalid": ariaInvalid, "aria-haspopup": "dialog", "data-slot": "font-picker-trigger", className: cn(controlVariants({ size }), "justify-between text-start", className), children: [_jsx("span", { className: "flex min-w-0 items-baseline gap-2", children: value ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "truncate text-[1.05em]", style: font ? { fontFamily: fontStack(font.family) } : undefined, children: value }), showCategory && font ? _jsx("span", { className: "truncate text-[11.5px] text-fg-subtle", children: fontGroupOf(font).label }) : null] })) : (_jsx("span", { className: "truncate text-fg-subtle", children: placeholder ?? t("placeholder") })) }), _jsx(ChevronsUpDown, { "aria-hidden": true, className: "shrink-0 text-fg-subtle" })] }) }), name ? _jsx("input", { type: "hidden", name: name, value: value ?? "", required: required }) : null, _jsx(PopoverPrimitive.Portal, { container: container, children: _jsx(Layer, { asChild: true, children: _jsx(PopoverPrimitive.Content, { align: align, sideOffset: 6, collisionPadding: 12, "aria-label": t("list"), onOpenAutoFocus: (e) => {
+                            e.preventDefault();
+                            e.currentTarget?.querySelector("input[role=combobox]")?.focus();
+                        }, className: cn("surface-popover ui-pop z-(--z-popover) w-[24rem] max-w-[calc(100vw-1.5rem)] overflow-hidden rounded-ui-lg p-(--popover-p) outline-none [--popover-p:0.625rem]", contentClassName), children: _jsx(FieldContextReset, { children: _jsx(FontPickerList, { ...listProps, labels: labels, loadPreviews: loadPreviews, value: value, onValueChange: (fam, f) => {
+                                    setValue(fam);
+                                    onValueChange?.(fam, f);
+                                    setOpen(false);
+                                } }) }) }) }) })] }));
+});

package/dist/fonts/index.d.ts

@@ -0,0 +1,6 @@
+export { googleFonts, fontGroups, fontCategories, getFont, fontGroupOf, fontStack, isVariableFont, type GoogleFont, type FontAxis, type FontCategory, type FontStyle, type FontGroup, } from "./catalog.js";
+export { googleFontsUrl, familySpec, nearestWeight, loadGoogleFonts, loadFontPreviews, preconnectGoogleFonts, fontPreviewCharacters, FONT_PREVIEW_TEXT, GOOGLE_FONTS_CSS, GOOGLE_FONTS_ORIGINS, type FontRequest, type FontDisplay, type GoogleFontsUrlOptions, type LoadGoogleFontsOptions, } from "./loader.js";
+export { fontPairings, getFontPairing, createFontPairing, displayTokensFor, pairingFamilies, pairingUrl, pairingVars, applyFontPairing, clearFontPairing, serializeFontPairing, parseFontPairing, fontBootScript, FONT_PAIRING_VARS, type FontPairing, type FontDisplayTokens, type ApplyFontPairingOptions, type StoredFontPairing, } from "./pairings.js";
+export { FontProvider, useFontPairing, type FontProviderProps, type FontPairingContextValue } from "./provider.js";
+export { FontPicker, FontPickerList, fontPickerLabels, type FontPickerProps, type FontPickerListProps, type FontPickerLabels } from "./font-picker.js";
+export { FontPairingPicker, fontPairingPickerLabels, type FontPairingPickerProps, type FontPairingPickerLabels } from "./pairing-picker.js";

package/dist/fonts/index.js

@@ -0,0 +1,7 @@
+// Public API of @vamos-ui/react/fonts — Google Fonts catalog, pairings, loader, pickers.
+export { googleFonts, fontGroups, fontCategories, getFont, fontGroupOf, fontStack, isVariableFont, } from "./catalog.js";
+export { googleFontsUrl, familySpec, nearestWeight, loadGoogleFonts, loadFontPreviews, preconnectGoogleFonts, fontPreviewCharacters, FONT_PREVIEW_TEXT, GOOGLE_FONTS_CSS, GOOGLE_FONTS_ORIGINS, } from "./loader.js";
+export { fontPairings, getFontPairing, createFontPairing, displayTokensFor, pairingFamilies, pairingUrl, pairingVars, applyFontPairing, clearFontPairing, serializeFontPairing, parseFontPairing, fontBootScript, FONT_PAIRING_VARS, } from "./pairings.js";
+export { FontProvider, useFontPairing } from "./provider.js";
+export { FontPicker, FontPickerList, fontPickerLabels } from "./font-picker.js";
+export { FontPairingPicker, fontPairingPickerLabels } from "./pairing-picker.js";

package/dist/fonts/loader.d.ts

@@ -0,0 +1,66 @@
+import { type GoogleFont } from "./catalog.js";
+export declare const GOOGLE_FONTS_CSS = "https://fonts.googleapis.com/css2";
+export declare const GOOGLE_FONTS_ORIGINS: readonly ["https://fonts.googleapis.com", "https://fonts.gstatic.com"];
+/** A family to request, optionally narrowed. */
+export interface FontRequest {
+    family: string;
+    /** Only these weights (default: the whole range / every static weight). */
+    weights?: number[];
+    /** Request italics when the family has them. Default `true`. */
+    italics?: boolean;
+}
+export type FontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
+export interface GoogleFontsUrlOptions {
+    /** `font-display` for every face. Default `"swap"`. */
+    display?: FontDisplay;
+    /** Only the glyphs in this string (tiny files — for previews and logos). */
+    text?: string;
+    /** Request the optical-size axis when a variable family has one. Default `true`. */
+    opticalSize?: boolean;
+}
+/** The `family=` value of one request, e.g. `Fraunces:ital,opsz,wght@0,9..144,100..900;1,9..144,100..900`. */
+export declare function familySpec(request: string | FontRequest, options?: Pick<GoogleFontsUrlOptions, "opticalSize">): string;
+/** Closest available weight to `target`. */
+export declare function nearestWeight(font: GoogleFont, target?: number): number;
+/**
+ * Google Fonts CSS2 URL for one or more families. Duplicates are dropped.
+ *
+ * ```ts
+ * googleFontsUrl(["Onest", "Instrument Serif"]);
+ * // https://fonts.googleapis.com/css2?family=Onest:wght@100..900&family=Instrument+Serif:ital@0;1&display=swap
+ * ```
+ */
+export declare function googleFontsUrl(families: Array<string | FontRequest>, options?: GoogleFontsUrlOptions): string;
+export interface LoadGoogleFontsOptions extends GoogleFontsUrlOptions {
+    /** Document to inject into (iframes, tests). Default: the global `document`. */
+    document?: Document;
+    /**
+     * Add `blocking="render"` to the link so supporting browsers wait for the CSS
+     * (not the font files) before first paint. Use only in a boot script. Default `false`.
+     */
+    renderBlocking?: boolean;
+}
+/** Adds `<link rel="preconnect">` for both Google Fonts origins, once per document. */
+export declare function preconnectGoogleFonts(doc?: Document | undefined): void;
+/**
+ * Loads Google Fonts families by injecting a single `<link rel="stylesheet">` (plus preconnect).
+ * Families already requested by an earlier call — with the same options — are skipped, so calling
+ * it on every render is cheap. Resolves when the stylesheet has loaded (or failed); a no-op on the server.
+ *
+ * ```ts
+ * await loadGoogleFonts(["Fraunces", "Figtree"], { display: "swap" });
+ * ```
+ */
+export declare function loadGoogleFonts(families: Array<string | FontRequest>, options?: LoadGoogleFontsOptions): Promise<void>;
+/** The sample line pickers show under each family. */
+export declare const FONT_PREVIEW_TEXT = "Hamburgefonstiv \u2014 A\u011Fa\u00E7 i\u015F\u00E7ili\u011Fi";
+/** Every glyph a preview may need: the sample line, digits and all catalog family names. Stable, so loads dedupe. */
+export declare function fontPreviewCharacters(extra?: string): string;
+/**
+ * Loads tiny glyph-subset files — one weight per family, only the characters of the preview line and
+ * the catalog family names — so a picker can show every family in its own face without full downloads.
+ * Pass `{ family, weights: [700] }` to preview a heavier weight.
+ */
+export declare function loadFontPreviews(families: Array<string | FontRequest>, options?: Omit<LoadGoogleFontsOptions, "text" | "opticalSize"> & {
+    extraText?: string;
+}): Promise<void>;

package/dist/fonts/loader.js

@@ -0,0 +1,161 @@
+// Google Fonts CSS2 URL builder and a deduped, SSR-safe <link> loader.
+import { getFont, googleFonts } from "./catalog.js";
+export const GOOGLE_FONTS_CSS = "https://fonts.googleapis.com/css2";
+export const GOOGLE_FONTS_ORIGINS = ["https://fonts.googleapis.com", "https://fonts.gstatic.com"];
+const norm = (r) => (typeof r === "string" ? { family: r } : r);
+/** The `family=` value of one request, e.g. `Fraunces:ital,opsz,wght@0,9..144,100..900;1,9..144,100..900`. */
+export function familySpec(request, options = {}) {
+    const r = norm(request);
+    const font = getFont(r.family);
+    const name = (font?.family ?? r.family).trim().replace(/\s+/g, "+");
+    if (!font) {
+        // Not in the catalog: pass weights through as given.
+        return r.weights?.length ? `${name}:wght@${[...r.weights].sort((a, b) => a - b).join(";")}` : name;
+    }
+    const ital = font.italics && r.italics !== false;
+    const wghtAxis = font.axes.find((a) => a.tag === "wght");
+    const opszAxis = options.opticalSize === false || r.weights ? undefined : font.axes.find((a) => a.tag === "opsz");
+    let weights;
+    if (r.weights?.length) {
+        const ok = r.weights.filter((w) => (wghtAxis ? w >= wghtAxis.min && w <= wghtAxis.max : font.weights.includes(w)));
+        weights = [...new Set(ok.length ? ok : [nearestWeight(font, 400)])].sort((a, b) => a - b).map(String);
+    }
+    else if (wghtAxis) {
+        weights = [`${wghtAxis.min}..${wghtAxis.max}`];
+    }
+    else {
+        weights = font.weights.map(String);
+    }
+    const single = weights.length === 1 && weights[0] === "400" && !opszAxis;
+    if (single && !ital)
+        return name;
+    if (single && ital)
+        return `${name}:ital@0;1`;
+    const tags = [ital && "ital", opszAxis && "opsz", "wght"].filter(Boolean).join(",");
+    const tuples = [];
+    for (const i of ital ? [0, 1] : [null]) {
+        for (const w of weights) {
+            const parts = [];
+            if (i !== null)
+                parts.push(String(i));
+            if (opszAxis)
+                parts.push(`${opszAxis.min}..${opszAxis.max}`);
+            parts.push(w);
+            tuples.push(parts.join(","));
+        }
+    }
+    return `${name}:${tags}@${tuples.join(";")}`;
+}
+/** Closest available weight to `target`. */
+export function nearestWeight(font, target = 400) {
+    return font.weights.reduce((best, w) => (Math.abs(w - target) < Math.abs(best - target) ? w : best), font.weights[0] ?? 400);
+}
+/**
+ * Google Fonts CSS2 URL for one or more families. Duplicates are dropped.
+ *
+ * ```ts
+ * googleFontsUrl(["Onest", "Instrument Serif"]);
+ * // https://fonts.googleapis.com/css2?family=Onest:wght@100..900&family=Instrument+Serif:ital@0;1&display=swap
+ * ```
+ */
+export function googleFontsUrl(families, options = {}) {
+    const seen = new Set();
+    const specs = [];
+    for (const f of families) {
+        const spec = familySpec(f, options);
+        if (seen.has(spec))
+            continue;
+        seen.add(spec);
+        specs.push(`family=${spec}`);
+    }
+    let url = `${GOOGLE_FONTS_CSS}?${specs.join("&")}&display=${options.display ?? "swap"}`;
+    if (options.text)
+        url += `&text=${encodeURIComponent(uniqueChars(options.text))}`;
+    return url;
+}
+function uniqueChars(s) {
+    return [...new Set(Array.from(s))].sort().join("");
+}
+const LINK_ATTR = "data-vamos-fonts";
+/** Adds `<link rel="preconnect">` for both Google Fonts origins, once per document. */
+export function preconnectGoogleFonts(doc = typeof document === "undefined" ? undefined : document) {
+    if (!doc)
+        return;
+    for (const origin of GOOGLE_FONTS_ORIGINS) {
+        if (doc.head.querySelector(`link[rel="preconnect"][href="${origin}"]`))
+            continue;
+        const l = doc.createElement("link");
+        l.rel = "preconnect";
+        l.href = origin;
+        if (origin.includes("gstatic"))
+            l.crossOrigin = "anonymous";
+        doc.head.appendChild(l);
+    }
+}
+/**
+ * Loads Google Fonts families by injecting a single `<link rel="stylesheet">` (plus preconnect).
+ * Families already requested by an earlier call — with the same options — are skipped, so calling
+ * it on every render is cheap. Resolves when the stylesheet has loaded (or failed); a no-op on the server.
+ *
+ * ```ts
+ * await loadGoogleFonts(["Fraunces", "Figtree"], { display: "swap" });
+ * ```
+ */
+export function loadGoogleFonts(families, options = {}) {
+    const doc = options.document ?? (typeof document === "undefined" ? undefined : document);
+    if (!doc || families.length === 0)
+        return Promise.resolve();
+    const variant = `${options.display ?? "swap"}|${options.text ? uniqueChars(options.text) : ""}|${options.opticalSize === false ? 0 : 1}`;
+    const loaded = new Set(Array.from(doc.head.querySelectorAll(`link[${LINK_ATTR}]`)).flatMap((l) => l.getAttribute("data-variant") === variant ? (l.getAttribute(LINK_ATTR) ?? "").split("|") : []));
+    const fresh = [];
+    const keys = [];
+    for (const f of families) {
+        const key = familySpec(f, options);
+        if (loaded.has(key) || keys.includes(key))
+            continue;
+        keys.push(key);
+        fresh.push(f);
+    }
+    if (fresh.length === 0)
+        return Promise.resolve();
+    preconnectGoogleFonts(doc);
+    const link = doc.createElement("link");
+    link.rel = "stylesheet";
+    link.href = googleFontsUrl(fresh, options);
+    link.setAttribute(LINK_ATTR, keys.join("|"));
+    link.setAttribute("data-variant", variant);
+    if (options.renderBlocking)
+        link.setAttribute("blocking", "render");
+    const done = new Promise((resolve) => {
+        link.addEventListener("load", () => resolve(), { once: true });
+        link.addEventListener("error", () => resolve(), { once: true });
+    });
+    doc.head.appendChild(link);
+    return done;
+}
+/** The sample line pickers show under each family. */
+export const FONT_PREVIEW_TEXT = "Hamburgefonstiv — Ağaç işçiliği";
+let previewChars;
+/** Every glyph a preview may need: the sample line, digits and all catalog family names. Stable, so loads dedupe. */
+export function fontPreviewCharacters(extra = "") {
+    previewChars ??= uniqueChars(FONT_PREVIEW_TEXT + "AaGg0123456789 " + googleFonts.map((f) => f.family).join(""));
+    return extra ? uniqueChars(previewChars + extra) : previewChars;
+}
+/**
+ * Loads tiny glyph-subset files — one weight per family, only the characters of the preview line and
+ * the catalog family names — so a picker can show every family in its own face without full downloads.
+ * Pass `{ family, weights: [700] }` to preview a heavier weight.
+ */
+export function loadFontPreviews(families, options = {}) {
+    const { extraText, ...rest } = options;
+    const reqs = [];
+    for (const r of families.map(norm)) {
+        const f = getFont(r.family);
+        if (!f)
+            continue;
+        reqs.push({ family: f.family, weights: r.weights?.length ? r.weights : [nearestWeight(f, 400)], italics: r.italics ?? false });
+    }
+    if (reqs.length === 0)
+        return Promise.resolve();
+    return loadGoogleFonts(reqs, { ...rest, text: fontPreviewCharacters(extraText), opticalSize: false });
+}

package/dist/fonts/pairing-picker.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+import { type LabelsProp } from "../lib/labels.js";
+import { type FontPairing } from "./pairings.js";
+export declare const fontPairingPickerLabels: {
+    label: string;
+    headings: string;
+    body: string;
+    code: string;
+};
+export type FontPairingPickerLabels = typeof fontPairingPickerLabels;
+export interface FontPairingPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue" | "dir"> {
+    /** Selected pairing id. */
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (id: string, pairing: FontPairing) => void;
+    /** Pairings to offer. Default: the 16 built-ins. */
+    pairings?: FontPairing[];
+    /** `"grid"` cards (settings pages) or a compact `"list"` (popovers). Default `"grid"`. */
+    layout?: "grid" | "list";
+    /** Show the one-line description. Default: `true` for grid, `false` for list. */
+    showDescription?: boolean;
+    /** Load preview glyphs from Google Fonts. Default `true`. */
+    loadPreviews?: boolean;
+    disabled?: boolean;
+    labels?: LabelsProp<FontPairingPickerLabels>;
+}
+/**
+ * Pick one of the curated pairings. A WAI-ARIA radio group with a roving tab stop:
+ * arrow keys move and select, Home/End jump to the ends.
+ */
+export declare const FontPairingPicker: React.ForwardRefExoticComponent<FontPairingPickerProps & React.RefAttributes<HTMLDivElement>>;