@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/utils/shapeGeometry.ts

@@ -0,0 +1,464 @@
+/**
+ * shapeGeometry — pure SVG geometry for the drawing/diagram shape vocabulary.
+ *
+ * Three concerns, all deterministic and dependency-free:
+ *  - `shapePath(kind, x, y, w, h)` → an SVG path `d` for a named shape inscribed
+ *    in a bounding box. Returns null for the natively-rendered primitives
+ *    (rect / circle / line / text / path) so the caller can keep using a
+ *    `ShapeLayer` for those; everything else becomes a computed `PathLayer`.
+ *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
+ *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
+ *    editor's edge renderer).
+ *  - `connectorPath(routing, start, end)` + `clipEndpoints(a, b)` → the line/edge
+ *    geometry between two shapes (straight / orthogonal / curved), lifted from the
+ *    diagram template so drawings and diagrams draw identical connectors.
+ */
+
+import type { MarkerStyle } from '../../schemas/Doc.js';
+
+// ============================================
+// Shapes
+// ============================================
+
+/** Connector routing styles. */
+export type ConnectorRouting = 'straight' | 'orthogonal' | 'curved';
+
+/**
+ * Shape kinds rendered as computed paths (everything except the primitives the
+ * renderer draws natively). Used by templates to decide ShapeLayer vs PathLayer.
+ */
+export const PATH_SHAPE_KINDS = new Set([
+  'triangle',
+  'right-triangle',
+  'diamond',
+  'pentagon',
+  'hexagon',
+  'octagon',
+  'star',
+  'star4',
+  'star6',
+  'parallelogram',
+  'trapezoid',
+  'plus',
+  'chevron',
+  'arrow-right',
+  'arrow-left',
+  'arrow-up',
+  'arrow-down',
+  'double-arrow',
+  'callout',
+  'cylinder',
+  'cloud',
+  'heart',
+  'lightning',
+]);
+
+/** Round to 1 decimal for compact, stable path output. */
+function r(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+
+/** Close a list of points into an `M … L … Z` polygon path. */
+function poly(points: ReadonlyArray<readonly [number, number]>): string {
+  if (points.length === 0) return '';
+  const [first, ...rest] = points;
+  const head = `M ${r(first[0])} ${r(first[1])}`;
+  const tail = rest.map(([x, y]) => `L ${r(x)} ${r(y)}`).join(' ');
+  return `${head} ${tail} Z`;
+}
+
+/** Regular polygon points inscribed in the box ellipse, `rotation` in radians. */
+function regular(
+  cx: number,
+  cy: number,
+  rx: number,
+  ry: number,
+  sides: number,
+  rotation: number,
+): Array<[number, number]> {
+  const pts: Array<[number, number]> = [];
+  for (let i = 0; i < sides; i++) {
+    const a = rotation + (i * 2 * Math.PI) / sides;
+    pts.push([cx + rx * Math.cos(a), cy + ry * Math.sin(a)]);
+  }
+  return pts;
+}
+
+/** Star points alternating outer/inner radius. */
+function star(
+  cx: number,
+  cy: number,
+  rx: number,
+  ry: number,
+  spikes: number,
+  innerRatio: number,
+): Array<[number, number]> {
+  const pts: Array<[number, number]> = [];
+  const rot = -Math.PI / 2; // first point up
+  for (let i = 0; i < spikes * 2; i++) {
+    const outer = i % 2 === 0;
+    const a = rot + (i * Math.PI) / spikes;
+    const fx = outer ? rx : rx * innerRatio;
+    const fy = outer ? ry : ry * innerRatio;
+    pts.push([cx + fx * Math.cos(a), cy + fy * Math.sin(a)]);
+  }
+  return pts;
+}
+
+/**
+ * SVG path `d` for a named shape inscribed in `[x, y, w, h]`, or null when the
+ * kind is rendered natively (rect / circle / line / text / path / arrow).
+ */
+export function shapePath(kind: string, x: number, y: number, w: number, h: number): string | null {
+  const cx = x + w / 2;
+  const cy = y + h / 2;
+  const rx = w / 2;
+  const ry = h / 2;
+  const right = x + w;
+  const bottom = y + h;
+
+  switch (kind) {
+    case 'triangle':
+      return poly([
+        [cx, y],
+        [right, bottom],
+        [x, bottom],
+      ]);
+    case 'right-triangle':
+      return poly([
+        [x, y],
+        [x, bottom],
+        [right, bottom],
+      ]);
+    case 'diamond':
+      return poly([
+        [cx, y],
+        [right, cy],
+        [cx, bottom],
+        [x, cy],
+      ]);
+    case 'pentagon':
+      return poly(regular(cx, cy, rx, ry, 5, -Math.PI / 2));
+    case 'hexagon': {
+      // Flat top/bottom hexagon: inset the left/right vertices.
+      const inset = w * 0.25;
+      return poly([
+        [x + inset, y],
+        [right - inset, y],
+        [right, cy],
+        [right - inset, bottom],
+        [x + inset, bottom],
+        [x, cy],
+      ]);
+    }
+    case 'octagon': {
+      const cut = Math.min(w, h) * 0.29;
+      return poly([
+        [x + cut, y],
+        [right - cut, y],
+        [right, y + cut],
+        [right, bottom - cut],
+        [right - cut, bottom],
+        [x + cut, bottom],
+        [x, bottom - cut],
+        [x, y + cut],
+      ]);
+    }
+    case 'star':
+      return poly(star(cx, cy, rx, ry, 5, 0.4));
+    case 'star4':
+      return poly(star(cx, cy, rx, ry, 4, 0.4));
+    case 'star6':
+      return poly(star(cx, cy, rx, ry, 6, 0.5));
+    case 'parallelogram': {
+      const off = w * 0.25;
+      return poly([
+        [x + off, y],
+        [right, y],
+        [right - off, bottom],
+        [x, bottom],
+      ]);
+    }
+    case 'trapezoid': {
+      const off = w * 0.25;
+      return poly([
+        [x + off, y],
+        [right - off, y],
+        [right, bottom],
+        [x, bottom],
+      ]);
+    }
+    case 'plus': {
+      const t = Math.min(w, h) / 3; // arm thickness
+      const lx = x + (w - t) / 2;
+      const rxp = lx + t;
+      const ty = y + (h - t) / 2;
+      const byp = ty + t;
+      return poly([
+        [lx, y],
+        [rxp, y],
+        [rxp, ty],
+        [right, ty],
+        [right, byp],
+        [rxp, byp],
+        [rxp, bottom],
+        [lx, bottom],
+        [lx, byp],
+        [x, byp],
+        [x, ty],
+        [lx, ty],
+      ]);
+    }
+    case 'chevron': {
+      const notch = w * 0.25;
+      return poly([
+        [x, y],
+        [right - notch, y],
+        [right, cy],
+        [right - notch, bottom],
+        [x, bottom],
+        [x + notch, cy],
+      ]);
+    }
+    case 'arrow-right':
+      return blockArrow(x, y, w, h, 'right');
+    case 'arrow-left':
+      return blockArrow(x, y, w, h, 'left');
+    case 'arrow-up':
+      return blockArrow(x, y, w, h, 'up');
+    case 'arrow-down':
+      return blockArrow(x, y, w, h, 'down');
+    case 'double-arrow': {
+      const head = w * 0.3;
+      const bodyT = h * 0.4;
+      const ty = cy - bodyT / 2;
+      const by = cy + bodyT / 2;
+      return poly([
+        [x, cy],
+        [x + head, y],
+        [x + head, ty],
+        [right - head, ty],
+        [right - head, y],
+        [right, cy],
+        [right - head, bottom],
+        [right - head, by],
+        [x + head, by],
+        [x + head, bottom],
+      ]);
+    }
+    case 'callout': {
+      // Speech bubble: rounded-ish body (square corners for path simplicity)
+      // with a tail off the lower-left.
+      const bodyH = h * 0.78;
+      const bb = y + bodyH;
+      const tailX = x + w * 0.25;
+      return `M ${r(x)} ${r(y)} L ${r(right)} ${r(y)} L ${r(right)} ${r(bb)} L ${r(tailX + w * 0.12)} ${r(bb)} L ${r(tailX)} ${r(bottom)} L ${r(tailX - w * 0.02)} ${r(bb)} L ${r(x)} ${r(bb)} Z`;
+    }
+    case 'cylinder': {
+      const ell = h * 0.16; // ellipse half-height
+      return (
+        `M ${r(x)} ${r(y + ell)} ` +
+        `A ${r(rx)} ${r(ell)} 0 0 1 ${r(right)} ${r(y + ell)} ` +
+        `L ${r(right)} ${r(bottom - ell)} ` +
+        `A ${r(rx)} ${r(ell)} 0 0 1 ${r(x)} ${r(bottom - ell)} ` +
+        `Z ` +
+        // top ellipse outline
+        `M ${r(x)} ${r(y + ell)} ` +
+        `A ${r(rx)} ${r(ell)} 0 0 0 ${r(right)} ${r(y + ell)}`
+      );
+    }
+    case 'cloud': {
+      // Four bumps along the top + a flat-ish bottom, via arcs.
+      const b = h * 0.5;
+      return (
+        `M ${r(x + w * 0.2)} ${r(bottom)} ` +
+        `A ${r(w * 0.2)} ${r(b)} 0 0 1 ${r(x + w * 0.15)} ${r(cy)} ` +
+        `A ${r(w * 0.2)} ${r(b)} 0 0 1 ${r(x + w * 0.45)} ${r(y + h * 0.2)} ` +
+        `A ${r(w * 0.2)} ${r(b)} 0 0 1 ${r(x + w * 0.8)} ${r(y + h * 0.25)} ` +
+        `A ${r(w * 0.18)} ${r(b)} 0 0 1 ${r(x + w * 0.85)} ${r(bottom)} ` +
+        `Z`
+      );
+    }
+    case 'heart': {
+      const topY = y + h * 0.3;
+      return (
+        `M ${r(cx)} ${r(bottom)} ` +
+        `C ${r(x - w * 0.1)} ${r(cy)} ${r(x)} ${r(y)} ${r(cx)} ${r(topY)} ` +
+        `C ${r(right)} ${r(y)} ${r(right + w * 0.1)} ${r(cy)} ${r(cx)} ${r(bottom)} ` +
+        `Z`
+      );
+    }
+    case 'lightning':
+      return poly([
+        [x + w * 0.55, y],
+        [x + w * 0.2, y + h * 0.55],
+        [x + w * 0.45, y + h * 0.55],
+        [x + w * 0.3, bottom],
+        [right, y + h * 0.4],
+        [x + w * 0.55, y + h * 0.4],
+      ]);
+    default:
+      return null;
+  }
+}
+
+/** Block arrow (body rectangle + triangular head) pointing in `dir`. */
+function blockArrow(
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  dir: 'right' | 'left' | 'up' | 'down',
+): string {
+  const right = x + w;
+  const bottom = y + h;
+  const cx = x + w / 2;
+  const cy = y + h / 2;
+  if (dir === 'right' || dir === 'left') {
+    const head = w * 0.4;
+    const bodyT = h * 0.5;
+    const ty = cy - bodyT / 2;
+    const by = cy + bodyT / 2;
+    if (dir === 'right') {
+      return poly([
+        [x, ty],
+        [right - head, ty],
+        [right - head, y],
+        [right, cy],
+        [right - head, bottom],
+        [right - head, by],
+        [x, by],
+      ]);
+    }
+    return poly([
+      [right, ty],
+      [x + head, ty],
+      [x + head, y],
+      [x, cy],
+      [x + head, bottom],
+      [x + head, by],
+      [right, by],
+    ]);
+  }
+  const head = h * 0.4;
+  const bodyT = w * 0.5;
+  const lx = cx - bodyT / 2;
+  const rxp = cx + bodyT / 2;
+  if (dir === 'down') {
+    return poly([
+      [lx, y],
+      [rxp, y],
+      [rxp, bottom - head],
+      [right, bottom - head],
+      [cx, bottom],
+      [x, bottom - head],
+      [lx, bottom - head],
+    ]);
+  }
+  return poly([
+    [lx, bottom],
+    [rxp, bottom],
+    [rxp, y + head],
+    [right, y + head],
+    [cx, y],
+    [x, y + head],
+    [lx, y + head],
+  ]);
+}
+
+// ============================================
+// End markers
+// ============================================
+
+/**
+ * The `<marker>` path for a line end-style, in the 0–10 marker viewBox.
+ * `dir` selects orientation (`end` points along +x; `start` is mirrored).
+ * Returns null for `'none'`. `filled` shapes paint with the stroke color;
+ * non-filled (`open`) draw as a stroked outline.
+ */
+export function markerPath(
+  style: MarkerStyle,
+  dir: 'start' | 'end',
+): { d: string; filled: boolean } | null {
+  const mirror = dir === 'start';
+  const mx = (n: number) => (mirror ? 10 - n : n);
+  const tri = (closed: boolean) => `M ${mx(0)} 0 L ${mx(10)} 5 L ${mx(0)} 10${closed ? ' z' : ''}`;
+  switch (style) {
+    case 'arrow':
+      return { d: tri(true), filled: true };
+    case 'open':
+      return { d: tri(false), filled: false };
+    case 'diamond':
+      return { d: 'M 0 5 L 5 0 L 10 5 L 5 10 z', filled: true };
+    case 'square':
+      return { d: 'M 1 1 L 9 1 L 9 9 L 1 9 z', filled: true };
+    case 'circle':
+      return { d: 'M 0 5 A 5 5 0 1 0 10 5 A 5 5 0 1 0 0 5 z', filled: true };
+    case 'none':
+    default:
+      return null;
+  }
+}
+
+// ============================================
+// Connector routing
+// ============================================
+
+export interface ClipBox {
+  cx: number;
+  cy: number;
+  rx: number;
+  ry: number;
+}
+
+/** Intersection of the center-to-center line with `from`'s bounding box. */
+export function clipPoint(from: ClipBox, to: ClipBox): { x: number; y: number } {
+  const dx = to.cx - from.cx;
+  const dy = to.cy - from.cy;
+  if (dx === 0 && dy === 0) return { x: from.cx, y: from.cy };
+  const sx = Math.abs(dx) > 0 ? from.rx / Math.abs(dx) : Infinity;
+  const sy = Math.abs(dy) > 0 ? from.ry / Math.abs(dy) : Infinity;
+  const s = Math.min(sx, sy);
+  return { x: from.cx + dx * s, y: from.cy + dy * s };
+}
+
+/** Clip both endpoints of an edge to the two shapes it joins. */
+export function clipEndpoints(
+  a: ClipBox,
+  b: ClipBox,
+): { start: { x: number; y: number }; end: { x: number; y: number } } {
+  return { start: clipPoint(a, b), end: clipPoint(b, a) };
+}
+
+/** Build the SVG `d` for a connector between two clipped endpoints. */
+export function connectorPath(
+  routing: ConnectorRouting,
+  start: { x: number; y: number },
+  end: { x: number; y: number },
+): string {
+  if (routing === 'straight') {
+    return `M ${r(start.x)} ${r(start.y)} L ${r(end.x)} ${r(end.y)}`;
+  }
+  if (routing === 'orthogonal') {
+    const midX = (start.x + end.x) / 2;
+    return `M ${r(start.x)} ${r(start.y)} L ${r(midX)} ${r(start.y)} L ${r(midX)} ${r(end.y)} L ${r(end.x)} ${r(end.y)}`;
+  }
+  // curved
+  const dx = Math.abs(end.x - start.x);
+  const cp = Math.max(40, dx / 2);
+  return `M ${r(start.x)} ${r(start.y)} C ${r(start.x + cp)} ${r(start.y)}, ${r(end.x - cp)} ${r(end.y)}, ${r(end.x)} ${r(end.y)}`;
+}
+
+/** Map a `lineStyle` (solid|dashed|dotted) to an SVG `stroke-dasharray`. */
+export function lineStyleDasharray(style: string | undefined): string | undefined {
+  switch (style?.toLowerCase()) {
+    case 'dashed':
+    case 'dash':
+      return '8 6';
+    case 'dotted':
+    case 'dot':
+      return '2 6';
+    default:
+      return undefined;
+  }
+}

package/src/doc/utils/themeUtils.ts

@@ -8,8 +8,9 @@
 
 import type { TemplateContext } from '../../schemas/BlockTemplates.js';
 import type { ThemeColorScheme, RenderStyle } from '../../schemas/Theme.js';
-import type { AnimationType } from '../../schemas/Doc.js';
+import type { Animation, AnimationType, ImageTreatment } from '../../schemas/Doc.js';
 import { resolveFontFamily } from '../../schemas/fontStacks.js';
+import { oklchDarken, withAlpha } from '../../schemas/colorUtils.js';
 
 // ============================================
 // Color Scheme Resolution
@@ -123,6 +124,30 @@ export function getDefaultAnimation(
   return layerType === 'text' ? rs.defaultTextAnimation : rs.defaultImageAnimation;
 }
 
+/**
+ * Theme-aware entrance animation for a template layer.
+ *
+ * The theme's `renderStyle.defaultTextAnimation` / `defaultImageAnimation`
+ * overrides the entrance *type*; the template keeps its authored duration,
+ * delay, and stagger. Templates opt in per layer:
+ *
+ * ```ts
+ * animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 })
+ * ```
+ *
+ * `slowZoom` is excluded — it's an ambient treatment handled by the
+ * `applyRenderStyleToLayers` post-pass, not an entrance.
+ */
+export function themedEntrance(
+  context: TemplateContext,
+  layerType: 'text' | 'image',
+  fallback: Animation,
+): Animation {
+  const type = getDefaultAnimation(context, layerType);
+  if (!type || type === 'slowZoom' || type === fallback.type) return fallback;
+  return { ...fallback, type };
+}
+
 // ============================================
 // Style Helpers
 // ============================================
@@ -142,6 +167,55 @@ export function getOverlayOpacity(context: TemplateContext): number {
   return context.theme.style.overlayOpacity ?? 0.5;
 }
 
+/**
+ * Resolve the effective photographic treatment for a block's imagery.
+ *
+ * Precedence: the block's `imageTreatment` override ('none' opts out, a
+ * type forces that grade) → the theme's `style.imageTreatment` → none.
+ * Duotone tints default to the theme primary. Templates pass the result
+ * straight into `ImageLayer.content.treatment`.
+ */
+export function themedImageTreatment(
+  context: TemplateContext,
+  override?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool',
+): ImageTreatment | undefined {
+  if (override === 'none') return undefined;
+  const themeTreatment = context.theme.style.imageTreatment;
+  const base: ImageTreatment | undefined = override
+    ? { type: override, strength: themeTreatment?.strength }
+    : themeTreatment;
+  if (!base || base.type === 'none') return undefined;
+  if (base.type === 'duotone' && !base.color) {
+    return { ...base, color: context.theme.colors.primary };
+  }
+  return base;
+}
+
+/**
+ * Theme-derived surface gradient for text-first templates.
+ *
+ * Runs from the theme's alternate surface into a slightly deepened
+ * background, staying inside the theme's own hue. Templates must use
+ * this instead of hard-coding a dark endpoint (`#0f1520`, `#1e2030`, …):
+ * hard-coded navy endpoints made light themes render dark panels and
+ * warm themes drift cold halfway down the block.
+ */
+export function themedSurfaceGradient(context: TemplateContext, angleDeg = 160): string {
+  const { background, backgroundLight } = context.theme.colors;
+  return `linear-gradient(${angleDeg}deg, ${backgroundLight} 0%, ${oklchDarken(background, 0.04)} 100%)`;
+}
+
+/**
+ * Translucent overlay tint derived from the theme background, for text
+ * bands/scrims painted over imagery. Light themes get a light scrim with
+ * dark theme text on top; dark themes get the familiar dark scrim —
+ * `theme.colors.text` stays legible on it by construction.
+ */
+export function themedScrim(context: TemplateContext, alpha?: number): string {
+  const a = alpha ?? Math.max(0.55, getOverlayOpacity(context));
+  return withAlpha(context.theme.colors.background, a);
+}
+
 // ============================================
 // Template Hint Access
 // ============================================