makersclaw 0.8.0 → 0.8.2

package/registry/blocks/suggestion/README.md

@@ -0,0 +1,171 @@
+# Suggestion
+
+A value the agent proposes, drawn in pencil: **dashed** while it is a
+proposal, **solid** once kept. Its source is always shown, and a person
+keeps or drops it. A proposal differs from a fact in shape, never colour
+alone.
+
+Five shapes, one idea:
+
+- **FieldSuggestion** — under a field: what it holds now ("empty now"),
+  the proposed value, where it came from, Keep and Drop.
+- **InlineSuggestion** — found in place: a small dashed chip inside the
+  cell or field it would fill, its source, a tick and a cross (CRM v2).
+- **TextSuggestion** — a span of text: the old words struck, the new
+  beside them, the reason, the source (Writing Review's proof marks).
+- **Pencil** — the dashed frame for a whole proposed record: a drafted
+  email, a deal, a week's plan ("pencil to ink", Weekly Planner).
+- **SuggestionGroup** — the head over several: "Keep all 6", "Drop all".
+
+And **Looking**: "✦ Looking…" where a value is still being found.
+
+Grown in the CRM (0.7.0) as `field-suggestion`; every export kept its
+props. One change: a FieldSuggestion that was dropped now goes, as an
+InlineSuggestion always did.
+
+```jsx
+import { FieldSuggestion, InlineSuggestion, TextSuggestion, Pencil, SuggestionGroup, Looking } from "../components/blocks/suggestion";   // a Makersclaw app ("./blocks/suggestion" from components/)
+import { FieldSuggestion } from "@/components/makersclaw/blocks/suggestion";   // a shadcn project
+```
+
+Client components; `suggestionSource` is a plain function.
+
+## Which hook feeds it
+
+None of its own. The proposals are app data the agent wrote (a
+`suggestions` table, a column of proposed values). **A keep runs the
+app's own declared action** (`runAction`, lib/actions), so a keep is the
+same write the agent would make, and the door's rules hold for it.
+
+## The verbs are props
+
+Each app says it its way: Keep/Drop (CRM), Apply/Dismiss (Data Tables),
+Accept/Decline (Writing Review). Every shape takes `keepLabel` and
+`dropLabel`; FieldSuggestion and TextSuggestion also take `keptLabel`
+("Applied").
+
+## Props
+
+### FieldSuggestion
+
+- `label` — the field's name ("Job title"). It also names the group for a
+  reader ("Suggested job title") and the buttons ("Keep job title").
+- `current` — what the field holds now; empty → "empty now".
+- `value` — the proposed value (text or a node).
+- `source` — `{ from, at }` ("her email signature", "2026-09-12") or a
+  string.
+- `onKeep()` · `onDrop()` — async, answer `{ ok: true }` or `{ ok: false,
+  error }` (a throw counts as failed). The frame spins while it runs,
+  turns solid when kept, goes when dropped, and says why when it fails.
+- `compact` — icon buttons at the row's end, the label inside the frame:
+  for a list of several.
+- `showLabel` — `false` when you draw the field's label above it.
+- `keepLabel` · `dropLabel` · `keptLabel` — default "Keep", "Drop", "Kept".
+- `formatDate(date)` — how `source.at` is worded (default "Sat 12 Sep").
+
+Under 22rem of its own width the buttons go below the value.
+
+### InlineSuggestion
+
+- `value`, `source`, `label` (names the buttons for a reader),
+  `onKeep()` · `onDrop()`, `keepLabel` · `dropLabel`, `formatDate`.
+
+A dashed chip in the agent's tone (`border-info`); kept, solid with a
+tick; dropped, gone. For a table cell or a record's field list.
+
+### TextSuggestion
+
+- `before` — the words now, struck. Empty for an insertion.
+- `after` — the words proposed. Empty for a cut.
+- `lead` · `tail` — a few words around the span, muted, so it reads in
+  place ("…sorry about ", " order").
+- `reason` — why, one line.
+- `source` — `{ from, at }` or a string: what it leans on (the style
+  guide, a page).
+- `onKeep()` · `onDrop()` — async `{ ok }`.
+- `keepLabel` · `dropLabel` · `keptLabel`.
+
+A reader hears "Remove: … Add: …" for the struck and new words.
+
+### Pencil
+
+- `kicker` — the small line above ("A NEW DEAL").
+- `title` — what it is ("Crumb & Co: 22 shops").
+- `reason` — why the agent proposes it.
+- `children` — your content between the title and the reason.
+- `actions` — your buttons, with your verbs ("Make the deal", "Drop").
+- `state` — `pencil` (default) · `kept` (solid) · `failed` (with
+  `error`).
+- `label` — the region's name for a reader.
+
+### SuggestionGroup
+
+- `title` — "3 details found for Sofia: job title, LinkedIn and city".
+- `description` — where they came from; that nothing changes until kept.
+- `count` — for "Keep all 3" (or `keepAllLabel`). `dropAllLabel` —
+  default "Drop all".
+- `onKeepAll()` · `onDropAll()` — async `{ ok }`; a failure shows under
+  the title.
+- `children` — the suggestions under it.
+
+### Looking
+
+`children` replaces "Looking…". Pulses, and stays still under reduced
+motion.
+
+### suggestionSource({ from, at }, format?)
+
+"her email signature, Sat 12 Sep".
+
+## Who may do what
+
+The block shows the buttons it is given. Give `onKeep`/`onDrop` only to a
+member who may make that write; the declared action's door refuses anyone
+else anyway.
+
+## Never
+
+- Never write the value yourself on render: nothing changes until a
+  person keeps it.
+- Never draw a proposal solid, or a kept value dashed.
+- Never hide the source.
+
+## Example
+
+A contact's found details, kept through the app's declared actions.
+
+```jsx
+"use client";
+import { runAction } from "../lib/actions";
+import { FieldSuggestion, SuggestionGroup } from "../components/blocks/suggestion";
+
+export function FoundDetails({ person, suggestions, reload }) {
+  const done = (r) => {
+    if (r.ok) reload();
+    return r;
+  };
+  return (
+    <SuggestionGroup
+      title={`${suggestions.length} details found for ${person.first_name}`}
+      description="From her email signature and a web search. Nothing changes until you keep them."
+      count={suggestions.length}
+      onKeepAll={async () => done(await runAction({ name: "keep_details", args: { person: person.id } }))}
+      onDropAll={async () => done(await runAction({ name: "drop_details", args: { person: person.id } }))}
+    >
+      {suggestions.map((s) => (
+        <FieldSuggestion
+          key={s.id}
+          label={s.label}
+          current={person[s.column]}
+          value={s.value}
+          source={{ from: s.from, at: s.at }}
+          onKeep={async () => done(await runAction({ name: "keep_detail", args: { id: s.id } }))}
+          onDrop={async () => done(await runAction({ name: "drop_detail", args: { id: s.id } }))}
+        />
+      ))}
+    </SuggestionGroup>
+  );
+}
+```
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.

package/registry/blocks/suggestion/block.json

@@ -0,0 +1,40 @@
+{
+  "name": "suggestion",
+  "title": "Suggestion",
+  "description": "A value the agent proposes, drawn in pencil — dashed while it is a proposal, solid once kept — with its source always shown and a keep or a drop. Five shapes: FieldSuggestion under a field (\"empty now\", the proposed value, where it came from, Keep and Drop); InlineSuggestion found in place, a small dashed chip inside the cell it would fill with a tick and a cross; TextSuggestion, a span of text struck with its replacement beside it, the reason and the source; Pencil, the dashed frame for a whole proposed record (\"pencil to ink\"); SuggestionGroup, the head over several (\"Keep all 6\", \"Drop all\"); and Looking while a value is still being found. The verbs are props (Keep/Drop, Apply/Dismiss, Accept/Decline). Keeps and drops go out through async callbacks that answer { ok }; a failure says why in place.",
+  "useWhen": "The agent proposes values or changes a person keeps or drops: a CRM filling in a contact, a cleaner value in a table cell, a priority on an issue, a proofread sentence, a drafted plan for the week, a batch of moves on a board. For a whole column of answers across many records use agent-column; for one ask's finished changes with an undo use agent-changes.",
+  "tags": [
+    "suggestion",
+    "proposal",
+    "keep",
+    "drop",
+    "accept",
+    "decline",
+    "apply",
+    "dismiss",
+    "pencil",
+    "field",
+    "inline",
+    "found in place",
+    "proofread",
+    "redline",
+    "diff",
+    "enrichment",
+    "source",
+    "review"
+  ],
+  "exports": [
+    "FieldSuggestion",
+    "InlineSuggestion",
+    "TextSuggestion",
+    "Pencil",
+    "SuggestionGroup",
+    "Looking",
+    "suggestionSource"
+  ],
+  "files": [
+    "index.js",
+    "suggestion.jsx"
+  ],
+  "requires": []
+}

package/registry/blocks/suggestion/demo.jsx

@@ -0,0 +1,91 @@
+"use client";
+
+// Every shape of a suggestion, kept, dropped, saving and failing — the
+// gallery's and the smoke test's surface. Not installed into apps.
+import { Button, Card } from "../components/ui";
+import { FieldSuggestion, InlineSuggestion, TextSuggestion, Pencil, SuggestionGroup, Looking } from "../components/blocks/suggestion";
+
+const ok = () => new Promise((r) => setTimeout(() => r({ ok: true }), 600));
+const no = () => new Promise((r) => setTimeout(() => r({ ok: false, error: "The table didn't answer. Try again." }), 600));
+const slow = () => new Promise(() => undefined);
+
+export default function SuggestionDemo() {
+  return (
+    <div className="grid gap-6 p-6 [grid-template-columns:repeat(auto-fit,minmax(min(100%,22rem),1fr))]">
+      <div className="grid content-start gap-4">
+        <SuggestionGroup
+          title="3 details found for Sofia: job title, LinkedIn and city"
+          description="From her email signature of Sat 12 Sep and a web search. Nothing changes until you keep them."
+          count={3}
+          onKeepAll={ok}
+          onDropAll={ok}
+        />
+        <FieldSuggestion label="Job title" value="Head of Retail Operations" source={{ from: "her email signature", at: "2026-09-12" }} onKeep={ok} onDrop={ok} />
+        <FieldSuggestion label="LinkedIn" current="linkedin.com/in/sofia" value="linkedin.com/in/sofia-lindqvist" source="a web search" onKeep={no} onDrop={ok} />
+        <FieldSuggestion compact label="City" value="Minneapolis, MN · Central time" source="her email signature" onKeep={ok} onDrop={ok} />
+        <FieldSuggestion label="Priority" value="Urgent" source="three customers wrote in today" keepLabel="Apply" dropLabel="Dismiss" keptLabel="Applied" onKeep={slow} onDrop={ok} />
+      </div>
+
+      <div className="grid content-start gap-4">
+        <Card title="Found in place">
+          <table className="w-full table-fixed text-sm">
+            <tbody>
+              <tr className="border-b border-border">
+                <td className="w-[7.5rem] py-2 pr-3 text-muted-foreground">Phone</td>
+                <td className="py-2">
+                  <InlineSuggestion label="Phone" value="+1 612 555 0142" source={{ from: "her email signature", at: "2026-09-12" }} onKeep={ok} onDrop={ok} />
+                </td>
+              </tr>
+              <tr className="border-b border-border">
+                <td className="py-2 pr-3 text-muted-foreground">Company size</td>
+                <td className="py-2">
+                  <InlineSuggestion label="Company size" value="51–200" source="LinkedIn" onKeep={no} onDrop={ok} />
+                </td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-3 text-muted-foreground">Website</td>
+                <td className="py-2">
+                  <Looking />
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </Card>
+
+        <TextSuggestion
+          lead="We're sorry about "
+          before="you're"
+          after="your"
+          tail=" order arriving late."
+          reason="“Your” is the owner's; “you're” is “you are”."
+          source="Kestrel's style guide"
+          keepLabel="Accept"
+          dropLabel="Decline"
+          keptLabel="Accepted"
+          onKeep={ok}
+          onDrop={ok}
+        />
+        <TextSuggestion before="we are working to resolve it" reason="Says nothing the next sentence doesn't." onKeep={ok} onDrop={ok} />
+        <TextSuggestion lead="Ships in " after="two to three" tail=" days." reason="The order page says two to three." onKeep={no} onDrop={ok} />
+
+        <Pencil
+          kicker="A new deal"
+          title="Crumb & Co: 22 shops"
+          reason="Sofia: “we're looking at scheduling for all 22 shops”"
+          actions={
+            <>
+              <Button size="sm" variant="primary">
+                Make the deal
+              </Button>
+              <Button size="sm" variant="quiet">
+                Drop
+              </Button>
+            </>
+          }
+        />
+        <Pencil kicker="Monday" title="Pencilled: deep work 9–11, the board review at 2" state="kept" />
+        <Pencil kicker="A move" title="Harbor Seed to Proposal" state="failed" error="Proposal needs an amount first." />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/suggestion/index.js

@@ -0,0 +1,3 @@
+// The Suggestion block — `makersclaw add suggestion`. Fixed: compose it
+// through its props (README.md beside this file).
+export { FieldSuggestion, InlineSuggestion, TextSuggestion, Pencil, SuggestionGroup, Looking, suggestionSource } from "./suggestion";