@bendyline/squisq 1.3.0 → 1.4.0

package/src/doc/templates/featureBlock.ts

@@ -0,0 +1,202 @@
+/**
+ * Feature Block Templates — `leftFeature` and `rightFeature`
+ *
+ * Pairs a "feature" image on one side of the block with a title + body
+ * paragraph on the other. The two templates are mirror images, so the
+ * actual layer-builder lives here once and the per-side template files
+ * just call it with a `side` parameter.
+ *
+ * Used for editorial layouts like product highlights, profile cards,
+ * and section intros where a single image deserves to sit next to a
+ * short text block rather than behind it (which is what
+ * `imageWithCaption` does).
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type {
+  LeftFeatureInput,
+  RightFeatureInput,
+  TemplateContext,
+} from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { getThemeFont } from '../utils/themeUtils.js';
+
+type FeatureInput = LeftFeatureInput | RightFeatureInput;
+
+/**
+ * Build the layer list for either feature template. Layers are in
+ * back-to-front order: background, image, then text.
+ */
+function buildFeatureLayers(
+  input: FeatureInput,
+  context: TemplateContext,
+  side: 'left' | 'right',
+): Layer[] {
+  const { imageSrc, imageAlt, imageWidth, imageHeight, title, body } = input;
+  const { theme, layout } = context;
+  // Treat the image as "sized" when the host gave us an explicit width
+  // or height — that's our cue that the user resized the image in the
+  // editor and we should respect that as a sizing hint instead of
+  // stretching the image to fill the whole half.
+  const sized = (imageWidth ?? 0) > 0 || (imageHeight ?? 0) > 0;
+  // In portrait the image stacks above the text rather than splitting
+  // horizontally — same flag the twoColumn template uses, so the two
+  // behave consistently on narrow viewports.
+  const stack = layout.stackColumns;
+
+  const titleFontSize = scaledFontSize(48, context, true);
+  const bodyFontSize = scaledFontSize(24, context, false);
+
+  // Image takes the full left or right half. The text column gets the
+  // opposite half, with a comfortable inset so the text doesn't kiss
+  // the image edge or the card border. All values are percentages of
+  // the block viewport so they scale with the card size.
+  //
+  // When the image is "sized" we shrink it inside its half: the half
+  // still claims the space (so the text column stays the same width
+  // and the layout doesn't shift around when dimensions are toggled)
+  // but the image itself sits centered with padding around it. The
+  // sized box uses a square envelope sized to the smaller dimension of
+  // its half so the image breathes regardless of viewport aspect.
+  let imgX: string;
+  let imgY: string;
+  let imgW: string;
+  let imgH: string;
+  let imageFit: 'cover' | 'contain';
+  if (stack) {
+    imgX = '0';
+    imgY = '0';
+    imgW = '100%';
+    imgH = '50%';
+    imageFit = sized ? 'contain' : 'cover';
+  } else if (sized) {
+    // 90% of the half (with explicit aspect via fit='contain') so the
+    // image keeps its natural proportions and never touches the card
+    // edges. We don't try to honor the literal pixel value — block
+    // viewports are designed in their own coordinate space — but the
+    // *intent* (smaller image, padded, centered) is what comes through.
+    const halfStart = side === 'left' ? 5 : 55; // %
+    imgX = `${halfStart}%`;
+    imgY = '5%';
+    imgW = '40%';
+    imgH = '90%';
+    imageFit = 'contain';
+  } else {
+    imgX = side === 'left' ? '0' : '50%';
+    imgY = '0';
+    imgW = '50%';
+    imgH = '100%';
+    imageFit = 'cover';
+  }
+
+  // Text-column geometry. `textX` is the LEFT edge of the column when
+  // the side is "left" (image left, text right), and the RIGHT edge of
+  // the column when the side is "right" — we use top-left / top-right
+  // anchors below so text reads left-aligned in both cases without
+  // having to flip the column origin manually.
+  const COLUMN_INSET = 4; // % of block width — padding from card edge / divider
+  const textColumnWidth = stack ? 90 : 42;
+  const textX = stack
+    ? `${(100 - textColumnWidth) / 2}%`
+    : side === 'left'
+      ? `${50 + COLUMN_INSET}%` // text column starts just past the divider
+      : `${50 - COLUMN_INSET}%`; // right edge of left-half text column
+
+  // Stack the title above the body, with the pair vertically centered
+  // in the text column. The title sits 8% above center; body sits 2%
+  // below — these offsets keep both lines visible at the small card
+  // sizes used by the inline preview gutter without overflowing.
+  const titleY = stack ? '60%' : body ? '42%' : '50%';
+  const bodyY = stack ? '78%' : title ? '55%' : '50%';
+  const textAnchor = side === 'right' && !stack ? 'top-right' : 'top-left';
+  const textAlign: 'left' | 'right' = side === 'right' && !stack ? 'right' : 'left';
+
+  // Paint our own background so the text column has a theme-paired
+  // surface to sit on. The host wrapper's surface isn't always theme-
+  // aware (e.g. the InlinePreviewGutter card uses a fixed light SVG
+  // background), and `theme.colors.text` is only guaranteed legible
+  // against `theme.colors.background` — themes like Gezellig pair
+  // cream text with a dark warm-brown background, which would
+  // disappear on a light wrapper. Matching the convention every other
+  // text-bearing template uses (see twoColumn / listBlock).
+  const layers: Layer[] = [
+    {
+      type: 'shape',
+      id: 'feature-bg',
+      content: { shape: 'rect', fill: theme.colors.background },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+  ];
+
+  if (imageSrc) {
+    layers.push({
+      type: 'image',
+      id: 'feature-image',
+      content: {
+        src: imageSrc,
+        alt: imageAlt ?? title ?? '',
+        fit: imageFit,
+      },
+      position: { x: imgX, y: imgY, width: imgW, height: imgH },
+    });
+  }
+
+  if (title) {
+    layers.push({
+      type: 'text',
+      id: 'feature-title',
+      content: {
+        text: title,
+        style: {
+          fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
+          fontWeight: 'bold',
+          color: theme.colors.text,
+          textAlign,
+          lineHeight: 1.2,
+        },
+      },
+      position: {
+        x: textX,
+        y: titleY,
+        anchor: textAnchor,
+        width: `${textColumnWidth}%`,
+      },
+      animation: { type: 'fadeIn', duration: 0.8 },
+    });
+  }
+
+  if (body) {
+    layers.push({
+      type: 'text',
+      id: 'feature-body',
+      content: {
+        text: body,
+        style: {
+          fontSize: bodyFontSize,
+          fontFamily: getThemeFont(context, 'body'),
+          color: theme.colors.textMuted,
+          textAlign,
+          lineHeight: 1.5,
+        },
+      },
+      position: {
+        x: textX,
+        y: bodyY,
+        anchor: textAnchor,
+        width: `${textColumnWidth}%`,
+      },
+      animation: { type: 'fadeIn', duration: 0.8, delay: 0.2 },
+    });
+  }
+
+  return layers;
+}
+
+export function leftFeature(input: LeftFeatureInput, context: TemplateContext): Layer[] {
+  return buildFeatureLayers(input, context, 'left');
+}
+
+export function rightFeature(input: RightFeatureInput, context: TemplateContext): Layer[] {
+  return buildFeatureLayers(input, context, 'right');
+}

package/src/doc/templates/fullBleedQuote.ts

@@ -13,6 +13,19 @@ import type { FullBleedQuoteInput, TemplateContext } from '../../schemas/BlockTe
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
 import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
 
+/**
+ * Hint schema published for the theme validator + future customizer hint UI.
+ * Themes may set `templateHints.fullBleedQuote` entries matching these keys.
+ */
+export const fullBleedQuoteHintSchema = {
+  /** Entrance style for the quote text. 'subtle' or 'dramatic'. */
+  entrance: {
+    type: 'string' as const,
+    options: ['subtle', 'dramatic'] as const,
+    default: 'subtle',
+  },
+} as const;
+
 export function fullBleedQuote(input: FullBleedQuoteInput, context: TemplateContext): Layer[] {
   const { text, colorScheme = 'blue' } = input;
   const { theme } = context;

package/src/doc/templates/index.ts

@@ -35,6 +35,7 @@ import { factCard } from './factCard.js';
 import { twoColumn } from './twoColumn.js';
 import { dateEvent } from './dateEvent.js';
 import { imageWithCaption } from './imageWithCaption.js';
+import { leftFeature, rightFeature } from './featureBlock.js';
 import { mapBlock } from './mapBlock.js';
 import { fullBleedQuote } from './fullBleedQuote.js';
 import { listBlock } from './listBlock.js';
@@ -47,22 +48,33 @@ import { videoPullQuote } from './videoPullQuote.js';
 import { dataTable } from './dataTable.js';
 
 /**
- * Registry mapping template names to their implementation functions.
- * Note: coverBlock is not in the registry as it's used directly for start blocks,
- * not as a regular template in the block sequence.
+ * Registry mapping template ids (the strings that appear in
+ * `{[name]}` markdown annotations) to their implementation functions.
+ *
+ * Some implementation functions keep historical "Block" suffixes
+ * (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`) for source
+ * readability — the registry surfaces them under the cleaner short
+ * ids (`title`, `quote`, `map`, `list`). {@link TEMPLATE_ALIASES} keeps
+ * the legacy long ids resolvable for documents written before the
+ * rename.
+ *
+ * Note: coverBlock is not in the registry as it's used directly for
+ * start blocks, not as a regular template in the block sequence.
  */
 export const templateRegistry: TemplateRegistry = {
-  titleBlock,
+  title: titleBlock,
   sectionHeader,
   statHighlight,
-  quoteBlock,
+  quote: quoteBlock,
   factCard,
   twoColumn,
   dateEvent,
   imageWithCaption,
-  mapBlock,
+  leftFeature,
+  rightFeature,
+  map: mapBlock,
   fullBleedQuote,
-  listBlock,
+  list: listBlock,
   photoGrid,
   definitionCard,
   comparisonBar,
@@ -72,11 +84,35 @@ export const templateRegistry: TemplateRegistry = {
   dataTable,
 };
 
+/**
+ * Back-compat: maps legacy template ids (kept around for documents
+ * authored before the "Block" suffix was dropped) to the canonical
+ * short ids. Resolved by {@link resolveTemplateName} so both the
+ * registry lookup and `hasTemplate()` accept either form.
+ */
+export const TEMPLATE_ALIASES: Readonly<Record<string, string>> = {
+  titleBlock: 'title',
+  quoteBlock: 'quote',
+  mapBlock: 'map',
+  listBlock: 'list',
+};
+
+/**
+ * Resolve a template id through {@link TEMPLATE_ALIASES}. Returns the
+ * input unchanged when no alias is registered.
+ */
+export function resolveTemplateName(name: string): string {
+  return TEMPLATE_ALIASES[name] ?? name;
+}
+
 /**
  * Expand a template block into a full Block with layers.
  */
 export function expandTemplateBlock(templateBlock: TemplateBlock, context: TemplateContext): Block {
-  const templateFn = templateRegistry[templateBlock.template];
+  const resolved = resolveTemplateName(templateBlock.template);
+  const templateFn = (templateRegistry as Record<string, unknown>)[resolved] as
+    | ((input: TemplateBlock, ctx: TemplateContext) => Layer[])
+    | undefined;
 
   if (!templateFn) {
     console.warn(`Unknown template: ${templateBlock.template}`);
@@ -94,12 +130,7 @@ export function expandTemplateBlock(templateBlock: TemplateBlock, context: Templ
   // Generate layers from template with error handling
   let layers: Layer[];
   try {
-    // Each registry entry accepts its specific TemplateBlock variant; the
-    // discriminated union guarantees the shapes match at runtime.
-    layers = (templateFn as (input: TemplateBlock, ctx: TemplateContext) => Layer[])(
-      templateBlock,
-      context,
-    );
+    layers = templateFn(templateBlock, context);
     if (!Array.isArray(layers)) {
       console.error(
         `Template ${templateBlock.template} did not return an array, got:`,
@@ -503,10 +534,12 @@ export function getAvailableTemplates(): string[] {
 }
 
 /**
- * Check if a template exists.
+ * Check if a template exists. Accepts both the canonical short id
+ * (`title`, `quote`, `map`, `list`) and legacy aliases
+ * (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`).
  */
 export function hasTemplate(name: string): boolean {
-  return name in templateRegistry;
+  return resolveTemplateName(name) in templateRegistry;
 }
 
 // Re-export types and utilities from schemas
@@ -556,6 +589,7 @@ export { factCard } from './factCard.js';
 export { twoColumn } from './twoColumn.js';
 export { dateEvent } from './dateEvent.js';
 export { imageWithCaption } from './imageWithCaption.js';
+export { leftFeature, rightFeature } from './featureBlock.js';
 export { mapBlock } from './mapBlock.js';
 export { coverBlock, expandCoverBlock } from './coverBlock.js';
 export type { CoverBlockInput } from './coverBlock.js';

package/src/doc/templates/listBlock.ts

@@ -15,7 +15,13 @@ import { getThemeFont } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
 export function listBlock(input: ListBlockInput, context: TemplateContext): Layer[] {
-  const { items, title, accentImage } = input;
+  const { title, accentImage } = input;
+  // `items` is required by the schema, but malformed / partially-authored
+  // blocks (e.g. someone wrote `template: list` with no items yet) reach
+  // this code path during live preview. Treat missing/non-array as empty
+  // so we render the title-and-background frame instead of blowing up
+  // every keystroke with a TypeError.
+  const items: string[] = Array.isArray(input.items) ? input.items : [];
   const { theme } = context;
 
   // Get layout adjustments if accent image is present
@@ -68,7 +74,20 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
     });
   }
 
-  // Calculate vertical spacing for items
+  // Left edge of the text column — derived from the center+width pair so
+  // items sit flush with the column's left margin instead of being
+  // centered. Falls back to a safe 8% if the layout strings ever turn
+  // out unparseable (they're authored, but defensive against future
+  // edits to the accent-layout types).
+  const centerX = parseFloat(accentLayout.textCenterX);
+  const widthPct = parseFloat(accentLayout.textWidth);
+  const leftX =
+    Number.isFinite(centerX) && Number.isFinite(widthPct) ? `${centerX - widthPct / 2}%` : '8%';
+
+  // Calculate vertical spacing for items. We keep the available band
+  // (startY → endY) but use a tighter line-height (1.2) so wrapped
+  // items don't bleed into the next entry as aggressively as the old
+  // 1.4 value did.
   const endY = 80;
   const spacing = items.length > 1 ? (endY - startY) / (items.length - 1) : 0;
 
@@ -86,14 +105,14 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           fontSize: itemFontSize,
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
-          lineHeight: 1.4,
+          textAlign: 'left',
+          lineHeight: 1.2,
           shadow: !!accentImage,
         },
       },
       position: {
-        x: accentLayout.textCenterX,
+        x: leftX,
         y: adjustY(`${y}%`, accentLayout),
-        anchor: 'center',
         width: accentLayout.textWidth,
       },
       animation: { type: 'fadeIn', duration: 0.8, delay: 0.3 + 0.3 * i },

package/src/doc/templates/statHighlight.ts

@@ -17,6 +17,19 @@ import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
+/**
+ * Hint schema published for the theme validator + future customizer hint UI.
+ * Themes may set `templateHints.statHighlight` entries matching these keys.
+ */
+export const statHighlightHintSchema = {
+  /** Entrance style for the stat number. 'subtle' or 'dramatic'. */
+  entrance: {
+    type: 'string' as const,
+    options: ['subtle', 'dramatic'] as const,
+    default: 'subtle',
+  },
+} as const;
+
 export function statHighlight(input: StatHighlightInput, context: TemplateContext): Layer[] {
   const { stat, description, detail, colorScheme = 'blue', accentImage } = input;
   const { theme } = context;

package/src/doc/templates/titleBlock.ts

@@ -13,6 +13,15 @@ import type { TitleBlockInput, TemplateContext } from '../../schemas/BlockTempla
 import { scaledFontSize } from '../../schemas/BlockTemplates.js';
 import { getThemeFont } from '../utils/themeUtils.js';
 
+/**
+ * Hint schema published for the theme validator + future customizer hint UI.
+ * Themes may set `templateHints.title` entries matching these keys.
+ */
+export const titleBlockHintSchema = {
+  /** Whether to render a thin accent line above the title. Default: theme-dependent. */
+  showAccentLine: { type: 'boolean' as const, default: true },
+} as const;
+
 export function titleBlock(input: TitleBlockInput, context: TemplateContext): Layer[] {
   const { title, subtitle, backgroundColor } = input;
   const { theme, layout } = context;

package/src/doc/utils/themeUtils.ts

@@ -9,6 +9,7 @@
 import type { TemplateContext } from '../../schemas/BlockTemplates.js';
 import type { ThemeColorScheme, RenderStyle } from '../../schemas/Theme.js';
 import type { AnimationType } from '../../schemas/Doc.js';
+import { resolveFontFamily } from '../../schemas/fontStacks.js';
 
 // ============================================
 // Color Scheme Resolution
@@ -47,22 +48,22 @@ const FALLBACK_TITLE = 'Georgia, "Times New Roman", serif';
 const FALLBACK_MONO = 'Consolas, "Courier New", monospace';
 
 /**
- * Get the theme font family for a given role.
+ * Get the theme font family for a given role, resolved to a CSS string.
  * Templates call this to set `fontFamily` on text layers.
  *
- * @param context Template context (includes theme with typography settings)
- * @param role    'title' for headings, 'body' for descriptions, 'mono' for code
- * @returns A CSS font-family string with the theme's font and safe fallbacks
+ * 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 typography.titleFontFamily || FALLBACK_TITLE;
+      return resolveFontFamily(typography.titleFont, FALLBACK_TITLE);
     case 'body':
-      return typography.bodyFontFamily || FALLBACK_BODY;
+      return resolveFontFamily(typography.bodyFont, FALLBACK_BODY);
     case 'mono':
-      return typography.monoFontFamily || FALLBACK_MONO;
+      return resolveFontFamily(typography.monoFont, FALLBACK_MONO);
   }
 }
 

package/src/generate/slideshowGenerator.ts

@@ -158,7 +158,7 @@ export function generateSlideshow(
   if (title) {
     const titleBlock: TitleBlockInput = {
       id: `slide-${slideIndex++}`,
-      template: 'titleBlock',
+      template: 'title',
       title,
       subtitle,
       duration: Math.min(perSlide, 6),

package/src/generate/templateMapper.ts

@@ -109,7 +109,7 @@ function mapDate(data: DateData, base: Base, opts: MapOptions): DateEventInput {
 function mapQuote(data: QuoteData, base: Base, opts: MapOptions): QuoteBlockInput {
   return {
     ...base,
-    template: 'quoteBlock',
+    template: 'quote',
     quote: data.quote,
     attribution: data.attribution,
     accentImage: opts.accentImage,
@@ -149,7 +149,7 @@ function mapImpactLine(data: ImpactLineData, base: Base, opts: MapOptions): Full
 function mapList(data: ListData, base: Base, opts: MapOptions): ListBlockInput {
   return {
     ...base,
-    template: 'listBlock',
+    template: 'list',
     items: data.items,
     title: data.title,
     colorScheme: opts.colorScheme,