@bendyline/squisq 2.1.0 → 2.2.0

package/src/doc/utils/themeUtils.ts

@@ -1,243 +0,0 @@
-/**
- * Theme Utilities
- *
- * Template-facing helpers that read from the Theme object on the
- * TemplateContext. Templates call these instead of hard-coding style
- * decisions, so the same template code adapts to any theme.
- */
-
-import type { TemplateContext } from '../../schemas/BlockTemplates.js';
-import type { ThemeColorScheme, RenderStyle } from '../../schemas/Theme.js';
-import type { Animation, AnimationType, ImageTreatment } from '../../schemas/Doc.js';
-import { resolveFontFamily } from '../../schemas/fontStacks.js';
-import { oklchDarken, withAlpha } from '../../schemas/colorUtils.js';
-
-// ============================================
-// Color Scheme Resolution
-// ============================================
-
-/** Fallback color scheme when a name is not found in the theme. */
-const FALLBACK_COLOR_SCHEME: ThemeColorScheme = {
-  bg: '#1a365d',
-  text: '#63b3ed',
-  accent: '#90cdf4',
-};
-
-/**
- * Resolve a named color scheme from the theme, with a safe fallback.
- * Templates call this instead of `COLOR_SCHEMES[name]`.
- */
-export function resolveColorScheme(
-  context: TemplateContext,
-  name: string | undefined,
-): ThemeColorScheme {
-  const schemes = context.theme.colorSchemes;
-  if (name && name in schemes) return schemes[name];
-  // Fall back to first defined scheme, then hard fallback
-  const keys = Object.keys(schemes);
-  if (keys.length > 0) return schemes[keys[0]];
-  return FALLBACK_COLOR_SCHEME;
-}
-
-// ============================================
-// Font Family Resolution
-// ============================================
-
-/** Safe system font fallbacks. */
-const FALLBACK_BODY = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
-const FALLBACK_TITLE = 'Georgia, "Times New Roman", serif';
-const FALLBACK_MONO = 'Consolas, "Courier New", monospace';
-
-/**
- * Get the theme font family for a given role, resolved to a CSS string.
- * Templates call this to set `fontFamily` on text layers.
- *
- * Theme fields are structured `FontFamily` references (`{ stackId }` or
- * `{ custom: { name, fallback } }`); this helper resolves them to a
- * CSS font-family string with safe fallbacks.
- */
-export function getThemeFont(context: TemplateContext, role: 'title' | 'body' | 'mono'): string {
-  const { typography } = context.theme;
-  switch (role) {
-    case 'title':
-      return resolveFontFamily(typography.titleFont, FALLBACK_TITLE);
-    case 'body':
-      return resolveFontFamily(typography.bodyFont, FALLBACK_BODY);
-    case 'mono':
-      return resolveFontFamily(typography.monoFont, FALLBACK_MONO);
-  }
-}
-
-// ============================================
-// Font Sizing
-// ============================================
-
-/**
- * Calculate a theme-aware scaled font size.
- * Applies the theme's typography scale multipliers on top of the
- * viewport-based font scale from LayoutStrategy.
- *
- * @param basePx  Base font size designed for 1920×1080
- * @param context Template context (includes fontScale, layout, theme)
- * @param isTitle Whether this is title text (uses titleScale) or body (bodyScale)
- */
-export function themedFontSize(
-  basePx: number,
-  context: TemplateContext,
-  isTitle: boolean = false,
-): number {
-  const { fontScale, layout, theme } = context;
-
-  // Base scale from viewport + orientation
-  const layoutScale = isTitle ? layout.titleScale : layout.bodyScale;
-
-  // Theme multiplier (defaults to 1.0 when not set)
-  const themeScale = isTitle
-    ? (theme.typography.titleScale ?? 1.0)
-    : (theme.typography.bodyScale ?? 1.0);
-
-  return Math.round(basePx * fontScale * layoutScale * themeScale);
-}
-
-// ============================================
-// Animation Helpers
-// ============================================
-
-/**
- * Scale an animation duration by the theme's animationSpeed multiplier.
- * A speed of 1.0 returns the base duration unchanged.
- */
-export function scaleAnimationDuration(baseDuration: number, context: TemplateContext): number {
-  const speed = context.theme.style.animationSpeed ?? 1.0;
-  return baseDuration * speed;
-}
-
-/**
- * Get the theme's default animation type for a layer kind.
- * Returns `undefined` when the theme doesn't specify one (template picks its own).
- */
-export function getDefaultAnimation(
-  context: TemplateContext,
-  layerType: 'text' | 'image',
-): AnimationType | undefined {
-  const rs: RenderStyle = context.theme.renderStyle;
-  return layerType === 'text' ? rs.defaultTextAnimation : rs.defaultImageAnimation;
-}
-
-/**
- * Theme-aware entrance animation for a template layer.
- *
- * The theme's `renderStyle.defaultTextAnimation` / `defaultImageAnimation`
- * overrides the entrance *type*; the template keeps its authored duration,
- * delay, and stagger. Templates opt in per layer:
- *
- * ```ts
- * animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 })
- * ```
- *
- * `slowZoom` is excluded — it's an ambient treatment handled by the
- * `applyRenderStyleToLayers` post-pass, not an entrance.
- */
-export function themedEntrance(
-  context: TemplateContext,
-  layerType: 'text' | 'image',
-  fallback: Animation,
-): Animation {
-  const type = getDefaultAnimation(context, layerType);
-  if (!type || type === 'slowZoom' || type === fallback.type) return fallback;
-  return { ...fallback, type };
-}
-
-// ============================================
-// Style Helpers
-// ============================================
-
-/**
- * Whether the theme defaults to text shadows.
- * Templates should consult this when choosing `shadow: true/false`.
- */
-export function shouldUseShadow(context: TemplateContext): boolean {
-  return context.theme.style.textShadow ?? true;
-}
-
-/**
- * Get the theme's overlay opacity for image-backed blocks.
- */
-export function getOverlayOpacity(context: TemplateContext): number {
-  return context.theme.style.overlayOpacity ?? 0.5;
-}
-
-/**
- * Resolve the effective photographic treatment for a block's imagery.
- *
- * Precedence: the block's `imageTreatment` override ('none' opts out, a
- * type forces that grade) → the theme's `style.imageTreatment` → none.
- * Duotone tints default to the theme primary. Templates pass the result
- * straight into `ImageLayer.content.treatment`.
- */
-export function themedImageTreatment(
-  context: TemplateContext,
-  override?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool',
-): ImageTreatment | undefined {
-  if (override === 'none') return undefined;
-  const themeTreatment = context.theme.style.imageTreatment;
-  const base: ImageTreatment | undefined = override
-    ? { type: override, strength: themeTreatment?.strength }
-    : themeTreatment;
-  if (!base || base.type === 'none') return undefined;
-  if (base.type === 'duotone' && !base.color) {
-    return { ...base, color: context.theme.colors.primary };
-  }
-  return base;
-}
-
-/**
- * Theme-derived surface gradient for text-first templates.
- *
- * Runs from the theme's alternate surface into a slightly deepened
- * background, staying inside the theme's own hue. Templates must use
- * this instead of hard-coding a dark endpoint (`#0f1520`, `#1e2030`, …):
- * hard-coded navy endpoints made light themes render dark panels and
- * warm themes drift cold halfway down the block.
- */
-export function themedSurfaceGradient(context: TemplateContext, angleDeg = 160): string {
-  const { background, backgroundLight } = context.theme.colors;
-  return `linear-gradient(${angleDeg}deg, ${backgroundLight} 0%, ${oklchDarken(background, 0.04)} 100%)`;
-}
-
-/**
- * Translucent overlay tint derived from the theme background, for text
- * bands/scrims painted over imagery. Light themes get a light scrim with
- * dark theme text on top; dark themes get the familiar dark scrim —
- * `theme.colors.text` stays legible on it by construction.
- */
-export function themedScrim(context: TemplateContext, alpha?: number): string {
-  const a = alpha ?? Math.max(0.55, getOverlayOpacity(context));
-  return withAlpha(context.theme.colors.background, a);
-}
-
-// ============================================
-// Template Hint Access
-// ============================================
-
-/**
- * Read a per-template hint from the theme's renderStyle.
- * Returns `fallback` when the hint isn't defined.
- *
- * @example
- * ```ts
- * const entrance = getTemplateHint(context, 'statHighlight', 'entrance', 'subtle');
- * ```
- */
-export function getTemplateHint<T extends string | number | boolean>(
-  context: TemplateContext,
-  templateName: string,
-  key: string,
-  fallback: T,
-): T {
-  const hints = context.theme.renderStyle.templateHints;
-  if (!hints) return fallback;
-  const tplHints = hints[templateName];
-  if (!tplHints || !(key in tplHints)) return fallback;
-  return tplHints[key] as T;
-}