@bendyline/squisq 0.1.1

package/src/doc/utils/animationUtils.ts

@@ -0,0 +1,135 @@
+/**
+ * Animation Utilities
+ *
+ * Helper functions for mapping Doc animations to CSS classes and styles.
+ * Generates the appropriate animation class names and CSS custom properties
+ * for duration, delay, and easing.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Animation, AnimationType, TransitionType } from '../../schemas/Doc.js';
+
+interface AnimationResult {
+  /** CSS class name to apply */
+  className: string;
+  /** Inline styles for CSS custom properties */
+  style: Record<string, string>;
+}
+
+/**
+ * Get CSS class and styles for an animation.
+ */
+export function getAnimationStyle(
+  animation: Animation | undefined,
+  _currentTime: number = 0,
+): AnimationResult {
+  if (!animation || animation.type === 'none') {
+    return { className: '', style: {} };
+  }
+
+  const className = getAnimationClassName(animation);
+  const style = getAnimationCSSVars(animation);
+
+  return { className, style };
+}
+
+/**
+ * Map animation type to CSS class name.
+ */
+function getAnimationClassName(animation: Animation): string {
+  const { type, direction, panDirection } = animation;
+
+  switch (type) {
+    case 'fadeIn':
+      return 'anim-fadeIn';
+    case 'fadeOut':
+      return 'anim-fadeOut';
+    case 'slowZoom':
+      // Slow zoom (Ken Burns style) has variants based on direction and pan
+      if (panDirection === 'left') return 'anim-slowZoom-panLeft';
+      if (panDirection === 'right') return 'anim-slowZoom-panRight';
+      if (direction === 'out') return 'anim-slowZoom-out';
+      return 'anim-slowZoom-in';
+    case 'zoomIn':
+      return 'anim-zoomIn';
+    case 'zoomOut':
+      return 'anim-zoomOut';
+    case 'panLeft':
+      return 'anim-panLeft';
+    case 'panRight':
+      return 'anim-panRight';
+    case 'typewriter':
+      return 'anim-typewriter';
+    default:
+      return '';
+  }
+}
+
+/**
+ * Generate CSS custom properties for animation timing.
+ */
+function getAnimationCSSVars(animation: Animation): Record<string, string> {
+  const vars: Record<string, string> = {};
+
+  if (animation.duration !== undefined) {
+    vars['--anim-duration'] = `${animation.duration}s`;
+  }
+
+  if (animation.delay !== undefined) {
+    vars['--anim-delay'] = `${animation.delay}s`;
+  }
+
+  if (animation.easing) {
+    vars['--anim-easing'] = animation.easing;
+  }
+
+  return vars;
+}
+
+/**
+ * Get default duration for an animation type.
+ */
+export function getDefaultAnimationDuration(type: AnimationType): number {
+  switch (type) {
+    case 'slowZoom':
+    case 'panLeft':
+    case 'panRight':
+      return 8; // Long, slow animations
+    case 'typewriter':
+      return 3;
+    case 'fadeIn':
+    case 'fadeOut':
+      return 1;
+    case 'zoomIn':
+    case 'zoomOut':
+      return 0.5;
+    default:
+      return 1;
+  }
+}
+
+/**
+ * Get transition class for slide entry/exit.
+ */
+export function getTransitionClass(type: TransitionType, entering: boolean): string {
+  const mode = entering ? 'enter' : 'exit';
+  return `transition-${type}-${mode}`;
+}
+
+/**
+ * Calculate animation progress (0-1) based on current time.
+ */
+export function getAnimationProgress(
+  animation: Animation,
+  currentTime: number,
+  slideDuration: number,
+): number {
+  const delay = animation.delay || 0;
+  const duration = animation.duration || slideDuration;
+
+  if (currentTime < delay) return 0;
+  if (currentTime >= delay + duration) return 1;
+
+  return (currentTime - delay) / duration;
+}

package/src/doc/utils/themeUtils.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 { AnimationType } from '../../schemas/Doc.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 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;
+}
+
+// ============================================
+// 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;
+}
+
+// ============================================
+// 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;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './schemas/index.js';
+export * from './doc/index.js';
+export * from './spatial/index.js';
+export * from './storage/index.js';
+export * from './markdown/index.js';