makersclaw 0.2.0 → 0.3.1

package/registry/blocks/diagram/diagram.jsx

@@ -0,0 +1,481 @@
+"use client";
+
+// Diagram — Mermaid text drawn in the workspace theme, with zoom and pan.
+//
+// Client only, one static bundle: Mermaid needs the DOM to measure text,
+// and the app's check refuses import() (so no next/dynamic). The modules
+// load with the page; the drawing happens after the first effect (the
+// mount guard). Until then — on the server and in the first client paint —
+// the frame shows the Mermaid text itself, so the HTML already says what
+// the diagram is.
+//
+// Colours: the tokens are read from the page at run time (palette.js) and
+// handed to Mermaid as its theme; a change of workspace theme or of
+// light/dark reads them again and redraws.
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Button, Empty, Icon, IconButton, Menu, Notice, Skeleton, ToggleGroup, cx, toast } from "../../ui";
+import { renderMermaid } from "./mermaid";
+import { mermaidTheme, paletteKey, resolvePalette } from "./palette";
+import { diagramKind, diagramTitle } from "./source";
+
+const PAD = 24;
+const MIN_K = 0.2;
+const MAX_K = 4;
+const px = (v) => (typeof v === "number" ? `${v}px` : v);
+const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
+
+// The layout effect runs only in the browser; on the server it would warn.
+const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+export function Diagram(props) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return <DiagramPlaceholder {...props} />;
+  return <LiveDiagram {...props} />;
+}
+
+const FRAME = "flex min-w-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground";
+
+function heading(source, title) {
+  return title ?? diagramTitle(source) ?? diagramKind(source) ?? "Diagram";
+}
+
+/** What the server renders: the frame, its heading, and the Mermaid text. */
+function DiagramPlaceholder({ source = "", title, height, minHeight = 160, toolbar = true, className }) {
+  const kind = diagramKind(source);
+  return (
+    <figure className={cx(FRAME, className)} aria-busy="true">
+      {toolbar ? (
+        <figcaption className="flex min-h-12 items-center gap-2 border-b border-border ps-4 pe-2">
+          <span className="truncate text-sm font-medium">{heading(source, title)}</span>
+          {kind && title ? <span className="truncate text-xs text-muted-foreground max-sm:hidden">{kind}</span> : null}
+        </figcaption>
+      ) : null}
+      <pre className="overflow-hidden px-4 py-3 font-mono text-xs leading-relaxed text-muted-foreground" style={height != null ? { height: px(height) } : { minHeight: px(minHeight), maxHeight: px(minHeight * 2) }}>
+        {source}
+      </pre>
+    </figure>
+  );
+}
+
+function LiveDiagram({ source = "", title, label, height, minHeight = 160, maxHeight = 560, toolbar = true, look = "classic", onRender, className }) {
+  const frame = useRef(null);
+  const viewport = useRef(null);
+  const content = useRef(null);
+  const [palette, setPalette] = useState(null);
+  const [result, setResult] = useState(null);
+  const [good, setGood] = useState(null);
+  const [size, setSize] = useState(null);
+  const [box, setBox] = useState({ w: 0, h: 0 });
+  const [t, setT] = useState({ k: 1, x: 0, y: 0 });
+  const [pristine, setPristine] = useState(true);
+  const [smooth, setSmooth] = useState(false);
+  const [tab, setTab] = useState("diagram");
+  const [dragging, setDragging] = useState(false);
+  const onRenderRef = useRef(onRender);
+  onRenderRef.current = onRender;
+
+  // The tokens, read now and again whenever the theme may have changed.
+  useEffect(() => {
+    const el = frame.current;
+    let raf = 0;
+    const read = () => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(() => {
+        const p = resolvePalette(el);
+        setPalette((prev) => (prev && paletteKey(prev) === paletteKey(p) ? prev : p));
+      });
+    };
+    read();
+    const mo = new MutationObserver(read);
+    const attrs = { attributes: true, attributeFilter: ["class", "style", "data-theme"] };
+    mo.observe(document.documentElement, attrs);
+    mo.observe(document.head, { childList: true });
+    const themed = el.parentElement?.closest("[data-theme]");
+    if (themed) mo.observe(themed, attrs);
+    const mq = window.matchMedia?.("(prefers-color-scheme: dark)");
+    mq?.addEventListener?.("change", read);
+    // A theme stylesheet that finishes loading changes the tokens too.
+    const onLoad = (e) => {
+      if (e.target?.tagName === "LINK") read();
+    };
+    document.addEventListener("load", onLoad, true);
+    return () => {
+      cancelAnimationFrame(raf);
+      mo.disconnect();
+      mq?.removeEventListener?.("change", read);
+      document.removeEventListener("load", onLoad, true);
+    };
+  }, []);
+
+  // Draw: after the text rests for a moment (someone may be typing it).
+  useEffect(() => {
+    if (!palette) return;
+    if (!source.trim()) {
+      setResult(null);
+      setGood(null);
+      return;
+    }
+    let live = true;
+    const timer = setTimeout(() => {
+      const font = getComputedStyle(frame.current).fontFamily;
+      renderMermaid(source, { themeVariables: mermaidTheme(palette, { fontFamily: font }), look, fontFamily: font }).then((r) => {
+        if (!live) return;
+        setResult(r);
+        if (r.ok) setGood(r.svg);
+        onRenderRef.current?.(r);
+      });
+    }, result ? 150 : 0);
+    return () => {
+      live = false;
+      clearTimeout(timer);
+    };
+    // `result` only picks the delay; it must not redraw.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [source, palette, look]);
+
+  // The drawing's own size, once it is in the page; Mermaid's width="100%"
+  // and max-width are taken off so zoom is ours.
+  useIsoLayoutEffect(() => {
+    const svg = content.current?.querySelector("svg");
+    if (!svg) return;
+    const vb = svg.viewBox?.baseVal;
+    let w = vb?.width || 0;
+    let h = vb?.height || 0;
+    if (!w || !h) {
+      const r = svg.getBoundingClientRect();
+      w = r.width || 400;
+      h = r.height || 300;
+    }
+    svg.style.maxWidth = "none";
+    svg.setAttribute("width", String(w));
+    svg.setAttribute("height", String(h));
+    svg.setAttribute("aria-hidden", "true");
+    setSize((s) => (s && s.w === w && s.h === h ? s : { w, h }));
+  }, [good, tab]);
+
+  // The viewport's size.
+  useEffect(() => {
+    const el = viewport.current;
+    if (!el) return;
+    const measure = () => setBox((b) => (b.w === el.clientWidth && b.h === el.clientHeight ? b : { w: el.clientWidth, h: el.clientHeight }));
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [tab, good]);
+
+  // How tall the canvas is: `height`, else the drawing at the width's fit.
+  const autoH = size && box.w ? size.h * Math.min(1, (box.w - 2 * PAD) / size.w) + 2 * PAD : minHeight;
+  const canvasH = height != null ? px(height) : `${Math.round(clamp(autoH, minHeight, maxHeight))}px`;
+
+  const fitted = () => {
+    if (!size || !box.w || !box.h) return null;
+    const k = clamp(Math.min(1, (box.w - 2 * PAD) / size.w, (box.h - 2 * PAD) / size.h), MIN_K, MAX_K);
+    return { k, x: (box.w - size.w * k) / 2, y: (box.h - size.h * k) / 2 };
+  };
+
+  // Untouched, the drawing follows the frame (a resize, a new drawing).
+  useEffect(() => {
+    if (!pristine) return;
+    const f = fitted();
+    if (f) setT(f);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [size, box.w, box.h, pristine]);
+
+  const glide = () => {
+    setSmooth(true);
+    setTimeout(() => setSmooth(false), 180);
+  };
+  const zoomAt = (factor, cx0 = box.w / 2, cy0 = box.h / 2, animate = true) => {
+    setPristine(false);
+    if (animate) glide();
+    setT((cur) => {
+      const k = clamp(cur.k * factor, MIN_K, MAX_K);
+      return { k, x: cx0 - ((cx0 - cur.x) * k) / cur.k, y: cy0 - ((cy0 - cur.y) * k) / cur.k };
+    });
+  };
+  const fit = () => {
+    glide();
+    setPristine(true);
+    const f = fitted();
+    if (f) setT(f);
+  };
+  const actual = () => {
+    if (!size) return;
+    glide();
+    setPristine(false);
+    setT({ k: 1, x: (box.w - size.w) / 2, y: (box.h - size.h) / 2 });
+  };
+  const pan = (dx, dy) => {
+    setPristine(false);
+    setT((cur) => ({ ...cur, x: cur.x + dx, y: cur.y + dy }));
+  };
+
+  // Pointer: drag pans; two fingers pinch; Cmd/Ctrl+wheel (and a trackpad
+  // pinch) zooms at the pointer. A plain wheel scrolls the page, as it should.
+  const pointers = useRef(new Map());
+  const gesture = useRef(null);
+  const local = (e) => {
+    const r = viewport.current.getBoundingClientRect();
+    return { x: e.clientX - r.left, y: e.clientY - r.top };
+  };
+  const onPointerDown = (e) => {
+    if (e.button !== 0 || !good) return;
+    viewport.current.setPointerCapture?.(e.pointerId);
+    pointers.current.set(e.pointerId, local(e));
+    const pts = [...pointers.current.values()];
+    gesture.current = pts.length === 2 ? { pinch: Math.hypot(pts[0].x - pts[1].x, pts[0].y - pts[1].y), t } : { from: local(e), t };
+    setDragging(true);
+  };
+  const onPointerMove = (e) => {
+    if (!pointers.current.has(e.pointerId) || !gesture.current) return;
+    pointers.current.set(e.pointerId, local(e));
+    const pts = [...pointers.current.values()];
+    const g = gesture.current;
+    setPristine(false);
+    if (pts.length === 2 && g.pinch) {
+      const d = Math.hypot(pts[0].x - pts[1].x, pts[0].y - pts[1].y);
+      const mid = { x: (pts[0].x + pts[1].x) / 2, y: (pts[0].y + pts[1].y) / 2 };
+      const k = clamp(g.t.k * (d / g.pinch), MIN_K, MAX_K);
+      setT({ k, x: mid.x - ((mid.x - g.t.x) * k) / g.t.k, y: mid.y - ((mid.y - g.t.y) * k) / g.t.k });
+    } else if (g.from) {
+      const p = local(e);
+      setT({ ...g.t, x: g.t.x + p.x - g.from.x, y: g.t.y + p.y - g.from.y });
+    }
+  };
+  const onPointerUp = (e) => {
+    pointers.current.delete(e.pointerId);
+    const pts = [...pointers.current.values()];
+    gesture.current = pts.length === 1 ? { from: pts[0], t } : null;
+    if (!pts.length) setDragging(false);
+  };
+  useEffect(() => {
+    const el = viewport.current;
+    if (!el) return;
+    const onWheel = (e) => {
+      if (!(e.ctrlKey || e.metaKey)) return;
+      e.preventDefault();
+      const r = el.getBoundingClientRect();
+      zoomAt(Math.exp(-e.deltaY * 0.01), e.clientX - r.left, e.clientY - r.top, false);
+    };
+    el.addEventListener("wheel", onWheel, { passive: false });
+    return () => el.removeEventListener("wheel", onWheel);
+  });
+  const onKeyDown = (e) => {
+    const step = e.shiftKey ? 160 : 48;
+    const keys = {
+      "+": () => zoomAt(1.25),
+      "=": () => zoomAt(1.25),
+      "-": () => zoomAt(0.8),
+      _: () => zoomAt(0.8),
+      0: fit,
+      1: actual,
+      ArrowLeft: () => pan(step, 0),
+      ArrowRight: () => pan(-step, 0),
+      ArrowUp: () => pan(0, step),
+      ArrowDown: () => pan(0, -step),
+    };
+    const fn = keys[e.key];
+    if (!fn || e.metaKey || e.ctrlKey || e.altKey) return;
+    e.preventDefault();
+    fn();
+  };
+
+  async function copy(text, what) {
+    try {
+      await navigator.clipboard.writeText(text);
+      toast.success(`Copied ${what}`);
+    } catch {
+      toast.error("Could not reach the clipboard");
+    }
+  }
+  const download = () => {
+    const blob = new Blob([good], { type: "image/svg+xml" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${(title ?? diagramTitle(source) ?? diagramKind(source) ?? "diagram").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "diagram"}.svg`;
+    a.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  };
+
+  const kind = diagramKind(source);
+  const error = result && !result.ok ? result.error : null;
+  const empty = !source.trim();
+  const name = label ?? `${heading(source, title)}${kind && title ? `, ${kind.toLowerCase()}` : ""}`;
+
+  return (
+    <figure ref={frame} className={cx(FRAME, className)}>
+      {toolbar ? (
+        <figcaption className="flex min-h-12 items-center gap-2 border-b border-border py-1.5 ps-4 pe-1.5">
+          <div className="me-auto flex min-w-0 items-baseline gap-2">
+            <span className="truncate text-sm font-medium">{heading(source, title)}</span>
+            {kind && title ? <span className="truncate text-xs text-muted-foreground max-sm:hidden">{kind}</span> : null}
+          </div>
+          <ToggleGroup
+            size="sm"
+            aria-label="Show"
+            value={tab}
+            onChange={setTab}
+            items={[
+              { value: "diagram", label: "Diagram" },
+              { value: "source", label: "Source" },
+            ]}
+          />
+          <Menu
+            label="Diagram actions"
+            items={[
+              { label: "Copy Mermaid source", icon: "copy", disabled: empty, onSelect: () => copy(source, "the Mermaid source") },
+              { label: "Copy SVG", icon: "code", disabled: !good, onSelect: () => copy(good, "the SVG") },
+              { label: "Download SVG", icon: "download", disabled: !good, onSelect: download },
+              { type: "separator" },
+              { label: "Fit to view", icon: "maximize", shortcut: "0", disabled: !good || tab !== "diagram", onSelect: fit },
+              { label: "Actual size", icon: "search", shortcut: "1", disabled: !good || tab !== "diagram", onSelect: actual },
+            ]}
+          />
+        </figcaption>
+      ) : null}
+
+      {tab === "source" ? (
+        <SourceView source={source} errorLine={error?.line} height={height != null ? px(height) : canvasH} onCopy={() => copy(source, "the Mermaid source")} />
+      ) : empty ? (
+        <div className="p-3">
+          <Empty icon="git-branch" title="No diagram yet" body="When there is Mermaid text — a flowchart, a sequence, a timeline — it is drawn here." />
+        </div>
+      ) : (
+        // raw: the canvas — a focusable surface that pans and zooms with the
+        // pointer, wheel and keys; no kit part is a zoomable viewport.
+        <div
+          ref={viewport}
+          role="img"
+          aria-label={name}
+          aria-roledescription="diagram"
+          tabIndex={good ? 0 : -1}
+          onKeyDown={onKeyDown}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onPointerCancel={onPointerUp}
+          onDoubleClick={(e) => {
+            if (!good) return;
+            const p = local(e);
+            zoomAt(e.shiftKey ? 0.5 : 2, p.x, p.y);
+          }}
+          className={cx(
+            "relative touch-none overflow-hidden outline-none select-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+            "bg-[radial-gradient(var(--color-border)_1px,transparent_1px)] [background-size:16px_16px]",
+            good && (dragging ? "cursor-grabbing" : "cursor-grab"),
+          )}
+          style={{ height: canvasH }}
+        >
+          {good ? (
+            <div
+              ref={content}
+              className={cx("absolute left-0 top-0 origin-top-left will-change-transform", smooth && "transition-transform duration-150 ease-out motion-reduce:transition-none", error && "opacity-40")}
+              style={{ transform: `translate(${t.x}px, ${t.y}px) scale(${t.k})`, visibility: size ? "visible" : "hidden" }}
+              dangerouslySetInnerHTML={{ __html: good }}
+            />
+          ) : null}
+
+          {!result && !good ? (
+            <div className="absolute inset-0 grid place-items-center p-6" aria-busy="true">
+              <Skeleton shape="rect" className="h-full max-h-64 w-full max-w-md" />
+              <span className="sr-only">Drawing the diagram</span>
+            </div>
+          ) : null}
+
+          {error && !good ? <ErrorPanel error={error} source={source} onShow={() => setTab("source")} /> : null}
+
+          {error && good ? (
+            <div className="absolute inset-x-3 top-3" onPointerDown={(e) => e.stopPropagation()}>
+              <Notice
+                tone="warning"
+                title={`${error.message} — showing the last version that worked`}
+                action={
+                  <Button size="sm" variant="quiet" onClick={() => setTab("source")}>
+                    Show source
+                  </Button>
+                }
+              >
+                {error.detail}
+              </Notice>
+            </div>
+          ) : null}
+
+          {good ? (
+            // raw: a floating cluster (the map-style zoom pill); its buttons are kit parts.
+            <div
+              className="absolute bottom-3 right-3 flex items-center gap-0.5 rounded-md border border-border bg-popover p-0.5 text-popover-foreground shadow-sm"
+              onPointerDown={(e) => e.stopPropagation()}
+              onDoubleClick={(e) => e.stopPropagation()}
+            >
+              <IconButton icon="minus" size="sm" label="Zoom out" onClick={() => zoomAt(0.8)} disabled={t.k <= MIN_K} />
+              <Button variant="quiet" size="sm" onClick={actual} className="tabular-nums max-sm:hidden" title="Actual size (1)">
+                {Math.round(t.k * 100)}%
+              </Button>
+              <IconButton icon="plus" size="sm" label="Zoom in" onClick={() => zoomAt(1.25)} disabled={t.k >= MAX_K} />
+              <IconButton icon="maximize" size="sm" label="Fit to view (0)" onClick={fit} />
+            </div>
+          ) : null}
+        </div>
+      )}
+    </figure>
+  );
+}
+
+/** A mistake with nothing drawn yet: what, where, and the lines around it. */
+function ErrorPanel({ error, source, onShow }) {
+  const lines = source.split("\n");
+  const at = error.line ?? null;
+  const from = at ? Math.max(1, at - 2) : 1;
+  const to = at ? Math.min(lines.length, at + 2) : Math.min(lines.length, 5);
+  return (
+    <div className="absolute inset-0 overflow-auto p-4" onPointerDown={(e) => e.stopPropagation()}>
+      <div role="alert" className="mx-auto grid max-w-xl gap-3">
+        <div className="flex items-start gap-3">
+          <Icon name="warning" className="mt-0.5 shrink-0 text-destructive" />
+          <div className="min-w-0">
+            <p className="text-sm font-medium">{error.message}</p>
+            {error.detail ? <p className="mt-1 text-sm text-muted-foreground">{error.detail}</p> : null}
+          </div>
+        </div>
+        <pre className="overflow-x-auto rounded-md border border-border bg-background py-2 font-mono text-xs leading-relaxed">
+          {lines.slice(from - 1, to).map((l, i) => {
+            const n = from + i;
+            const bad = n === at;
+            return (
+              <div key={n} className={cx("flex pe-3", bad && "bg-destructive/10")}>
+                <span className={cx("w-10 shrink-0 pe-3 text-right tabular-nums select-none", bad ? "text-destructive" : "text-muted-foreground")}>{n}</span>
+                <span className="whitespace-pre">{l || " "}</span>
+              </div>
+            );
+          })}
+        </pre>
+        <div>
+          <Button size="sm" icon="code" onClick={onShow}>
+            Show source
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** The Mermaid text, numbered, the mistake's line marked. */
+function SourceView({ source, errorLine, height, onCopy }) {
+  const lines = source.split("\n");
+  return (
+    <div className="relative">
+      <pre className="overflow-auto py-3 font-mono text-xs leading-relaxed" style={{ height }} tabIndex={0} aria-label="Mermaid source">
+        {lines.map((l, i) => (
+          <div key={i} className={cx("flex pe-12", errorLine === i + 1 && "bg-destructive/10")}>
+            <span className={cx("w-12 shrink-0 pe-3 text-right tabular-nums select-none", errorLine === i + 1 ? "text-destructive" : "text-muted-foreground")}>{i + 1}</span>
+            <span className="whitespace-pre">{l || " "}</span>
+          </div>
+        ))}
+      </pre>
+      <IconButton icon="copy" size="sm" label="Copy source" onClick={onCopy} className="absolute right-2 top-2" />
+    </div>
+  );
+}

package/registry/blocks/diagram/index.js

@@ -0,0 +1,7 @@
+// The Diagram block — `makersclaw add diagram`. Fixed: compose it through
+// its props (README.md beside this file). The helpers read Mermaid text
+// anywhere, the server included; blocks built on this one draw through
+// <Diagram>, never mermaid directly.
+export { Diagram } from "./diagram";
+export { diagramKind, diagramTitle, describeError } from "./source";
+export { mermaidTheme } from "./palette";

package/registry/blocks/diagram/mermaid.js

@@ -0,0 +1,52 @@
+// The one door to Mermaid (MIT). Every file in this block reaches it
+// through here; a block built on this one renders through <Diagram>.
+//
+// Mermaid is one object for the whole page and its settings are global,
+// so renders go through a queue: each one sets the theme it was asked
+// for and draws, and the next waits. Mermaid loads on the server too (it
+// touches no browser global while it loads — checked in node); it only
+// ever renders in the browser, after the mount guard.
+import mermaid from "mermaid";
+import { describeError } from "./source";
+
+let queue = Promise.resolve();
+let seq = 0;
+
+/**
+ * Draw Mermaid text. Resolves { ok: true, svg } or { ok: false, error:
+ * { line, message, detail } } — never rejects.
+ *   themeVariables  from mermaidTheme (palette.js)
+ *   look            "classic" (default) · "neo" · "handDrawn"
+ */
+export function renderMermaid(source, { themeVariables = {}, look = "classic", fontFamily } = {}) {
+  const job = queue.then(async () => {
+    const id = `mc-diagram-${Date.now().toString(36)}-${++seq}`;
+    try {
+      mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme: "base",
+        look,
+        themeVariables,
+        fontFamily: fontFamily || themeVariables.fontFamily,
+        suppressErrorRendering: true,
+        htmlLabels: true,
+        flowchart: { curve: "basis", padding: 12 },
+        sequence: { mirrorActors: false },
+      });
+      await mermaid.parse(source);
+      const { svg } = await mermaid.render(id, source);
+      return { ok: true, svg };
+    } catch (e) {
+      return { ok: false, error: describeError(e, source) };
+    } finally {
+      // A failed render can leave its scratch element in the body.
+      if (typeof document !== "undefined") {
+        document.getElementById(`d${id}`)?.remove();
+        document.getElementById(id)?.remove();
+      }
+    }
+  });
+  queue = job.catch(() => {});
+  return job;
+}