makersclaw 0.2.0 → 0.3.1

package/registry/blocks/job-panel/job-panel.jsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { useEffect, useRef } from "react";
-import { Button, Icon, cx } from "../../ui";
+import { useEffect, useId, useRef, useState } from "react";
+import { Button, Card, Empty, Field, Icon, Skeleton, Textarea, cx } from "../../ui";
 
 // JobPanel — the panel that follows work the founder asked the app's
 // agent for (useJob in lib/hooks.js, README §5 "Commissioning work"). It
@@ -13,6 +13,17 @@ import { Button, Icon, cx } from "../../ui";
 //   const job = useJob();
 //   <Button onClick={() => job.start("Draft a launch plan for Rowhouse")}>Generate a launch plan</Button>
 //   <JobPanel job={job} title="Drafting the launch plan" doneTitle="Launch plan drafted" />
+//
+// variant="generator" is the same panel inside a small studio: a prompt,
+// the surface's own options, Generate, then the results the job made. The
+// block never calls a model and takes no API key or provider: Generate
+// hands the prompt to the app's agent (job.start, or `onGenerate`), and
+// the results are the rows the job wrote, passed back in as `results`.
+//
+//   <JobPanel variant="generator" job={job} promptLabel="Describe the photo"
+//             options={<Field …><Select …/></Field>}
+//             onGenerate={(prompt) => job.start(`Make a product photo: ${prompt}. Size ${size}.`)}
+//             results={photos.map((p) => <PhotoCard key={p.id} photo={p} />)} />
 
 function StepMark({ status }) {
   if (status === "done") return <Icon name="check" size={14} className="shrink-0 text-success" />;
@@ -20,7 +31,12 @@ function StepMark({ status }) {
   return <span aria-hidden="true" className="mx-[3px] size-2 shrink-0 animate-pulse rounded-full bg-primary" />;
 }
 
-export function JobPanel({
+export function JobPanel({ variant = "panel", ...props }) {
+  if (variant === "generator") return <Generator {...props} />;
+  return <Panel {...props} />;
+}
+
+function Panel({
   job,
   title = "Working on it",
   doneTitle = "Done",
@@ -108,3 +124,153 @@ export function JobPanel({
     </section>
   );
 }
+
+const isEmpty = (node) => node == null || node === false || node === "" || (Array.isArray(node) && node.filter(Boolean).length === 0);
+
+// The generator: a form (prompt, options, Generate), the running job's
+// panel under it, and the results. Stacked, or side by side from lg up.
+function Generator({
+  job,
+  prompt: controlled,
+  defaultPrompt = "",
+  onPromptChange,
+  onGenerate,
+  heading,
+  description,
+  promptLabel = "What should it make?",
+  placeholder = "Describe what you want…",
+  promptHint,
+  promptRows = 4,
+  options,
+  generateLabel = "Generate",
+  generateIcon = "wand",
+  canGenerateEmpty = false,
+  disabled = false,
+  aside,
+  results,
+  resultsTitle = "Results",
+  resultsActions,
+  resultsColumns = 1,
+  placeholderResult,
+  emptyTitle = "Nothing made yet",
+  emptyBody = "Describe what you want and press Generate. What it makes lands here.",
+  emptyState,
+  layout = "stacked",
+  title = "Working on it",
+  doneTitle = "Done",
+  failedTitle = "It stopped",
+  onRetry,
+  autoClose = 6000,
+  maxSteps = 6,
+  showText = true,
+  className,
+}) {
+  const id = useId();
+  const [own, setOwn] = useState(defaultPrompt);
+  const [error, setError] = useState(null);
+  const [starting, setStarting] = useState(false);
+  const lastPrompt = useRef("");
+  const value = controlled ?? own;
+  const setValue = (v) => {
+    if (controlled === undefined) setOwn(v);
+    onPromptChange?.(v);
+  };
+  const running = Boolean(job?.running);
+  const canGenerate = !disabled && !running && !starting && (canGenerateEmpty || value.trim().length > 0);
+
+  async function generate(text = value) {
+    if (disabled || running || starting || (!canGenerateEmpty && !text.trim())) return;
+    lastPrompt.current = text.trim();
+    setError(null);
+    setStarting(true);
+    let r;
+    try {
+      r = onGenerate ? await onGenerate(text.trim()) : await job?.start?.(text.trim());
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setStarting(false);
+    if (r && r.ok === false && !r.aborted) setError(r.error ?? "It did not start");
+  }
+  // useJob's start resolves when the job ends; a failure it reports is
+  // already the panel's error, so the field says only what the panel does not.
+  const fieldError = error && !job?.error ? error : null;
+
+  const cols = { 1: "grid-cols-1", 2: "grid-cols-1 sm:grid-cols-2", 3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", 4: "grid-cols-2 lg:grid-cols-4" };
+  const empty = isEmpty(results);
+  const split = layout === "split";
+
+  const form = (
+    <Card title={heading} description={description} className="min-w-0">
+      <div className="grid gap-4">
+        <Field id={id} label={promptLabel} hint={promptHint} error={fieldError ?? undefined}>
+          <Textarea
+            id={id}
+            rows={promptRows}
+            value={value}
+            placeholder={placeholder}
+            disabled={disabled}
+            invalid={Boolean(fieldError)}
+            aria-describedby={fieldError ? `${id}-error` : promptHint ? `${id}-hint` : undefined}
+            onChange={(e) => setValue(e.target.value)}
+            onKeyDown={(e) => {
+              // Cmd/Ctrl+Enter generates; Enter alone is a new line.
+              if (e.key === "Enter" && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+                e.preventDefault();
+                generate();
+              }
+            }}
+          />
+        </Field>
+        {options ? <div className="grid gap-4 sm:grid-cols-2">{options}</div> : null}
+        <div className="flex flex-wrap items-center gap-3">
+          <Button variant="primary" icon={running || starting ? undefined : generateIcon} loading={starting} disabled={!canGenerate} onClick={() => generate()}>
+            {running ? "Working…" : generateLabel}
+          </Button>
+          <p aria-hidden="true" className="hidden text-xs text-muted-foreground md:block">
+            ⌘/Ctrl + Enter
+          </p>
+        </div>
+        <Panel
+          job={job}
+          title={title}
+          doneTitle={doneTitle}
+          failedTitle={failedTitle}
+          onRetry={onRetry ?? (lastPrompt.current || canGenerateEmpty ? () => generate(lastPrompt.current) : undefined)}
+          autoClose={autoClose}
+          maxSteps={maxSteps}
+          showText={showText}
+        />
+      </div>
+    </Card>
+  );
+
+  const shelf = (
+    <section aria-label={resultsTitle} aria-busy={running || undefined} className="grid min-w-0 content-start gap-3">
+      <div className="flex min-h-9 items-center justify-between gap-3">
+        <h3 className="text-sm font-semibold">{resultsTitle}</h3>
+        {resultsActions ? <div className="flex shrink-0 items-center gap-2">{resultsActions}</div> : null}
+      </div>
+      {running ? (
+        <div className={cx("grid gap-3", cols[resultsColumns] ?? cols[1])}>
+          {placeholderResult ?? <Skeleton shape="rect" className="h-32 w-full" />}
+        </div>
+      ) : null}
+      {empty ? (
+        running ? null : emptyState ?? <Empty icon="sparkles" title={emptyTitle} body={emptyBody} className="rounded-lg border border-dashed border-border" />
+      ) : (
+        <div className={cx("grid gap-3", cols[resultsColumns] ?? cols[1])}>{results}</div>
+      )}
+    </section>
+  );
+
+  return (
+    <div className={cx("grid gap-4", split && "lg:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] lg:items-start", className)}>
+      <div className="grid min-w-0 gap-4">
+        {form}
+        {aside}
+      </div>
+      {shelf}
+    </div>
+  );
+}

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

@@ -0,0 +1,133 @@
+# JsonEditor
+
+A JSON editor with two views of one value. **Tree** shows it as folding
+rows: double-click a value to edit it, double-click a key to rename it,
+`+` adds a key or an item, and each row's ⋯ menu copies its path
+(`deal.owner.email`) or value, changes its type, or deletes it — with Undo
+in a toast. **Code** is the text, in the `code-editor` block's JSON mode.
+
+It is checked as it changes. The status line under the title says
+`Valid JSON · 5 keys`, or what is wrong in plain words and where —
+`Line 4: A comma is missing before this` — and clicking it opens the Code
+view at that spot. While the text does not parse the last valid value
+stands and the Tree view waits. Format lays the text out again (keys,
+order and numbers as written); the ⋯ menu copies it pretty or on one
+line, and expands or collapses the tree. Empty, it offers a new object, a
+new list, or a place to paste.
+
+Built on `code-editor` (which `add` installs with it); it never imports
+CodeMirror itself.
+
+```jsx
+import { JsonEditor } from "../components/blocks/json-editor";   // a Makersclaw app ("./blocks/json-editor" from components/)
+import { JsonEditor } from "@/components/makersclaw/blocks/json-editor";   // a shadcn project
+```
+
+`JsonEditor` is a client component: render it from a `"use client"`
+component. The tree helpers (`getAt`, `setAt`, `pathLabel`…) are plain
+functions and work on the server too.
+
+## The data
+
+A plain JSON value: an object, a list, text, a number, true/false or null
+— what `JSON.parse` gives and a `jsonb` column stores. The editor hands
+back a new value on every valid edit and never changes the one you gave
+it.
+
+Two things JavaScript does to any JSON value, here too: keys that look
+like whole numbers (`"2"`) come first in an object, and numbers past 2^53
+lose precision. The Code view's text keeps both as typed until it is
+edited from the Tree.
+
+## Props
+
+- `value` — the JSON value, controlled. A new `value` that is not what
+  the editor last sent through `onChange` is another record: it replaces
+  the text, the folds and the saved state.
+- `defaultValue` — the starting value, uncontrolled. With neither, the
+  editor starts empty.
+- `onChange(value)` — every valid edit, with the whole value. A keystroke
+  that leaves the text broken sends nothing.
+- `onSave(value) → { ok, error? }` — optional, may be async. Shows a Save
+  button (and Cmd/Ctrl+S) that is live when there are valid unsaved
+  changes. It is optimistic: the status says Saved at once; `{ ok: false,
+  error }` (or a throw) puts "Unsaved changes" back and shows `error` in a
+  notice with Try again. Without `onSave`, save through `onChange`
+  yourself.
+- `view` / `defaultView` — `"tree"` (default) or `"code"`, controlled or
+  not; `onViewChange(view)` hears the toggle.
+- `readOnly` — `false` (default). `true`: the tree only folds and copies,
+  the text only selects and copies.
+- `title` — a heading above the status line ("Webhook payload").
+- `expandDepth` — how many levels the tree opens with, default `2`
+  (`0` shows only the top level).
+- `height` — a fixed height (px number or CSS length) for both views.
+  Without it they grow to `maxHeight` (480), then scroll.
+- `placeholder` — the empty Code view's hint.
+- `label` — what a screen reader calls the tree and the editor (default:
+  `title`, else "JSON").
+- `className` — the frame's classes.
+
+### Keys
+
+In the tree (one Tab stop): ↑ ↓ move · → open, then into it · ← close,
+then to the parent · Home / End · Enter or Space opens a folder or edits a
+value · F2 renames a key · Delete removes the row (Undo in the toast).
+Editing: Enter keeps it, Esc puts it back. Cmd/Ctrl+S saves (with
+`onSave`); the Code view keeps every `code-editor` key (Shift+Alt+F
+formats).
+
+### Editing a value
+
+Text is edited bare (no quotes) and stays text. Anything else is read as
+JSON: `42`, `true`, `null`, `[1, 2]`, `{"a": 1}`; what does not read stays
+as text. To turn text into a number (or a list into an object…), use the
+row's ⋯ → Change type, which keeps what it can.
+
+## The helpers
+
+`typeOf(v)`, `pathLabel(path)` (`["deal", "tags", 0]` → `deal.tags[0]`),
+`getAt(root, path)`, `setAt(root, path, v)`, `removeAt(root, path)` →
+`{ root, removed, index }`, `insertAt(root, parentPath, { key?, index?,
+value })`, `renameKey(root, path, to)` → `{ root }` or `{ error }`,
+`flattenTree(value, openIds)`, `expandedTo(value, depth)`, `summary(v)`
+("3 keys"), `preview(v)`. Every edit returns a new root. `JsonTree` is the
+tree on its own (`value`, `onEdit(next, { undo?, message? })`, `open`,
+`setOpen`, `readOnly`) for a screen that wants rows without the frame.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { JsonEditor } from "../components/blocks/json-editor";
+import { saveIntegrationSettings } from "../lib/actions";   // your server action → { ok, error? }
+
+export function WebhookSettings({ integration }) {
+  const [settings, setSettings] = useState(integration.settings);
+  return (
+    <JsonEditor
+      title="Webhook settings"
+      value={settings}
+      onChange={setSettings}
+      onSave={(v) => saveIntegrationSettings(integration.id, v)}
+    />
+  );
+}
+```
+
+Inspect a payload, read-only, as text first:
+
+```jsx
+<JsonEditor title="Last delivery" value={delivery.body} readOnly defaultView="code" height={320} />
+```
+
+## What it will not do
+
+- No JSON Schema: it checks that the text is JSON, not that it has the
+  keys your app needs. Check that in `onSave` and return `{ ok: false,
+  error: "…" }`.
+- No drag to reorder rows; order changes in the Code view.
+- It does not diff two values or merge edits from two people.
+- Very large documents (tens of thousands of rows) are better read in the
+  Code view; the tree draws every open row.

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

@@ -0,0 +1,10 @@
+{
+  "name": "json-editor",
+  "title": "JsonEditor",
+  "description": "A JSON editor in the workspace theme with two views of one value: a Tree of folding rows (edit a value or rename a key in place, add keys and items, change a type, copy a path, delete with Undo, arrow keys throughout) and Code (the code-editor block in JSON mode). Checked as it changes: the status line says what is wrong in plain words and which line, and clicking it goes there. A Format button, copy as pretty or one-line JSON, a friendly empty state with starters, and an optional Save that is optimistic and rolls back with a notice when it fails.",
+  "useWhen": "A screen edits or inspects a JSON value: an integration's settings, a webhook payload, a record's metadata or custom fields column (jsonb), an API response, feature flags. Not for editing SQL or other code (code-editor), a form of known fields (record-form), or a table of rows (data-table).",
+  "tags": ["json", "editor", "tree", "jsonb", "config", "settings", "payload", "webhook", "metadata", "validate", "format", "inspector", "key value"],
+  "exports": ["JsonEditor", "JsonTree", "typeOf", "pathLabel", "getAt", "setAt", "removeAt", "insertAt", "renameKey", "flattenTree", "expandedTo", "summary", "preview"],
+  "files": ["index.js", "json-editor.jsx", "json-tree.jsx", "tree.js"],
+  "requires": ["code-editor"]
+}

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

@@ -0,0 +1,92 @@
+"use client";
+
+// JsonEditor three ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Settings   an integration's settings, edited in the tree, saved through
+//              onSave (a switch makes the save fail, to show the rollback).
+//   Payload    a webhook delivery, read-only, opened in the Code view.
+//   Empty      nothing yet: the starters.
+import { useState } from "react";
+import { Switch, TabPanel, Tabs } from "../components/ui";
+import { JsonEditor } from "../components/blocks/json-editor";
+
+const HUBSPOT_SYNC = {
+  enabled: true,
+  direction: "two-way",
+  schedule: { every: 15, unit: "minutes", quiet_hours: ["22:00", "06:00"] },
+  objects: {
+    contacts: { match_on: "email", fields: ["first_name", "last_name", "title", "phone"] },
+    companies: { match_on: "domain", fields: ["name", "industry", "employees"] },
+    deals: { match_on: "external_id", stages: { qualified: "appointmentscheduled", proposal: "presentationscheduled", won: "closedwon" } },
+  },
+  owner_map: { "priya@acme-sales.co": 51023, "marcus@acme-sales.co": 51087 },
+  notify: { channel: "#revops", on: ["error", "conflict"] },
+  retry_limit: 3,
+  last_error: null,
+};
+
+const DELIVERY = {
+  id: "evt_2Qk81",
+  type: "invoice.paid",
+  created: "2026-09-21T09:14:52Z",
+  livemode: false,
+  data: {
+    invoice: {
+      number: "INV-2041",
+      customer: { name: "Northwind Traders", email: "billing@northwind.example" },
+      lines: [
+        { description: "Growth plan — annual", quantity: 1, amount: 4800 },
+        { description: "Extra seats", quantity: 6, amount: 540 },
+      ],
+      total: 5340,
+      currency: "usd",
+      paid: true,
+    },
+  },
+};
+
+function SettingsDemo() {
+  const [value, setValue] = useState(HUBSPOT_SYNC);
+  const [fail, setFail] = useState(false);
+  return (
+    <div className="grid gap-3">
+      <Switch id="json-fail" label="Make saves fail" checked={fail} onChange={(e) => setFail(e.target.checked)} />
+      <JsonEditor
+        title="HubSpot sync settings"
+        value={value}
+        onChange={setValue}
+        onSave={async () => {
+          await new Promise((r) => setTimeout(r, 600));
+          return fail ? { ok: false, error: "HubSpot rejected the owner map: 51087 is not a user in this portal." } : { ok: true };
+        }}
+      />
+    </div>
+  );
+}
+
+export default function JsonEditorDemo() {
+  const [tab, setTab] = useState("settings");
+  return (
+    <div className="mx-auto w-full max-w-3xl">
+      <Tabs
+        aria-label="Examples"
+        tabs={[
+          { key: "settings", label: "Settings" },
+          { key: "payload", label: "Payload" },
+          { key: "empty", label: "Empty" },
+        ]}
+        value={tab}
+        onChange={setTab}
+      />
+      <TabPanel tab="settings" value={tab}>
+        <SettingsDemo />
+      </TabPanel>
+      <TabPanel tab="payload" value={tab}>
+        <JsonEditor title="Last delivery · invoice.paid" defaultValue={DELIVERY} readOnly defaultView="code" height={360} />
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        <JsonEditor title="Custom fields" />
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/json-editor/index.js

@@ -0,0 +1,7 @@
+// The JsonEditor block — `makersclaw add json-editor`. Fixed: compose it
+// through its props (README.md beside this file). Built on code-editor:
+// the Code view is a CodeEditor in JSON mode. The tree helpers are plain
+// functions of plain values and run anywhere, the server included.
+export { JsonEditor } from "./json-editor";
+export { JsonTree } from "./json-tree";
+export { typeOf, pathLabel, getAt, setAt, removeAt, insertAt, renameKey, flattenTree, expandedTo, summary, preview } from "./tree";