@bendyline/squisq 1.5.0 → 1.5.1

package/src/doc/templates/inputDescriptors.ts

@@ -0,0 +1,432 @@
+/**
+ * Template input descriptors — a typed catalog of the inline `{[…]}` params
+ * each built-in template understands, plus the pure coercion + lint logic
+ * that consumes it.
+ *
+ * Two jobs, one source of truth:
+ *
+ * - **Coercion (`coerceTemplateParams`)** turns a flat `key → raw string`
+ *   param map (from a `{[name key=value]}` annotation, always strings) into a
+ *   partial typed input the template functions can consume directly — e.g.
+ *   `center="47.6,-122.3"` → `{ lat: 47.6, lng: -122.3 }`, `zoom=9` → `9`.
+ *   This is what makes `{[map center="47.6,-122.3" zoom=9]}` render with no
+ *   changes to any template function. Unknown keys ALWAYS pass through
+ *   untouched (as strings), so coercion is never lossy; coercion failures are
+ *   returned as `warnings` and the raw string is preserved.
+ *
+ * - **Linting (`lintTemplateParams`)** checks a param map against the
+ *   descriptors and reports unknown keys (with a did-you-mean suggestion),
+ *   values outside a closed enum / that fail coercion, and missing required
+ *   inputs. The document validator surfaces these as diagnostics.
+ *
+ * This mirrors the proven block-meta descriptor pattern in
+ * `markdown/annotationCoercion.ts` (`BLOCK_META_KEY_DESCRIPTORS`), extended
+ * from block geometry/timing to per-template content inputs.
+ *
+ * The descriptors are the `{[…]}` counterpart of the template input
+ * interfaces in `schemas/BlockTemplates.ts` — only keys/enums that provably
+ * exist on those interfaces are declared. Keys that can't be meaningfully
+ * expressed as a single inline string (e.g. a `dataTable`'s `rows`) are still
+ * declared with `coerce: 'string'` so they aren't mis-flagged as unknown.
+ */
+
+import { KNOWN_BLOCK_META_KEYS, parseNumber } from '../../markdown/annotationCoercion.js';
+import { resolveTemplateName } from './index.js';
+import { nearestName } from '../utils/nearest.js';
+
+// ============================================
+// Types
+// ============================================
+
+/** How a raw `{[…]}` param string is coerced into a typed input value. */
+export type InputCoercion =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'latLng'
+  | 'labeledPair'
+  | 'stringList';
+
+/**
+ * Editor/validator-facing description of a single template input key: what it
+ * does, how to coerce its raw string, and either its closed set of valid
+ * values or a free-form format hint. `values`/`valueHint` are mutually
+ * exclusive (a key has a closed enum OR a hint, not both).
+ */
+export interface TemplateInputDescriptor {
+  /** The `{[name key=…]}` param key, matching the template input interface. */
+  key: string;
+  /** One-line description of the input. */
+  description: string;
+  /** Coercion strategy for the raw string (default `'string'`). */
+  coerce?: InputCoercion;
+  /** Closed set of valid values, for keys backed by an enum. */
+  values?: readonly string[];
+  /** Format hint shown when the value is free-form (no closed set). */
+  valueHint?: string;
+  /** When true, the validator warns if the key is absent and can't be derived. */
+  required?: boolean;
+}
+
+/** A single lint finding produced by {@link lintTemplateParams}. */
+export interface TemplateParamFinding {
+  kind: 'unknown-input' | 'invalid-input-value' | 'missing-input';
+  key: string;
+  message: string;
+  /** Did-you-mean candidate (for `unknown-input`). */
+  suggestion?: string;
+}
+
+// ============================================
+// Shared enum vocabularies (verified against BlockTemplates.ts)
+// ============================================
+
+/** `ambientMotion` on image/video/map templates. */
+const AMBIENT_MOTION_VALUES = ['zoomIn', 'zoomOut', 'panLeft', 'panRight'] as const;
+/** `captionPosition` on imageWithCaption / videoWithCaption. */
+const CAPTION_POSITION_VALUES = ['bottom', 'top', 'center'] as const;
+/** `mapStyle` — mirrors `MapTileStyle` in `schemas/Doc.ts`. */
+const MAP_STYLE_VALUES = ['terrain', 'satellite', 'road', 'toner', 'watercolor'] as const;
+/** `mood` on dateEvent. */
+const DATE_EVENT_MOOD_VALUES = ['neutral', 'somber', 'celebratory'] as const;
+
+/** Shared free-form hint for `colorScheme`-style keys. */
+const COLOR_SCHEME_HINT = "theme color-scheme name — e.g. 'blue', 'green'";
+
+// ============================================
+// Descriptor tables
+// ============================================
+
+/**
+ * Inputs shared by every template via `BaseTemplateBlock`. Merged into each
+ * template's known-key set for coercion + lint. Block-level timing/geometry
+ * keys (`duration`, `x`, `y`, …) are NOT here — those stay owned by the
+ * block-meta registry (`KNOWN_BLOCK_META_KEYS`) and are folded into the lint
+ * known-key set separately.
+ */
+export const BASE_INPUT_DESCRIPTORS: readonly TemplateInputDescriptor[] = [
+  {
+    key: 'imageTreatment',
+    description: "Per-block photographic grade override ('none' opts out)",
+    values: ['none', 'mono', 'duotone', 'warm', 'cool'],
+  },
+  {
+    key: 'useBottomLayer',
+    description: "Show the doc's bottom persistent layers",
+    coerce: 'boolean',
+  },
+  { key: 'useTopLayer', description: "Show the doc's top persistent layers", coerce: 'boolean' },
+];
+
+/**
+ * Per-template input descriptors, keyed by canonical template id. A template
+ * absent from this map has no descriptors and is exempt from lint (custom
+ * templates and not-yet-described built-ins).
+ */
+export const TEMPLATE_INPUT_DESCRIPTORS: Readonly<
+  Record<string, readonly TemplateInputDescriptor[]>
+> = {
+  title: [
+    { key: 'title', description: 'Main title text' },
+    { key: 'subtitle', description: 'Subtitle or tagline' },
+    { key: 'backgroundColor', description: 'Background color', valueHint: 'CSS color' },
+  ],
+  statHighlight: [
+    { key: 'stat', description: 'The statistic (e.g. "89%", "2x")' },
+    { key: 'description', description: 'What the stat means' },
+    { key: 'detail', description: 'Additional detail or context' },
+    { key: 'colorScheme', description: 'Color scheme for the stat', valueHint: COLOR_SCHEME_HINT },
+  ],
+  quote: [
+    { key: 'quote', description: 'The quote text' },
+    { key: 'attribution', description: 'Attribution (author, source)' },
+  ],
+  pullQuote: [
+    { key: 'text', description: 'Quote text' },
+    { key: 'attribution', description: 'Attribution' },
+  ],
+  twoColumn: [
+    {
+      key: 'left',
+      description: 'Left column, as "label|sublabel"',
+      coerce: 'labeledPair',
+      required: true,
+    },
+    {
+      key: 'right',
+      description: 'Right column, as "label|sublabel"',
+      coerce: 'labeledPair',
+      required: true,
+    },
+    { key: 'header', description: 'Optional header above the columns' },
+    { key: 'leftColor', description: 'Left column color scheme', valueHint: COLOR_SCHEME_HINT },
+    { key: 'rightColor', description: 'Right column color scheme', valueHint: COLOR_SCHEME_HINT },
+  ],
+  dateEvent: [
+    { key: 'date', description: 'The date (e.g. "July 14, 1974")' },
+    { key: 'description', description: 'What happened' },
+    { key: 'footer', description: 'Optional footer text' },
+    { key: 'mood', description: 'Emotional tone', values: DATE_EVENT_MOOD_VALUES },
+  ],
+  imageWithCaption: [
+    { key: 'imageSrc', description: 'Path to the image file', required: true },
+    { key: 'imageAlt', description: 'Alt text for accessibility' },
+    { key: 'caption', description: 'Caption text' },
+    { key: 'captionPosition', description: 'Caption placement', values: CAPTION_POSITION_VALUES },
+    { key: 'ambientMotion', description: 'Slow zoom/pan effect', values: AMBIENT_MOTION_VALUES },
+    { key: 'isTitle', description: 'Style the caption as a title', coerce: 'boolean' },
+    { key: 'subtitle', description: 'Subtitle (only when isTitle)' },
+    { key: 'imageCredit', description: 'Photo credit / artist name' },
+    { key: 'imageLicense', description: 'License identifier' },
+  ],
+  leftFeature: FEATURE_DESCRIPTORS(),
+  rightFeature: FEATURE_DESCRIPTORS(),
+  map: [
+    {
+      key: 'center',
+      description: 'Map center as "lat,lng"',
+      coerce: 'latLng',
+      required: true,
+    },
+    { key: 'zoom', description: 'Zoom level (4-16)', coerce: 'number' },
+    { key: 'mapStyle', description: 'Map tile style', values: MAP_STYLE_VALUES },
+    { key: 'title', description: 'Optional title overlay' },
+    { key: 'caption', description: 'Optional caption' },
+  ],
+  photoGrid: [
+    { key: 'images', description: 'Comma-separated image paths', coerce: 'stringList' },
+    { key: 'caption', description: 'Optional caption below the grid' },
+    {
+      key: 'ambientMotion',
+      description: 'Slow zoom/pan on the largest image',
+      values: AMBIENT_MOTION_VALUES,
+    },
+  ],
+  comparisonBar: [
+    { key: 'leftLabel', description: 'Left bar label', required: true },
+    { key: 'leftValue', description: 'Left bar numeric value', coerce: 'number', required: true },
+    { key: 'rightLabel', description: 'Right bar label', required: true },
+    { key: 'rightValue', description: 'Right bar numeric value', coerce: 'number', required: true },
+    { key: 'unit', description: 'Unit label (e.g. "km")' },
+    { key: 'colorScheme', description: 'Color scheme', valueHint: COLOR_SCHEME_HINT },
+  ],
+  dataTable: [
+    { key: 'title', description: 'Optional title above the table' },
+    { key: 'headers', description: 'Comma-separated header cells', coerce: 'stringList' },
+    // `rows`/`align` are structured (string[][] / alignment[]) and can't be
+    // expressed as a single inline string — declared so they aren't flagged
+    // as unknown when supplied via a data fence's overriding params.
+    { key: 'rows', description: 'Table rows (supply via a data fence)' },
+    { key: 'align', description: 'Per-column alignment (supply via a data fence)' },
+    { key: 'colorScheme', description: 'Header color scheme', valueHint: COLOR_SCHEME_HINT },
+  ],
+  videoWithCaption: [
+    { key: 'videoSrc', description: 'Path to the video file', required: true },
+    { key: 'posterSrc', description: 'Poster frame path' },
+    { key: 'videoAlt', description: 'Alt text for accessibility' },
+    { key: 'clipStart', description: 'Clip start time (seconds)', coerce: 'number' },
+    { key: 'clipEnd', description: 'Clip end time (seconds)', coerce: 'number' },
+    { key: 'caption', description: 'Caption text' },
+    { key: 'captionPosition', description: 'Caption placement', values: CAPTION_POSITION_VALUES },
+    { key: 'videoCredit', description: 'Video credit / artist name' },
+    { key: 'videoLicense', description: 'License identifier' },
+  ],
+};
+
+/** Shared descriptor list for `leftFeature`/`rightFeature` (identical inputs). */
+function FEATURE_DESCRIPTORS(): readonly TemplateInputDescriptor[] {
+  return [
+    { key: 'imageSrc', description: 'Path to the feature image', required: true },
+    { key: 'imageAlt', description: 'Alt text for accessibility' },
+    { key: 'imageWidth', description: 'Explicit display width in px', coerce: 'number' },
+    { key: 'imageHeight', description: 'Explicit display height in px', coerce: 'number' },
+    { key: 'title', description: 'Heading text next to the image' },
+    { key: 'body', description: 'Body text below the title' },
+  ];
+}
+
+// ============================================
+// Descriptor lookup
+// ============================================
+
+/** All descriptors (template-specific + base) for a canonical template id. */
+function descriptorsFor(canonical: string): readonly TemplateInputDescriptor[] | undefined {
+  const specific = TEMPLATE_INPUT_DESCRIPTORS[canonical];
+  if (!specific) return undefined;
+  return [...specific, ...BASE_INPUT_DESCRIPTORS];
+}
+
+function descriptorMap(
+  descriptors: readonly TemplateInputDescriptor[],
+): Map<string, TemplateInputDescriptor> {
+  return new Map(descriptors.map((d) => [d.key, d]));
+}
+
+// ============================================
+// Coercion (M2)
+// ============================================
+
+/**
+ * Coerce a flat `{[…]}` param map into a partial typed template input.
+ *
+ * Known descriptor keys are coerced per their `coerce` strategy; unknown keys
+ * (and `string`-typed keys) pass through unchanged. A coercion failure leaves
+ * the raw string in place and adds a human-readable `warnings` entry — the
+ * output is never lossy. Returns a fresh object; the caller must NOT feed
+ * `templateOverrides` back in — only the ephemeral merged input is coerced.
+ */
+export function coerceTemplateParams(
+  template: string | undefined,
+  params: Record<string, string>,
+): { input: Record<string, unknown>; warnings: string[] } {
+  const input: Record<string, unknown> = {};
+  const warnings: string[] = [];
+  const descriptors = template ? descriptorsFor(resolveTemplateName(template)) : undefined;
+  const byKey = descriptors ? descriptorMap(descriptors) : undefined;
+
+  for (const [key, raw] of Object.entries(params)) {
+    const coerce = byKey?.get(key)?.coerce ?? 'string';
+    const { value, warning } = coerceValue(coerce, raw);
+    if (warning) {
+      warnings.push(`"${key}": ${warning}`);
+      input[key] = raw; // preserve the raw string on failure
+    } else {
+      input[key] = value;
+    }
+  }
+
+  return { input, warnings };
+}
+
+/** Coerce one raw string per a coercion kind. `warning` set on failure. */
+function coerceValue(coerce: InputCoercion, raw: string): { value: unknown; warning?: string } {
+  switch (coerce) {
+    case 'number': {
+      const n = parseNumber(raw);
+      return n == null
+        ? { value: raw, warning: `not a number (${JSON.stringify(raw)})` }
+        : { value: n };
+    }
+    case 'boolean':
+      return coerceBoolean(raw);
+    case 'latLng':
+      return coerceLatLng(raw);
+    case 'labeledPair':
+      return { value: coerceLabeledPair(raw) };
+    case 'stringList':
+      return { value: coerceStringList(raw) };
+    case 'string':
+    default:
+      return { value: raw };
+  }
+}
+
+/** `'true'`/`''` (bare flag) → true, `'false'` → false; anything else fails. */
+function coerceBoolean(raw: string): { value: unknown; warning?: string } {
+  const t = raw.trim().toLowerCase();
+  if (t === 'true' || t === '') return { value: true };
+  if (t === 'false') return { value: false };
+  return { value: raw, warning: `not a boolean (${JSON.stringify(raw)}) — expected true or false` };
+}
+
+/** `"47.6,-122.3"` → `{ lat, lng }`; malformed → failure (raw preserved). */
+function coerceLatLng(raw: string): { value: unknown; warning?: string } {
+  const parts = raw.split(',');
+  if (parts.length === 2) {
+    const lat = parseNumber(parts[0]);
+    const lng = parseNumber(parts[1]);
+    if (lat != null && lng != null) return { value: { lat, lng } };
+  }
+  return { value: raw, warning: `not a "lat,lng" pair (${JSON.stringify(raw)})` };
+}
+
+/** `"Label|Sub"` → `{ label, sublabel? }`; sublabel omitted when empty. */
+function coerceLabeledPair(raw: string): { label: string; sublabel?: string } {
+  const sep = raw.indexOf('|');
+  if (sep < 0) return { label: raw.trim() };
+  const label = raw.slice(0, sep).trim();
+  const sublabel = raw.slice(sep + 1).trim();
+  return sublabel ? { label, sublabel } : { label };
+}
+
+/** `"a, b ,c"` → `['a','b','c']` (trimmed, empties dropped). */
+function coerceStringList(raw: string): string[] {
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+// ============================================
+// Linting (M5)
+// ============================================
+
+/**
+ * Lint a template's `{[…]}` params against its descriptors. Returns findings
+ * for unknown keys, values outside a closed enum / that fail coercion, and
+ * missing required inputs. Templates without descriptors (custom or
+ * not-yet-described built-ins) return `[]`.
+ */
+export function lintTemplateParams(
+  template: string,
+  params: Record<string, string>,
+): TemplateParamFinding[] {
+  const canonical = resolveTemplateName(template);
+  const specific = TEMPLATE_INPUT_DESCRIPTORS[canonical];
+  if (!specific) return [];
+
+  const findings: TemplateParamFinding[] = [];
+  const allDescriptors = [...specific, ...BASE_INPUT_DESCRIPTORS];
+  const byKey = descriptorMap(allDescriptors);
+  // Known keys for did-you-mean: descriptor keys ∪ block-meta keys (which are
+  // honored on the same annotation, e.g. `duration`, `transition`).
+  const knownKeys = new Set<string>([...byKey.keys(), ...Object.keys(KNOWN_BLOCK_META_KEYS)]);
+
+  for (const [key, raw] of Object.entries(params)) {
+    const descriptor = byKey.get(key);
+    if (!descriptor) {
+      if (knownKeys.has(key)) continue; // block-meta key — valid, not a template input
+      const suggestion = nearestName(key, knownKeys);
+      findings.push({
+        kind: 'unknown-input',
+        key,
+        message:
+          `Unknown input "${key}" for template "${canonical}"` +
+          (suggestion ? `. Did you mean "${suggestion}"?` : ''),
+        ...(suggestion ? { suggestion } : {}),
+      });
+      continue;
+    }
+
+    // Value validation: closed enum first, then coercion.
+    if (descriptor.values) {
+      const v = raw.trim();
+      if (v !== '' && !descriptor.values.includes(v)) {
+        findings.push({
+          kind: 'invalid-input-value',
+          key,
+          message: `Invalid value ${JSON.stringify(raw)} for "${key}" — expected one of: ${descriptor.values.join(', ')}`,
+        });
+      }
+    } else if (descriptor.coerce && descriptor.coerce !== 'string') {
+      const { warning } = coerceValue(descriptor.coerce, raw);
+      if (warning) {
+        findings.push({ kind: 'invalid-input-value', key, message: `"${key}": ${warning}` });
+      }
+    }
+  }
+
+  // Missing required inputs (checked over template-specific descriptors only;
+  // base inputs are never required).
+  for (const descriptor of specific) {
+    if (descriptor.required && params[descriptor.key] == null) {
+      findings.push({
+        kind: 'missing-input',
+        key: descriptor.key,
+        message: `Missing required input "${descriptor.key}" for template "${canonical}"`,
+      });
+    }
+  }
+
+  return findings;
+}

package/src/doc/templates/photoGrid.ts

@@ -17,12 +17,7 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { PhotoGridInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import {
-  getThemeFont,
-  shouldUseShadow,
-  themedFontSize,
-  themedImageTreatment,
-} from '../utils/themeUtils.js';
+import { getThemeFont, themedFontSize, themedImageTreatment } from '../utils/themeUtils.js';
 import { withAlpha } from '../../schemas/colorUtils.js';
 import { cleanCaption } from './captionUtils.js';
 
@@ -50,16 +45,11 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
     },
   ];
 
-  // Reserve bottom space for caption — sized to the caption's one-to-two
-  // lines rather than a fixed fifth of the block (which left a dead band).
-  const captionHeight = caption ? (layout.stackColumns ? 16 : 14) : 0;
-  const gridHeight = 100 - captionHeight;
+  const gridHeight = 100;
 
   // Generate image positions based on count; stack vertically in portrait
   const positions = getGridPositions(images.length, gridHeight, layout.stackColumns);
 
-  const altFontSize = themedFontSize(24, context, false);
-
   for (let i = 0; i < Math.min(images.length, 4); i++) {
     const img = images[i];
     const pos = positions[i];
@@ -72,24 +62,6 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
       position: { x: `${pos.x}%`, y: `${pos.y}%`, width: `${pos.w}%`, height: `${pos.h}%` },
     });
 
-    // Alt-text label on placeholder
-    if (img.alt) {
-      layers.push({
-        type: 'text',
-        id: `grid-alt-${i}`,
-        content: {
-          text: img.alt,
-          style: {
-            fontSize: altFontSize,
-            fontFamily: getThemeFont(context, 'body'),
-            color: theme.colors.textMuted,
-            textAlign: 'center' as const,
-          },
-        },
-        position: { x: `${pos.x + pos.w / 2}%`, y: `${pos.y + pos.h / 2}%`, anchor: 'center' },
-      });
-    }
-
     // Image layer (covers placeholder when loaded)
     layers.push({
       type: 'image',
@@ -116,20 +88,23 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
     });
   }
 
-  // Caption with gradient overlay
+  // Caption in a compact translucent chip above player controls. Long
+  // archival/Wikimedia descriptions are intentionally clamped.
   if (caption) {
-    const captionFontSize = themedFontSize(layout.stackColumns ? 28 : 32, context, false);
+    const captionFontSize = themedFontSize(layout.stackColumns ? 24 : 26, context, false);
+    const captionY = layout.stackColumns ? '78%' : '74%';
+    const captionBgY = layout.stackColumns ? '72%' : '68%';
+    const captionHeight = layout.stackColumns ? '13%' : '16%';
+    const bg = theme.colors.background;
 
-    // Caption band fades from the theme surface so the theme text color
-    // on it always reads (a fixed black band hid dark text in light themes).
     layers.push({
       type: 'shape',
       id: 'caption-bg',
       content: {
         shape: 'rect',
-        fill: `linear-gradient(${withAlpha(theme.colors.background, 0)}, ${withAlpha(theme.colors.background, 0.85)})`,
+        fill: `linear-gradient(90deg, ${withAlpha(bg, 0)}, ${withAlpha(bg, 0.78)} 16%, ${withAlpha(bg, 0.78)} 84%, ${withAlpha(bg, 0)})`,
       },
-      position: { x: 0, y: `${gridHeight - 4}%`, width: '100%', height: `${captionHeight + 4}%` },
+      position: { x: 0, y: captionBgY, width: '100%', height: captionHeight },
     });
 
     layers.push({
@@ -142,14 +117,16 @@ export function photoGrid(input: PhotoGridInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: shouldUseShadow(context),
+          shadow: true,
+          lineHeight: 1.18,
+          maxLines: layout.stackColumns ? 2 : 1,
         },
       },
       position: {
         x: '50%',
-        y: `${gridHeight + captionHeight / 2}%`,
+        y: captionY,
         anchor: 'center',
-        width: '90%',
+        width: '78%',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 0.5 },
     });