@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/templates/pullQuote.ts

@@ -10,18 +10,28 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { PullQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  themedEntrance,
+  themedFontSize,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
+import { estimateTextHeight } from './captionUtils.js';
 
 export function pullQuote(input: PullQuoteInput, context: TemplateContext): Layer[] {
   const { text, attribution, backgroundImage, ambientMotion } = input;
+  const { viewport } = context;
+
+  const treatment = themedImageTreatment(context, input.imageTreatment);
 
   // Guard: backgroundImage is required
   if (!backgroundImage?.src) return [];
 
-  const quoteFontSize = scaledFontSize(52, context, true);
-  const attrFontSize = scaledFontSize(24, context, false);
-  const decoFontSize = scaledFontSize(200, context, true);
+  const quoteFontSize = themedFontSize(52, context, true);
+  const attrFontSize = themedFontSize(26, context, false);
+  const decoFontSize = themedFontSize(200, context, true);
+  const quoteLineHeight = 1.4;
+  const quoteYPct = attribution ? 45 : 50;
 
   const layers: Layer[] = [
     // Full-bleed background image
@@ -34,6 +44,7 @@ export function pullQuote(input: PullQuoteInput, context: TemplateContext): Laye
         fit: 'cover',
         credit: backgroundImage.credit,
         license: backgroundImage.license,
+        ...(treatment ? { treatment } : {}),
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
       animation: ambientMotion ? { type: ambientMotion, duration: 15 } : undefined,
@@ -81,22 +92,29 @@ export function pullQuote(input: PullQuoteInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'title'),
           color: '#ffffff',
           textAlign: 'center',
-          lineHeight: 1.5,
+          lineHeight: quoteLineHeight,
           shadow: true,
         },
       },
       position: {
         x: '50%',
-        y: attribution ? '45%' : '50%',
+        y: `${quoteYPct}%`,
         anchor: 'center',
-        width: '80%',
+        width: '72%',
       },
-      animation: { type: 'fadeIn', duration: 2 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 }),
     },
   ];
 
-  // Attribution
+  // Attribution \u2014 hangs just below the quote's estimated bottom edge so
+  // the two read as one lockup instead of stranding near the bottom.
   if (attribution) {
+    const quoteWidthPx = 0.72 * viewport.width;
+    const quoteHeightPx = estimateTextHeight(text, quoteFontSize, quoteWidthPx, quoteLineHeight);
+    const attrYPct = Math.min(
+      82,
+      quoteYPct + ((quoteHeightPx / 2 + quoteFontSize * 1.7) / viewport.height) * 100,
+    );
     layers.push({
       type: 'text',
       id: 'attribution',
@@ -105,14 +123,14 @@ export function pullQuote(input: PullQuoteInput, context: TemplateContext): Laye
         style: {
           fontSize: attrFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: 'rgba(255, 255, 255, 0.7)',
+          color: 'rgba(255, 255, 255, 0.85)',
           textAlign: 'center',
           shadow: true,
         },
       },
       position: {
         x: '50%',
-        y: '72%',
+        y: `${attrYPct}%`,
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 1.5 },

package/src/doc/templates/quoteBlock.ts

@@ -1,8 +1,10 @@
 /**
  * Quote Block Template
  *
- * Large centered quote with optional attribution.
- * Good for impactful statements or descriptions.
+ * Large centered quote with optional attribution, composed as one
+ * vertically-centered lockup: the attribution hangs a fixed distance
+ * below the quote's estimated bottom edge instead of being pinned to a
+ * far-away layout slot.
  * Adapts font sizes and positioning for different viewports.
  *
  * Supports optional accent images that appear as tasteful side/bottom strips.
@@ -12,59 +14,72 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { QuoteBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+  themedSurfaceGradient,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
-import { createBackgroundLayer } from './captionUtils.js';
+import { createBackgroundLayer, estimateTextHeight } from './captionUtils.js';
 
 export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): Layer[] {
   const { quote, attribution, accentImage } = input;
-  const { theme, layout } = context;
+  const { theme, viewport } = context;
 
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
   // Scale font sizes for viewport
-  const quoteFontSize = scaledFontSize(48, context, true);
-  const attrFontSize = scaledFontSize(24, context, false);
+  const quoteFontSize = themedFontSize(48, context, true);
+  const attrFontSize = themedFontSize(26, context, false);
+  const quoteLineHeight = Math.max(theme.typography.titleLineHeight ?? 1.4, 1.25);
 
   // Decorative quotation mark font size
-  const decorativeQuoteFontSize = scaledFontSize(280, context, true);
+  const decorativeQuoteFontSize = themedFontSize(280, context, true);
 
-  const layers: Layer[] = [
-    createBackgroundLayer(
-      'bg',
-      `linear-gradient(160deg, ${theme.colors.backgroundLight} 0%, #1e2636 100%)`,
-    ),
-  ];
+  const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 160))];
 
   // Add accent image layers (behind text, after background)
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
-  // Decorative opening quotation mark — oversized, low-opacity behind quote
+  // Decorative opening quotation mark — oversized, low-opacity behind the
+  // quote. Derived from the theme text color so it stays a subtle ornament
+  // on light and dark surfaces alike (a hard-coded white glyph was
+  // invisible on both).
   layers.push({
     type: 'text',
     id: 'deco-quote',
     content: {
-      text: '\u201C',
+      text: '“',
       style: {
         fontSize: decorativeQuoteFontSize,
         fontFamily: getThemeFont(context, 'title'),
-        color: 'rgba(255, 255, 255, 0.06)',
+        color: withAlpha(theme.colors.text, 0.09),
         textAlign: 'center',
       },
     },
     position: {
       x: accentLayout.textCenterX,
-      y: adjustY('18%', accentLayout),
+      y: adjustY('26%', accentLayout),
       anchor: 'center',
     },
   });
 
-  // Quote text - positioned based on accent layout
-  const quoteY = attribution ? layout.primaryY : '50%';
+  // Quote text — optically centered, nudged up slightly when an
+  // attribution hangs below it.
+  const quoteYPct = attribution ? 45 : 50;
   layers.push({
     type: 'text',
     id: 'quote',
@@ -75,21 +90,31 @@ export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): La
         fontFamily: getThemeFont(context, 'title'),
         color: theme.colors.text,
         textAlign: 'center',
-        lineHeight: 1.6,
-        shadow: true,
+        lineHeight: quoteLineHeight,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
       x: accentLayout.textCenterX,
-      y: adjustY(quoteY, accentLayout),
+      y: adjustY(`${quoteYPct}%`, accentLayout),
       anchor: 'center',
       width: accentLayout.textWidth,
     },
-    animation: { type: 'fadeIn', duration: 2 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 }),
   });
 
-  // Add attribution if provided
+  // Attribution hangs just below the quote's estimated bottom edge, so
+  // the two read as one lockup instead of the attribution stranding near
+  // the bottom of the block.
   if (attribution) {
+    const quoteWidthPx = (parseFloat(accentLayout.textWidth) / 100) * viewport.width;
+    const quoteHeightPx = estimateTextHeight(quote, quoteFontSize, quoteWidthPx, quoteLineHeight);
+    const gapPx = quoteFontSize * 1.7;
+    const attrYPct = Math.min(
+      82,
+      quoteYPct + ((quoteHeightPx / 2 + gapPx) / viewport.height) * 100,
+    );
+
     layers.push({
       type: 'text',
       id: 'attribution',
@@ -100,12 +125,12 @@ export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): La
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: accentLayout.textCenterX,
-        y: adjustY(layout.captionY, accentLayout),
+        y: adjustY(`${attrYPct}%`, accentLayout),
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 1.5 },

package/src/doc/templates/sectionHeader.ts

@@ -11,16 +11,27 @@
 
 import type { Layer, AnimationType } from '../../schemas/Doc.js';
 import type { SectionHeaderInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
+import {
+  resolveColorScheme,
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+  themedScrim,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 
 export function sectionHeader(input: SectionHeaderInput, context: TemplateContext): Layer[] {
   const { title = '', colorScheme = 'blue', imageSrc, imageAlt, ambientMotion } = input;
-  const { layout } = context;
+  const { theme, layout } = context;
+
+  const treatment = themedImageTreatment(context, input.imageTreatment);
   const colors = resolveColorScheme(context, colorScheme);
 
-  // Scale font sizes for viewport
-  const titleFontSize = scaledFontSize(72, context, true);
+  // Scale font sizes for viewport. Section dividers are the loudest
+  // interstitial in a doc, so the title sits a step above ordinary
+  // content-block headings.
+  const titleFontSize = themedFontSize(84, context, true);
 
   const layers: Layer[] = [];
 
@@ -34,6 +45,7 @@ export function sectionHeader(input: SectionHeaderInput, context: TemplateContex
         src: imageSrc,
         alt: imageAlt || title,
         fit: 'cover',
+        ...(treatment ? { treatment } : {}),
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
       animation: ambientMotion
@@ -41,13 +53,14 @@ export function sectionHeader(input: SectionHeaderInput, context: TemplateContex
         : { type: 'slowZoom', duration: 8, direction: 'in' },
     });
 
-    // Dark overlay for text readability
+    // Theme-tinted overlay for text readability — light themes get a
+    // light scrim with dark theme text, dark themes the familiar dark one.
     layers.push({
       type: 'shape',
       id: 'overlay',
       content: {
         shape: 'rect',
-        fill: 'rgba(0, 0, 0, 0.5)',
+        fill: themedScrim(context),
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     });
@@ -78,7 +91,8 @@ export function sectionHeader(input: SectionHeaderInput, context: TemplateContex
     });
   }
 
-  // Section title - white text with shadow for readability over images
+  // Section title — theme text over the theme-tinted scrim (readable by
+  // construction), scheme text on the solid-color fallback
   layers.push({
     type: 'text',
     id: 'title',
@@ -88,9 +102,9 @@ export function sectionHeader(input: SectionHeaderInput, context: TemplateContex
         fontSize: titleFontSize,
         fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
-        color: imageSrc ? '#ffffff' : colors.text,
+        color: imageSrc ? theme.colors.text : colors.text,
         textAlign: 'center',
-        shadow: true,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -99,7 +113,7 @@ export function sectionHeader(input: SectionHeaderInput, context: TemplateContex
       anchor: 'center',
       width: layout.maxTextWidth,
     },
-    animation: { type: 'fadeIn', duration: 1.5 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1.5 }),
   });
 
   return layers;

package/src/doc/templates/statHighlight.ts

@@ -12,8 +12,15 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { StatHighlightInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
+import {
+  resolveColorScheme,
+  getTemplateHint,
+  getThemeFont,
+  shouldUseShadow,
+  themedFontSize,
+  themedSurfaceGradient,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
@@ -39,20 +46,21 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
   // Scale font sizes — stat is dramatically large, description is understated
-  const statFontSize = scaledFontSize(148, context, true);
-  const descFontSize = scaledFontSize(32, context, false);
-  const detailFontSize = scaledFontSize(26, context, false);
+  const statFontSize = themedFontSize(148, context, true);
+  const descFontSize = themedFontSize(32, context, false);
+  const detailFontSize = themedFontSize(26, context, false);
 
-  const layers: Layer[] = [
-    createBackgroundLayer(
-      'bg',
-      `linear-gradient(180deg, ${theme.colors.background} 0%, #0f1520 100%)`,
-    ),
-  ];
+  const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 180))];
 
   // Add accent image layers (behind text, after background)
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
   // Big stat — hero element, dominates the slide
@@ -66,18 +74,23 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
         fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
         color: colors.text,
-        shadow: !!accentImage,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
       x: accentLayout.textCenterX,
-      y: adjustY('32%', accentLayout),
+      y: adjustY('36%', accentLayout),
       anchor: 'center',
     },
-    animation: { type: 'zoomIn', duration: 0.6 },
+    animation:
+      getTemplateHint<string>(context, 'statHighlight', 'entrance', 'subtle') === 'dramatic'
+        ? { type: 'zoomIn', duration: 0.4 }
+        : { type: 'zoomIn', duration: 0.6 },
   });
 
-  // Description — smaller and understated beneath the stat
+  // Description — smaller and understated beneath the stat. Sits close
+  // under the stat (the ~26% fixed gap it used to get read as two
+  // unrelated elements floating in the panel).
   layers.push({
     type: 'text',
     id: 'description',
@@ -88,13 +101,13 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
         fontFamily: getThemeFont(context, 'body'),
         color: theme.colors.textMuted,
         textAlign: 'center',
-        lineHeight: 1.6,
-        shadow: !!accentImage,
+        lineHeight: 1.5,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
       x: accentLayout.textCenterX,
-      y: adjustY('58%', accentLayout),
+      y: adjustY('54%', accentLayout),
       width: accentLayout.textWidth,
       anchor: 'center',
     },
@@ -111,14 +124,18 @@ export function statHighlight(input: StatHighlightInput, context: TemplateContex
         style: {
           fontSize: detailFontSize,
           fontFamily: getThemeFont(context, 'body'),
-          color: colors.accent,
+          // Scheme *text* rather than *accent*: accents in the built-in
+          // schemes are tuned as chart/fill colors and drop below legible
+          // contrast as body copy on light surfaces.
+          color: colors.text,
           textAlign: 'center',
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: accentLayout.textCenterX,
-        y: adjustY('75%', accentLayout),
+        y: adjustY('66%', accentLayout),
+        width: accentLayout.textWidth,
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 1 },

package/src/doc/templates/titleBlock.ts

@@ -2,7 +2,9 @@
  * Title Block Template
  *
  * Large title with optional subtitle for doc intros.
- * Centered text with fade-in animations.
+ * Centered text with fade-in animations, composed as one lockup:
+ * accent rule, title, and subtitle are spaced from the title's
+ * estimated height instead of fixed slots that collide on wrap.
  * Adapts font sizes and positioning for different viewports.
  *
  * This is shared code used by both site and efb-app doc renderers.
@@ -10,8 +12,15 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { TitleBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getTemplateHint,
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+} from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
+import { estimateTextHeight } from './captionUtils.js';
 
 /**
  * Hint schema published for the theme validator + future customizer hint UI.
@@ -24,40 +33,68 @@ export const titleBlockHintSchema = {
 
 export function titleBlock(input: TitleBlockInput, context: TemplateContext): Layer[] {
   const { title, subtitle, backgroundColor } = input;
-  const { theme, layout } = context;
+  const { theme, layout, viewport } = context;
 
   // Scale font sizes for viewport
-  const titleFontSize = scaledFontSize(96, context, true);
-  const subtitleFontSize = scaledFontSize(36, context, false);
+  const titleFontSize = themedFontSize(96, context, true);
+  const subtitleFontSize = themedFontSize(36, context, false);
 
   const baseBg = backgroundColor || theme.colors.primary;
 
+  // Estimate the title's rendered height so the rule and subtitle key off
+  // its real extent — fixed slots let the rule overlap the ascenders and
+  // stranded the subtitle when the title wrapped.
+  const maxWidthPx = (parseFloat(layout.maxTextWidth) / 100) * viewport.width;
+  const titleH = estimateTextHeight(title, titleFontSize, maxWidthPx, 1.15);
+  const titleYPct = subtitle ? 42 : 48;
+  const px = (v: number) => (v / viewport.height) * 100;
+
   const layers: Layer[] = [
-    // Background — radial gradient for depth instead of flat color
+    // Background — theme surface with a soft radial accent tint. The tint
+    // is translucent so the theme's text color keeps its contrast with the
+    // surface; a full-strength `primary` hotspot behind the title made
+    // dark-primary light themes unreadable.
     {
       type: 'shape',
       id: 'bg',
       content: {
         shape: 'rect',
-        fill: `radial-gradient(ellipse at 50% 40%, ${baseBg} 0%, ${theme.colors.background} 100%)`,
+        fill: theme.colors.background,
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     },
-    // Subtle decorative line above title
     {
+      type: 'shape',
+      id: 'bg-tint',
+      content: {
+        shape: 'rect',
+        fill: `radial-gradient(ellipse at 50% 40%, ${withAlpha(baseBg, 0.32)} 0%, ${withAlpha(baseBg, 0)} 75%)`,
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+  ];
+
+  // Subtle decorative line, clear above the title's ascenders. Themes can
+  // hide it via `templateHints.title.showAccentLine: false` (the line is
+  // decorative; title/subtitle positions don't depend on it).
+  if (getTemplateHint(context, 'title', 'showAccentLine', true)) {
+    layers.push({
       type: 'shape',
       id: 'accent-line',
       content: {
         shape: 'rect',
-        fill: 'rgba(255, 255, 255, 0.2)',
+        fill: withAlpha(theme.colors.text, 0.3),
       },
       position: {
-        x: '40%',
-        y: subtitle ? '28%' : '38%',
-        width: '20%',
-        height: '2px',
+        x: '44%',
+        y: `${titleYPct - px(titleH / 2 + 56)}%`,
+        width: '12%',
+        height: '3px',
       },
-    },
+    });
+  }
+
+  layers.push(
     // Title
     {
       type: 'text',
@@ -70,21 +107,22 @@ export function titleBlock(input: TitleBlockInput, context: TemplateContext): La
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: '50%',
-        y: subtitle ? layout.primaryY : '50%',
+        y: `${titleYPct}%`,
         anchor: 'center',
         width: layout.maxTextWidth,
       },
-      animation: { type: 'fadeIn', duration: 2 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 }),
     },
-  ];
+  );
 
-  // Add subtitle if provided
+  // Add subtitle if provided — hangs from the title's estimated bottom edge
   if (subtitle) {
+    const subH = estimateTextHeight(subtitle, subtitleFontSize, maxWidthPx, 1.5);
     layers.push({
       type: 'text',
       id: 'subtitle',
@@ -100,7 +138,7 @@ export function titleBlock(input: TitleBlockInput, context: TemplateContext): La
       },
       position: {
         x: '50%',
-        y: layout.secondaryY,
+        y: `${titleYPct + px(titleH / 2 + 56 + subH / 2)}%`,
         anchor: 'center',
         width: layout.maxTextWidth,
       },