makersclaw 0.2.0 → 0.3.0

package/registry/blocks/flow-canvas/context.jsx

@@ -0,0 +1,35 @@
+"use client";
+
+// The canvas's context: what a node or a connector needs from the board
+// around it — the handle (api), the active tool, who is being edited, the
+// read-only flag, the palette, the caller's card renderer. FlowCanvas
+// provides it; built-in nodes and a block's own node types read it with
+// useCanvas().
+import { createContext, useContext } from "react";
+
+export const CanvasContext = createContext(null);
+
+const NONE = {
+  api: null,
+  tool: "select",
+  editingNode: null,
+  editingEdge: null,
+  soleEdge: null,
+  readOnly: true,
+  palette: [],
+  renderCard: null,
+  grid: 20,
+};
+
+/**
+ * Inside a node component: `const { api, readOnly, editingNode } = useCanvas()`.
+ *   api          the canvas handle (README "The handle"): updateNodeData,
+ *                edit, commit, addNodes…
+ *   tool         the rail tool in use ("select", "hand", "connector"…)
+ *   editingNode  the id of the node whose words are being edited, or null
+ *   readOnly     true in read-only and presentation mode
+ *   palette      the colour tokens on offer
+ */
+export function useCanvas() {
+  return useContext(CanvasContext) ?? NONE;
+}

package/registry/blocks/flow-canvas/demo.jsx

@@ -0,0 +1,249 @@
+"use client";
+
+// FlowCanvas three ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Board         a launch board with every node type: stickies, the four
+//                 shapes, text, a frame, a card drawn with kit parts
+//                 (renderCard), an image, and a block's own node type
+//                 ("metric") with its own rail tool (M). Connectors with
+//                 labels. Beside it what the helpers read out of the board.
+//                 Read-only, presentation and a failing save behind switches.
+//   Empty         a new board: the first-run hint and the starter templates.
+//   Flowchart     a process drawn by autoLayout, left to right or top down.
+import { useMemo, useState } from "react";
+import { Avatar, Badge, Button, Card, Delta, Switch, TabPanel, Tabs } from "../components/ui";
+import {
+  FlowCanvas,
+  NodeShell,
+  EditableText,
+  autoLayout,
+  boardToMarkdown,
+  boardToText,
+  createEdge,
+  createNode,
+  useCanvas,
+  useFlowCanvas,
+} from "../components/blocks/flow-canvas";
+
+// A block's own node type: a metric tile. NodeShell gives it the selection
+// box, the connection dots and the resize handles; the inside is kit parts.
+function MetricNode({ id, data, selected }) {
+  const { api, editingNode, readOnly } = useCanvas();
+  return (
+    <NodeShell id={id} selected={selected} locked={data?.locked} minWidth={160} minHeight={80}>
+      <div className="grid size-full content-center gap-1 rounded-lg border border-border bg-card p-3 shadow-sm">
+        <EditableText
+          singleLine
+          editing={!readOnly && editingNode === id}
+          value={data?.label}
+          onChange={(v) => api?.updateNodeData(id, { label: v }, { commit: false })}
+          onDone={() => api?.stopEditing()}
+          placeholder="Metric"
+          label="Metric name"
+          className="text-xs font-medium uppercase tracking-wide text-muted-foreground"
+        />
+        <div className="flex items-baseline gap-2">
+          <span className="text-2xl font-semibold tabular-nums">{data?.value ?? "—"}</span>
+          {typeof data?.delta === "number" ? <Delta value={data.delta} suffix="%" /> : null}
+        </div>
+      </div>
+    </NodeShell>
+  );
+}
+const NODE_TYPES = { metric: MetricNode };
+const TOOLS = [
+  {
+    id: "metric",
+    label: "Metric",
+    icon: "chart",
+    shortcut: "M",
+    create: (point) => createNode("metric", point, { width: 200, height: 100, data: { label: "New metric", value: "0" } }),
+  },
+];
+const describeMetric = (n) => (n.type === "metric" ? `Metric: ${n.data?.label ?? "Untitled"} = ${n.data?.value ?? "—"}` : undefined);
+
+// The card node's inside, drawn by the app with kit parts.
+function renderCard(node) {
+  const d = node.data;
+  if (d.kind !== "person") return undefined;
+  return (
+    <div className="flex items-center gap-3 p-3">
+      <Avatar name={d.title} size="md" />
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-sm font-medium">{d.title}</p>
+        <p className="truncate text-xs text-muted-foreground">{d.body}</p>
+      </div>
+      {d.role ? <Badge variant="soft">{d.role}</Badge> : null}
+    </div>
+  );
+}
+
+function launchBoard() {
+  const at = (type, x, y, opts) => createNode(type, { x, y }, opts);
+  const frame = createNode("frame", null, { id: "f-discover", rect: { x: 0, y: 120, width: 700, height: 300 }, data: { title: "Discover", color: "chart-2" } });
+  const title = at("text", 360, 30, { id: "t-title", width: 720, data: { text: "Harbor 2.0 — launch board", textSize: "xl" } });
+  const s1 = at("sticky", 120, 270, { id: "s-interviews", data: { text: "Interview 8 customers who churned in May", color: "warning", meta: "Priya" } });
+  const s2 = at("sticky", 350, 270, { id: "s-heatmap", data: { text: "Pricing page heatmap", color: "chart-3", badge: 3 } });
+  const s3 = at("sticky", 580, 270, { id: "s-trials", data: { text: "Why do trials stall on day 3?", color: "chart-4" } });
+  const kickoff = at("shape", 100, 580, { id: "sh-kickoff", data: { shape: "pill", text: "Kickoff", color: "chart-2" } });
+  const brief = at("shape", 340, 580, { id: "sh-brief", data: { shape: "rect", text: "Draft the brief", color: "muted" } });
+  const legal = at("shape", 580, 580, { id: "sh-legal", data: { shape: "diamond", text: "Legal OK?", color: "warning" } });
+  const ship = at("shape", 840, 580, { id: "sh-ship", data: { shape: "ellipse", text: "Ship 14 Nov", color: "success" } });
+  const owner = at("card", 950, 250, { id: "c-june", data: { kind: "person", title: "June Okafor", body: "Owns the launch", role: "Lead" } });
+  const note = at("card", 950, 400, { id: "c-risk", data: { title: "Risk: EU email timing", body: "The EU list opens at 11:00 — move the send.", icon: "warning", color: "destructive" } });
+  const metric = at("metric", 1220, 580, { id: "m-signups", width: 200, height: 100, data: { label: "Waitlist", value: "4,812", delta: 12 } });
+  const shot = at("image", 1260, 290, { id: "i-hero", width: 260, height: 170, data: { src: "", alt: "Hero screenshot (to come)" } });
+  return {
+    nodes: [frame, title, s1, s2, s3, kickoff, brief, legal, ship, owner, note, metric, shot],
+    edges: [
+      createEdge(kickoff.id, brief.id, { id: "e1" }),
+      createEdge(brief.id, legal.id, { id: "e2" }),
+      createEdge(legal.id, ship.id, { id: "e3", label: "Yes" }),
+      createEdge(legal.id, brief.id, { id: "e4", label: "Changes", data: { line: "elbow", dashed: true } }),
+      createEdge(s1.id, brief.id, { id: "e5", label: "feeds", data: { arrow: "end" } }),
+      createEdge(owner.id, note.id, { id: "e6", data: { arrow: "none", line: "straight" } }),
+    ],
+  };
+}
+
+function BoardDemo() {
+  const start = useMemo(launchBoard, []);
+  const [board, setBoard] = useState(start);
+  const [readOnly, setReadOnly] = useState(false);
+  const [failSave, setFailSave] = useState(false);
+  const [present, setPresent] = useState(false);
+  const [view, setView] = useState("markdown");
+  const canvas = useFlowCanvas();
+  const onSave = async () => (failSave ? { ok: false, error: "Offline — not saved" } : { ok: true });
+  return (
+    <div className="grid gap-4 xl:grid-cols-[minmax(0,1fr)_22rem]">
+      <div className="grid min-w-0 gap-3">
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-1">
+          <Switch id="fc-ro" label="Read-only" checked={readOnly} onChange={(e) => setReadOnly(e.target.checked)} />
+          <Switch id="fc-fail" label="Saving fails" checked={failSave} onChange={(e) => setFailSave(e.target.checked)} />
+          <Button size="sm" icon="play" onClick={() => setPresent(true)}>
+            Present
+          </Button>
+          <Button size="sm" variant="quiet" icon="sparkles" onClick={() => canvas.current?.autoLayout({ direction: "LR" })} disabled={readOnly}>
+            Tidy up
+          </Button>
+        </div>
+        <FlowCanvas
+          canvasRef={canvas}
+          value={board}
+          onChange={setBoard}
+          onSave={onSave}
+          readOnly={readOnly}
+          presentation={present}
+          onExitPresentation={() => setPresent(false)}
+          nodeTypes={NODE_TYPES}
+          tools={TOOLS}
+          renderCard={renderCard}
+          describeNode={describeMetric}
+          pickImage={async () => ({ src: "", alt: "Screenshot placeholder" })}
+          label="Launch board"
+          height={640}
+        />
+      </div>
+      <Card padding="none" className="min-w-0">
+        <Tabs
+          aria-label="What the helpers read"
+          className="px-3"
+          value={view}
+          onChange={setView}
+          tabs={[
+            { key: "markdown", label: "Markdown" },
+            { key: "text", label: "Text (agents)" },
+          ]}
+        />
+        <TabPanel tab="markdown" value={view} className="p-3">
+          <pre className="max-h-[36rem] overflow-auto font-mono text-xs break-words whitespace-pre-wrap text-muted-foreground">{boardToMarkdown(board, { title: "Launch board", describe: describeMetric })}</pre>
+        </TabPanel>
+        <TabPanel tab="text" value={view} className="p-3">
+          <pre className="max-h-[36rem] overflow-auto font-mono text-xs break-words whitespace-pre-wrap text-muted-foreground">{boardToText(board, { describe: describeMetric })}</pre>
+        </TabPanel>
+      </Card>
+    </div>
+  );
+}
+
+function EmptyDemo() {
+  const [board, setBoard] = useState(null);
+  return (
+    <div className="grid gap-3">
+      <p className="text-sm text-muted-foreground">A new board. Double-click the canvas, press N, or start from a template.</p>
+      <FlowCanvas value={board ?? undefined} onChange={setBoard} label="New board" height={520} />
+    </div>
+  );
+}
+
+const STEPS = [
+  ["Lead comes in", "pill", "chart-2"],
+  ["Enrich the account", "rect", "muted"],
+  ["Fits the ICP?", "diamond", "warning"],
+  ["Book a call", "rect", "muted"],
+  ["Nurture list", "rect", "muted"],
+  ["Won", "pill", "success"],
+];
+
+function flowchart(direction) {
+  const nodes = STEPS.map(([text, shape, color], i) => createNode("shape", { x: i * 10, y: 0 }, { id: `p-${i}`, data: { text, shape, color } }));
+  const edges = [
+    createEdge("p-0", "p-1", { id: "pe-1" }),
+    createEdge("p-1", "p-2", { id: "pe-2" }),
+    createEdge("p-2", "p-3", { id: "pe-3", label: "Yes" }),
+    createEdge("p-2", "p-4", { id: "pe-4", label: "No", data: { dashed: true } }),
+    createEdge("p-3", "p-5", { id: "pe-5" }),
+    createEdge("p-4", "p-1", { id: "pe-6", label: "In 30 days", data: { line: "elbow" } }),
+  ];
+  return { nodes: autoLayout(nodes, edges, { direction }), edges };
+}
+
+function FlowchartDemo() {
+  const [direction, setDirection] = useState("LR");
+  const [board, setBoard] = useState(() => flowchart("LR"));
+  const relayout = (d) => {
+    setDirection(d);
+    setBoard((b) => ({ ...b, nodes: autoLayout(b.nodes, b.edges, { direction: d }) }));
+  };
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <Button size="sm" variant={direction === "LR" ? "primary" : "secondary"} onClick={() => relayout("LR")}>
+          Left to right
+        </Button>
+        <Button size="sm" variant={direction === "TB" ? "primary" : "secondary"} onClick={() => relayout("TB")}>
+          Top to bottom
+        </Button>
+      </div>
+      <FlowCanvas value={board} onChange={setBoard} rail={["select", "hand", "|", "shape", "text", "connector"]} label="Lead routing" height={520} />
+    </div>
+  );
+}
+
+export default function FlowCanvasDemo() {
+  const [tab, setTab] = useState("board");
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="FlowCanvas variants"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "board", label: "Board" },
+          { key: "empty", label: "Empty" },
+          { key: "flow", label: "Flowchart" },
+        ]}
+      />
+      <TabPanel tab="board" value={tab}>
+        <BoardDemo />
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        <EmptyDemo />
+      </TabPanel>
+      <TabPanel tab="flow" value={tab}>
+        <FlowchartDemo />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/flow-canvas/edges.jsx

@@ -0,0 +1,107 @@
+"use client";
+
+// The connector: a line between two cards that finds its own way. It
+// leaves and enters by the sides that face each other (board.js
+// facingSides), so it re-routes as the cards move — Miro's behaviour, not
+// React Flow's fixed handles. Curved (default), straight or elbow; an
+// arrowhead at the end, both ends or none; dashed or not; a label in the
+// middle that edits on double-click. Painted with token classes only.
+import { EdgeLabelRenderer, useInternalNode } from "@xyflow/react";
+import { cx } from "../../ui";
+import { facingSides, sidePoint } from "./board";
+import { useCanvas } from "./context";
+import { EditableText } from "./nodes";
+
+const NORMAL = { left: { x: -1, y: 0 }, right: { x: 1, y: 0 }, top: { x: 0, y: -1 }, bottom: { x: 0, y: 1 } };
+
+function rectOf(n) {
+  const p = n.internals?.positionAbsolute ?? n.position ?? { x: 0, y: 0 };
+  return { x: p.x, y: p.y, width: n.measured?.width ?? n.width ?? 0, height: n.measured?.height ?? n.height ?? 0 };
+}
+
+const unit = (v) => {
+  const l = Math.hypot(v.x, v.y) || 1;
+  return { x: v.x / l, y: v.y / l };
+};
+
+/** The path, its middle and the direction at each end, for one connector. */
+export function connectorGeometry(a, sa, b, sb, line = "curved") {
+  if (line === "straight") {
+    const dir = unit({ x: b.x - a.x, y: b.y - a.y });
+    return { d: `M${a.x},${a.y} L${b.x},${b.y}`, mid: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, end: dir, start: { x: -dir.x, y: -dir.y } };
+  }
+  if (line === "elbow") {
+    const horizontal = sa === "left" || sa === "right";
+    if (horizontal) {
+      const mx = (a.x + b.x) / 2;
+      return { d: `M${a.x},${a.y} H${mx} V${b.y} H${b.x}`, mid: { x: mx, y: (a.y + b.y) / 2 }, end: { x: -NORMAL[sb].x, y: 0 }, start: { x: -NORMAL[sa].x, y: 0 } };
+    }
+    const my = (a.y + b.y) / 2;
+    return { d: `M${a.x},${a.y} V${my} H${b.x} V${b.y}`, mid: { x: (a.x + b.x) / 2, y: my }, end: { x: 0, y: -NORMAL[sb].y }, start: { x: 0, y: -NORMAL[sa].y } };
+  }
+  const k = Math.min(160, Math.max(30, Math.hypot(b.x - a.x, b.y - a.y) * 0.4));
+  const c1 = { x: a.x + NORMAL[sa].x * k, y: a.y + NORMAL[sa].y * k };
+  const c2 = { x: b.x + NORMAL[sb].x * k, y: b.y + NORMAL[sb].y * k };
+  const mid = { x: (a.x + 3 * c1.x + 3 * c2.x + b.x) / 8, y: (a.y + 3 * c1.y + 3 * c2.y + b.y) / 8 };
+  return { d: `M${a.x},${a.y} C${c1.x},${c1.y} ${c2.x},${c2.y} ${b.x},${b.y}`, mid, end: { x: -NORMAL[sb].x, y: -NORMAL[sb].y }, start: { x: -NORMAL[sa].x, y: -NORMAL[sa].y } };
+}
+
+function arrowAt(tip, dir, size = 10) {
+  const base = { x: tip.x - dir.x * size, y: tip.y - dir.y * size };
+  const px = -dir.y * size * 0.5;
+  const py = dir.x * size * 0.5;
+  return `M${tip.x},${tip.y} L${base.x + px},${base.y + py} L${base.x - px},${base.y - py} Z`;
+}
+
+const INK = "transition-[stroke,fill] duration-150 motion-reduce:transition-none";
+
+export function FlowEdge({ id, source, target, selected, data, label }) {
+  const s = useInternalNode(source);
+  const t = useInternalNode(target);
+  const { api, editingEdge, readOnly } = useCanvas();
+  if (!s || !t) return null;
+  const a = rectOf(s);
+  const b = rectOf(t);
+  const sides = facingSides(a, b);
+  const p1 = sidePoint(a, sides.source);
+  const p2 = sidePoint(b, sides.target);
+  const g = connectorGeometry(p1, sides.source, p2, sides.target, data?.line ?? "curved");
+  const arrow = data?.arrow ?? "end";
+  const editing = !readOnly && editingEdge === id;
+  const ink = selected ? "stroke-primary" : "stroke-muted-foreground [.react-flow__edge:hover_&]:stroke-foreground";
+  const fill = selected ? "fill-primary" : "fill-muted-foreground [.react-flow__edge:hover_&]:fill-foreground";
+  return (
+    <>
+      <path d={g.d} fill="none" stroke="transparent" strokeWidth={18} className="react-flow__edge-interaction" />
+      <path d={g.d} fill="none" strokeWidth={selected ? 2.5 : 2} strokeDasharray={data?.dashed ? "6 5" : undefined} strokeLinecap="round" className={cx(ink, INK)} />
+      {arrow !== "none" ? <path d={arrowAt(p2, g.end)} className={cx(fill, INK)} /> : null}
+      {arrow === "both" ? <path d={arrowAt(p1, g.start)} className={cx(fill, INK)} /> : null}
+      <EdgeLabelRenderer>
+        {label || editing ? (
+          <div
+            className="nodrag nopan pointer-events-auto absolute top-0 left-0"
+            style={{ transform: `translate(${g.mid.x}px, ${g.mid.y}px) translate(-50%, -50%)` }}
+            onClick={() => !readOnly && !editing && api?.select([], [id])}
+            onDoubleClick={() => !readOnly && api?.editEdge(id)}
+          >
+            <EditableText
+              singleLine
+              editing={editing}
+              value={label}
+              label="Connector label"
+              placeholder="Label"
+              onChange={(v) => api?.updateEdge(id, { label: v }, { commit: false })}
+              onDone={() => api?.stopEditing()}
+              className={cx(
+                "min-w-10 max-w-60 rounded-md border bg-background px-1.5 py-0.5 text-center text-xs leading-snug break-words text-foreground shadow-sm",
+                selected ? "border-primary" : "border-border",
+              )}
+            />
+          </div>
+        ) : null}
+      </EdgeLabelRenderer>
+    </>
+  );
+}
+
+export const BUILT_IN_EDGES = { flow: FlowEdge };