@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/fonts/pairing-picker.js

@@ -0,0 +1,81 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useLabels } from "../lib/labels.js";
+import { fontStack, getFont } from "./catalog.js";
+import { loadFontPreviews } from "./loader.js";
+import { fontPairings } from "./pairings.js";
+export const fontPairingPickerLabels = {
+    label: "Type pairing",
+    headings: "Headings",
+    body: "Body",
+    code: "Code",
+};
+/**
+ * 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 const FontPairingPicker = React.forwardRef(function FontPairingPicker({ value: valueProp, defaultValue, onValueChange, pairings = fontPairings, layout = "grid", showDescription, loadPreviews = true, disabled, labels, className, onKeyDown, ...props }, ref) {
+    const t = useLabels("fontPairingPicker", fontPairingPickerLabels, labels);
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? null, name: "FontPairingPicker" });
+    const refs = React.useRef([]);
+    const describe = showDescription ?? layout === "grid";
+    React.useEffect(() => {
+        if (!loadPreviews)
+            return;
+        void loadFontPreviews(pairings.flatMap((p) => [
+            { family: p.heading, weights: [p.display.weight], italics: p.display.em === "italic" },
+            { family: p.body, weights: [400] },
+        ]));
+    }, [loadPreviews, pairings]);
+    const selectedIndex = pairings.findIndex((p) => p.id === value);
+    const tabIndexOf = (i) => (selectedIndex === -1 ? (i === 0 ? 0 : -1) : i === selectedIndex ? 0 : -1);
+    const choose = (i, focus = false) => {
+        const p = pairings[i];
+        if (!p || disabled)
+            return;
+        if (focus)
+            refs.current[i]?.focus();
+        if (p.id !== value) {
+            setValue(p.id);
+            onValueChange?.(p.id, p);
+        }
+    };
+    const handleKey = (e) => {
+        onKeyDown?.(e);
+        if (e.defaultPrevented)
+            return;
+        const current = refs.current.findIndex((el) => el === document.activeElement);
+        if (current === -1)
+            return;
+        const rtl = getComputedStyle(e.currentTarget).direction === "rtl";
+        const last = pairings.length - 1;
+        let next = null;
+        if (e.key === "ArrowDown" || e.key === (rtl ? "ArrowLeft" : "ArrowRight"))
+            next = current === last ? 0 : current + 1;
+        else if (e.key === "ArrowUp" || e.key === (rtl ? "ArrowRight" : "ArrowLeft"))
+            next = current === 0 ? last : current - 1;
+        else if (e.key === "Home")
+            next = 0;
+        else if (e.key === "End")
+            next = last;
+        if (next !== null) {
+            e.preventDefault();
+            choose(next, true);
+        }
+    };
+    return (_jsx("div", { ref: ref, role: "radiogroup", "aria-label": props["aria-labelledby"] ? undefined : t("label"), "aria-disabled": disabled || undefined, "data-slot": "font-pairing-picker", "data-layout": layout, onKeyDown: handleKey, className: cn(layout === "grid" ? "grid grid-cols-[repeat(auto-fill,minmax(13.5rem,1fr))] gap-2" : "grid gap-0.5", className), ...props, children: pairings.map((p, i) => {
+            const checked = p.id === value;
+            const heading = { fontFamily: fontStack(p.heading), fontWeight: p.display.weight, letterSpacing: p.display.tracking };
+            const body = { fontFamily: fontStack(p.body) };
+            const hName = getFont(p.heading)?.family ?? "System UI";
+            const bName = getFont(p.body)?.family ?? "System UI";
+            return (_jsx("button", { ref: (el) => {
+                    refs.current[i] = el;
+                }, type: "button", role: "radio", "aria-checked": checked, "aria-label": `${p.label}: ${hName} / ${bName}`, tabIndex: tabIndexOf(i), disabled: disabled, "data-state": checked ? "checked" : "unchecked", onClick: () => choose(i), className: cn("group/pair relative text-start outline-none transition-[border-color,background-color,box-shadow] duration-150 focus-ring disabled:cursor-not-allowed disabled:opacity-50", layout === "grid"
+                    ? "grid min-h-32 content-between gap-3 rounded-ui border border-line bg-surface-2 p-3.5 hover:border-field-border-hover data-[state=checked]:border-fg/70 data-[state=checked]:bg-surface data-[state=checked]:shadow-[inset_0_0_0_1px_var(--fg)]"
+                    : "grid grid-cols-[2.75rem_minmax(0,1fr)] items-center gap-3 rounded-ui-sm px-2 py-1.5 hover:bg-hover data-[state=checked]:bg-selected"), children: layout === "grid" ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "flex items-start justify-between gap-2", children: [_jsxs("span", { "aria-hidden": true, className: "text-[44px] leading-[0.9] text-fg", style: heading, children: ["A", _jsx("em", { style: { fontStyle: p.display.em }, children: "g" })] }), _jsx("span", { "aria-hidden": true, className: cn("mt-1 size-2 rounded-full border border-field-border transition-colors", checked && "border-transparent bg-accent shadow-[0_0_0_3px_var(--accent-soft)]") })] }), _jsxs("span", { className: "grid gap-1", children: [_jsxs("span", { className: "flex items-baseline justify-between gap-2", children: [_jsx("span", { className: "text-[13.5px] font-semibold text-fg", children: p.label }), _jsx("span", { className: "truncate font-mono text-[10.5px] text-fg-subtle", children: p.id })] }), _jsxs("span", { "aria-hidden": true, className: "truncate text-[12px] text-fg-muted", children: [_jsx("span", { style: heading, children: hName }), _jsx("span", { className: "px-1 text-fg-subtle", children: "/" }), _jsx("span", { style: body, children: bName })] }), describe ? _jsx("span", { className: "line-clamp-2 text-[11.5px] leading-snug text-fg-subtle", children: p.description }) : null] })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: "grid h-9 place-items-center rounded-ui-sm border border-line bg-surface-2 text-[22px] leading-none text-fg", style: heading, children: "Ag" }), _jsxs("span", { className: "grid min-w-0", children: [_jsxs("span", { className: "flex items-baseline justify-between gap-2", children: [_jsx("span", { className: "text-[13px] font-medium text-fg", children: p.label }), checked ? _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-accent shadow-[0_0_0_3px_var(--accent-soft)]" }) : null] }), _jsxs("span", { "aria-hidden": true, className: "truncate text-[11.5px] text-fg-muted", children: [_jsx("span", { style: heading, children: hName }), _jsx("span", { className: "px-1 text-fg-subtle", children: "/" }), _jsx("span", { style: body, children: bName })] }), describe ? _jsx("span", { className: "truncate text-[11px] text-fg-subtle", children: p.description }) : null] })] })) }, p.id));
+        }) }));
+});

package/dist/fonts/pairings.d.ts

@@ -0,0 +1,84 @@
+import { googleFontsUrl, type FontRequest, type LoadGoogleFontsOptions } from "./loader.js";
+export interface FontDisplayTokens {
+    /** `--display-weight`: weight of display headings. */
+    weight: number;
+    /** `--display-tracking`, e.g. `"-0.02em"`. */
+    tracking: string;
+    /** `--display-em`: how `<em>` inside a display heading looks. */
+    em: "italic" | "normal";
+    /** `--display-scale`: multiplier on the display sizes (wide faces want < 1). */
+    scale: number;
+}
+export interface FontPairing {
+    id: string;
+    label: string;
+    /** One line: the mood and where it fits. */
+    description: string;
+    /** Heading family (catalog name) or a raw CSS stack. */
+    heading: string;
+    /** UI / body family. */
+    body: string;
+    /** Code, IDs and numbers. */
+    mono: string;
+    display: FontDisplayTokens;
+    /** The preset also exists as a `[data-font="<id>"]` block in styles.css. */
+    css?: boolean;
+}
+/** 16 curated pairings. The first four match the `data-font` presets in styles.css (same ids). */
+export declare const fontPairings: FontPairing[];
+/** Find a pairing by id. */
+export declare function getFontPairing(id: string, pairings?: FontPairing[]): FontPairing | undefined;
+/** Display tokens that suit a heading family (used for custom pairings). */
+export declare function displayTokensFor(heading: string): FontDisplayTokens;
+/** Build a pairing from any three families; display tokens follow the heading family. */
+export declare function createFontPairing(input: {
+    heading: string;
+    body: string;
+    mono?: string;
+    id?: string;
+    label?: string;
+    description?: string;
+    display?: Partial<FontDisplayTokens>;
+}): FontPairing;
+/** The Google Fonts families a pairing needs (skips raw CSS stacks). */
+export declare function pairingFamilies(pairing: FontPairing): FontRequest[];
+/** Stylesheet URL for a pairing, or `null` when it needs no web fonts (System). */
+export declare function pairingUrl(pairing: FontPairing, options?: Parameters<typeof googleFontsUrl>[1]): string | null;
+export declare const FONT_PAIRING_VARS: readonly ["--font-ui", "--font-heading", "--font-code", "--display-weight", "--display-tracking", "--display-em", "--display-scale"];
+/** The CSS custom properties a pairing sets, ready for `style` or `setProperty`. */
+export declare function pairingVars(pairing: FontPairing): Record<(typeof FONT_PAIRING_VARS)[number], string>;
+export interface ApplyFontPairingOptions extends LoadGoogleFontsOptions {
+    /** Inject the Google Fonts stylesheet. Default `true`. */
+    load?: boolean;
+}
+/**
+ * Applies a pairing to an element: sets `data-font`, the three family tokens and the display tokens
+ * as inline custom properties, and (by default) loads the families from Google Fonts.
+ * Resolves when the stylesheet has loaded.
+ */
+export declare function applyFontPairing(el: HTMLElement, pairing: FontPairing, options?: ApplyFontPairingOptions): Promise<void>;
+/** Removes the inline pairing tokens so the `[data-font]` CSS preset (if any) applies again. */
+export declare function clearFontPairing(el: HTMLElement): void;
+/** A pairing resolved for storage (localStorage, cookies): a boot script can apply it without the catalog. */
+export interface StoredFontPairing {
+    id: string;
+    label: string;
+    heading: string;
+    body: string;
+    mono: string;
+    display: FontDisplayTokens;
+    css?: boolean;
+    /** Google Fonts stylesheet, `null` when none is needed. */
+    href: string | null;
+    /** Dedupe key of the stylesheet (lets `loadGoogleFonts` skip what the boot script loaded). */
+    key: string;
+    vars: Record<string, string>;
+}
+export declare function serializeFontPairing(pairing: FontPairing): StoredFontPairing;
+/** Reads a stored pairing back (validates the shape; unknown input returns `undefined`). */
+export declare function parseFontPairing(value: unknown): FontPairing | undefined;
+/**
+ * Inline boot script (string) that applies a stored pairing before first paint. Put it in `<head>`.
+ * It reads `localStorage[storageKey][field]` (a `StoredFontPairing`).
+ */
+export declare function fontBootScript(storageKey?: string, field?: string): string;

package/dist/fonts/pairings.js

@@ -0,0 +1,149 @@
+// Curated type pairings (heading + body + mono + display character) and the helpers that apply them.
+import { fontStack, getFont } from "./catalog.js";
+import { familySpec, googleFontsUrl, loadGoogleFonts } from "./loader.js";
+const SYSTEM_SANS = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+const SYSTEM_MONO = 'ui-monospace, "SF Mono", Menlo, Consolas, monospace';
+const d = (weight, tracking, em, scale) => ({ weight, tracking, em, scale });
+/** 16 curated pairings. The first four match the `data-font` presets in styles.css (same ids). */
+export const fontPairings = [
+    { id: "editorial", label: "Editorial", description: "Condensed serif headlines over a warm sans. The house style.", heading: "Instrument Serif", body: "Onest", mono: "JetBrains Mono", display: d(400, "-0.01em", "italic", 1), css: true },
+    { id: "grotesk", label: "Grotesk", description: "Expressive grotesque headlines; neutral text. Product and agency sites.", heading: "Bricolage Grotesque", body: "Hanken Grotesk", mono: "Geist Mono", display: d(640, "-0.035em", "normal", 0.86), css: true },
+    { id: "corporate", label: "Corporate", description: "One engineered superfamily. B2B, finance, internal tools.", heading: "IBM Plex Sans", body: "IBM Plex Sans", mono: "IBM Plex Mono", display: d(600, "-0.025em", "normal", 0.8), css: true },
+    { id: "system", label: "System", description: "The platform UI font. Zero downloads.", heading: SYSTEM_SANS, body: SYSTEM_SANS, mono: SYSTEM_MONO, display: d(650, "-0.03em", "normal", 0.8), css: true },
+    { id: "newsroom", label: "Newsroom", description: "Optical-size text serif headlines with a calm sans. Blogs and magazines.", heading: "Newsreader", body: "Source Sans 3", mono: "IBM Plex Mono", display: d(500, "-0.02em", "italic", 0.94) },
+    { id: "product", label: "Product", description: "Tight Swiss-style grotesk throughout. Developer tools and dashboards.", heading: "Geist", body: "Geist", mono: "Geist Mono", display: d(600, "-0.045em", "normal", 0.82) },
+    { id: "fintech", label: "Fintech", description: "Wide geometric headlines, compact text, clear numerals. Banking and SaaS.", heading: "Sora", body: "Manrope", mono: "JetBrains Mono", display: d(600, "-0.035em", "normal", 0.8) },
+    { id: "boutique", label: "Boutique", description: "Soft, wonky serif over a friendly sans. Spas, food and hospitality.", heading: "Fraunces", body: "Figtree", mono: "DM Mono", display: d(420, "-0.02em", "italic", 0.92) },
+    { id: "luxe", label: "Luxe", description: "Razor-thin Didone with an airy geometric. Fashion and beauty.", heading: "Bodoni Moda", body: "Urbanist", mono: "DM Mono", display: d(500, "-0.015em", "italic", 0.96) },
+    { id: "magazine", label: "Magazine", description: "High-contrast display serif over its sans sibling. Features and lookbooks.", heading: "DM Serif Display", body: "DM Sans", mono: "DM Mono", display: d(400, "-0.015em", "italic", 0.94) },
+    { id: "studio", label: "Studio", description: "Extended avant-garde headlines, precise text, retro mono. Art and culture.", heading: "Syne", body: "Instrument Sans", mono: "Space Mono", display: d(700, "-0.03em", "normal", 0.8) },
+    { id: "bistro", label: "Bistro", description: "Chunky warm serif with a modern sans. Cafes, bakeries, restaurants.", heading: "Young Serif", body: "Plus Jakarta Sans", mono: "JetBrains Mono", display: d(400, "-0.02em", "normal", 0.9) },
+    { id: "friendly", label: "Friendly", description: "Rounded throughout. Education, health and consumer apps.", heading: "Fredoka", body: "Nunito", mono: "DM Mono", display: d(600, "-0.02em", "normal", 0.86) },
+    { id: "poster", label: "Poster", description: "Condensed sports-poster headlines over a sturdy grotesk. Events and transport.", heading: "Barlow Condensed", body: "Archivo", mono: "Martian Mono", display: d(700, "-0.005em", "normal", 1.08) },
+    { id: "bookish", label: "Bookish", description: "Classic Garamond headings with a screen-reading serif. Long reads and archives.", heading: "EB Garamond", body: "Literata", mono: "Fira Code", display: d(500, "-0.01em", "italic", 0.96) },
+    { id: "civic", label: "Civic", description: "Open, sturdy and neutral. Public sector, HR and non-profits.", heading: "Commissioner", body: "Commissioner", mono: "IBM Plex Mono", display: d(620, "-0.025em", "normal", 0.82) },
+];
+/** Find a pairing by id. */
+export function getFontPairing(id, pairings = fontPairings) {
+    return pairings.find((p) => p.id === id);
+}
+/** Display tokens that suit a heading family (used for custom pairings). */
+export function displayTokensFor(heading) {
+    const f = getFont(heading);
+    if (!f)
+        return d(650, "-0.03em", "normal", 0.8);
+    const w = (target) => clampWeight(f, target);
+    switch (f.category) {
+        case "serif":
+            return f.style === "display" ? d(w(400), "-0.01em", "italic", 0.96) : d(w(500), "-0.02em", "italic", 0.94);
+        case "condensed":
+            return d(w(700), "-0.005em", "normal", 1.06);
+        case "display":
+            return d(w(700), "-0.03em", "normal", 0.78);
+        case "rounded":
+            return d(w(600), "-0.02em", "normal", 0.86);
+        case "handwriting":
+            return d(w(600), "0em", "normal", 1);
+        case "mono":
+            return d(w(600), "-0.04em", "normal", 0.74);
+        default:
+            return d(w(620), "-0.035em", "normal", 0.84);
+    }
+}
+function clampWeight(f, target) {
+    const axis = f.axes.find((a) => a.tag === "wght");
+    if (axis)
+        return Math.min(axis.max, Math.max(axis.min, target));
+    return f.weights.reduce((best, x) => (Math.abs(x - target) < Math.abs(best - target) ? x : best), f.weights[0] ?? 400);
+}
+/** Build a pairing from any three families; display tokens follow the heading family. */
+export function createFontPairing(input) {
+    return {
+        id: input.id ?? "custom",
+        label: input.label ?? "Custom",
+        description: input.description ?? `${input.heading} · ${input.body}`,
+        heading: input.heading,
+        body: input.body,
+        mono: input.mono ?? "JetBrains Mono",
+        display: { ...displayTokensFor(input.heading), ...input.display },
+    };
+}
+/** The Google Fonts families a pairing needs (skips raw CSS stacks). */
+export function pairingFamilies(pairing) {
+    const out = [];
+    for (const fam of [pairing.heading, pairing.body, pairing.mono]) {
+        const f = getFont(fam);
+        if (f && !out.some((r) => r.family === f.family))
+            out.push({ family: f.family });
+    }
+    return out;
+}
+/** Stylesheet URL for a pairing, or `null` when it needs no web fonts (System). */
+export function pairingUrl(pairing, options) {
+    const fams = pairingFamilies(pairing);
+    return fams.length ? googleFontsUrl(fams, options) : null;
+}
+export const FONT_PAIRING_VARS = ["--font-ui", "--font-heading", "--font-code", "--display-weight", "--display-tracking", "--display-em", "--display-scale"];
+/** The CSS custom properties a pairing sets, ready for `style` or `setProperty`. */
+export function pairingVars(pairing) {
+    return {
+        "--font-ui": fontStack(pairing.body),
+        "--font-heading": fontStack(pairing.heading),
+        "--font-code": fontStack(pairing.mono),
+        "--display-weight": String(pairing.display.weight),
+        "--display-tracking": pairing.display.tracking,
+        "--display-em": pairing.display.em,
+        "--display-scale": String(pairing.display.scale),
+    };
+}
+/**
+ * Applies a pairing to an element: sets `data-font`, the three family tokens and the display tokens
+ * as inline custom properties, and (by default) loads the families from Google Fonts.
+ * Resolves when the stylesheet has loaded.
+ */
+export function applyFontPairing(el, pairing, options = {}) {
+    const { load = true, ...loadOptions } = options;
+    el.dataset.font = pairing.id;
+    const vars = pairingVars(pairing);
+    for (const k of FONT_PAIRING_VARS)
+        el.style.setProperty(k, vars[k]);
+    return load ? loadGoogleFonts(pairingFamilies(pairing), { document: el.ownerDocument, ...loadOptions }) : Promise.resolve();
+}
+/** Removes the inline pairing tokens so the `[data-font]` CSS preset (if any) applies again. */
+export function clearFontPairing(el) {
+    for (const k of FONT_PAIRING_VARS)
+        el.style.removeProperty(k);
+}
+export function serializeFontPairing(pairing) {
+    return {
+        id: pairing.id,
+        label: pairing.label,
+        heading: pairing.heading,
+        body: pairing.body,
+        mono: pairing.mono,
+        display: pairing.display,
+        css: pairing.css,
+        href: pairingUrl(pairing),
+        key: pairingFamilies(pairing).map((f) => familySpec(f)).join("|"),
+        vars: pairingVars(pairing),
+    };
+}
+/** Reads a stored pairing back (validates the shape; unknown input returns `undefined`). */
+export function parseFontPairing(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const v = value;
+    if (typeof v.id !== "string" || typeof v.heading !== "string" || typeof v.body !== "string")
+        return undefined;
+    const preset = getFontPairing(v.id);
+    if (preset && preset.heading === v.heading && preset.body === v.body && preset.mono === v.mono)
+        return preset;
+    return createFontPairing({ id: v.id, label: v.label ?? "Custom", heading: v.heading, body: v.body, mono: typeof v.mono === "string" ? v.mono : undefined, display: v.display });
+}
+/**
+ * Inline boot script (string) that applies a stored pairing before first paint. Put it in `<head>`.
+ * It reads `localStorage[storageKey][field]` (a `StoredFontPairing`).
+ */
+export function fontBootScript(storageKey = "vamos-theme", field = "fontPairing") {
+    return `try{var s=JSON.parse(localStorage.getItem(${JSON.stringify(storageKey)})||"{}"),p=s[${JSON.stringify(field)}],h=document.documentElement;if(p&&p.id){h.dataset.font=p.id;if(!p.css&&p.vars){for(var k in p.vars)h.style.setProperty(k,p.vars[k]);if(p.href){["https://fonts.googleapis.com","https://fonts.gstatic.com"].forEach(function(o,i){var c=document.createElement("link");c.rel="preconnect";c.href=o;if(i)c.crossOrigin="anonymous";document.head.appendChild(c)});var l=document.createElement("link");l.rel="stylesheet";l.href=p.href;l.setAttribute("blocking","render");l.setAttribute("data-vamos-fonts",p.key||"");l.setAttribute("data-variant","swap||1");document.head.appendChild(l)}}}}catch(e){}`;
+}

package/dist/fonts/provider.d.ts

@@ -0,0 +1,34 @@
+import * as React from "react";
+import { type FontPairing } from "./pairings.js";
+export interface FontPairingContextValue {
+    pairing: FontPairing;
+    setPairing: (pairing: FontPairing | string) => void;
+    pairings: FontPairing[];
+}
+/** The active pairing and a setter. Outside a `FontProvider` it returns the Editorial preset and a no-op setter. */
+export declare function useFontPairing(): FontPairingContextValue;
+export interface FontProviderProps {
+    /** Controlled pairing (object or preset id). */
+    pairing?: FontPairing | string;
+    defaultPairing?: FontPairing | string;
+    onPairingChange?: (pairing: FontPairing) => void;
+    /** Presets offered to `useFontPairing().pairings` and resolvable by id. Default: the 16 built-ins. */
+    pairings?: FontPairing[];
+    /**
+     * `"element"` (default) renders a wrapper `<div>` carrying the tokens, so only its subtree changes;
+     * `"document"` applies the pairing to `<html>`.
+     */
+    scope?: "element" | "document";
+    /** Load the families from Google Fonts. Default `true`. Turn off when you self-host. */
+    load?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Applies a type pairing to its subtree (or the document) and shares it through `useFontPairing()`.
+ *
+ * ```tsx
+ * <FontProvider defaultPairing="boutique"><SitePreview /></FontProvider>
+ * ```
+ */
+export declare function FontProvider({ pairing: pairingProp, defaultPairing, onPairingChange, pairings, scope, load, className, children }: FontProviderProps): React.JSX.Element;

package/dist/fonts/provider.js

@@ -0,0 +1,51 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useControllableState, useIsomorphicLayoutEffect } from "../lib/use-controllable-state.js";
+import { applyFontPairing, clearFontPairing, fontPairings, getFontPairing, pairingFamilies, pairingVars } from "./pairings.js";
+import { loadGoogleFonts } from "./loader.js";
+const FontPairingContext = React.createContext(null);
+/** The active pairing and a setter. Outside a `FontProvider` it returns the Editorial preset and a no-op setter. */
+export function useFontPairing() {
+    return React.useContext(FontPairingContext) ?? { pairing: fontPairings[0], setPairing: () => { }, pairings: fontPairings };
+}
+/**
+ * Applies a type pairing to its subtree (or the document) and shares it through `useFontPairing()`.
+ *
+ * ```tsx
+ * <FontProvider defaultPairing="boutique"><SitePreview /></FontProvider>
+ * ```
+ */
+export function FontProvider({ pairing: pairingProp, defaultPairing = "editorial", onPairingChange, pairings = fontPairings, scope = "element", load = true, className, children }) {
+    const resolve = React.useCallback((p) => (typeof p === "string" ? getFontPairing(p, pairings) : p), [pairings]);
+    const [pairing, setPairingState] = useControllableState({
+        value: resolve(pairingProp),
+        defaultValue: resolve(defaultPairing) ?? pairings[0],
+        onChange: onPairingChange,
+    });
+    const active = pairing ?? pairings[0];
+    const setPairing = React.useCallback((p) => {
+        const next = resolve(p);
+        if (next)
+            setPairingState(next);
+    }, [resolve, setPairingState]);
+    useIsomorphicLayoutEffect(() => {
+        if (scope !== "document" || typeof document === "undefined")
+            return;
+        const el = document.documentElement;
+        const prevFont = el.dataset.font;
+        void applyFontPairing(el, active, { load });
+        return () => {
+            clearFontPairing(el);
+            if (prevFont)
+                el.dataset.font = prevFont;
+        };
+    }, [scope, active, load]);
+    React.useEffect(() => {
+        if (scope === "element" && load)
+            void loadGoogleFonts(pairingFamilies(active));
+    }, [scope, active, load]);
+    const value = React.useMemo(() => ({ pairing: active, setPairing, pairings }), [active, setPairing, pairings]);
+    return (_jsx(FontPairingContext.Provider, { value: value, children: scope === "element" ? (_jsx("div", { "data-font": active.id, "data-slot": "font-provider", style: pairingVars(active), className: cn("font-sans", className), children: children })) : (children) }));
+}

package/dist/form/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/form/index.js

@@ -0,0 +1 @@
+export {};

package/dist/format/core.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @vamos-ui/react/format — React-free formatting core. Works in server components, route
+ * handlers and the browser. Every formatter goes through cached `Intl.*` instances.
+ *
+ * Value rules (X11): a date-only value is a `"YYYY-MM-DD"` string (formatted as a calendar
+ * date, never shifted by a time zone); money is a decimal string (`"1250.50"`) or a number;
+ * the time zone is always explicit (default `"UTC"`, so server and client agree).
+ */
+export type DateInput = Date | number | string;
+export type NumericInput = number | bigint | string;
+export interface FormatterOptions {
+    /** ISO 4217 code used by `currency()` when none is passed. Default `"USD"`. */
+    currency?: string;
+    /** IANA time zone for instants. Default `"UTC"`. Date-only strings ignore it. */
+    timeZone?: string;
+}
+export type DatePreset = "short" | "medium" | "long" | "full" | "datetime" | "datetime-short" | "datetime-seconds" | "month-year" | "weekday";
+export type DurationStyle = "narrow" | "short" | "long";
+export interface CurrencyOptions extends Intl.NumberFormatOptions {
+    currency?: string;
+    /** `"symbol"` (default) | `"narrowSymbol"` | `"code"` | `"name"`. */
+    display?: Intl.NumberFormatOptions["currencyDisplay"];
+}
+export interface BytesOptions {
+    /** Default 1. */
+    maximumFractionDigits?: number;
+    /** Use 1024 steps. Default `false` (1000, SI — what file managers show). */
+    binary?: boolean;
+    unitDisplay?: "short" | "long" | "narrow";
+}
+export interface DurationOptions {
+    /** Unit of the input. Default `"s"`. */
+    unit?: "ms" | "s" | "min" | "h";
+    /** Default: `"narrow"` for English ("2m 47s"), `"short"` elsewhere ("2 dk. 47 sn."). */
+    style?: DurationStyle;
+    /** Max number of parts, largest first. Default 2 ("1h 5m", not "1h 5m 12s"). */
+    maxParts?: number;
+    /** Smallest unit shown. Default `"s"`. */
+    smallest?: "d" | "h" | "min" | "s";
+}
+export interface RelativeOptions {
+    /** Reference time. Default `Date.now()`. */
+    now?: DateInput;
+    style?: Intl.RelativeTimeFormatStyle;
+    /** `"auto"` (default) gives "yesterday"/"dün"; `"always"` gives "1 day ago". */
+    numeric?: Intl.RelativeTimeFormatNumeric;
+}
+export declare const numberFormat: (locale: string, o?: Intl.NumberFormatOptions) => Intl.NumberFormat;
+export declare const dateTimeFormat: (locale: string, o?: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat;
+/** `true` for `"YYYY-MM-DD"` strings. */
+export declare const isDateOnly: (v: unknown) => v is string;
+/** Fraction digits a currency uses (USD/TRY 2, JPY 0, KWD 3). */
+export declare function currencyDigits(currency: string): number;
+/** The kit's formatter. Create one with `createFormatter(locale)`; in client components use `useFormat()`. */
+export interface Formatter {
+    readonly locale: string;
+    readonly currencyCode: string;
+    readonly timeZone: string;
+    /** `1234.5` → "1,234.5" / "1.234,5". Accepts decimal strings exactly ("1250.50"). */
+    number(value: NumericInput, options?: Intl.NumberFormatOptions): string;
+    /** Money. `currency(1250.5)` uses the default currency; `currency(5, "EUR")` or `currency(5, { currency: "EUR" })`. */
+    currency(value: NumericInput, currency?: string | CurrencyOptions, options?: Intl.NumberFormatOptions): string;
+    /** Ratio → percent: `0.124` → "12.4%" / "%12,4". Max 1 fraction digit by default. */
+    percent(value: number, options?: Intl.NumberFormatOptions): string;
+    /** `1234567` → "1.2M" / "1,2 Mn". */
+    compact(value: NumericInput, options?: Intl.NumberFormatOptions): string;
+    /** Bytes → "1.2 MB" / "1,2 MB". */
+    bytes(value: number, options?: BytesOptions): string;
+    /** `167` (seconds) → "2m 47s" / "2 dk. 47 sn.". */
+    duration(value: number, options?: DurationOptions): string;
+    /** Date, instant or `"YYYY-MM-DD"`. Preset name or Intl options. Default `"medium"`. */
+    date(value: DateInput, options?: DatePreset | Intl.DateTimeFormatOptions): string;
+    /** Shorthand for `date(value, "datetime")`. */
+    dateTime(value: DateInput, options?: Intl.DateTimeFormatOptions): string;
+    /** "Nov 8 – 12, 2026" / "8–12 Kas 2026". */
+    dateRange(start: DateInput, end: DateInput, options?: DatePreset | Intl.DateTimeFormatOptions): string;
+    /** Time of an instant, or an `"HH:mm"` string: "9:30 AM" / "09:30". */
+    time(value: DateInput, options?: Intl.DateTimeFormatOptions): string;
+    /** "3 minutes ago", "yesterday", "in 2 weeks". Also the classic `relative(-1, "day")`. */
+    relative(value: DateInput, options?: RelativeOptions): string;
+    relative(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Omit<RelativeOptions, "now">): string;
+    /** "Ada, Grace, and Linus" / "Ada, Grace ve Linus". */
+    list(items: string[], options?: Intl.ListFormatOptions): string;
+    /** Counts with a cap: `count(120)` → "99+". */
+    count(value: number, max?: number): string;
+}
+/**
+ * Creates a formatter bound to a locale, a default currency and a time zone.
+ *
+ * ```ts
+ * const f = createFormatter("tr-TR", { currency: "TRY", timeZone: "Europe/Istanbul" });
+ * f.currency("1250.50"); // "₺1.250,50"
+ * f.date("2026-11-08");  // "8 Kas 2026"
+ * ```
+ */
+export declare function createFormatter(locale?: string, options?: FormatterOptions): Formatter;
+/** Decimal and group separators of a locale: en-US `{ decimal: ".", group: "," }`, tr-TR `{ decimal: ",", group: "." }`. */
+export declare function numberSeparators(locale?: string): {
+    decimal: string;
+    group: string;
+};
+/**
+ * Parses user input into a normalised decimal string (`"-1250.5"`), or `null` when it isn't a number.
+ * Strict about the locale's separators, lenient about what people actually type:
+ *
+ * ```ts
+ * parseDecimal("1.250,50", "tr-TR"); // "1250.50"
+ * parseDecimal("₺1.250", "tr-TR");   // "1250"
+ * parseDecimal("12,5", "tr-TR");     // "12.5"
+ * parseDecimal("1250.75", "tr-TR");  // "1250.75" (single non-locale separator not followed by 3 digits → decimal)
+ * parseDecimal("(42.00)", "en-US");  // "-42.00" (accounting negative)
+ * ```
+ */
+export declare function parseDecimal(input: string, locale?: string): string | null;
+/**
+ * `parseNumber(locale)` returns a parser: `parseNumber("tr-TR")("1.250,5")` → `1250.5`.
+ * Prefer `parseDecimal` for money (no float).
+ */
+export declare function parseNumber(locale?: string): (input: string) => number | null;
+/** `true` for canonical decimal strings: `"12"`, `"-0.5"`, `"1250.50"`. */
+export declare const isDecimalString: (v: unknown) => v is string;
+export type RoundingMode = "half-up" | "half-even" | "down" | "up";
+/** Decimal string → integer minor units at `scale` (`"12.345"`, 2 → `1235n` with half-up). */
+export declare function toMinorUnits(value: string | number, scale?: number, rounding?: RoundingMode): bigint;
+/** Integer minor units → decimal string with exactly `scale` digits (`1235n`, 2 → `"12.35"`). */
+export declare function fromMinorUnits(minor: bigint, scale?: number): string;
+/** Round a decimal string to `scale` digits: `roundDecimal("2.345", 2)` → `"2.35"`. */
+export declare const roundDecimal: (value: string, scale?: number, rounding?: RoundingMode) => string;
+/** Exact sum of decimal strings at `scale` digits. */
+export declare const addDecimal: (values: string[], scale?: number) => string;
+/** `a - b` at `scale` digits. */
+export declare const subtractDecimal: (a: string, b: string, scale?: number) => string;
+/**
+ * `value × factor`, rounded to `scale` (quantity × unit price, VAT rate…). `factor` may be a decimal string.
+ *
+ * ```ts
+ * multiplyDecimal("19.99", "3");    // "59.97"
+ * multiplyDecimal("1250.00", "0.20"); // "250.00"
+ * ```
+ */
+export declare function multiplyDecimal(value: string, factor: string | number, scale?: number, rounding?: RoundingMode): string;
+/** -1, 0 or 1. */
+export declare function compareDecimal(a: string, b: string): -1 | 0 | 1;
+/** Estimated reading time in whole minutes (min 1) for text or a word count. Default 220 wpm. */
+export declare function readingMinutes(textOrWords: string | number, wordsPerMinute?: number): number;
+/** Local calendar date → `"YYYY-MM-DD"` (never `toISOString()`, which shifts the day at UTC+3). */
+export declare function toISODate(d: Date): string;
+/** `"YYYY-MM-DD"` → a local-midnight `Date` (for date pickers). Returns `null` for invalid input. */
+export declare function fromISODate(s: string): Date | null;