makersclaw 0.7.0 → 0.8.1

package/registry/blocks/agent-column/agent-column.jsx

@@ -0,0 +1,492 @@
+"use client";
+
+import { useId, useState } from "react";
+import { Button, Icon, Input, cx } from "../../ui";
+import { CONFIDENCE, answerState, answerWords, markWords, needsCheck, progressWords, shortUrl } from "./model";
+
+// AgentColumn — the pieces of a column an agent fills (or suggests) for
+// every record: the answer as a cell, how sure it is as a mark, the
+// column's progress under its name, and the answer's detail with what a
+// person can do about it. Props in, callbacks out; the block never
+// fetches. The answer's shape is in model.js.
+
+/* ------------------------------ the mark ------------------------------ */
+
+// How sure, drawn so it differs in shape (never colour alone): filled =
+// sure, half = likely, dashed ring = guess, a tick = a person accepted
+// or typed it.
+export function SureMark({ confidence, checked = false, typed = false, className }) {
+  const label = typed ? "typed by you" : checked ? "checked by you" : CONFIDENCE[confidence]?.label;
+  if (!label) return null;
+  if (checked || typed)
+    return (
+      <span role="img" aria-label={label} className={cx("inline-grid size-3 shrink-0 place-items-center text-primary", className)}>
+        <Icon name="check" size={12} />
+      </span>
+    );
+  return (
+    <span role="img" aria-label={label} className={cx("relative inline-block size-2.5 shrink-0 rounded-full", className, MARK[confidence])}>
+      {confidence === "likely" ? <span aria-hidden="true" className="absolute inset-y-0 left-0 w-1/2 bg-foreground" /> : null}
+    </span>
+  );
+}
+
+const MARK = {
+  sure: "bg-foreground",
+  likely: "overflow-hidden border border-foreground",
+  guess: "border border-dashed border-foreground",
+};
+
+/** The key to the marks: "● sure ◐ likely ◌ guess". */
+export function SureLegend({ className }) {
+  return (
+    <span aria-label="How sure" className={cx("flex flex-wrap items-center gap-x-3.5 gap-y-1 text-xs text-muted-foreground", className)}>
+      {["sure", "likely", "guess"].map((c) => (
+        <span key={c} className="inline-flex items-center gap-1.5">
+          <SureMark confidence={c} />
+          <span className={c === "guess" ? "italic" : undefined}>{c}</span>
+        </span>
+      ))}
+    </span>
+  );
+}
+
+/* ------------------------------ the cell ------------------------------ */
+
+const MONO = new Set(["link", "email", "number", "domain"]);
+
+/**
+ * One answer, as a cell: the value and its detail, or the state in words.
+ *
+ *   answer   the answer (model.js), or null for "not asked yet"
+ *   type     how the value reads: text · link · email · number · domain (mono)
+ *   onOpen   makes the cell a button that opens its detail
+ *   onRetry  a failed answer's "Try again" in the cell
+ *   lines    the value's lines before it clips (default 2)
+ */
+export function AnswerCell({ answer, type = "text", onOpen, onRetry, lines = 2, className, label }) {
+  const st = answerState(answer);
+  const mono = MONO.has(type);
+  const body = (() => {
+    switch (st) {
+      case "empty":
+        return <Quiet>not asked yet</Quiet>;
+      case "queued":
+        return <Quiet>{answer?.value ? <Old answer={answer} /> : "Queued"}</Quiet>;
+      case "waiting":
+        return <Quiet>{answerWords(answer)}</Quiet>;
+      case "blocked":
+        return (
+          <div className="min-w-0">
+            <div className="font-medium text-muted-foreground">Can&rsquo;t fill</div>
+            <div className="text-xs text-muted-foreground">needs {answer.blockedBy.join(" and ")}</div>
+          </div>
+        );
+      case "working":
+        return (
+          <div className="min-w-0">
+            <div className="flex items-center gap-2 font-medium text-primary">
+              <span aria-hidden="true" className="size-1.5 animate-pulse rounded-full bg-primary motion-reduce:animate-none" />
+              {answer.value ? "Writing" : "Looking up"}
+            </div>
+            {answer.looking ? <div className="truncate text-xs text-muted-foreground">{answer.looking}</div> : null}
+          </div>
+        );
+      case "two_answers":
+        return (
+          <div className="min-w-0">
+            <div className={cx("flex flex-wrap items-baseline gap-x-1.5", mono && "font-mono")}>
+              <Icon name="git-branch" size={13} className="self-center text-warning" />
+              <span className="font-medium">{answer.value}</span>
+              <span className="font-sans text-xs text-muted-foreground">or</span>
+              <span className="font-medium">{answer.other?.value}</span>
+            </div>
+            <div className="text-xs font-medium text-warning">two answers</div>
+          </div>
+        );
+      case "not_found":
+        return (
+          <div className="min-w-0">
+            <div className="font-medium text-warning">Not found</div>
+            {answer.detail ? <div className="truncate text-xs text-muted-foreground">{answer.detail}</div> : null}
+          </div>
+        );
+      case "failed":
+        return (
+          <div className="min-w-0">
+            <div className="font-medium text-destructive">Failed</div>
+            {answer.detail || answer.note ? <div className="truncate text-xs text-muted-foreground">{answer.detail || answer.note}</div> : null}
+          </div>
+        );
+      case "stale":
+        return (
+          <div className="min-w-0">
+            <div className="text-xs italic text-muted-foreground">out of date</div>
+            <Clamp lines={lines} className="text-muted-foreground">{answer.value}</Clamp>
+          </div>
+        );
+      default:
+        return <Found answer={answer} mono={mono} lines={lines} />;
+    }
+  })();
+  const tint = st === "two_answers" || (needsCheck(answer) && answer?.flag) ? "bg-warning/10" : undefined;
+  const inner = <div className={cx("min-w-0 text-sm", tint && "-mx-2 -my-1 rounded-sm px-2 py-1", tint, className)}>{body}</div>;
+  const retry = st === "failed" && onRetry ? (
+    <Button size="sm" variant="link" onClick={onRetry} className="mt-1 text-xs">
+      Try again
+    </Button>
+  ) : null;
+  if (!onOpen || st === "empty")
+    return (
+      <div>
+        {inner}
+        {retry}
+      </div>
+    );
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={onOpen}
+        aria-label={label}
+        className="block w-full min-w-0 rounded-sm text-left outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        {inner}
+      </button>
+      {retry}
+    </div>
+  );
+}
+
+function Quiet({ children }) {
+  return <div className="text-xs text-muted-foreground">{children}</div>;
+}
+
+function Old({ answer }) {
+  return (
+    <span>
+      Queued · <span className="italic">{answer.value}</span>
+    </span>
+  );
+}
+
+function Clamp({ lines, className, children }) {
+  return (
+    <div className={cx("min-w-0 overflow-hidden", className)} style={{ display: "-webkit-box", WebkitLineClamp: lines, WebkitBoxOrient: "vertical" }}>
+      {children}
+    </div>
+  );
+}
+
+function Found({ answer, mono, lines }) {
+  const st = answerState(answer);
+  const guess = answer.confidence === "guess" && st === "found";
+  const flagLine = answer.flag === "may_not_fit" && !answer.checked ? "may not fit" : null;
+  return (
+    <div className="flex min-w-0 gap-2">
+      <SureMark confidence={answer.confidence} checked={st === "checked"} typed={st === "typed"} className="mt-1.5" />
+      <div className="min-w-0">
+        <Clamp lines={answer.detail ? 1 : lines} className={cx(mono ? "font-mono text-xs leading-5" : "", guess && "italic", answer.flag === "left" && "font-medium")}>
+          {answer.value}
+        </Clamp>
+        {answer.detail ? <div className="truncate text-xs text-muted-foreground">{answer.detail}</div> : null}
+        {flagLine ? <div className="text-xs font-medium text-warning">{flagLine}</div> : null}
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------ the header ------------------------------ */
+
+/**
+ * A column's name and its progress: "Headcount / 20 of 22 · 3 to check".
+ * `progress` is summarizeAnswers(); `agent` false draws a person's own
+ * column (its name and "yours").
+ */
+export function ColumnHeader({ name, progress, agent = true, note, className }) {
+  const words = progress ? progressWords(progress) : null;
+  const [head, ...rest] = words ? words.split(" · ") : [];
+  return (
+    <div className={cx("min-w-0", className)}>
+      <div className="truncate text-sm font-semibold text-foreground">{name}</div>
+      <div className="truncate font-mono text-xs font-normal text-muted-foreground">
+        {agent ? (
+          <>
+            {head}
+            {rest.map((p) => (
+              <span key={p} className={p.endsWith("to check") ? "text-warning" : undefined}>
+                {" · "}
+                {p}
+              </span>
+            ))}
+          </>
+        ) : (
+          (note ?? "yours")
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------ the detail ------------------------------ */
+
+/**
+ * One answer in full, and what a person can do about it.
+ *
+ *   answer         the answer (model.js)
+ *   type           how the value reads: text · link · email · number · domain (mono)
+ *   title          the record ("Klarwerk"); subtitle, a line under it
+ *   question       the column's name ("Headcount")
+ *   needs          [{ name, answer }] the answers this one read (shown as "It needed")
+ *   history        [{ at, words, credits }] earlier asks, oldest first
+ *   askCost        credits an ask again costs ("40")
+ *   placeholder    for "type your own"; hintPlaceholder for the hint
+ *   onAccept()     accept a found answer or a guess
+ *   onPick("one" | "other")   choose one of two answers
+ *   onType(value)  a person's own value
+ *   onAskAgain(hint)
+ *   onKeepNotFound()
+ *   onKeep() / onDrop()   a suggestion's keep and drop
+ *   busy           a call is running (disables the actions)
+ *   children       more of your own under the actions (a row's choices)
+ */
+export function AnswerDetail({
+  answer,
+  type = "text",
+  title,
+  subtitle,
+  question,
+  needs = [],
+  history = [],
+  askCost,
+  placeholder = "Your answer",
+  hintPlaceholder = "a hint, if you have one",
+  onAccept,
+  onPick,
+  onType,
+  onAskAgain,
+  onKeepNotFound,
+  onKeep,
+  onDrop,
+  busy = false,
+  note,
+  children,
+}) {
+  const st = answerState(answer);
+  const [own, setOwn] = useState("");
+  const [hint, setHint] = useState(answer?.hint ?? "");
+  const ownId = useId();
+  const hintId = useId();
+  const typeWord = st === "not_found" ? "Type who it is" : st === "two_answers" ? "Or type your own" : "Or type the one you know";
+  return (
+    <div className="grid gap-5">
+      <header className="grid gap-1">
+        {title ? <h3 className="font-display text-3xl leading-tight">{title}</h3> : null}
+        {subtitle ? <p className="text-sm text-muted-foreground">{subtitle}</p> : null}
+      </header>
+
+      {st === "two_answers" ? (
+        <section className="grid gap-3">
+          <p className="text-sm font-medium text-warning">Two answers: the sources disagree</p>
+          <Choice value={answer.value} detail={answer.detail} source={answer.source} onUse={onPick ? () => onPick("one") : null} busy={busy} />
+          <Choice value={answer.other?.value} detail={answer.other?.detail} source={answer.other?.source} onUse={onPick ? () => onPick("other") : null} busy={busy} />
+        </section>
+      ) : st === "not_found" ? (
+        <section className="grid gap-3">
+          <p className="flex items-baseline gap-2">
+            <span className="font-display text-2xl italic text-warning">Not found</span>
+            {history.length ? <span className="text-sm text-muted-foreground">· asked {history.length + 1 === 2 ? "twice" : `${history.length + 1} times`}</span> : null}
+          </p>
+          {answer.note ? <p className="text-sm">{answer.note}</p> : null}
+          {answer.tried?.length ? (
+            <div className="grid gap-2">
+              <h4 className="text-xs font-medium text-muted-foreground">What it read</h4>
+              {answer.tried.map((t, i) => (
+                <Source key={i} source={t} />
+              ))}
+            </div>
+          ) : null}
+        </section>
+      ) : st === "blocked" || st === "waiting" || st === "queued" || st === "working" || st === "empty" ? (
+        <section className="grid gap-2">
+          <p className="font-display text-2xl italic">{st === "working" ? "Looking up" : answerWords(answer)}</p>
+          {st === "blocked" ? <p className="text-sm text-muted-foreground">It needs {answer.blockedBy.join(" and ")}, which wasn&rsquo;t found. Type it there and this fills from it.</p> : null}
+          {answer?.looking ? <p className="text-sm text-muted-foreground">{answer.looking}</p> : null}
+        </section>
+      ) : (
+        <section className="grid gap-3">
+          <p className={cx("break-words text-xl", MONO.has(type) ? "font-mono text-base" : "font-medium", answer.confidence === "guess" && st === "found" && "italic")}>{answer.value}</p>
+          {answer.detail ? <p className="text-sm text-muted-foreground">{answer.detail}</p> : null}
+          <p className="flex items-center gap-2 text-sm">
+            <SureMark confidence={answer.confidence} checked={st === "checked"} typed={st === "typed"} />
+            <span className="font-medium capitalize">{st === "checked" || st === "typed" ? answerWords(answer) : CONFIDENCE[answer.confidence]?.label ?? "found"}</span>
+            {st === "found" && CONFIDENCE[answer.confidence] ? <span className="text-muted-foreground">· {CONFIDENCE[answer.confidence].words}</span> : null}
+          </p>
+          {answer.source?.url || answer.source?.evidence ? <Source source={answer.source} mark={answer.value} /> : null}
+          {st === "stale" ? <p className="text-sm text-muted-foreground">Out of date: its question or its row changed. It keeps this until a new answer lands.</p> : null}
+        </section>
+      )}
+
+      {needs.length ? (
+        <section className="grid gap-2">
+          <h4 className="text-xs font-medium text-muted-foreground">It needed</h4>
+          <ul className="grid gap-1.5 text-sm">
+            {needs.map((n) => (
+              <li key={n.name} className="flex items-center gap-2">
+                {n.answer ? <SureMark confidence={n.answer.confidence} checked={answerState(n.answer) === "checked"} typed={answerState(n.answer) === "typed"} /> : null}
+                <span>
+                  {n.name}
+                  {n.answer?.confidence ? <span className="text-muted-foreground"> · {n.answer.confidence}</span> : null}
+                  {n.answer?.value ? <span className="text-muted-foreground"> · {n.answer.value}</span> : null}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+
+      {answer?.note && st !== "not_found" ? (
+        <p className="text-sm">
+          <span className="font-medium">How it was found.</span> {answer.note}
+        </p>
+      ) : null}
+
+      {history.length ? (
+        <section className="grid gap-2">
+          <h4 className="text-xs font-medium text-muted-foreground">Asked</h4>
+          <ul className="grid gap-1 text-sm">
+            {history.map((h, i) => (
+              <li key={i} className="flex gap-3">
+                <span className="w-14 shrink-0 text-muted-foreground">{h.at}</span>
+                <span className="min-w-0 flex-1">{h.words}</span>
+                {h.credits != null ? <span data-nums className="font-mono text-xs text-muted-foreground">{h.credits}</span> : null}
+              </li>
+            ))}
+          </ul>
+        </section>
+      ) : null}
+
+      {note ? <p className="text-sm text-muted-foreground">{note}</p> : null}
+
+      {st === "suggested" && (onKeep || onDrop) ? (
+        <div className="flex flex-wrap gap-2">
+          {onKeep ? (
+            <Button variant="primary" onClick={onKeep} disabled={busy}>
+              Keep it
+            </Button>
+          ) : null}
+          {onDrop ? (
+            <Button onClick={onDrop} disabled={busy}>
+              Drop it
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+
+      {(st === "found" || st === "stale") && onAccept && needsCheck(answer) ? (
+        <Button variant="primary" onClick={onAccept} disabled={busy} className="justify-self-start">
+          Accept it
+        </Button>
+      ) : null}
+
+      {onType && st !== "working" ? (
+        <form
+          className="grid gap-1.5"
+          onSubmit={(e) => {
+            e.preventDefault();
+            if (own.trim()) onType(own.trim());
+          }}
+        >
+          <label htmlFor={ownId} className="text-sm font-medium">
+            {typeWord}
+          </label>
+          <div className="flex gap-2">
+            <Input id={ownId} value={own} onChange={(e) => setOwn(e.target.value)} placeholder={placeholder} className="min-w-0 flex-1" />
+            <Button type="submit" disabled={busy || !own.trim()}>
+              Save
+            </Button>
+          </div>
+        </form>
+      ) : null}
+
+      {onAskAgain && st !== "working" && st !== "typed" ? (
+        <form
+          className="grid gap-1.5"
+          onSubmit={(e) => {
+            e.preventDefault();
+            onAskAgain(hint.trim());
+          }}
+        >
+          <label htmlFor={hintId} className="text-sm font-medium">
+            Or ask again, with a hint
+          </label>
+          <div className="flex gap-2">
+            <Input id={hintId} value={hint} onChange={(e) => setHint(e.target.value)} placeholder={hintPlaceholder} className="min-w-0 flex-1" />
+            <Button type="submit" disabled={busy}>
+              Ask again{askCost != null ? <span data-nums className="font-mono text-xs"> · {askCost}</span> : null}
+            </Button>
+          </div>
+        </form>
+      ) : null}
+
+      {st === "not_found" && onKeepNotFound ? (
+        <Button onClick={onKeepNotFound} disabled={busy} className="justify-self-start">
+          Keep &ldquo;not found&rdquo;
+        </Button>
+      ) : null}
+
+      {children}
+    </div>
+  );
+}
+
+function Choice({ value, detail, source, onUse, busy }) {
+  return (
+    <div className="grid gap-2 rounded-lg border border-border p-4">
+      <div className="flex items-baseline gap-3">
+        <span className="font-display text-4xl leading-none">{value}</span>
+        {detail ? <span className="text-sm text-muted-foreground">{detail}</span> : null}
+      </div>
+      {source ? <Source source={source} mark={value} /> : null}
+      {onUse ? (
+        <Button variant="secondary" size="sm" onClick={onUse} disabled={busy} className="justify-self-start">
+          Use {value}
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/** A source: its title and address, and the words on it in the display
+ *  face, the answer marked where it appears. */
+export function Source({ source, mark, className }) {
+  if (!source) return null;
+  const words = markWords(source.evidence, mark);
+  return (
+    <div className={cx("grid gap-0.5 border-l-2 border-border pl-3", className)}>
+      <div className="flex min-w-0 flex-wrap items-baseline gap-x-2 text-sm">
+        {source.title ? <span className="font-medium">{source.title}</span> : null}
+        {source.url ? (
+          <a href={/^https?:/i.test(source.url) ? source.url : `https://${source.url}`} target="_blank" rel="noreferrer" className="min-w-0 truncate font-mono text-xs text-primary underline-offset-2 hover:underline">
+            {shortUrl(source.url)}
+          </a>
+        ) : null}
+      </div>
+      {source.evidence ? (
+        <blockquote className="font-display text-lg leading-snug">
+          &ldquo;
+          {words.map((w, i) =>
+            w.marked ? (
+              <mark key={i} className="rounded-sm bg-primary/15 px-0.5 text-foreground">
+                {w.text}
+              </mark>
+            ) : (
+              <span key={i}>{w.text}</span>
+            ),
+          )}
+          &rdquo;
+        </blockquote>
+      ) : null}
+    </div>
+  );
+}

package/registry/blocks/agent-column/block.json

@@ -0,0 +1,67 @@
+{
+  "name": "agent-column",
+  "title": "AgentColumn",
+  "description": "A column an agent fills (or suggests) for every record, cell by cell: each answer shows its state in words (queued, waits for another column, looking up, found, not found, two answers, can't fill, failed, out of date, checked or typed by a person) and how sure it is as a mark that differs in shape (filled sure, half likely, dashed guess, a tick for a person). Its detail shows the source, the words on the page with the answer marked in them, how it was found, both answers when sources disagree, what was tried when nothing was found, and what a person can do: accept, pick one of two, type their own, ask again with a hint, keep not found, or keep and drop a suggestion. With a column header that carries live progress, a legend, and a picker that chooses columns with their cost per record. Works in data-table cells, a spreadsheet column type, or a list of its own. Grown in Data Enrichment 0.5.0: the receipt (an answer opened as a claim with its citation: each source a clipping with the deciding words underlined, two clippings to pick from, what was tried crossed off), the one-line answer and trust mark a dense grid draws, and a column heading drawn as a job (its progress, its cost per row, its menu).",
+  "useWhen": "An app whose agent fills or proposes values record by record and a person checks them: enrichment of a list, a CRM filling in a contact, a base whose agent fills a field or suggests a cleaner value, a research table. Not for a single agent reply (job-panel) or a person's own typing (spreadsheet, record-form).",
+  "tags": [
+    "enrichment",
+    "column",
+    "cell",
+    "answer",
+    "source",
+    "citation",
+    "confidence",
+    "suggestion",
+    "proposal",
+    "fill",
+    "research",
+    "table",
+    "spreadsheet",
+    "keep",
+    "drop",
+    "receipt",
+    "clipping",
+    "trust",
+    "job",
+    "heading"
+  ],
+  "exports": [
+    "AnswerCell",
+    "AnswerDetail",
+    "ColumnHeader",
+    "SureMark",
+    "SureLegend",
+    "Source",
+    "AgentMark",
+    "AnswerLine",
+    "Clipping",
+    "JobHeader",
+    "Receipt",
+    "ReceiptActions",
+    "TriedList",
+    "TrustMark",
+    "ColumnPicker",
+    "answerColumnType",
+    "answerState",
+    "answerWords",
+    "needsCheck",
+    "summarizeAnswers",
+    "progressWords",
+    "markWords",
+    "decidingWords",
+    "plainWords",
+    "shortUrl",
+    "CONFIDENCE"
+  ],
+  "files": [
+    "index.js",
+    "agent-column.jsx",
+    "receipt.jsx",
+    "column-picker.jsx",
+    "spreadsheet-type.jsx",
+    "model.js"
+  ],
+  "requires": [
+    "agent-marks"
+  ]
+}