@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/fonts/virtual-modules.ts

@@ -0,0 +1,159 @@
+/**
+ * Virtual module source generators for the timber-fonts plugin.
+ *
+ * The plugin exposes three virtual modules:
+ *
+ * - `@timber/fonts/google` — exports Google font loader functions. The
+ *   transform hook replaces actual call sites with static `FontResult`
+ *   objects, so this module is only loaded as a fallback (e.g. when the
+ *   transform hook hasn't run yet, or when an unknown font is referenced
+ *   via the default export proxy).
+ * - `@timber/fonts/local` — exports `localFont()` as a fallback default.
+ * - `virtual:timber-font-css-register` — side-effect module that sets the
+ *   combined `@font-face` CSS on `globalThis.__timber_font_css`. The RSC
+ *   entry reads this at render time to inline a `<style>` tag.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import type { ExtractedFont, FontFaceDescriptor } from './types.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from './css.js';
+import { generateFallbackCss } from './fallbacks.js';
+import { generateLocalFontFaces } from './local.js';
+
+export const VIRTUAL_GOOGLE = '@timber/fonts/google';
+export const VIRTUAL_LOCAL = '@timber/fonts/local';
+export const RESOLVED_GOOGLE = '\0@timber/fonts/google';
+export const RESOLVED_LOCAL = '\0@timber/fonts/local';
+
+export const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
+export const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
+
+/**
+ * Convert a font family name to a PascalCase export name.
+ * e.g. "JetBrains Mono" → "JetBrains_Mono"
+ */
+function familyToExportName(family: string): string {
+  return family.replace(/\s+/g, '_');
+}
+
+/**
+ * Generate the virtual module source for `@timber/fonts/google`.
+ *
+ * The transform hook replaces real call sites at build time, so this
+ * module only matters as a runtime fallback. We export a Proxy default
+ * that handles any font name plus named exports for known families
+ * (for tree-shaking).
+ */
+export function generateGoogleVirtualModule(fonts: Iterable<ExtractedFont>): string {
+  const families = new Set<string>();
+  for (const font of fonts) {
+    if (font.provider === 'google') families.add(font.family);
+  }
+
+  const lines = [
+    '// Auto-generated virtual module: @timber/fonts/google',
+    '// Each export is a font loader function that returns a FontResult.',
+    '',
+    'function createFontResult(family, config) {',
+    '  return {',
+    '    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,',
+    '    style: { fontFamily: family },',
+    '    variable: config?.variable,',
+    '  };',
+    '}',
+    '',
+    'export default new Proxy({}, {',
+    '  get(_, prop) {',
+    '    if (typeof prop === "string") {',
+    '      return (config) => createFontResult(prop.replace(/_/g, " "), config);',
+    '    }',
+    '  }',
+    '});',
+  ];
+
+  for (const family of families) {
+    const exportName = familyToExportName(family);
+    lines.push('');
+    lines.push(`export function ${exportName}(config) {`);
+    lines.push(`  return createFontResult('${family}', config);`);
+    lines.push('}');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate the virtual module source for `@timber/fonts/local`.
+ *
+ * Like the google virtual module, this is a runtime fallback. The
+ * transform hook normally replaces `localFont(...)` calls with static
+ * `FontResult` objects at build time.
+ */
+export function generateLocalVirtualModule(): string {
+  return [
+    '// Auto-generated virtual module: @timber/fonts/local',
+    '',
+    'export default function localFont(config) {',
+    '  const family = config?.family || "Local Font";',
+    '  return {',
+    '    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,',
+    '    style: { fontFamily: family },',
+    '    variable: config?.variable,',
+    '  };',
+    '}',
+  ].join('\n');
+}
+
+/**
+ * Generate combined CSS for a single extracted font.
+ *
+ * Includes `@font-face` rules (local or Google), the size-adjusted fallback
+ * `@font-face`, and the scoped class rule. For Google fonts the resolved
+ * `FontFaceDescriptor[]` must be passed in (from `generateProductionFontFaces`
+ * in production or `resolveDevFontFaces` in dev).
+ */
+export function generateFontCss(font: ExtractedFont, googleFaces?: FontFaceDescriptor[]): string {
+  const cssParts: string[] = [];
+
+  if (font.provider === 'local' && font.localSources) {
+    const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  if (font.provider === 'google' && googleFaces && googleFaces.length > 0) {
+    const faceCss = generateFontFaces(googleFaces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(font.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (font.variable) {
+    cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}
+
+/**
+ * Generate the CSS output for all extracted fonts.
+ *
+ * Includes `@font-face` rules for local and Google fonts, fallback rules,
+ * and scoped classes. `googleFontFacesMap` provides pre-resolved
+ * `FontFaceDescriptor[]` for each Google font (keyed by `ExtractedFont.id`).
+ */
+export function generateAllFontCss(
+  registry: Map<string, ExtractedFont>,
+  googleFontFacesMap?: Map<string, FontFaceDescriptor[]>
+): string {
+  const cssParts: string[] = [];
+  for (const font of registry.values()) {
+    const googleFaces = googleFontFacesMap?.get(font.id);
+    cssParts.push(generateFontCss(font, googleFaces));
+  }
+  return cssParts.join('\n\n');
+}