@bendyline/squisq-editor-react 1.5.3 → 1.6.1

package/src/customTemplates/library.ts

@@ -0,0 +1,97 @@
+/**
+ * Browser-local library of user-defined custom templates.
+ *
+ * Library templates live in `localStorage` under
+ * `LIBRARY_STORAGE_KEY`. They're a cross-doc convenience — a personal
+ * collection of designs the user reuses across documents — but they're
+ * NOT used by the SSR pipeline. When a user applies a library template
+ * to a block, `applyTemplate` (in CustomTemplateContext) copies the
+ * definition into the doc's `customTemplates` so the doc remains
+ * self-sufficient (the markdown file ships with everything it needs).
+ *
+ * Safe to import in SSR / Node — gracefully no-ops when
+ * `localStorage` is unavailable.
+ */
+
+import type { CustomTemplateDefinition } from '@bendyline/squisq/schemas';
+
+export const LIBRARY_STORAGE_KEY = 'squisq:custom-template-library';
+
+interface LibraryPayload {
+  /** Schema version for forward-compatibility. */
+  version: 1;
+  templates: CustomTemplateDefinition[];
+}
+
+function safeStorage(): Storage | null {
+  try {
+    return typeof globalThis !== 'undefined' && globalThis.localStorage
+      ? globalThis.localStorage
+      : null;
+  } catch {
+    // Some browsers throw on localStorage access in private mode.
+    return null;
+  }
+}
+
+function readPayload(): LibraryPayload {
+  const storage = safeStorage();
+  if (!storage) return { version: 1, templates: [] };
+  const raw = storage.getItem(LIBRARY_STORAGE_KEY);
+  if (!raw) return { version: 1, templates: [] };
+  try {
+    const parsed = JSON.parse(raw) as Partial<LibraryPayload>;
+    if (parsed && Array.isArray(parsed.templates)) {
+      return { version: 1, templates: parsed.templates };
+    }
+  } catch {
+    // Corrupt payload — drop it.
+  }
+  return { version: 1, templates: [] };
+}
+
+function writePayload(payload: LibraryPayload): void {
+  const storage = safeStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(LIBRARY_STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Quota exceeded or storage disabled — best-effort write.
+  }
+}
+
+/** Return every template currently in the user's library, sorted by label. */
+export function listLibraryTemplates(): CustomTemplateDefinition[] {
+  const { templates } = readPayload();
+  return templates.slice().sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/**
+ * Insert or replace a library template (matched by `name`). Returns
+ * the persisted list so callers can update their state without
+ * re-reading.
+ */
+export function saveLibraryTemplate(def: CustomTemplateDefinition): CustomTemplateDefinition[] {
+  const payload = readPayload();
+  const idx = payload.templates.findIndex((t) => t.name === def.name);
+  if (idx >= 0) {
+    payload.templates[idx] = def;
+  } else {
+    payload.templates.push(def);
+  }
+  writePayload(payload);
+  return payload.templates.slice().sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** Remove a library template by name. Returns the updated list. */
+export function deleteLibraryTemplate(name: string): CustomTemplateDefinition[] {
+  const payload = readPayload();
+  payload.templates = payload.templates.filter((t) => t.name !== name);
+  writePayload(payload);
+  return payload.templates.slice().sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** Wipe the entire library — useful for tests and "reset" affordances. */
+export function clearLibrary(): void {
+  writePayload({ version: 1, templates: [] });
+}

package/src/customTemplates/normalizePositions.ts

@@ -0,0 +1,75 @@
+/**
+ * Normalize numeric position fields on a Layer[] to `%`-strings
+ * relative to the designer canvas.
+ *
+ * Why: the designer drags layers around in pixel coordinates (that's
+ * how pointer events work), but saved templates need to be
+ * resolution-independent so the same definition renders correctly
+ * across the landscape / portrait / square viewport presets. On Save
+ * we run this normalizer to convert pixel positions to percentages.
+ *
+ * Width / height are converted against their own dimension (width
+ * against canvas width, height against canvas height) — not "always
+ * against width" like SVG `viewBox`-style coordinates.
+ *
+ * Already-`%`-valued fields are preserved verbatim. Anchor fields and
+ * non-position content fields are untouched. Layers without an
+ * explicit `position` are passed through unchanged.
+ */
+
+import type { Layer, Position } from '@bendyline/squisq/schemas';
+
+export interface Canvas {
+  width: number;
+  height: number;
+}
+
+/**
+ * Return a new Layer[] where each numeric position field has been
+ * converted to a `%`-string relative to `canvas`. Pure function;
+ * doesn't mutate the input.
+ */
+export function normalizePositions(layers: readonly Layer[], canvas: Canvas): Layer[] {
+  return layers.map((layer) => normalizeLayer(layer, canvas));
+}
+
+function normalizeLayer<L extends Layer>(layer: L, canvas: Canvas): L {
+  if (!layer.position) return layer;
+  const pos: Position = { ...layer.position };
+  if (pos.x !== undefined) pos.x = toPercent(pos.x, canvas.width);
+  if (pos.y !== undefined) pos.y = toPercent(pos.y, canvas.height);
+  if (pos.width !== undefined) pos.width = toPercent(pos.width, canvas.width);
+  if (pos.height !== undefined) pos.height = toPercent(pos.height, canvas.height);
+  // `anchor` (top-left / center / etc.) is preserved verbatim.
+  return { ...layer, position: pos } as L;
+}
+
+/**
+ * Convert a single position value to a `%`-string. Already-string
+ * `%` values pass through; non-numeric strings (e.g. hand-written
+ * pixel expressions) are returned unchanged so we don't corrupt
+ * intentional author markup.
+ */
+function toPercent(value: number | string, base: number): string {
+  if (typeof value === 'string') {
+    if (value.endsWith('%')) return value;
+    // Try to parse as a number ("180" → 180px → percent).
+    const n = parseFloat(value);
+    if (Number.isFinite(n) && String(n) === value) {
+      return formatPercent((n / base) * 100);
+    }
+    return value;
+  }
+  if (!Number.isFinite(value) || base <= 0) return String(value);
+  return formatPercent((value / base) * 100);
+}
+
+/** Format a percentage with up to two decimal places, trailing zeros trimmed. */
+function formatPercent(pct: number): string {
+  // Round to 0.01% precision — enough for visually faithful round-trip
+  // without bloating the saved layout JSON.
+  const rounded = Math.round(pct * 100) / 100;
+  // Drop trailing zeros: 50.00 → "50%", 50.10 → "50.1%".
+  const str = rounded.toString();
+  return `${str}%`;
+}

package/src/customTemplates/shapeDefs.ts

@@ -0,0 +1,131 @@
+/**
+ * Standard shape definitions for the template designer's "Add" bin.
+ *
+ * Each entry maps to one of Squisq's shape kinds. The three primitives
+ * the renderer draws natively (`rect`, `circle`, `line`) become a
+ * `ShapeLayer`; every other kind is compiled to an SVG path via
+ * {@link shapePath} and stored as a `PathLayer` — the same split the
+ * `drawing` template uses (see `shapeGeometry.ts`). Both render through
+ * the shared layer components, so the bin preview, the editor canvas,
+ * and the final block render stay identical.
+ *
+ * Like {@link TOKEN_DEFS}, a shape can be placed two ways: drag it onto
+ * the canvas (the drag carries the id on {@link SHAPE_DRAG_MIME}) or
+ * click it to arm the matching place tool, then click the canvas.
+ */
+
+import type { Layer, PathLayer, ShapeLayer } from '@bendyline/squisq/schemas';
+import { shapePath } from '@bendyline/squisq/doc';
+
+/** MIME type carried on the drag's `dataTransfer` for a shape. */
+export const SHAPE_DRAG_MIME = 'application/x-squisq-shape';
+
+export interface ShapeDef {
+  /** Stable id, used both as the place-tool id and the drag payload. */
+  id: string;
+  /** Short button label. */
+  label: string;
+  /**
+   * Shape kind. `rect`/`circle`/`line` render as a native `ShapeLayer`;
+   * any other kind is compiled to a `PathLayer` path via `shapePath`.
+   */
+  kind: string;
+  /** For `rect`: render with rounded corners. */
+  rounded?: boolean;
+}
+
+export const SHAPE_DEFS: ShapeDef[] = [
+  { id: 'shape-rect', label: 'Rectangle', kind: 'rect' },
+  { id: 'shape-rect-rounded', label: 'Rounded', kind: 'rect', rounded: true },
+  { id: 'shape-circle', label: 'Ellipse', kind: 'circle' },
+  { id: 'shape-line', label: 'Line', kind: 'line' },
+  { id: 'shape-triangle', label: 'Triangle', kind: 'triangle' },
+  { id: 'shape-right-triangle', label: 'Right triangle', kind: 'right-triangle' },
+  { id: 'shape-diamond', label: 'Diamond', kind: 'diamond' },
+  { id: 'shape-pentagon', label: 'Pentagon', kind: 'pentagon' },
+  { id: 'shape-hexagon', label: 'Hexagon', kind: 'hexagon' },
+  { id: 'shape-octagon', label: 'Octagon', kind: 'octagon' },
+  { id: 'shape-star', label: 'Star', kind: 'star' },
+  { id: 'shape-star4', label: '4-point star', kind: 'star4' },
+  { id: 'shape-star6', label: '6-point star', kind: 'star6' },
+  { id: 'shape-parallelogram', label: 'Parallelogram', kind: 'parallelogram' },
+  { id: 'shape-trapezoid', label: 'Trapezoid', kind: 'trapezoid' },
+  { id: 'shape-plus', label: 'Plus', kind: 'plus' },
+  { id: 'shape-chevron', label: 'Chevron', kind: 'chevron' },
+  { id: 'shape-arrow-right', label: 'Arrow right', kind: 'arrow-right' },
+  { id: 'shape-arrow-left', label: 'Arrow left', kind: 'arrow-left' },
+  { id: 'shape-arrow-up', label: 'Arrow up', kind: 'arrow-up' },
+  { id: 'shape-arrow-down', label: 'Arrow down', kind: 'arrow-down' },
+  { id: 'shape-double-arrow', label: 'Double arrow', kind: 'double-arrow' },
+  { id: 'shape-callout', label: 'Callout', kind: 'callout' },
+  { id: 'shape-cylinder', label: 'Cylinder', kind: 'cylinder' },
+  { id: 'shape-cloud', label: 'Cloud', kind: 'cloud' },
+  { id: 'shape-heart', label: 'Heart', kind: 'heart' },
+  { id: 'shape-lightning', label: 'Lightning', kind: 'lightning' },
+];
+
+/** Kinds the renderer draws natively as a `ShapeLayer`. */
+const NATIVE_KINDS = new Set(['rect', 'circle', 'line']);
+
+/** Default visual styling for a freshly placed shape. */
+const FILL = '#e2e8f0'; // slate-200
+const STROKE = '#475569'; // slate-600
+const STROKE_WIDTH = 2;
+const ROUNDED_RADIUS = 20;
+
+/** Default placement box (top-left anchored at the drop/click point). */
+function defaultSize(kind: string): { width: number; height: number } {
+  if (kind === 'line') return { width: 280, height: 120 };
+  return { width: 220, height: 180 };
+}
+
+let counter = 0;
+function nextShapeId(): string {
+  counter += 1;
+  return `shape-${Date.now().toString(36)}-${counter}`;
+}
+
+/**
+ * Build the layer a shape def adds, top-left at the given viewport point.
+ * Native kinds produce a `ShapeLayer`; everything else a computed
+ * `PathLayer`. Shared by the click-to-place tool and the drag-drop
+ * handler so both paths produce identical layers.
+ */
+export function buildShapeLayer(def: ShapeDef, point: { x: number; y: number }): Layer {
+  const { width, height } = defaultSize(def.kind);
+  const position = { x: point.x, y: point.y, width, height };
+  const id = nextShapeId();
+
+  if (NATIVE_KINDS.has(def.kind)) {
+    const layer: ShapeLayer = {
+      id,
+      type: 'shape',
+      position,
+      content: {
+        shape: def.kind as 'rect' | 'circle' | 'line',
+        fill: def.kind === 'line' ? 'none' : FILL,
+        stroke: STROKE,
+        strokeWidth: STROKE_WIDTH,
+        ...(def.kind === 'rect' ? { borderRadius: def.rounded ? ROUNDED_RADIUS : 0 } : {}),
+      },
+    };
+    return layer;
+  }
+
+  const layer: PathLayer = {
+    id,
+    type: 'path',
+    position,
+    content: {
+      // `d` is the initial geometry; `shapeKind` lets the renderer
+      // re-derive it from `position` so the shape moves, resizes, and
+      // adapts to the viewport (see PathLayer).
+      d: shapePath(def.kind, point.x, point.y, width, height) ?? '',
+      shapeKind: def.kind,
+      fill: FILL,
+      stroke: STROKE,
+      strokeWidth: STROKE_WIDTH,
+    },
+  };
+  return layer;
+}

package/src/customTemplates/thumbnail.tsx

@@ -0,0 +1,63 @@
+/**
+ * Custom-template thumbnails for the picker gallery.
+ *
+ * Renders a CustomTemplateDefinition's layers in a small SVG that
+ * matches the picker card's icon slot (56×40). Layers are rendered via
+ * the same `RenderLayer` the editor canvas uses, so the thumbnail is
+ * an accurate (just smaller) preview.
+ *
+ * Tokens are NOT resolved — the thumbnail shows placeholder strings
+ * (`{title}`, `{content}`) so the user can see what fields the
+ * template will fill in. That's the point of a template preview.
+ */
+
+import type { CustomTemplateDefinition } from '@bendyline/squisq/schemas';
+import { RenderLayer } from '../scene/layers/renderLayer';
+
+const W = 56;
+const H = 40;
+
+interface TemplateThumbnailProps {
+  def: CustomTemplateDefinition;
+  /** Override width / height (defaults match the picker icon slot). */
+  width?: number;
+  height?: number;
+}
+
+export function TemplateThumbnail({ def, width = W, height = H }: TemplateThumbnailProps) {
+  // The SVG renders the template's authoring viewport as its viewBox,
+  // so a 1920×1080 design becomes a 56×40 preview at the same aspect.
+  // `preserveAspectRatio="xMidYMid meet"` letterboxes when the
+  // requested width/height don't match — important for very narrow or
+  // very wide custom canvases.
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${def.viewport.width} ${def.viewport.height}`}
+      preserveAspectRatio="xMidYMid meet"
+      className="squisq-template-thumbnail"
+      aria-hidden="true"
+    >
+      {/* Background so an all-text template doesn't paint over the card. */}
+      <rect width={def.viewport.width} height={def.viewport.height} fill="#f8fafc" />
+      {def.layers.map((layer) => (
+        <g key={layer.id}>
+          <RenderLayer layer={layer} viewport={def.viewport} />
+        </g>
+      ))}
+      {/* Subtle 1px border in viewport-space so the preview stays
+          distinguishable from the picker card around it. */}
+      <rect
+        x={0}
+        y={0}
+        width={def.viewport.width}
+        height={def.viewport.height}
+        fill="none"
+        stroke="#cbd5e1"
+        strokeWidth={2}
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+}

package/src/customTemplates/tokenDefs.ts

@@ -0,0 +1,60 @@
+/**
+ * Placeholder token definitions for the template designer — the single
+ * source of truth shared by:
+ *
+ *   - `AddBin`              (renders the draggable/clickable buttons),
+ *   - `TemplateDesigner`    (builds one `createTokenTool` per entry, and
+ *                            looks an entry up by id on drop).
+ *
+ * Each token's `token` string is the literal substituted at render time
+ * (e.g. `{title}`) and doubles as the preview shown on the button.
+ */
+
+import type { TokenKind } from '../scene';
+
+export interface TokenDef {
+  /** Stable id, used both as the tool id and the drag payload. */
+  id: string;
+  /** Short button label. */
+  label: string;
+  /** Tooltip describing what the placeholder substitutes. */
+  desc: string;
+  /** Placeholder string dropped into the layer and shown as the preview. */
+  token: string;
+  /** Which layer kind the token creates. */
+  kind: TokenKind;
+}
+
+/** MIME type carried on the drag's `dataTransfer` for a placeholder token. */
+export const TOKEN_DRAG_MIME = 'application/x-squisq-token';
+
+export const TOKEN_DEFS: TokenDef[] = [
+  {
+    id: 'token-title',
+    label: 'Title',
+    desc: "Substitutes the block's heading text.",
+    token: '{title}',
+    kind: 'text',
+  },
+  {
+    id: 'token-content',
+    label: 'Content',
+    desc: "Substitutes the block's body text.",
+    token: '{content}',
+    kind: 'text',
+  },
+  {
+    id: 'token-children',
+    label: 'Children',
+    desc: 'Comma-joined list of child heading titles.',
+    token: '{children}',
+    kind: 'text',
+  },
+  {
+    id: 'token-image',
+    label: 'Image',
+    desc: "The first image found in the block's body.",
+    token: '{image:0}',
+    kind: 'image',
+  },
+];

package/src/customTemplates/useDocCustomTemplates.ts

@@ -0,0 +1,52 @@
+/**
+ * useDocCustomTemplates — read + persist the active doc's custom
+ * templates (the list inlined into the doc's frontmatter under
+ * `squisq-custom-templates`).
+ *
+ * Both the WYSIWYG editor and the standalone Custom Layout Manager need
+ * the same two things: the current `Doc.customTemplates` array and a way
+ * to write a new list back into the markdown source. Centralizing the
+ * frontmatter encoding here keeps the two call sites from drifting.
+ */
+
+import { useCallback, useMemo } from 'react';
+import type { CustomTemplateDefinition } from '@bendyline/squisq/schemas';
+import {
+  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
+  writeCustomTemplatesToFrontmatter,
+} from '@bendyline/squisq/doc';
+import { setFrontmatterValues } from '@bendyline/squisq/markdown';
+import { useEditorContext } from '../EditorContext';
+
+export interface DocCustomTemplates {
+  /** Custom templates inlined in the active doc's frontmatter. */
+  docTemplates: CustomTemplateDefinition[];
+  /**
+   * Persist a new custom-templates list back into the markdown source's
+   * frontmatter so the doc round-trips through save/load. The whole list
+   * is encoded as a single base64-JSON string per the flat YAML
+   * frontmatter parser's constraint.
+   */
+  onDocTemplatesChange: (next: CustomTemplateDefinition[]) => void;
+}
+
+export function useDocCustomTemplates(): DocCustomTemplates {
+  const { doc, markdownSource, setMarkdownSource } = useEditorContext();
+  // Memoized so identity is stable across renders that don't touch
+  // frontmatter — keeps the CustomTemplateProvider value stable.
+  const docTemplates = useMemo<CustomTemplateDefinition[]>(
+    () => doc?.customTemplates ?? [],
+    [doc?.customTemplates],
+  );
+  const onDocTemplatesChange = useCallback(
+    (next: CustomTemplateDefinition[]) => {
+      const payload = writeCustomTemplatesToFrontmatter(next);
+      const updated = setFrontmatterValues(markdownSource, {
+        [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload ?? null,
+      });
+      if (updated !== markdownSource) setMarkdownSource(updated);
+    },
+    [markdownSource, setMarkdownSource],
+  );
+  return { docTemplates, onDocTemplatesChange };
+}

package/src/customTemplates/useMemoryLayerAdapter.ts

@@ -0,0 +1,123 @@
+/**
+ * In-memory variant of LayoutAdapter.
+ *
+ * `useLayoutAdapter` persists Layer mutations to a heading's
+ * `data-block-attrs` Pandoc param. For the template designer, the
+ * Layer[] doesn't belong to a heading — it's being authored in a
+ * modal and saved to the doc / library as a `CustomTemplateDefinition`
+ * only when the user clicks Save. This adapter swaps Tiptap-backed
+ * storage for a plain React state holder so the designer can reuse
+ * the Scene component verbatim.
+ *
+ * Returns the same `{ layers, tools, dispatch }` shape as
+ * `useLayoutAdapter` so the Scene API surface stays consistent.
+ */
+
+import { useCallback, useState } from 'react';
+import type { Layer } from '@bendyline/squisq/schemas';
+import type { SceneCommand, SceneTool } from '../scene';
+
+export interface MemoryLayerAdapterResult {
+  layers: Layer[];
+  tools: SceneTool[];
+  dispatch: (cmd: SceneCommand) => void;
+  /** Replace the entire layer array (e.g. for Load / Reset / template-fork flows). */
+  setLayers: (next: Layer[]) => void;
+}
+
+export interface MemoryLayerAdapterOptions {
+  /** Initial layer array. */
+  initial?: Layer[];
+  /** Tool set the host should expose. Required — typically Select + token tools. */
+  tools: SceneTool[];
+}
+
+/**
+ * Manage a Layer[] in React state and expose it through the same
+ * adapter contract the Scene expects. SceneCommands are interpreted
+ * against the in-memory array and applied via `setLayers`.
+ */
+export function useMemoryLayerAdapter(
+  options: MemoryLayerAdapterOptions,
+): MemoryLayerAdapterResult {
+  const [layers, setLayers] = useState<Layer[]>(() => options.initial ?? []);
+
+  const dispatch = useCallback((cmd: SceneCommand) => {
+    setLayers((current) => applyCommand(current, cmd));
+  }, []);
+
+  return {
+    layers,
+    tools: options.tools,
+    dispatch,
+    setLayers,
+  };
+}
+
+/**
+ * Pure application of a SceneCommand against a Layer[]. Exported so
+ * tests can exercise the reducer in isolation.
+ */
+export function applyCommand(layers: readonly Layer[], cmd: SceneCommand): Layer[] {
+  switch (cmd.kind) {
+    case 'moveLayer':
+      return layers.map((l) =>
+        l.id === cmd.id ? ({ ...l, position: { ...l.position, x: cmd.x, y: cmd.y } } as Layer) : l,
+      );
+    case 'resizeLayer':
+      return layers.map((l) =>
+        l.id === cmd.id
+          ? ({
+              ...l,
+              position: { ...l.position, width: cmd.width, height: cmd.height },
+            } as Layer)
+          : l,
+      );
+    case 'addLayer':
+      return [...layers, cmd.layer];
+    case 'removeLayer':
+      return layers.filter((l) => l.id !== cmd.id);
+    case 'setLayerAttr':
+      return layers.map((l) => (l.id === cmd.id ? setAttrAtPath(l, cmd.path, cmd.value) : l));
+    case 'renameLayer':
+      return layers.map((l) => {
+        if (l.id !== cmd.id) return l;
+        if (l.type !== 'text') return l;
+        return { ...l, content: { ...l.content, text: cmd.label } };
+      });
+    case 'setLayerText':
+      return layers.map((l) => {
+        if (l.id !== cmd.id || l.type !== 'text') return l;
+        const content = { ...l.content, text: cmd.text };
+        if (cmd.html && cmd.html.trim()) content.html = cmd.html;
+        else delete content.html;
+        return { ...l, content };
+      });
+    case 'addEdge':
+    case 'removeEdge':
+      // No edge model in memory adapter; ignored.
+      return layers.slice();
+  }
+  const _exhaustive: never = cmd;
+  void _exhaustive;
+  return layers.slice();
+}
+
+/**
+ * Set a deeply-nested field on a Layer via a dotted path. Returns a
+ * new Layer; the input is not mutated. JSON-clone is safe for Layer
+ * since the schema is pure plain data.
+ */
+function setAttrAtPath(layer: Layer, path: string, value: unknown): Layer {
+  const segments = path.split('.');
+  const next = JSON.parse(JSON.stringify(layer)) as Layer;
+  let target: Record<string, unknown> = next as unknown as Record<string, unknown>;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const key = segments[i];
+    const child = target[key];
+    if (typeof child !== 'object' || child === null) return layer;
+    target = child as Record<string, unknown>;
+  }
+  target[segments[segments.length - 1]] = value;
+  return next;
+}