@timber-js/app 0.1.1 → 0.1.3

package/src/fonts/ast.ts

@@ -0,0 +1,359 @@
+/**
+ * Acorn-based AST utilities for extracting static font configs from source code.
+ *
+ * Replaces the fragile regex-based extraction in fonts.ts and local.ts.
+ * Uses acorn (already a Vite dependency) for robust parsing that handles
+ * comments, trailing commas, multi-line configs, and other edge cases
+ * the regex approach missed.
+ *
+ * Design doc: 24-fonts.md §"Step 1: Static Analysis"
+ */
+
+import { parse } from 'acorn';
+import type { GoogleFontConfig } from './types.js';
+import type { LocalFontConfig, LocalFontSrc } from './types.js';
+
+// ── AST node types (minimal subset of estree) ────────────────────────────────
+
+interface AstNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface LiteralNode extends AstNode {
+  type: 'Literal';
+  value: string | number | boolean | null;
+}
+
+interface ArrayExpressionNode extends AstNode {
+  type: 'ArrayExpression';
+  elements: AstNode[];
+}
+
+interface ObjectExpressionNode extends AstNode {
+  type: 'ObjectExpression';
+  properties: PropertyNode[];
+}
+
+interface PropertyNode extends AstNode {
+  type: 'Property';
+  key: AstNode & { name?: string; value?: string | number };
+  value: AstNode;
+}
+
+interface IdentifierNode extends AstNode {
+  type: 'Identifier';
+  name: string;
+}
+
+// ── Core AST extraction helpers ──────────────────────────────────────────────
+
+/**
+ * Parse a JavaScript expression string into an AST node.
+ *
+ * Wraps the expression in parens so acorn treats it as an expression statement.
+ * Returns null if parsing fails.
+ */
+function parseExpression(source: string): AstNode | null {
+  try {
+    const ast = parse(`(${source})`, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    }) as unknown as { body: Array<{ expression: AstNode }> };
+    return ast.body[0]?.expression ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract a static string value from an AST node.
+ * Returns undefined if the node is not a string literal.
+ */
+function extractString(node: AstNode): string | undefined {
+  if (node.type === 'Literal' && typeof (node as LiteralNode).value === 'string') {
+    return (node as LiteralNode).value as string;
+  }
+  return undefined;
+}
+
+/**
+ * Extract a static boolean value from an AST node.
+ * Returns undefined if the node is not a boolean literal.
+ */
+function extractBoolean(node: AstNode): boolean | undefined {
+  if (node.type === 'Literal' && typeof (node as LiteralNode).value === 'boolean') {
+    return (node as LiteralNode).value as boolean;
+  }
+  return undefined;
+}
+
+/**
+ * Extract a string array from an AST ArrayExpression node.
+ * Returns undefined if any element is not a string literal.
+ */
+function extractStringArray(node: AstNode): string[] | undefined {
+  if (node.type !== 'ArrayExpression') return undefined;
+  const arr = node as ArrayExpressionNode;
+  const result: string[] = [];
+  for (const elem of arr.elements) {
+    const s = extractString(elem);
+    if (s === undefined) return undefined;
+    result.push(s);
+  }
+  return result;
+}
+
+/**
+ * Get the key name from a Property node.
+ */
+function getPropertyKey(prop: PropertyNode): string | undefined {
+  if (prop.key.type === 'Identifier') {
+    return (prop.key as IdentifierNode).name;
+  }
+  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') {
+    return prop.key.value;
+  }
+  return undefined;
+}
+
+/**
+ * Build a map of property name → value node from an ObjectExpression.
+ */
+function objectProperties(node: ObjectExpressionNode): Map<string, AstNode> {
+  const map = new Map<string, AstNode>();
+  for (const prop of node.properties) {
+    // Skip spread elements or computed keys
+    if (prop.type !== 'Property') continue;
+    const key = getPropertyKey(prop);
+    if (key) map.set(key, prop.value);
+  }
+  return map;
+}
+
+// ── Google font config extraction ────────────────────────────────────────────
+
+/**
+ * Extract a GoogleFontConfig from the source text of a font function call's
+ * object argument.
+ *
+ * The `callSource` should be the text of the call's argument list including
+ * parens, e.g. `({ subsets: ['latin'], weight: '400' })`.
+ *
+ * Returns null if parsing or extraction fails.
+ */
+export function extractFontConfigAst(callSource: string): GoogleFontConfig | null {
+  const node = parseExpression(callSource);
+  if (!node || node.type !== 'ObjectExpression') return null;
+
+  const props = objectProperties(node as ObjectExpressionNode);
+  const config: GoogleFontConfig = {};
+
+  // subsets: string[]
+  const subsetsNode = props.get('subsets');
+  if (subsetsNode) {
+    const arr = extractStringArray(subsetsNode);
+    if (arr) config.subsets = arr;
+  }
+
+  // weight: string | string[]
+  const weightNode = props.get('weight');
+  if (weightNode) {
+    const arr = extractStringArray(weightNode);
+    if (arr) {
+      config.weight = arr;
+    } else {
+      const s = extractString(weightNode);
+      if (s !== undefined) config.weight = s;
+    }
+  }
+
+  // display: string
+  const displayNode = props.get('display');
+  if (displayNode) {
+    const s = extractString(displayNode);
+    if (s !== undefined) config.display = s as GoogleFontConfig['display'];
+  }
+
+  // variable: string
+  const variableNode = props.get('variable');
+  if (variableNode) {
+    const s = extractString(variableNode);
+    if (s !== undefined) config.variable = s;
+  }
+
+  // style: string | string[]
+  const styleNode = props.get('style');
+  if (styleNode) {
+    const arr = extractStringArray(styleNode);
+    if (arr) {
+      config.style = arr;
+    } else {
+      const s = extractString(styleNode);
+      if (s !== undefined) config.style = s;
+    }
+  }
+
+  // preload: boolean
+  const preloadNode = props.get('preload');
+  if (preloadNode) {
+    const b = extractBoolean(preloadNode);
+    if (b !== undefined) config.preload = b;
+  }
+
+  return config;
+}
+
+// ── Local font config extraction ─────────────────────────────────────────────
+
+/**
+ * Extract a single LocalFontSrc entry from an ObjectExpression AST node.
+ */
+function extractLocalFontSrcEntry(node: AstNode): LocalFontSrc | null {
+  if (node.type !== 'ObjectExpression') return null;
+  const props = objectProperties(node as ObjectExpressionNode);
+
+  const pathNode = props.get('path');
+  if (!pathNode) return null;
+  const path = extractString(pathNode);
+  if (path === undefined) return null;
+
+  const entry: LocalFontSrc = { path };
+
+  const weightNode = props.get('weight');
+  if (weightNode) {
+    const w = extractString(weightNode);
+    if (w !== undefined) entry.weight = w;
+  }
+
+  const styleNode = props.get('style');
+  if (styleNode) {
+    const s = extractString(styleNode);
+    if (s !== undefined) entry.style = s;
+  }
+
+  return entry;
+}
+
+/**
+ * Extract a LocalFontConfig from the source text of a localFont() call's
+ * object argument.
+ *
+ * Returns null if parsing or extraction fails.
+ */
+export function extractLocalFontConfigAst(callSource: string): LocalFontConfig | null {
+  const node = parseExpression(callSource);
+  if (!node || node.type !== 'ObjectExpression') return null;
+
+  const props = objectProperties(node as ObjectExpressionNode);
+
+  // display: string
+  const displayNode = props.get('display');
+  const display = displayNode
+    ? (extractString(displayNode) as LocalFontConfig['display'])
+    : undefined;
+
+  // variable: string
+  const variableNode = props.get('variable');
+  const variable = variableNode ? extractString(variableNode) : undefined;
+
+  // family: string
+  const familyNode = props.get('family');
+  const family = familyNode ? extractString(familyNode) : undefined;
+
+  // src: string | LocalFontSrc[]
+  const srcNode = props.get('src');
+  if (!srcNode) return null;
+
+  // String form: src: './fonts/MyFont.woff2'
+  const srcString = extractString(srcNode);
+  if (srcString !== undefined) {
+    return { src: srcString, display, variable, family };
+  }
+
+  // Array form: src: [{ path: '...', weight: '...' }, ...]
+  if (srcNode.type === 'ArrayExpression') {
+    const arr = srcNode as ArrayExpressionNode;
+    const entries: LocalFontSrc[] = [];
+    for (const elem of arr.elements) {
+      const entry = extractLocalFontSrcEntry(elem);
+      if (!entry) return null;
+      entries.push(entry);
+    }
+    if (entries.length === 0) return null;
+    return { src: entries, display, variable, family };
+  }
+
+  return null;
+}
+
+// ── Dynamic call detection ───────────────────────────────────────────────────
+
+/**
+ * Detect if source code contains dynamic/computed font function calls
+ * that cannot be statically analyzed.
+ *
+ * Uses acorn to parse the full source and inspect CallExpression nodes.
+ * Returns the offending expression string if found, null if all calls are static.
+ */
+export function detectDynamicFontCallAst(source: string, importedNames: string[]): string | null {
+  if (importedNames.length === 0) return null;
+
+  let ast;
+  try {
+    ast = parse(source, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    }) as unknown as { body: AstNode[] };
+  } catch {
+    // If we can't parse the source at all, fall back to no detection
+    return null;
+  }
+
+  const nameSet = new Set(importedNames);
+  const result = walkForDynamicCalls(ast as unknown as AstNode, nameSet, source);
+  return result;
+}
+
+/**
+ * Recursively walk the AST looking for CallExpression nodes where
+ * the callee is one of the imported font names and the first argument
+ * is not an ObjectExpression (i.e. it's dynamic).
+ */
+function walkForDynamicCalls(node: AstNode, names: Set<string>, source: string): string | null {
+  if (!node || typeof node !== 'object') return null;
+
+  if (node.type === 'CallExpression') {
+    const callee = node.callee as AstNode;
+    if (callee.type === 'Identifier' && names.has((callee as IdentifierNode).name)) {
+      const args = node.arguments as AstNode[];
+      if (args.length > 0 && args[0].type !== 'ObjectExpression') {
+        // Extract the argument source text
+        const argStart = (args[0] as AstNode & { start: number }).start;
+        const argEnd = (args[0] as AstNode & { end: number }).end;
+        const argText = source.slice(argStart, argEnd);
+        const calleeName = (callee as IdentifierNode).name;
+        return `${calleeName}(${argText})`;
+      }
+    }
+  }
+
+  // Walk all child properties
+  for (const key of Object.keys(node)) {
+    if (key === 'type') continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (item && typeof item === 'object' && (item as AstNode).type) {
+          const result = walkForDynamicCalls(item as AstNode, names, source);
+          if (result) return result;
+        }
+      }
+    } else if (child && typeof child === 'object' && (child as AstNode).type) {
+      const result = walkForDynamicCalls(child as AstNode, names, source);
+      if (result) return result;
+    }
+  }
+
+  return null;
+}

package/src/fonts/css.ts

@@ -0,0 +1,68 @@
+/**
+ * @font-face CSS generation.
+ *
+ * Generates CSS strings from font face descriptors. Used by both
+ * Google and local font providers.
+ *
+ * Design doc: 24-fonts.md §"Step 3: @font-face Generation"
+ */
+
+import type { FontFaceDescriptor } from './types.js';
+
+/**
+ * Generate a single `@font-face` CSS rule from a descriptor.
+ */
+export function generateFontFace(desc: FontFaceDescriptor): string {
+  const lines: string[] = [];
+  lines.push('@font-face {');
+  lines.push(`  font-family: '${desc.family}';`);
+  lines.push(`  src: ${desc.src};`);
+  if (desc.weight) lines.push(`  font-weight: ${desc.weight};`);
+  if (desc.style) lines.push(`  font-style: ${desc.style};`);
+  if (desc.display) lines.push(`  font-display: ${desc.display};`);
+  if (desc.unicodeRange) lines.push(`  unicode-range: ${desc.unicodeRange};`);
+  lines.push('}');
+  return lines.join('\n');
+}
+
+/**
+ * Generate multiple `@font-face` rules from an array of descriptors.
+ */
+export function generateFontFaces(descriptors: FontFaceDescriptor[]): string {
+  return descriptors.map(generateFontFace).join('\n\n');
+}
+
+/**
+ * Generate a scoped CSS class that sets a CSS custom property for the font.
+ *
+ * Example output:
+ * ```css
+ * .timber-font-inter {
+ *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ * }
+ * ```
+ */
+export function generateVariableClass(
+  className: string,
+  variable: string,
+  fontFamily: string
+): string {
+  return `.${className} {\n  ${variable}: ${fontFamily};\n}`;
+}
+
+/**
+ * Generate a scoped CSS class that applies font-family directly.
+ *
+ * Used when no `variable` is specified — the className applies
+ * the font-family inline instead of through a CSS custom property.
+ *
+ * Example output:
+ * ```css
+ * .timber-font-inter {
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ * }
+ * ```
+ */
+export function generateFontFamilyClass(className: string, fontFamily: string): string {
+  return `.${className} {\n  font-family: ${fontFamily};\n}`;
+}

package/src/fonts/fallbacks.ts

@@ -0,0 +1,248 @@
+/**
+ * Size-adjusted fallback font generation.
+ *
+ * Generates `@font-face` declarations for fallback fonts with
+ * `size-adjust`, `ascent-override`, `descent-override`, and
+ * `line-gap-override` to match custom font metrics and eliminate CLS.
+ *
+ * Design doc: 24-fonts.md §"Step 4: Size-Adjusted Fallbacks"
+ */
+
+import type { FontFaceDescriptor } from './types.js';
+
+/**
+ * Font metrics for size-adjusted fallback calculation.
+ *
+ * Values are percentages used in CSS override descriptors.
+ */
+interface FallbackMetrics {
+  /** The local() system font to use as base. */
+  fallbackFont: string;
+  /** size-adjust percentage (e.g. 107.64). */
+  sizeAdjust: number;
+  /** ascent-override percentage (e.g. 90.49). */
+  ascentOverride: number;
+  /** descent-override percentage (e.g. 22.48). */
+  descentOverride: number;
+  /** line-gap-override percentage (e.g. 0). */
+  lineGapOverride: number;
+}
+
+/**
+ * Lookup table for commonly used Google Fonts.
+ *
+ * Metrics sourced from fontaine / @capsizecss/metrics.
+ * Keyed by lowercase font family name.
+ */
+const FALLBACK_METRICS: Record<string, FallbackMetrics> = {
+  'inter': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 107.64,
+    ascentOverride: 90.49,
+    descentOverride: 22.48,
+    lineGapOverride: 0,
+  },
+  'roboto': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 100.3,
+    ascentOverride: 92.77,
+    descentOverride: 24.41,
+    lineGapOverride: 0,
+  },
+  'open sans': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 105.48,
+    ascentOverride: 101.03,
+    descentOverride: 27.47,
+    lineGapOverride: 0,
+  },
+  'lato': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 112.5,
+    ascentOverride: 100.22,
+    descentOverride: 21.16,
+    lineGapOverride: 0,
+  },
+  'montserrat': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 112.17,
+    ascentOverride: 85.13,
+    descentOverride: 22.07,
+    lineGapOverride: 0,
+  },
+  'poppins': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 112.76,
+    ascentOverride: 96.31,
+    descentOverride: 32.1,
+    lineGapOverride: 0,
+  },
+  'roboto mono': {
+    fallbackFont: 'Courier New',
+    sizeAdjust: 109.29,
+    ascentOverride: 87.79,
+    descentOverride: 23.1,
+    lineGapOverride: 0,
+  },
+  'jetbrains mono': {
+    fallbackFont: 'Courier New',
+    sizeAdjust: 112.7,
+    ascentOverride: 89.53,
+    descentOverride: 24.21,
+    lineGapOverride: 0,
+  },
+  'source code pro': {
+    fallbackFont: 'Courier New',
+    sizeAdjust: 106.13,
+    ascentOverride: 93.47,
+    descentOverride: 26.01,
+    lineGapOverride: 0,
+  },
+  'fira code': {
+    fallbackFont: 'Courier New',
+    sizeAdjust: 112.96,
+    ascentOverride: 86.87,
+    descentOverride: 26.34,
+    lineGapOverride: 0,
+  },
+  'nunito': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 103.62,
+    ascentOverride: 99.45,
+    descentOverride: 34.8,
+    lineGapOverride: 0,
+  },
+  'playfair display': {
+    fallbackFont: 'Georgia',
+    sizeAdjust: 110.72,
+    ascentOverride: 84.44,
+    descentOverride: 23.56,
+    lineGapOverride: 0,
+  },
+  'merriweather': {
+    fallbackFont: 'Georgia',
+    sizeAdjust: 107.66,
+    ascentOverride: 91.93,
+    descentOverride: 27.6,
+    lineGapOverride: 0,
+  },
+  'raleway': {
+    fallbackFont: 'Arial',
+    sizeAdjust: 107.74,
+    ascentOverride: 94.19,
+    descentOverride: 26.76,
+    lineGapOverride: 0,
+  },
+};
+
+/**
+ * Known serif font families (lowercase).
+ * Used for generic family detection when the name doesn't contain "serif".
+ */
+const SERIF_FAMILIES = new Set([
+  'playfair display',
+  'merriweather',
+  'lora',
+  'georgia',
+  'garamond',
+  'eb garamond',
+  'crimson text',
+  'libre baskerville',
+  'source serif pro',
+  'source serif 4',
+  'dm serif display',
+  'dm serif text',
+  'noto serif',
+  'pt serif',
+  'bitter',
+  'domine',
+  'cormorant',
+  'cormorant garamond',
+]);
+
+export function getGenericFamily(family: string): string {
+  const lc = family.toLowerCase();
+  if (lc.includes('mono') || lc.includes('code')) return 'monospace';
+  if ((lc.includes('serif') && !lc.includes('sans')) || SERIF_FAMILIES.has(lc)) {
+    return 'serif';
+  }
+  return 'sans-serif';
+}
+
+/**
+ * Generate a size-adjusted fallback @font-face for a given font family.
+ *
+ * Returns null if no metrics are available (unknown font — no fallback generated).
+ */
+export function generateFallbackFontFace(family: string): FontFaceDescriptor | null {
+  const metrics = FALLBACK_METRICS[family.toLowerCase()];
+  if (!metrics) return null;
+
+  const fallbackFamily = `${family} Fallback`;
+
+  return {
+    family: fallbackFamily,
+    src: `local('${metrics.fallbackFont}')`,
+    // Encode the metrics into a CSS descriptor string.
+    // We abuse the 'style' field to carry the override properties
+    // since FontFaceDescriptor doesn't have dedicated fields.
+    // The generateFallbackCss function handles this specially.
+  };
+}
+
+/**
+ * Generate the full CSS for a size-adjusted fallback font.
+ *
+ * This produces a complete @font-face block with override descriptors
+ * that FontFaceDescriptor doesn't natively support.
+ */
+export function generateFallbackCss(family: string): string | null {
+  const metrics = FALLBACK_METRICS[family.toLowerCase()];
+  if (!metrics) return null;
+
+  const fallbackFamily = `${family} Fallback`;
+
+  const lines = [
+    '@font-face {',
+    `  font-family: '${fallbackFamily}';`,
+    `  src: local('${metrics.fallbackFont}');`,
+    `  size-adjust: ${metrics.sizeAdjust}%;`,
+    `  ascent-override: ${metrics.ascentOverride}%;`,
+    `  descent-override: ${metrics.descentOverride}%;`,
+    `  line-gap-override: ${metrics.lineGapOverride}%;`,
+    '}',
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Check whether fallback metrics are available for a font family.
+ */
+export function hasFallbackMetrics(family: string): boolean {
+  return family.toLowerCase() in FALLBACK_METRICS;
+}
+
+/**
+ * Build the full font stack string for a font, including its
+ * size-adjusted fallback and a generic family.
+ *
+ * Example: `'Inter', 'Inter Fallback', system-ui, sans-serif`
+ */
+export function buildFontStack(family: string): string {
+  const generic = getGenericFamily(family);
+  const hasMetrics = hasFallbackMetrics(family);
+
+  const parts = [`'${family}'`];
+  if (hasMetrics) parts.push(`'${family} Fallback'`);
+
+  // Add system-ui for sans-serif fonts, ui-monospace for mono
+  if (generic === 'monospace') {
+    parts.push('ui-monospace');
+  } else if (generic === 'sans-serif') {
+    parts.push('system-ui');
+  }
+  parts.push(generic);
+
+  return parts.join(', ');
+}