makersclaw 0.8.0 → 0.8.1

package/registry/blocks/flow-editor/README.md

@@ -0,0 +1,108 @@
+# FlowEditor
+
+An automation as a node canvas, in the app's theme. It draws a definition
+and says what was pressed; the screen around it holds the definition and
+applies the edits (`automation-editor` is that screen, ready made).
+
+- **The canvas** — drag the ground to pan; the wheel pans, Ctrl or ⌘ with
+  the wheel and a pinch zoom; **+**, **−**, **0** and the fit button; a map
+  in the corner you can press and drag. Icon cards with a port on each
+  side, curved connectors with arrowheads, the card's number above it and
+  its words below.
+- **A + on every connector** and at the end of every path. A press opens
+  the step picker there and the new step lands exactly where the + was
+  (`onInsert(slot, kind)`).
+- **Branches** — a condition draws its Yes and No paths one above the
+  other, labelled, and they meet again at a small join dot where the next
+  step carries on. A Stop ends its path.
+- **For each** — a dashed box around its steps with a door in and a door
+  out; fold it to one card that lists them.
+- **The agent and the model call** — an agent step is solid in the app's
+  accent (`primary`, as the kit's `AgentMark` draws the agent) with an "A"
+  mark; a model call is outlined in it with a "model" mark; every other step
+  is plain. Shape and a word say which, never colour alone.
+- **A palette** along the bottom (wide enough), or a round + (narrow).
+- **The outline** — the same flow as a nested list: the phone's second
+  view, and a way in by keyboard or a screen reader. Every step is a
+  button; every place a step can go has an "Add a step" button.
+- **A run** — with an `overlay` (from `overlayOf`) every card wears how it
+  went (done, running, failed, waiting, skipped, fixed by the agent,
+  not reached), the path taken is lit and the others dimmed, and a looped
+  step says how many times. A **test run** (a dry run) draws a step that
+  stood in for itself as a dashed card with a pencil and one line of what
+  it would do ("Would send with send_email."); a step that needs what such
+  a step would have made says "Not checked". Both read off `overlayOf`'s
+  `would` state and the summary's `would` and `unchecked`.
+
+```jsx
+import { FlowEditor } from "../components/blocks/flow-editor";   // a Makersclaw app
+import { FlowEditor } from "@/components/makersclaw/blocks/flow-editor";   // a shadcn project
+```
+
+`makersclaw add flow-editor` lays `step-picker` and `automation-model`
+with it. A client component. It takes the width it is given and its own
+width decides its layout; give it a parent with a height (it fills it, and
+is at least 320 px tall). It never scrolls the page.
+
+## Props
+
+### FlowEditor
+
+- `def` — the definition shown (`{ trigger, steps, … }`).
+- `selectedId`, `onSelect(id | null)` — a step id, `"trigger"`, or none.
+- `editable` — the + buttons and the palette. Leave it out to look.
+- `onInsert(slot, kind)` — a + was pressed and a kind chosen. `slot` is
+  `{ list, index }`: pass it to automation-model's `insertStep` or
+  `addStep(def, slot, kind)`.
+- `onAddAtSelection(kind)` — the palette (or the round add) chose a kind.
+- `overlay` — a run's `overlayOf(layout, steps, status)`, or null.
+- `flagged` — a `Set` of step ids with something to fix (a red mark).
+- `prices` — a `Map` of step id → `{ credits, max }`: a paid step's price
+  tag ("about 3 cr"), from `priceMap(estimate)`.
+- `fitKey` — changes when the picture should fit again (another
+  automation, another run). `revealId` — pan so this step is in view.
+- `runnable` — a `Set` of the kinds the platform runs.
+- `undo` — `{ canUndo, canRedo, onUndo, onRedo }`: draws the history
+  buttons. `onOpenFlow` — draws the gear (the automation's own settings).
+- `className`.
+
+### The parts
+
+`FlowCanvas` (the canvas alone, given a `layout`), `StepOutline` (the
+list), `Minimap`.
+
+## Never
+
+- Never edit the definition inside it: it only says what was pressed.
+- Never a state by colour alone: each card has its mark and its word.
+- Never a graph with a free arrow: the format is a tree, so a branch only
+  meets again where its condition ends.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { addStep, blankAutomation } from "../components/blocks/automation-model";
+import { FlowEditor } from "../components/blocks/flow-editor";
+
+export default function Flow() {
+  const [def, setDef] = useState(() => ({ ...blankAutomation("Monday note", "monday-note", { type: "schedule", cron: "0 9 * * 1", tz: "team" }), steps: [{ id: "note", kind: "notify", message: "Look at the week ahead." }] }));
+  const [selected, setSelected] = useState(null);
+  return (
+    <div className="flex h-[560px] flex-col rounded-lg border border-border">
+      <FlowEditor
+        def={def}
+        editable
+        selectedId={selected}
+        onSelect={setSelected}
+        onInsert={(slot, kind) => {
+          const r = addStep(def, slot, kind);
+          setDef(r.def);
+          setSelected(r.id);
+        }}
+      />
+    </div>
+  );
+}
+```

package/registry/blocks/flow-editor/block.json

@@ -0,0 +1,44 @@
+{
+  "name": "flow-editor",
+  "title": "FlowEditor",
+  "description": "An automation as a node canvas, in the app's theme: pan, zoom, fit and a map; icon cards with ports and curved connectors with arrowheads; a + on every connector and at every path's end; labelled Yes/No branches that meet again at a join; a dashed for-each box that folds to one card; the app's accent on agent and model steps (solid for the agent, outlined for a model call); a palette of the kinds; undo and redo; and an outline view of the same flow for a thumb or a keyboard. FlowEditor draws a definition and says what was pressed (insert, select, fold); FlowCanvas, StepOutline and Minimap are its parts. In a run it wears an overlay: each card shows how it went, the path taken is lit and the others dimmed, a card the agent fixed says so.",
+  "useWhen": "An app shows what an automation does as a flow a member can read and change: a CRM's morning read, an inbox sweep, a nightly import, an event-driven workflow. For the whole page (header, panels, save) place automation-editor; for one run use run-view; for a read-only graph of a job's run top to bottom use workflow-view. Not a free-form board (flow-canvas) and not a mind map.",
+  "tags": [
+    "automation",
+    "workflow",
+    "canvas",
+    "node",
+    "flow",
+    "graph",
+    "trigger",
+    "steps",
+    "branches",
+    "condition",
+    "loop",
+    "for each",
+    "n8n",
+    "make",
+    "zapier",
+    "builder",
+    "editor",
+    "run",
+    "overlay"
+  ],
+  "exports": [
+    "FlowCanvas",
+    "FlowEditor",
+    "Minimap",
+    "StepOutline"
+  ],
+  "files": [
+    "index.js",
+    "flow-canvas.jsx",
+    "flow-editor.jsx",
+    "outline.jsx",
+    "minimap.jsx"
+  ],
+  "requires": [
+    "automation-model",
+    "step-picker"
+  ]
+}

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

@@ -0,0 +1,115 @@
+"use client";
+
+// FlowEditor with a pretend automation — the gallery's and the smoke
+// test's surface. Not installed into apps. Edit it (a + inserts a step, a
+// card selects), then look at a run: the path taken is lit and the others
+// dimmed, a step the agent fixed says so. A width picker shows the layout
+// at 1280, 800, 368 and 320 px of the block's own width.
+import { useMemo, useState } from "react";
+import { Button, ButtonGroup } from "../components/ui";
+import { FlowEditor } from "../components/blocks/flow-editor";
+import { addStep, flaggedSteps, checkAutomation, layoutAutomation, overlayOf, priceMap, triggerWords } from "../components/blocks/automation-model";
+
+const MORNING = {
+  format: 1,
+  key: "morning-read",
+  name: "Morning read",
+  does: "Reads your mail, saves who you met, drafts the follow-ups that are owed.",
+  trigger: { type: "schedule", cron: "0 7 * * 1-5", tz: "team" },
+  inputs: {},
+  settings: { overlap: "skip", on_failure: "retry_then_agent", only_if_changed: false },
+  steps: [
+    {
+      id: "gate",
+      kind: "condition",
+      label: "Is the morning read on?",
+      if: "{{ trigger.at }}",
+      then: [{ id: "mail", kind: "tool", label: "Read the mail since the last read", needs: { category: "mail" }, tool: "list_messages", input: { since: "{{ trigger.at }}", limit: 200 } }],
+      else: [{ id: "off", kind: "stop", message: "Switched off" }],
+    },
+    { id: "touches", kind: "action", label: "Save who wrote", action: "record_touches", input: { touches: "{{ steps.mail.output.messages }}" } },
+    {
+      id: "drafts",
+      kind: "loop",
+      over: "{{ steps.touches.output.owed }}",
+      max: 8,
+      steps: [
+        { id: "draft", kind: "llm", label: "Write the follow-up", tier: "smart", prompt: "Write a short follow-up to {{ item.name }}." },
+        { id: "save", kind: "action", label: "Save the draft", action: "suggest", input: { person: "{{ item.id }}", body: "{{ steps.draft.output.text }}" } },
+      ],
+    },
+    { id: "check", kind: "agent", label: "Look at anything odd", instructions: "Read the list and say what looks wrong.", cap_credits: 40 },
+    { id: "tell", kind: "notify", message: "Morning read done." },
+  ],
+};
+
+const T0 = "2026-10-12T07:00:00.000Z";
+const row = (step_id, over = {}) => ({ path: step_id, step_id, kind: "notify", attempt: 1, status: "done", started_at: T0, ended_at: T0, credits: 0, error: null, ...over });
+const RUN = [
+  row("gate", { kind: "condition", output: { taken: "then" } }),
+  row("mail", { kind: "tool" }),
+  row("touches", { kind: "action", fix: { by: "agent", kind: "format", before: "Ana@x.com ", after: "ana@x.com", why: "The mail tool refuses spaces." } }),
+  row("drafts", { kind: "loop" }),
+  row("draft", { path: "drafts[0]/draft", kind: "llm", credits: 1.2 }),
+  row("save", { path: "drafts[0]/save", kind: "action" }),
+  row("draft", { path: "drafts[1]/draft", kind: "llm", credits: 1.1 }),
+  row("save", { path: "drafts[1]/save", kind: "action", status: "failed", error: { code: "x", words: "That person was removed." } }),
+];
+const ESTIMATE = { credits: 5, credits_max: 60, steps: [{ id: "draft", credits: 1.2, credits_max: 8 }, { id: "check", credits: 10, credits_max: 40 }] };
+const WIDTHS = [1280, 800, 368, 320];
+
+export default function FlowEditorDemo() {
+  const [width, setWidth] = useState(1280);
+  const [mode, setMode] = useState("edit");
+  const [def, setDef] = useState(MORNING);
+  const [selected, setSelected] = useState(null);
+  const [reveal, setReveal] = useState(null);
+  const issues = useMemo(() => checkAutomation(def), [def]);
+  const overlay = useMemo(() => overlayOf(layoutAutomation(def, { triggerWords: triggerWords(def.trigger) }), RUN, "failed"), [def]);
+  return (
+    <div className="grid gap-4 p-4">
+      <div className="flex flex-wrap gap-2">
+        <ButtonGroup aria-label="The block's width">
+          {WIDTHS.map((w) => (
+            <Button key={w} size="sm" variant={w === width ? "primary" : "secondary"} onClick={() => setWidth(w)}>
+              {w} px
+            </Button>
+          ))}
+        </ButtonGroup>
+        <ButtonGroup aria-label="Editing or a run">
+          <Button size="sm" variant={mode === "edit" ? "primary" : "secondary"} onClick={() => setMode("edit")}>
+            Editing
+          </Button>
+          <Button size="sm" variant={mode === "run" ? "primary" : "secondary"} onClick={() => setMode("run")}>
+            A run
+          </Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex h-[620px] w-full flex-col overflow-hidden rounded-lg border border-border" style={{ maxWidth: width }}>
+        <FlowEditor
+          def={def}
+          selectedId={selected}
+          onSelect={setSelected}
+          editable={mode === "edit"}
+          overlay={mode === "run" ? overlay : null}
+          flagged={mode === "edit" ? flaggedSteps(issues) : undefined}
+          prices={priceMap(ESTIMATE)}
+          fitKey={mode}
+          revealId={reveal}
+          onInsert={(slot, kind) => {
+            const r = addStep(def, slot, kind);
+            setDef(r.def);
+            setSelected(r.id);
+            setReveal(r.id);
+          }}
+          onAddAtSelection={(kind) => {
+            const r = addStep(def, { list: { at: "root" }, index: def.steps.length }, kind);
+            setDef(r.def);
+            setSelected(r.id);
+            setReveal(r.id);
+          }}
+        />
+      </div>
+    </div>
+  );
+}