@bendyline/squisq 1.2.2 → 1.4.0

package/src/schemas/fontStacks.ts

@@ -0,0 +1,257 @@
+/**
+ * Font Stacks
+ *
+ * Curated registry of font families used by built-in themes and offered in
+ * the theme customizer. Each stack has a stable `id` (referenced by JSON
+ * theme files via `{ stackId }`) and a CSS `family` string that resolves
+ * to the actual font when rendered.
+ *
+ * Themes never carry raw CSS font strings — they reference a `stackId` or
+ * specify a `{ custom: { name, fallback } }` form, both of which resolve
+ * here at render time.
+ */
+
+import type { FontFamily, FontFamilyKind } from './Theme.js';
+
+export interface FontStack {
+  /** Stable identifier referenced by Theme JSON. */
+  id: string;
+  /** Display label for pickers. */
+  label: string;
+  /** Full CSS font-family string with safe fallbacks. */
+  family: string;
+  /** Categorical bucket for the picker UI. */
+  kind: FontFamilyKind;
+  /**
+   * Google Fonts family name, when this stack is served by Google Fonts.
+   * Used by exports that bundle a `<link>` to fonts.googleapis.com so the
+   * face renders correctly even when the host page doesn't preload it.
+   * Omit (or set to undefined) for purely system stacks.
+   */
+  googleFontFamily?: string;
+}
+
+/** All curated stacks, in the order they should appear in pickers. */
+export const AVAILABLE_FONT_STACKS: FontStack[] = [
+  // System defaults
+  {
+    id: 'system-sans',
+    label: 'System Sans',
+    family: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+  },
+  {
+    id: 'system-serif',
+    label: 'System Serif',
+    family: 'Georgia, "Times New Roman", serif',
+    kind: 'serif',
+  },
+  {
+    id: 'system-mono',
+    label: 'System Mono',
+    family: 'Consolas, "Courier New", monospace',
+    kind: 'mono',
+  },
+  // Curated Google Fonts. `googleFontFamily` is the canonical family
+  // name Google serves the face under (used by exports that emit a
+  // `<link rel="stylesheet" href="https://fonts.googleapis.com/...">`
+  // so the face renders even when the host doesn't preload it).
+  {
+    id: 'inter',
+    label: 'Inter',
+    family: '"Inter", "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'Inter',
+  },
+  {
+    id: 'ibm-plex-sans',
+    label: 'IBM Plex Sans',
+    family: '"IBM Plex Sans", "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'IBM Plex Sans',
+  },
+  {
+    id: 'roboto',
+    label: 'Roboto',
+    family: '"Roboto", "Segoe UI", Arial, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'Roboto',
+  },
+  {
+    id: 'dm-sans',
+    label: 'DM Sans',
+    family: '"DM Sans", "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'DM Sans',
+  },
+  {
+    id: 'oswald',
+    label: 'Oswald',
+    family: '"Oswald", Impact, "Arial Black", sans-serif',
+    kind: 'display',
+    googleFontFamily: 'Oswald',
+  },
+  {
+    id: 'playfair',
+    label: 'Playfair Display',
+    family: '"Playfair Display", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Playfair Display',
+  },
+  {
+    id: 'source-serif',
+    label: 'Source Serif',
+    family: '"Source Serif 4", "PT Serif", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Source Serif 4',
+  },
+  {
+    id: 'merriweather',
+    label: 'Merriweather',
+    family: '"Merriweather", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Merriweather',
+  },
+  {
+    id: 'lora',
+    label: 'Lora',
+    family: '"Lora", "Merriweather", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Lora',
+  },
+  {
+    id: 'pt-serif',
+    label: 'PT Serif',
+    family: '"PT Serif", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'PT Serif',
+  },
+  {
+    id: 'crimson',
+    label: 'Crimson Text',
+    family: '"Crimson Text", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Crimson Text',
+  },
+  {
+    id: 'cormorant',
+    label: 'Cormorant Garamond',
+    family: '"Cormorant Garamond", Garamond, Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Cormorant Garamond',
+  },
+  {
+    id: 'dm-serif',
+    label: 'DM Serif Display',
+    family: '"DM Serif Display", Georgia, serif',
+    kind: 'display',
+    googleFontFamily: 'DM Serif Display',
+  },
+  {
+    id: 'jetbrains-mono',
+    label: 'JetBrains Mono',
+    family: '"JetBrains Mono", "Fira Code", Consolas, monospace',
+    kind: 'mono',
+    googleFontFamily: 'JetBrains Mono',
+  },
+  // Themed system stacks with emoji fallbacks (used by gezellig)
+  {
+    id: 'system-sans-emoji',
+    label: 'System Sans + Emoji',
+    family:
+      'system-ui, -apple-system, "Segoe UI", Roboto, "OpenMoji Color", "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif',
+    kind: 'sans',
+  },
+  {
+    id: 'system-serif-emoji',
+    label: 'System Serif + Emoji',
+    family:
+      'Georgia, "Times New Roman", "OpenMoji Color", "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", serif',
+    kind: 'serif',
+  },
+];
+
+const STACKS_BY_ID: Record<string, FontStack> = Object.fromEntries(
+  AVAILABLE_FONT_STACKS.map((s) => [s.id, s]),
+);
+
+/** Look up a stack by id. Returns undefined if not registered. */
+export function getFontStack(id: string): FontStack | undefined {
+  return STACKS_BY_ID[id];
+}
+
+/** Default fallback CSS family per kind, used when a custom font has no fallback specified. */
+const FALLBACK_BY_KIND: Record<FontFamilyKind, string> = {
+  sans: 'system-ui, sans-serif',
+  serif: 'Georgia, serif',
+  mono: 'Consolas, monospace',
+  display: 'Impact, Arial, sans-serif',
+};
+
+/**
+ * Resolve a `FontFamily` reference (or legacy raw string) to a CSS family string.
+ * Used by `getThemeFont` at render time. Never returns an empty string —
+ * unrecognized stackIds fall back to the requested role's default.
+ */
+export function resolveFontFamily(
+  family: FontFamily | string | undefined,
+  roleFallback: string,
+): string {
+  if (!family) return roleFallback;
+  if (typeof family === 'string') return family;
+  if ('stackId' in family) {
+    const stack = STACKS_BY_ID[family.stackId];
+    return stack ? stack.family : roleFallback;
+  }
+  if ('custom' in family) {
+    const { name, fallback } = family.custom;
+    const fb =
+      fallback === 'system-ui'
+        ? 'system-ui, sans-serif'
+        : fallback === 'serif'
+          ? 'Georgia, serif'
+          : fallback === 'monospace'
+            ? 'Consolas, monospace'
+            : 'system-ui, sans-serif';
+    const safeName = name.includes(' ') || name.includes(',') ? `"${name}"` : name;
+    return `${safeName}, ${fb}`;
+  }
+  return roleFallback;
+}
+
+/** Convenience: quick `{ stackId }` factory for code that constructs themes. */
+export function fontStack(id: string): FontFamily {
+  return { stackId: id };
+}
+
+/**
+ * Build a `https://fonts.googleapis.com/css2?...` URL that loads the
+ * subset of supplied `FontFamily` references that are served by Google
+ * Fonts. Returns `null` when nothing in the list needs Google hosting
+ * (system stacks, custom fonts, or unknown stack ids) — callers can use
+ * that to skip emitting a `<link>` entirely.
+ *
+ * The URL requests regular + bold (400/700) for each family, which is
+ * what the templates use. `display=swap` keeps the fallback visible
+ * while the web font streams in.
+ */
+export function buildGoogleFontsUrl(families: Array<FontFamily | undefined>): string | null {
+  const names = new Set<string>();
+  for (const f of families) {
+    if (!f || typeof f === 'string') continue;
+    if ('stackId' in f) {
+      const stack = STACKS_BY_ID[f.stackId];
+      if (stack?.googleFontFamily) names.add(stack.googleFontFamily);
+    }
+  }
+  if (names.size === 0) return null;
+  // css2 syntax: ?family=Name+With+Spaces:wght@400;700&family=Other:wght@400;700&display=swap
+  const params = Array.from(names)
+    .sort()
+    .map((name) => `family=${encodeURIComponent(name).replace(/%20/g, '+')}:wght@400;700`)
+    .join('&');
+  return `https://fonts.googleapis.com/css2?${params}&display=swap`;
+}
+
+/** Default fallback families exposed for tools that need them. */
+export const FONT_FALLBACKS = FALLBACK_BY_KIND;

package/src/schemas/index.ts

@@ -3,6 +3,10 @@ export * from './Doc.js';
 export * from './BlockTemplates.js';
 export * from './Theme.js';
 export * from './themeLibrary.js';
+export * from './themeValidator.js';
+export * from './themeCompile.js';
+export * from './fontStacks.js';
+export * from './colorUtils.js';
 export * from './Viewport.js';
 export {
   getLayoutHints,
@@ -12,3 +16,11 @@ export {
 } from './LayoutStrategy.js';
 export type { LayoutHints } from './LayoutStrategy.js';
 export type { MediaProvider, MediaEntry } from './MediaProvider.js';
+export type {
+  ImageEditDoc,
+  ImageEditLayer,
+  ImageEditLayerKind,
+  ImageEditCanvas,
+  ImageEditMeta,
+  EditorLayerMeta,
+} from './ImageEditDoc.js';

package/src/schemas/themeCompile.ts

@@ -0,0 +1,203 @@
+/**
+ * Theme Compilation
+ *
+ * Turns a partial Theme (typically authored by the customizer panel from
+ * a few seed colors and preset choices) into a complete, validated Theme
+ * by:
+ *
+ *   1. Filling unspecified fields from a hardcoded `STARTER_THEME`.
+ *   2. Deriving missing color slots from `seedColors` via OKLCh math.
+ *   3. Validating the result.
+ *
+ * Built-in themes ship as fully-specified Theme JSON and skip this step.
+ */
+
+import type {
+  Theme,
+  DeepPartial,
+  ThemeColorPalette,
+  ThemeColorScheme,
+  ThemeSeedColors,
+  FontFamily,
+} from './Theme.js';
+import { THEME_SCHEMA_VERSION, createTheme } from './Theme.js';
+import { assertTheme } from './themeValidator.js';
+import {
+  oklchLighten,
+  oklchDarken,
+  oklchSetChroma,
+  pickContrastingText,
+  relativeLuminance,
+} from './colorUtils.js';
+
+/** Internal default theme used to fill in fields the customizer doesn't expose. */
+const STARTER_BODY_FONT: FontFamily = { stackId: 'system-sans' };
+const STARTER_TITLE_FONT: FontFamily = { stackId: 'system-serif' };
+const STARTER_MONO_FONT: FontFamily = { stackId: 'system-mono' };
+
+const STARTER_COLOR_SCHEMES: Record<string, ThemeColorScheme> = {
+  blue: { bg: '#1a365d', text: '#63b3ed', accent: '#90cdf4' },
+  green: { bg: '#22543d', text: '#9ae6b4', accent: '#68d391' },
+  purple: { bg: '#44337a', text: '#d6bcfa', accent: '#b794f4' },
+  red: { bg: '#742a2a', text: '#fc8181', accent: '#feb2b2' },
+  orange: { bg: '#744210', text: '#fbd38d', accent: '#f6ad55' },
+  teal: { bg: '#234e52', text: '#81e6d9', accent: '#4fd1c5' },
+};
+
+export const STARTER_THEME: Theme = {
+  schemaVersion: THEME_SCHEMA_VERSION,
+  id: 'custom',
+  name: 'Custom Theme',
+  description: 'Customizer starter — gets overridden by user choices.',
+  colors: {
+    primary: '#3182ce',
+    secondary: '#4a5568',
+    background: '#1a202c',
+    backgroundLight: '#2d3748',
+    text: '#f7fafc',
+    textMuted: '#a0aec0',
+    highlight: '#4299e1',
+    warning: '#fc8181',
+  },
+  typography: {
+    bodyFont: STARTER_BODY_FONT,
+    titleFont: STARTER_TITLE_FONT,
+    monoFont: STARTER_MONO_FONT,
+    titleWeight: 'bold',
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.45,
+    animationSpeed: 1.0,
+    borderRadius: 6,
+  },
+  renderStyle: {
+    name: 'standard',
+    defaultTextAnimation: 'fadeIn',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'fade', duration: 0.7 },
+  },
+  colorSchemes: STARTER_COLOR_SCHEMES,
+};
+
+/**
+ * Derive a full `ThemeColorPalette` from `seedColors`, with any explicit
+ * `partialColors` taking precedence over derived values. Background and
+ * text are guessed from luminance when the user gave only a primary.
+ */
+export function deriveColorPalette(
+  seeds: ThemeSeedColors,
+  partialColors: Partial<ThemeColorPalette> = {},
+  opts: { contrast?: 'subtle' | 'balanced' | 'high' } = {},
+): ThemeColorPalette {
+  const spread = opts.contrast === 'high' ? 0.22 : opts.contrast === 'subtle' ? 0.08 : 0.15;
+
+  const primary = seeds.primary;
+  const secondary = seeds.secondary ?? oklchSetChroma(oklchLighten(primary, 0.05), 0.5);
+  const accent = seeds.accent ?? oklchLighten(primary, spread);
+
+  // Decide light vs dark surface from the explicit background, the seed background,
+  // or default to dark.
+  const bgSeed = partialColors.background ?? seeds.background;
+  let background: string;
+  if (bgSeed) {
+    background = bgSeed;
+  } else {
+    // Pick a dark or light background that contrasts with primary
+    background = relativeLuminance(primary) > 0.5 ? '#0a0a0a' : '#1a202c';
+  }
+  const isLightSurface = relativeLuminance(background) > 0.5;
+
+  const backgroundLight =
+    partialColors.backgroundLight ??
+    (isLightSurface ? oklchDarken(background, 0.04) : oklchLighten(background, 0.04));
+
+  const text =
+    partialColors.text ?? seeds.text ?? pickContrastingText(background, '#f7fafc', '#1a202c');
+  const textMuted =
+    partialColors.textMuted ??
+    (isLightSurface ? oklchLighten(text, 0.25) : oklchDarken(text, 0.25));
+
+  const highlight = partialColors.highlight ?? accent;
+  const warning = partialColors.warning ?? '#fc8181';
+
+  return {
+    primary: partialColors.primary ?? primary,
+    secondary: partialColors.secondary ?? secondary,
+    background,
+    backgroundLight,
+    text,
+    textMuted,
+    highlight,
+    warning,
+  };
+}
+
+/** Map a contrast preset to numeric spread used by `deriveColorPalette`. */
+export type ContrastPreset = 'subtle' | 'balanced' | 'high';
+
+export interface CompileOptions {
+  /** Contrast level for OKLCh derivation (default 'balanced'). */
+  contrast?: ContrastPreset;
+}
+
+/**
+ * Compile a partial Theme into a complete one. Fills missing fields from
+ * `STARTER_THEME`, derives missing color slots from `seedColors` (when
+ * present), and validates the result.
+ */
+export function compileTheme(partial: DeepPartial<Theme>, opts: CompileOptions = {}): Theme {
+  // Step 1: deep-merge over the starter
+  const merged = createTheme(STARTER_THEME, partial);
+  merged.schemaVersion = THEME_SCHEMA_VERSION;
+
+  // Step 1b: typography fonts are discriminated unions ({stackId} | {custom}),
+  // so deep-merge would leave stale keys from the starter when the partial
+  // switches form. Replace each font wholesale when explicitly provided.
+  const partialTypography = partial.typography;
+  if (partialTypography) {
+    if (partialTypography.titleFont !== undefined) {
+      merged.typography.titleFont = partialTypography.titleFont as FontFamily;
+    }
+    if (partialTypography.bodyFont !== undefined) {
+      merged.typography.bodyFont = partialTypography.bodyFont as FontFamily;
+    }
+    if (partialTypography.monoFont !== undefined) {
+      merged.typography.monoFont = partialTypography.monoFont as FontFamily;
+    }
+  }
+
+  // Step 2: derive missing color slots from seeds, if present
+  if (merged.seedColors) {
+    const partialColors = (partial.colors ?? {}) as Partial<ThemeColorPalette>;
+    merged.colors = deriveColorPalette(merged.seedColors, partialColors, {
+      contrast: opts.contrast,
+    });
+  }
+
+  // Step 3: validate
+  return assertTheme(merged, `compiled theme "${merged.id}"`);
+}
+
+/**
+ * Parse a JSON string into a validated Theme. Throws on invalid input.
+ */
+export function parseTheme(json: string): Theme {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Invalid theme JSON: ${msg}`);
+  }
+  return assertTheme(parsed, 'parsed theme');
+}
+
+/**
+ * Serialize a Theme to a stable, pretty-printed JSON string. Round-trips
+ * cleanly through `parseTheme`.
+ */
+export function serializeTheme(theme: Theme): string {
+  return JSON.stringify(theme, null, 2);
+}