@bendyline/squisq 1.4.1 → 1.5.1

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,
       },