@bendyline/squisq 2.1.0 → 2.2.0

package/src/schemas/PageStyle.ts

@@ -1,213 +0,0 @@
-/**
- * Page Style — the theme's art-direction layer for Page (linear) mode.
- *
- * Slides render through fixed-viewport SVG templates; pages render through
- * a small closed vocabulary of variable-height HTML section layouts
- * (`PageSectionKind`). A `ThemePageStyle` is how a theme art-directs that
- * page rendition: it picks a design family, sets page-wide tokens
- * (column widths, spacing, dividers, hero treatment, image framing …),
- * and can override how individual section kinds or block templates map
- * onto the section vocabulary.
- *
- * Design principles (mirrors the rest of the Theme schema):
- * - Fully JSON-serializable — rides the `squisq-custom-themes` frontmatter
- *   codec unchanged.
- * - Closed enums everywhere so renderers can switch exhaustively and the
- *   validator can reject typos.
- * - Optional on `Theme`; `resolvePageStyle`/`defaultPageStyle` derive a
- *   complete style from existing theme fields when absent, so legacy and
- *   customizer themes keep working without edits.
- */
-
-// ============================================
-// Section vocabulary
-// ============================================
-
-/**
- * The closed set of page section layouts. Every block template maps onto
- * one of these kinds (see `doc/page/sectionExtractors.ts`); themes may
- * remap via `ThemePageStyle.sections` / `.templates`.
- */
-export const PAGE_SECTION_KINDS = [
-  'hero',
-  'banner',
-  'stat-band',
-  'quote-band',
-  'feature-split',
-  'media-figure',
-  'gallery',
-  'callout',
-  'card-grid',
-  'item-list',
-  'timeline-rail',
-  'table-section',
-  'canvas-embed',
-  'prose',
-  'footer',
-] as const;
-
-export type PageSectionKind = (typeof PAGE_SECTION_KINDS)[number];
-
-/** Relative visual weight of a section within the page. */
-export type PageEmphasis = 'lead' | 'strong' | 'standard' | 'quiet';
-
-/** Which background treatment a section sits on. */
-export type PageBackground = 'base' | 'alternate' | 'accent' | 'media';
-
-// ============================================
-// Design families + tokens
-// ============================================
-
-/**
- * Broad page design personalities. A family selects the structural
- * skeleton (how sections compose); tokens parameterize it per theme.
- */
-export const PAGE_DESIGN_FAMILIES = [
-  'clean',
-  'editorial',
-  'brutalist',
-  'terminal',
-  'cinematic',
-  'documentary',
-  'organic',
-  'soft',
-] as const;
-
-export type PageDesignFamily = (typeof PAGE_DESIGN_FAMILIES)[number];
-
-/** How headings announce themselves across the page. */
-export interface PageHeadingTreatment {
-  /** Small label above headings: none, plain kicker, "01 —" numbering, or a mono tag. */
-  eyebrow: 'none' | 'kicker' | 'numbered' | 'mono-tag';
-  /** Overall heading size register. */
-  scale: 'regular' | 'display' | 'oversized';
-  /** Optional case transform for headings/eyebrows. */
-  case?: 'none' | 'uppercase';
-  /** Optional decoration under headings. */
-  underline?: 'none' | 'accent-bar' | 'full-rule';
-}
-
-/**
- * Page-wide design tokens. Structural CSS reads these via
- * `--squisq-page-*` custom properties (see `doc/pageCss.ts`).
- */
-export interface PageTokens {
-  /** Reading-column max width in px (prose, callouts, quotes). */
-  contentMaxWidth: number;
-  /** Wide-band inner max width in px (figures, tables, feature splits). */
-  wideMaxWidth: number;
-  /** Vertical rhythm between sections. */
-  sectionSpacing: 'compact' | 'comfortable' | 'generous';
-  /** Corner radius for cards, media frames, panels (px). */
-  cornerRadius: number;
-  /** Divider treatment between sections. */
-  divider: 'none' | 'gap-only' | 'hairline' | 'thick-rule' | 'double-rule' | 'dotted';
-  /** How section backgrounds vary down the page. */
-  backgroundRhythm: 'flat' | 'alternate' | 'accent-bands' | 'tinted-panels';
-  /** Hero (cover/title) composition. */
-  heroStyle: 'stacked' | 'split' | 'full-bleed' | 'letterbox' | 'oversized-type';
-  /** Heading voice across the page. */
-  headingTreatment: PageHeadingTreatment;
-  /** Frame treatment for photographic media. */
-  imageFraming: 'flush' | 'rounded' | 'bordered' | 'polaroid' | 'letterboxed' | 'circle-accent';
-  /** Shadow language for elevated elements. */
-  shadow: 'none' | 'soft' | 'crisp' | 'heavy';
-  /** Decoration on quote sections. */
-  quoteMark: 'none' | 'oversized-glyph' | 'accent-bar';
-  /** Treatment of large stat numerals. */
-  numeralStyle: 'plain' | 'oversized' | 'boxed' | 'mono';
-  /** Optional page background pattern. */
-  pattern?: 'none' | 'dots' | 'grid' | 'diagonal' | 'noise';
-}
-
-// ============================================
-// Overrides + accent rotation
-// ============================================
-
-/**
- * A theme's override for one section kind or one block template —
- * remap the kind, force a variant, adjust emphasis/background, or pass
- * freeform scalar hints the section renderer understands.
- */
-export interface PageSectionOverride {
-  kind?: PageSectionKind;
-  variant?: string;
-  emphasis?: PageEmphasis;
-  background?: PageBackground;
-  /** Freeform scalar hints (e.g. `dropCap: true`, `frame: "terminal"`). */
-  hints?: Record<string, string | number | boolean>;
-}
-
-/** How named color schemes rotate across accent-bearing sections. */
-export interface PageAccentRotation {
-  strategy: 'primary-only' | 'cycle' | 'alternate-two' | 'none';
-  /**
-   * ColorScheme names (keys of `theme.colorSchemes`) to rotate through.
-   * Defaults to all schemes in insertion order.
-   */
-  schemes?: string[];
-}
-
-// ============================================
-// ThemePageStyle
-// ============================================
-
-/**
- * The complete page art direction for a theme. Optional on `Theme`;
- * `defaultPageStyle(theme)` derives one from existing theme fields.
- */
-export interface ThemePageStyle {
-  family: PageDesignFamily;
-  tokens: PageTokens;
-  /** Per-section-kind overrides. */
-  sections?: Partial<Record<PageSectionKind, PageSectionOverride>>;
-  /** Per-template overrides (canonical template ids); win over `sections`. */
-  templates?: Record<string, PageSectionOverride>;
-  accentRotation: PageAccentRotation;
-}
-
-// ============================================
-// Enum sets (shared by the validator + defaults)
-// ============================================
-
-export const PAGE_SECTION_SPACINGS = ['compact', 'comfortable', 'generous'] as const;
-export const PAGE_DIVIDERS = [
-  'none',
-  'gap-only',
-  'hairline',
-  'thick-rule',
-  'double-rule',
-  'dotted',
-] as const;
-export const PAGE_BACKGROUND_RHYTHMS = [
-  'flat',
-  'alternate',
-  'accent-bands',
-  'tinted-panels',
-] as const;
-export const PAGE_HERO_STYLES = [
-  'stacked',
-  'split',
-  'full-bleed',
-  'letterbox',
-  'oversized-type',
-] as const;
-export const PAGE_EYEBROWS = ['none', 'kicker', 'numbered', 'mono-tag'] as const;
-export const PAGE_HEADING_SCALES = ['regular', 'display', 'oversized'] as const;
-export const PAGE_HEADING_CASES = ['none', 'uppercase'] as const;
-export const PAGE_HEADING_UNDERLINES = ['none', 'accent-bar', 'full-rule'] as const;
-export const PAGE_IMAGE_FRAMINGS = [
-  'flush',
-  'rounded',
-  'bordered',
-  'polaroid',
-  'letterboxed',
-  'circle-accent',
-] as const;
-export const PAGE_SHADOWS = ['none', 'soft', 'crisp', 'heavy'] as const;
-export const PAGE_QUOTE_MARKS = ['none', 'oversized-glyph', 'accent-bar'] as const;
-export const PAGE_NUMERAL_STYLES = ['plain', 'oversized', 'boxed', 'mono'] as const;
-export const PAGE_PATTERNS = ['none', 'dots', 'grid', 'diagonal', 'noise'] as const;
-export const PAGE_EMPHASES = ['lead', 'strong', 'standard', 'quiet'] as const;
-export const PAGE_BACKGROUNDS = ['base', 'alternate', 'accent', 'media'] as const;
-export const PAGE_ACCENT_STRATEGIES = ['primary-only', 'cycle', 'alternate-two', 'none'] as const;

package/src/schemas/Theme.ts

@@ -1,413 +0,0 @@
-/**
- * Theme System
- *
- * A Theme bundles color palette, typography, visual style, render-style
- * algorithm, and per-block color schemes into one JSON-serializable object.
- *
- * Built-in themes and customizer-authored themes share this exact schema.
- * Customizer-authored themes additionally specify `seedColors` so the few
- * fields the user picked can be re-edited later; built-ins typically omit
- * `seedColors` and ship with explicit `colors` already filled in.
- *
- * Design principles:
- * - Fully JSON-serializable. No functions; no raw CSS font strings.
- * - Font families are structured `FontFamily` references resolved by
- *   `resolveFontFamily()` at render time.
- * - Doc carries an optional `themeId`; resolution happens at render time
- *   via `resolveTheme(id)`.
- * - `createTheme` deep-merges a base theme with partial overrides;
- *   `compileTheme` fills in defaults and derives missing color slots from
- *   `seedColors`; both produce a complete `Theme`.
- */
-
-import type { LayoutHints } from './LayoutStrategy.js';
-import type { AnimationType, ImageTreatment, TransitionType } from './Doc.js';
-import type { PersistentLayerConfig } from './BlockTemplates.js';
-import type { ThemePageStyle } from './PageStyle.js';
-import { THEME_SCHEMA_VERSION } from './themeConstants.js';
-import { validateTheme } from './themeValidator.js';
-import { cloneAndFreezeData } from '../internal/immutable.js';
-
-// ============================================
-// Schema version
-// ============================================
-
-export { THEME_SCHEMA_VERSION } from './themeConstants.js';
-export type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
-
-/**
- * Frontmatter key under which a document inlines its custom Theme
- * definitions. The theme analog of `FRONTMATTER_CUSTOM_TEMPLATES_KEY`
- * (custom block templates). See `doc/customThemesFrontmatter.ts` for the
- * codec and `doc/resolveDocTheme.ts` for doc-scoped resolution.
- */
-export const FRONTMATTER_CUSTOM_THEMES_KEY = 'squisq-custom-themes';
-
-// ============================================
-// Color Palette
-// ============================================
-
-/**
- * Core color palette for a theme. Every color is a `#rrggbb` hex string.
- */
-export interface ThemeColorPalette {
-  /** Primary accent color */
-  primary: string;
-  /** Secondary accent color */
-  secondary: string;
-  /** Background color (typically dark) */
-  background: string;
-  /** Lighter background for contrast panels */
-  backgroundLight: string;
-  /** Main text color */
-  text: string;
-  /** Muted/secondary text color */
-  textMuted: string;
-  /** Highlight/emphasis color */
-  highlight: string;
-  /** Warning/alert color */
-  warning: string;
-}
-
-/**
- * A named color scheme used by templates for per-block color variation
- * (e.g., statHighlight or sectionHeader).
- */
-export interface ThemeColorScheme {
-  /** Background fill */
-  bg: string;
-  /** Primary text tint */
-  text: string;
-  /** Accent / secondary tint */
-  accent: string;
-}
-
-/**
- * Optional authoring metadata. When present and `colors` is partial,
- * `compileTheme` derives missing color slots from these seeds via OKLCh
- * lightening / darkening. Round-trips a customizer-authored theme back
- * into editable form.
- */
-export interface ThemeSeedColors {
-  primary: string;
-  secondary?: string;
-  accent?: string;
-  background?: string;
-  text?: string;
-}
-
-// ============================================
-// Typography
-// ============================================
-
-/** Categorical bucket for a font family — drives default fallback. */
-export type FontFamilyKind = 'sans' | 'serif' | 'mono' | 'display';
-
-/**
- * Structured reference to a font family. Either a curated stack id (looked
- * up in `AVAILABLE_FONT_STACKS`) or a custom user-supplied name with a
- * structured fallback bucket. Themes never carry raw CSS family strings.
- */
-export type FontFamily =
-  | { stackId: string }
-  | {
-      custom: {
-        name: string;
-        fallback: 'serif' | 'sans-serif' | 'monospace' | 'system-ui';
-      };
-    };
-
-/**
- * Typography settings for a theme.
- */
-export interface ThemeTypography {
-  /** Font family for body / description text */
-  bodyFont: FontFamily;
-  /** Font family for titles and headings */
-  titleFont: FontFamily;
-  /** Font family for code / monospaced text (optional) */
-  monoFont?: FontFamily;
-  /** Multiplier applied to LayoutHints.titleScale (default 1.0) */
-  titleScale?: number;
-  /** Multiplier applied to LayoutHints.bodyScale (default 1.0) */
-  bodyScale?: number;
-  /** Default body line height (default 1.4) */
-  lineHeight?: number;
-  /** Default title line height */
-  titleLineHeight?: number;
-  /** Default title font weight */
-  titleWeight?: 'normal' | 'bold';
-}
-
-// ============================================
-// Visual Style
-// ============================================
-
-/**
- * Global visual-style knobs that templates consult.
- */
-export interface ThemeStyle {
-  /** Default border radius for cards / shapes (px) */
-  borderRadius?: number;
-  /** Whether templates should default to text shadows */
-  textShadow?: boolean;
-  /** Darkness of overlay on image-backed blocks (0–1) */
-  overlayOpacity?: number;
-  /** Multiplier on all animation durations (1.0 = normal, <1 faster, >1 slower) */
-  animationSpeed?: number;
-  /** Default horizontal padding for text (percentage string, e.g. "5%") */
-  blockPadding?: string;
-  /**
-   * Photographic grade applied to template imagery (full-bleed photos,
-   * feature halves, accent strips) so photos look native to the theme.
-   * Duotone tints default to the theme primary. Blocks opt out per
-   * template via `imageTreatment: 'none'`.
-   */
-  imageTreatment?: ImageTreatment;
-}
-
-// ============================================
-// Render Style
-// ============================================
-
-/**
- * Render-style algorithm preset. Controls layout tweaks, default animations,
- * transitions, and per-template behavioral hints.
- */
-export interface RenderStyle {
-  /** Identifier for this algorithmic approach (e.g. "documentary", "magazine") */
-  name: string;
-  /** Partial overrides merged onto the orientation-based LayoutHints */
-  layoutOverrides?: Partial<LayoutHints>;
-  /** Default entrance animation for text layers */
-  defaultTextAnimation?: AnimationType;
-  /** Default animation for background / image layers */
-  defaultImageAnimation?: AnimationType;
-  /** Whether to apply Ken Burns ambient motion to images by default */
-  ambientMotion?: boolean;
-  /** Default block-to-block transition */
-  defaultTransition?: { type: TransitionType; duration?: number };
-  /**
-   * Per-template behavioral hints. Keys are template names, values are
-   * string/number/boolean maps that templates can read to vary their output.
-   * Templates that consume hints publish a `hintSchema` export documenting
-   * the keys they recognise.
-   */
-  templateHints?: Record<string, Record<string, string | number | boolean>>;
-}
-
-// ============================================
-// Theme
-// ============================================
-
-/**
- * A complete, JSON-serializable theme definition. Built-in and customizer-
- * authored themes share this exact shape.
- */
-export interface Theme {
-  /** Schema version. Always '1' for now. */
-  schemaVersion: ThemeSchemaVersion;
-  /** Unique identifier (e.g. "documentary") */
-  id: string;
-  /** Human-readable display name */
-  name: string;
-  /** Short description for theme pickers */
-  description?: string;
-  /**
-   * Id of the theme this custom theme was derived from, if any. Recorded
-   * by `compileTheme({ base })` so a customizer can re-open the theme and
-   * re-inherit the base's render style / color schemes / typography.
-   * Absent on built-ins.
-   */
-  basedOn?: string;
-  /** Optional authoring seeds (customizer fills these; built-ins typically omit) */
-  seedColors?: ThemeSeedColors;
-  /** Color palette */
-  colors: ThemeColorPalette;
-  /** Typography settings */
-  typography: ThemeTypography;
-  /** Global visual-style knobs */
-  style: ThemeStyle;
-  /** Algorithmic render-style preset */
-  renderStyle: RenderStyle;
-  /**
-   * Named color schemes for per-block color variation.
-   * Templates reference these by name (e.g. "blue", "warm").
-   */
-  colorSchemes: Record<string, ThemeColorScheme>;
-  /** Optional persistent layers baked into the theme */
-  persistentLayers?: PersistentLayerConfig;
-  /**
-   * Optional page art direction for Page (linear) mode. When absent,
-   * `resolvePageStyle`/`defaultPageStyle` derive one from the fields above,
-   * so legacy themes render pages without declaring this.
-   */
-  pageStyle?: ThemePageStyle;
-}
-
-// ============================================
-// Deep-Partial helper type
-// ============================================
-
-/**
- * Recursively makes every property optional.
- */
-export type DeepPartial<T> = {
-  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-
-// ============================================
-// Helpers
-// ============================================
-
-/**
- * Deep-merge `source` into `target`, returning a new object.
- * Arrays are replaced wholesale (not concatenated).
- */
-function deepMerge<T extends Record<string, unknown>>(target: T, source: DeepPartial<T>): T {
-  const result = { ...target } as Record<string, unknown>;
-  for (const key of Object.keys(source)) {
-    const srcVal = (source as Record<string, unknown>)[key];
-    const tgtVal = (target as Record<string, unknown>)[key];
-    if (
-      srcVal !== null &&
-      srcVal !== undefined &&
-      typeof srcVal === 'object' &&
-      !Array.isArray(srcVal) &&
-      tgtVal !== null &&
-      tgtVal !== undefined &&
-      typeof tgtVal === 'object' &&
-      !Array.isArray(tgtVal)
-    ) {
-      result[key] = deepMerge(
-        tgtVal as Record<string, unknown>,
-        srcVal as DeepPartial<Record<string, unknown>>,
-      );
-    } else if (srcVal !== undefined) {
-      result[key] = srcVal;
-    }
-  }
-  return result as T;
-}
-
-/**
- * Create a new theme by deep-merging overrides onto a base theme.
- * The returned theme gets its own `id` if one is provided in overrides,
- * otherwise keeps the base theme's `id` suffixed with "-custom".
- */
-export function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme {
-  const merged = deepMerge(
-    base as unknown as Record<string, unknown>,
-    overrides as DeepPartial<Record<string, unknown>>,
-  ) as unknown as Theme;
-  if (!overrides.id && merged.id === base.id) {
-    merged.id = `${base.id}-custom`;
-  }
-  if (!merged.schemaVersion) merged.schemaVersion = THEME_SCHEMA_VERSION;
-  return merged;
-}
-
-// ============================================
-// Surface Schemes — orthogonal to Theme
-// ============================================
-
-/**
- * A Surface Scheme is the light/dark axis, orthogonal to the editorial
- * identity of a Theme. A Theme chooses voice (serif vs sans, muted vs
- * bold, documentary vs magazine); a SurfaceScheme chooses what the paper
- * looks like. Any theme can render on either surface.
- */
-export interface SurfaceScheme {
-  /** Identifier — 'light', 'dark', or a custom id. */
-  id: string;
-  background: string;
-  backgroundLight: string;
-  text: string;
-  textMuted: string;
-}
-
-/** Near-white paper with dark text — standard light mode. */
-export const LIGHT_SURFACE: SurfaceScheme = {
-  id: 'light',
-  background: '#ffffff',
-  backgroundLight: '#f5f5f5',
-  text: '#1a1a1a',
-  textMuted: '#666666',
-};
-
-/** Dark charcoal paper with light text — standard dark mode. */
-export const DARK_SURFACE: SurfaceScheme = {
-  id: 'dark',
-  background: '#1a202c',
-  backgroundLight: '#2d3748',
-  text: '#f0f0f0',
-  textMuted: '#a0aec0',
-};
-
-/**
- * Overlay a SurfaceScheme's surface colors onto a Theme's palette,
- * leaving everything else (primary, highlight, warning, typography,
- * style, renderStyle, colorSchemes) untouched.
- */
-export function applySurface(theme: Theme, surface: SurfaceScheme): Theme {
-  return {
-    ...theme,
-    colors: {
-      ...theme.colors,
-      background: surface.background,
-      backgroundLight: surface.backgroundLight,
-      text: surface.text,
-      textMuted: surface.textMuted,
-    },
-  };
-}
-
-// ============================================
-// Caller-owned registry — for custom themes
-// ============================================
-
-/** A caller-owned custom-theme registry for SSR tenants, tests, and embedders. */
-export interface ThemeRegistry {
-  register(theme: Theme): void;
-  unregister(id: string): boolean;
-  get(id: string): Theme | undefined;
-  list(): Theme[];
-}
-
-function validatedThemeSnapshot(theme: Theme): Theme {
-  const result = validateTheme(theme);
-  if (!result.valid || !result.theme) {
-    const details = result.errors
-      .slice(0, 5)
-      .map((error) => `${error.path || '<root>'}: ${error.message}`)
-      .join('; ');
-    throw new TypeError(`Cannot register invalid theme: ${details}`);
-  }
-  return cloneAndFreezeData(result.theme);
-}
-
-/**
- * Create a registry whose state is owned by the caller rather than the
- * process. Registered values are validated and stored as deeply frozen
- * snapshots, so later caller mutation cannot alter resolution behavior.
- */
-export function createThemeRegistry(initialThemes: readonly Theme[] = []): ThemeRegistry {
-  const themes = new Map<string, Theme>();
-  const registry: ThemeRegistry = {
-    register(theme): void {
-      const snapshot = validatedThemeSnapshot(theme);
-      themes.set(snapshot.id, snapshot);
-    },
-    unregister(id): boolean {
-      return themes.delete(id);
-    },
-    get(id): Theme | undefined {
-      return themes.get(id);
-    },
-    list(): Theme[] {
-      return Array.from(themes.values());
-    },
-  };
-  for (const theme of initialThemes) registry.register(theme);
-  return Object.freeze(registry);
-}