@bendyline/squisq-editor-react 1.5.3 → 1.6.1

package/src/scene/adapters/LayoutAdapter.ts

@@ -0,0 +1,310 @@
+/**
+ * LayoutAdapter — edit a `{[layout]}` block as semantic markdown.
+ *
+ * Read direction:  child `{[type …]}` headings → `computeLayoutLayers` →
+ *                  Scene layers (text content comes from each child's body).
+ * Write direction: SceneCommand → `layoutCommands` (insert/update/delete
+ *                  layer headings + bodies).
+ *
+ * The layout counterpart to `DrawingAdapter` — same seam
+ * (`LayoutAdapterResult`), absolute positioning, and text layers whose rich
+ * content lives in the child heading's markdown body. Nothing is persisted as
+ * a base64 `layers=` blob anymore; every layer is a heading. Documents that
+ * still carry the legacy blob are auto-migrated to child sub-blocks on first
+ * mount (see the migration effect).
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import type { Editor } from '@tiptap/react';
+import type { Layer, Block, TextStyle } from '@bendyline/squisq/schemas';
+import { computeLayoutLayers } from '@bendyline/squisq/doc';
+import type { SceneCommand, SceneEdge } from '../commands/SceneCommand';
+import type { SceneTool, SceneToolContext } from '../tools/SceneTool';
+import { SelectTool } from '../tools/SelectTool';
+import { markdownToTiptap } from '../../tiptapBridge';
+import { readLayersFromHeading, writeLayersToHeading } from './blockLayers';
+import {
+  listLayoutChildren,
+  addLayoutLayer,
+  moveLayoutLayer,
+  resizeLayoutLayer,
+  setLayoutParam,
+  setLayoutText,
+  removeLayoutLayer,
+} from '../commands/layoutCommands';
+
+export interface LayoutAdapterResult {
+  /** Layers to pass to `<Scene layers={...} />`. */
+  layers: Layer[];
+  /** Tool set the host should expose. */
+  tools: SceneTool[];
+  /** Command dispatch for `<Scene onCommand={...} />`. */
+  dispatch: (cmd: SceneCommand) => void;
+  // ── Connector-capable adapters (drawing) set these; layout omits them ──
+  /** Connector edges to pass to `<Scene edges={...} />`. */
+  edges?: SceneEdge[];
+  /** `<Scene layerFollows={...} />` — a label layer follows its shape. */
+  layerFollows?: (layerId: string) => string | null;
+  /** `<Scene renderExtras={...} />` — draws the connector pass behind layers. */
+  renderExtras?: (ctx: SceneToolContext) => ReactNode;
+}
+
+export interface LayoutAdapterOptions {
+  /** Override the tool set (defaults to `[SelectTool]`). */
+  tools?: SceneTool[];
+}
+
+/** Viewport the layout canvas composes against (matches `SceneBlockWidget`). */
+const SCENE_VIEWPORT = { width: 1920, height: 1080 };
+
+/**
+ * Build a LayoutAdapter for the heading at `headingPos`. Subscribes to the
+ * editor's transactions so the returned `layers` reflect the latest doc.
+ */
+export function useLayoutAdapter(
+  editor: Editor,
+  headingPos: number,
+  options: LayoutAdapterOptions = {},
+): LayoutAdapterResult {
+  const [, setVersion] = useState(0);
+  useEffect(() => {
+    const onUpdate = () => setVersion((v) => v + 1);
+    editor.on('transaction', onUpdate);
+    return () => {
+      editor.off('transaction', onUpdate);
+    };
+  }, [editor]);
+
+  // ── Read: child headings → layers ──────────────────────────────
+  const node = editor.state.doc.nodeAt(headingPos);
+  const children = node ? listLayoutChildren(editor, headingPos) : [];
+  const blocks: Block[] = children.map((c) => ({
+    id: c.id,
+    startTime: 0,
+    duration: 0,
+    audioSegment: 0,
+    ...(c.kind ? { template: c.kind } : {}),
+    ...(Object.keys(c.params).length > 0 ? { templateOverrides: c.params } : {}),
+  }));
+  const { layers } = computeLayoutLayers(blocks, SCENE_VIEWPORT);
+  // Text content comes from the child body (faithful rich HTML + plain text),
+  // not the annotation — overwrite what the core derivation left empty.
+  for (const l of layers) {
+    if (l.type !== 'text') continue;
+    const c = children.find((ch) => ch.id === l.id);
+    if (!c) continue;
+    l.content.text = c.bodyText;
+    if (c.bodyHtml.trim()) l.content.html = c.bodyHtml;
+  }
+
+  // ── Migration: legacy base64 `layers=` blob → child sub-blocks ──
+  // SSR never decoded the blob, so this only matters in the editor. Runs
+  // at most once: no-op when children already exist or no blob is present.
+  const migratedRef = useRef(false);
+  useEffect(() => {
+    if (migratedRef.current) return;
+    const n = editor.state.doc.nodeAt(headingPos);
+    if (!n) return;
+    if (listLayoutChildren(editor, headingPos).length > 0) {
+      migratedRef.current = true;
+      return;
+    }
+    const legacy = readLayersFromHeading(n);
+    if (legacy.length === 0) {
+      migratedRef.current = true;
+      return;
+    }
+    migratedRef.current = true;
+    for (const layer of legacy) {
+      const child = layerToLayoutChild(layer);
+      addLayoutLayer(editor, headingPos, layer.id, child.kind, child.params, child.bodyHtml);
+    }
+    writeLayersToHeading(editor, headingPos, []);
+  }, [editor, headingPos]);
+
+  // ── Write: SceneCommand → layout heading commands ──────────────
+  const dispatch = (cmd: SceneCommand) => {
+    switch (cmd.kind) {
+      case 'moveLayer':
+        moveLayoutLayer(editor, headingPos, cmd.id, cmd.x, cmd.y);
+        return;
+      case 'resizeLayer':
+        resizeLayoutLayer(editor, headingPos, cmd.id, cmd.width, cmd.height);
+        return;
+      case 'addLayer': {
+        const child = layerToLayoutChild(cmd.layer);
+        const id = cmd.layer.id || nextLayoutId(editor, headingPos, child.kind);
+        addLayoutLayer(editor, headingPos, id, child.kind, child.params, child.bodyHtml);
+        return;
+      }
+      case 'removeLayer':
+        removeLayoutLayer(editor, headingPos, cmd.id);
+        return;
+      case 'renameLayer':
+        // Layout text content lives in the body; treat a rename as a plain
+        // text replacement of that body.
+        setLayoutText(editor, headingPos, cmd.id, markdownToTiptap(cmd.label));
+        return;
+      case 'setLayerText':
+        setLayoutText(
+          editor,
+          headingPos,
+          cmd.id,
+          cmd.html && cmd.html.trim() ? cmd.html : markdownToTiptap(cmd.text),
+        );
+        return;
+      case 'setLayerAttr': {
+        const mapped = paramForLayoutPath(cmd.path);
+        if (mapped) setLayoutParam(editor, headingPos, cmd.id, mapped, String(cmd.value ?? ''));
+        return;
+      }
+      case 'addEdge':
+      case 'removeEdge':
+        // Layouts don't model edges.
+        return;
+    }
+    const _exhaustive: never = cmd;
+    void _exhaustive;
+  };
+
+  return {
+    layers,
+    tools: options.tools ?? [SelectTool],
+    dispatch,
+  };
+}
+
+// ============================================
+// Layer ↔ child mapping
+// ============================================
+
+interface LayoutChildWrite {
+  kind: string;
+  params: Record<string, string>;
+  /** Tiptap HTML for a text layer's body ('' for non-text layers). */
+  bodyHtml: string;
+}
+
+/** Map a Layer to a `{[type …]}` child heading's kind + params + body HTML. */
+function layerToLayoutChild(layer: Layer): LayoutChildWrite {
+  const params = posParams(layer.position);
+  if (layer.type === 'text') {
+    Object.assign(params, styleParams(layer.content.style));
+    const bodyHtml = layer.content.html?.trim()
+      ? layer.content.html
+      : markdownToTiptap(layer.content.text ?? '');
+    return { kind: 'text', params, bodyHtml };
+  }
+  if (layer.type === 'shape') {
+    const c = layer.content;
+    const kind = c.shape === 'rect' ? 'rectangle' : c.shape; // circle / line keep their name
+    if (c.fill) params.fill = c.fill;
+    if (c.stroke) params.stroke = c.stroke;
+    if (c.strokeWidth != null) params.strokeWidth = String(c.strokeWidth);
+    if (c.borderStyle) params.borderStyle = c.borderStyle;
+    if (c.borderRadius != null) params.borderRadius = String(c.borderRadius);
+    return { kind, params, bodyHtml: '' };
+  }
+  if (layer.type === 'path') {
+    const c = layer.content;
+    params.d = c.d;
+    if (c.stroke) params.stroke = c.stroke;
+    if (c.strokeWidth != null) params.strokeWidth = String(c.strokeWidth);
+    if (c.fill) params.fill = c.fill;
+    return { kind: 'path', params, bodyHtml: '' };
+  }
+  if (layer.type === 'image') {
+    const c = layer.content;
+    params.src = c.src;
+    if (c.alt) params.alt = c.alt;
+    if (c.fit) params.fit = c.fit;
+    return { kind: 'image', params, bodyHtml: '' };
+  }
+  // Unknown layer types degrade to an empty text box.
+  return { kind: 'text', params, bodyHtml: '' };
+}
+
+/** Pull numeric x/y/width/height out of a Layer position into string params. */
+function posParams(pos: Layer['position']): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (typeof pos.x === 'number') out.x = String(Math.round(pos.x));
+  if (typeof pos.y === 'number') out.y = String(Math.round(pos.y));
+  if (typeof pos.width === 'number') out.width = String(Math.round(pos.width));
+  if (typeof pos.height === 'number') out.height = String(Math.round(pos.height));
+  return out;
+}
+
+/** Serialize a text layer's style into annotation params. */
+function styleParams(style: TextStyle): Record<string, string> {
+  const p: Record<string, string> = {};
+  if (style.fontSize != null) p.fontSize = String(Math.round(style.fontSize));
+  if (style.color) p.color = style.color;
+  if (style.fontFamily) p.fontFamily = style.fontFamily;
+  if (style.fontWeight && style.fontWeight !== 'normal') p.fontWeight = style.fontWeight;
+  if (style.fontStyle && style.fontStyle !== 'normal') p.fontStyle = style.fontStyle;
+  if (style.textAlign) p.align = style.textAlign;
+  if (style.verticalAlign) p.valign = style.verticalAlign;
+  if (style.lineHeight != null) p.lineHeight = String(style.lineHeight);
+  if (style.padding != null) p.padding = String(style.padding);
+  if (style.background) p.background = style.background;
+  return p;
+}
+
+/** Map a `setLayerAttr` dotted path to a layout child param name. */
+function paramForLayoutPath(path: string): string | null {
+  switch (path) {
+    case 'content.style.textAlign':
+      return 'align';
+    case 'content.style.verticalAlign':
+      return 'valign';
+    case 'content.style.fontSize':
+      return 'fontSize';
+    case 'content.style.color':
+      return 'color';
+    case 'content.style.fontFamily':
+      return 'fontFamily';
+    case 'content.style.fontWeight':
+      return 'fontWeight';
+    case 'content.style.fontStyle':
+      return 'fontStyle';
+    case 'content.style.lineHeight':
+      return 'lineHeight';
+    case 'content.style.padding':
+      return 'padding';
+    case 'content.style.background':
+      return 'background';
+    case 'content.fill':
+      return 'fill';
+    case 'content.stroke':
+      return 'stroke';
+    case 'content.strokeWidth':
+      return 'strokeWidth';
+    case 'content.borderStyle':
+      return 'borderStyle';
+    case 'content.borderRadius':
+      return 'borderRadius';
+    default:
+      return null;
+  }
+}
+
+const KIND_PREFIX: Record<string, string> = {
+  text: 'text',
+  rectangle: 'box',
+  rect: 'box',
+  circle: 'circle',
+  line: 'line',
+  path: 'path',
+  image: 'image',
+};
+
+/** A fresh, unique heading id for a new layer, e.g. `text-1`, `box-2`. */
+function nextLayoutId(editor: Editor, parentPos: number, kind: string): string {
+  const used = new Set(listLayoutChildren(editor, parentPos).map((c) => c.id));
+  const prefix = KIND_PREFIX[kind] ?? (kind.replace(/[^a-z0-9]/gi, '').toLowerCase() || 'layer');
+  let i = 1;
+  let id = `${prefix}-${i}`;
+  while (used.has(id)) id = `${prefix}-${++i}`;
+  return id;
+}

package/src/scene/adapters/blockLayers.ts

@@ -0,0 +1,159 @@
+/**
+ * blockLayers — read / decode a block's legacy base64 Layer[] blob.
+ *
+ * **Legacy / migration only.** Layouts (and drawings) now persist every
+ * layer as a readable child sub-block heading (see `layoutCommands.ts` /
+ * `drawingCommands.ts`); nothing new is written here. These helpers remain
+ * so the editor can *read* documents authored before that change and
+ * migrate them to child sub-blocks on first edit (see `LayoutAdapter`'s
+ * migration effect). `updateLayer` is still used by the in-memory image
+ * editor designer.
+ *
+ * The legacy encoding piggy-backed on the `data-block-attrs` round-trip
+ * path by storing the layers as a base64-JSON Pandoc param named
+ * `layers="<...>"`. The bridge round-trips `{#id key="value"}` verbatim,
+ * so the markdown surface picked this up for free.
+ *
+ * Encoding choice — base64 keeps the JSON's commas, quotes, and braces
+ * from clashing with the Pandoc attribute tokenizer. Authors who want
+ * to hand-edit raw layer arrays can do so by switching to the raw
+ * markdown view, decoding, editing, re-encoding; future work may
+ * expose this in a more friendly format (e.g. a fenced `~~~layers`
+ * block).
+ */
+
+import type { Editor } from '@tiptap/react';
+import type { Node as PMNode } from '@tiptap/pm/model';
+import type { Layer } from '@bendyline/squisq/schemas';
+import {
+  parsePandocAttrTokens,
+  serializePandocAttributes,
+  type HeadingAttributes,
+} from '@bendyline/squisq/markdown';
+
+const LAYERS_PARAM = 'layers';
+
+/** Decode the `layers="..."` param into a Layer[]; returns [] when absent or invalid. */
+export function readLayersFromHeading(node: PMNode): Layer[] {
+  const attrs = getHeadingAttrs(node);
+  const encoded = attrs.params?.[LAYERS_PARAM];
+  if (!encoded) return [];
+  return decodeLayers(encoded);
+}
+
+/** Write a Layer[] back into the heading's `data-block-attrs`. */
+export function writeLayersToHeading(
+  editor: Editor,
+  headingPos: number,
+  layers: readonly Layer[],
+): boolean {
+  return editor
+    .chain()
+    .command(({ tr }) => {
+      const node = tr.doc.nodeAt(headingPos);
+      if (!node || node.type.name !== 'heading') return false;
+      const attrs = getHeadingAttrs(node);
+      const params = { ...(attrs.params ?? {}) };
+      if (layers.length === 0) {
+        delete params[LAYERS_PARAM];
+      } else {
+        params[LAYERS_PARAM] = encodeLayers(layers);
+      }
+      const nextAttrs: HeadingAttributes = { ...attrs };
+      nextAttrs.params = Object.keys(params).length > 0 ? params : undefined;
+      // `serializePandocAttributes` returns the full `{…}` block, but
+      // `data-block-attrs` stores the INSIDE of those braces (matching the
+      // reader `parsePandocAttrTokens` and `tiptapBridge`). Strip them so
+      // the value round-trips — otherwise the next read sees `{layers=…}`
+      // as a malformed token and drops every layer.
+      const raw = serializePandocAttributes(nextAttrs);
+      tr.setNodeAttribute(headingPos, 'dataBlockAttrs', stripBraces(raw));
+      return true;
+    })
+    .run();
+}
+
+function utf8ToBase64(str: string): string {
+  const bytes = new TextEncoder().encode(str);
+  if (typeof globalThis.btoa === 'function') {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return globalThis.btoa(binary);
+  }
+  return Buffer.from(bytes).toString('base64');
+}
+
+function base64ToUtf8(b64: string): string {
+  if (typeof globalThis.atob === 'function') {
+    const binary = globalThis.atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  return Buffer.from(b64, 'base64').toString('utf-8');
+}
+
+/** Base64-encode a Layer array as JSON. UTF-8 safe — handles Unicode layer content. */
+export function encodeLayers(layers: readonly Layer[]): string {
+  return utf8ToBase64(JSON.stringify(layers));
+}
+
+/** Inverse of {@link encodeLayers}. Returns [] when the string isn't valid. */
+export function decodeLayers(encoded: string): Layer[] {
+  try {
+    const parsed = JSON.parse(base64ToUtf8(encoded));
+    if (!Array.isArray(parsed)) return [];
+    return parsed as Layer[];
+  } catch {
+    return [];
+  }
+}
+
+function getHeadingAttrs(node: PMNode): HeadingAttributes {
+  const raw = (node.attrs as Record<string, unknown>).dataBlockAttrs;
+  if (typeof raw === 'string' && raw.length > 0) return parsePandocAttrTokens(raw);
+  return {};
+}
+
+/**
+ * Strip the wrapping `{…}` from a serialized Pandoc attribute block so it
+ * matches the inner form stored in `data-block-attrs`. An empty `{}`
+ * marker collapses to `null` (nothing to persist).
+ */
+function stripBraces(s: string | null): string | null {
+  if (s == null) return null;
+  if (s === '{}') return null;
+  if (s.startsWith('{') && s.endsWith('}')) return s.slice(1, -1);
+  return s;
+}
+
+/**
+ * Apply a per-layer transform to the persisted layer list. Convenience
+ * for adapter dispatch functions that need to mutate one layer in place
+ * (e.g. `moveLayer`, `setLayerAttr`). The transform receives the
+ * matching layer (or `undefined` to insert) and returns the next
+ * version (or `null` to remove).
+ */
+export function updateLayer(
+  editor: Editor,
+  headingPos: number,
+  layerId: string,
+  transform: (current: Layer | undefined) => Layer | null,
+): boolean {
+  const node = editor.state.doc.nodeAt(headingPos);
+  if (!node) return false;
+  const layers = readLayersFromHeading(node);
+  const idx = layers.findIndex((l) => l.id === layerId);
+  const current = idx >= 0 ? layers[idx] : undefined;
+  const next = transform(current);
+  let updated: Layer[];
+  if (next == null) {
+    updated = layers.filter((l) => l.id !== layerId);
+  } else if (idx >= 0) {
+    updated = layers.slice();
+    updated[idx] = next;
+  } else {
+    updated = [...layers, next];
+  }
+  return writeLayersToHeading(editor, headingPos, updated);
+}

package/src/scene/commands/SceneCommand.ts

@@ -0,0 +1,70 @@
+/**
+ * SceneCommand — the union of edits a Scene tool can request.
+ *
+ * Tools never mutate state directly. They produce a SceneCommand and the
+ * host adapter (DiagramAdapter / LayoutAdapter / DrawingAdapter) decides
+ * how to apply it — for diagrams that means a Tiptap transaction that
+ * updates a heading's Pandoc attrs; for layouts/drawings it's a write to
+ * the heading's `dataLayers` attr.
+ *
+ * Keeping the command shape adapter-agnostic is what lets the same Scene
+ * component drive three different editing surfaces.
+ */
+
+import type { Layer } from '@bendyline/squisq/schemas';
+
+export type SceneCommand =
+  /** Commit a layer's new top-left position (in viewport units). */
+  | { kind: 'moveLayer'; id: string; x: number; y: number }
+  /** Commit a layer's new size (in viewport units). */
+  | { kind: 'resizeLayer'; id: string; width: number; height: number }
+  /** Append a new layer to the scene. */
+  | { kind: 'addLayer'; layer: Layer }
+  /** Remove a layer by id. */
+  | { kind: 'removeLayer'; id: string }
+  /**
+   * Set a single attribute on a layer. `path` is a dotted path into the
+   * layer object (e.g. `content.text`, `content.style.fontSize`). The
+   * adapter is responsible for translating this to a domain-appropriate
+   * write (markdown attr, JSON-encoded override, etc.).
+   */
+  | { kind: 'setLayerAttr'; id: string; path: string; value: unknown }
+  /** Create an edge between two diagram nodes (diagram mode only). */
+  | { kind: 'addEdge'; source: string; target: string; type?: string }
+  /** Remove an edge by source/target (and optional type). */
+  | { kind: 'removeEdge'; source: string; target: string; type?: string }
+  /**
+   * Rename a labeled layer (e.g. a diagram node card or a TextLayer). The
+   * adapter decides whether this writes to TextLayer.content.text, a
+   * heading's text content, or something else.
+   */
+  | { kind: 'renameLayer'; id: string; label: string }
+  /**
+   * Set a text layer's content from the inline editor. `text` is the plain
+   * projection (always written); `html` is the optional rich representation
+   * (stored by adapters that can persist it — layout). Adapters that only
+   * keep plain text (diagram/drawing headings) ignore `html`.
+   */
+  | { kind: 'setLayerText'; id: string; text: string; html?: string };
+
+/**
+ * An edge in diagram mode. Lives outside the Layer schema because edges
+ * are derived from a node's `connectsTo` rather than being authored as
+ * top-level visual layers — the Scene renders them as PathLayers, but
+ * the adapter never writes a PathLayer to the markdown.
+ */
+export interface SceneEdge {
+  /** Stable edge id (`source->target` or `source->target:type`). */
+  id: string;
+  source: string;
+  target: string;
+  /** Optional label, rendered at the midpoint. */
+  label?: string;
+  /** End-of-line markers. Drawing connectors set these; diagrams default end→arrow. */
+  startMarker?: import('@bendyline/squisq/schemas').MarkerStyle;
+  endMarker?: import('@bendyline/squisq/schemas').MarkerStyle;
+  /** SVG stroke-dasharray for dashed/dotted lines. */
+  dasharray?: string;
+  /** Per-edge routing override (else the renderer's variant default). */
+  routing?: import('@bendyline/squisq/doc').ConnectorRouting;
+}