@timber-js/app 0.2.0-alpha.87 → 0.2.0-alpha.89

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');
+}

package/src/plugins/entries.ts

@@ -98,6 +98,38 @@ function stripRootPrefix(id: string, root: string): string {
  *
  * Serializes output mode and feature flags for runtime consumption.
  */
+/**
+ * Extract the JSON-serializable subset of `forms` config.
+ *
+ * Drops function-valued `stripSensitiveFields` with a build-time warning —
+ * functions cannot cross the JSON boundary to the runtime, so users must
+ * configure function predicates per-action via `createActionClient` instead.
+ */
+function serializeFormsConfig(
+  forms: { stripSensitiveFields?: unknown } | undefined
+): { stripSensitiveFields?: boolean | readonly string[] } | undefined {
+  if (!forms) return undefined;
+  const opt = forms.stripSensitiveFields;
+  if (opt === undefined) return {};
+  if (typeof opt === 'boolean') return { stripSensitiveFields: opt };
+  if (Array.isArray(opt)) {
+    // Coerce to a string array and drop any non-string entries.
+    const names = opt.filter((v): v is string => typeof v === 'string');
+    return { stripSensitiveFields: names };
+  }
+  if (typeof opt === 'function') {
+    console.warn(
+      '[timber] forms.stripSensitiveFields was set to a function in timber.config.ts — ' +
+        'this is not supported at the global level (functions cannot be serialized ' +
+        'into the runtime config). Use a per-action override via ' +
+        '`createActionClient({ stripSensitiveFields: (name) => ... })` instead. ' +
+        'The built-in deny-list will be used globally.'
+    );
+    return {};
+  }
+  return {};
+}
+
 function generateConfigModule(ctx: PluginContext): string {
   const runtimeConfig = {
     output: ctx.config.output ?? 'server',
@@ -114,6 +146,11 @@ function generateConfigModule(ctx: PluginContext): string {
     // Auto-generated sitemap config — opt-in via timber.config.ts.
     // See design/16-metadata.md §"Auto-generated Sitemap"
     sitemap: ctx.config.sitemap,
+    // Forms config — only the serializable subset. `stripSensitiveFields`
+    // accepts boolean | string[] at the global level. Functions must be
+    // configured per-action via `createActionClient({ stripSensitiveFields })`
+    // because JSON.stringify would silently drop them here. See TIM-816.
+    forms: serializeFormsConfig(ctx.config.forms),
     // Per-build deployment ID for version skew detection (TIM-446).
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,