makersclaw 0.8.0 → 0.8.1

package/registry/blocks/record-grid/record-grid.jsx

@@ -0,0 +1,251 @@
+"use client";
+
+// RecordGrid — a dense grid for reading many records at once: a row
+// number and a tick at the start of every row, the name column pinned
+// beside them while the rest scrolls sideways, a header that is yours to
+// draw (a column's live progress, its cost, its menu), a cell that is
+// yours to draw, marks on whole rows (selected, highlighted, struck,
+// dimmed), one active cell, and the keyboard. Only the rows in the window
+// are drawn, so 2,000 rows scroll like twenty. It scrolls itself: give it
+// a bounded parent (h-full, flex-1 min-h-0).
+//
+// Props in, callbacks out; it never fetches and formats nothing. Tokens
+// only.
+
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { cx } from "../../ui";
+
+const keyOf = (row, rowKey) => (typeof rowKey === "function" ? rowKey(row) : row?.[rowKey ?? "id"]);
+
+/**
+ *   rows         the records, in order
+ *   columns      [{ key, width (px), header (node), cell(row, index) (node),
+ *                 className?, headerClassName?, label? (a screen reader's
+ *                 name for the column when the header is not words) }]
+ *   lead         [{ key, width, header, cell(row, index), className? }]:
+ *                 the columns before the pinned ones (a row number, a tick)
+ *   pinned       how many of `columns` stay put beside `lead` (default 1)
+ *   rowKey       a key or (row) => key (default "id")
+ *   rowHeight    px (default 32); headerHeight px (default 50)
+ *   rowMark(row) { selected, highlighted, struck, dimmed }
+ *   active       { row: key, column: key } the active cell, or null
+ *   onActiveChange(next)  the keyboard or a click moved it
+ *   onCellClick(row, columnKey)  a click on a cell (open it)
+ *   onOpen(row, columnKey)  Enter on the active cell
+ *   after        a node in a row of its own after the last row
+ *   empty        what an empty grid says
+ *   label        what a screen reader calls the grid
+ *   className    layout around it
+ *   ref          { scrollToRow(key), scrollToEnd(), focus() }
+ */
+export const RecordGrid = forwardRef(function RecordGrid(
+  {
+    rows,
+    columns,
+    lead = [],
+    pinned = 1,
+    rowKey = "id",
+    rowHeight = 32,
+    headerHeight = 50,
+    overscan = 8,
+    rowMark,
+    active,
+    onActiveChange,
+    onCellClick,
+    onOpen,
+    after,
+    empty,
+    label = "Records",
+    className,
+  },
+  ref,
+) {
+  const box = useRef(null);
+  const [scroll, setScroll] = useState({ top: 0, left: 0, height: 600 });
+
+  const all = useMemo(() => [...lead.map((c) => ({ ...c, lead: true })), ...columns], [lead, columns]);
+  const stuck = lead.length + Math.max(0, Math.min(pinned, columns.length));
+  const offsets = useMemo(() => {
+    const out = [];
+    let x = 0;
+    for (const c of all) {
+      out.push(x);
+      x += Number(c.width) || 120;
+    }
+    return { at: out, width: x };
+  }, [all]);
+
+  const onScroll = useCallback(() => {
+    const el = box.current;
+    if (!el) return;
+    setScroll((s) => (s.top === el.scrollTop && s.left === el.scrollLeft && s.height === el.clientHeight ? s : { top: el.scrollTop, left: el.scrollLeft, height: el.clientHeight }));
+  }, []);
+
+  useEffect(() => {
+    const el = box.current;
+    if (!el) return;
+    onScroll();
+    const ro = typeof ResizeObserver === "function" ? new ResizeObserver(onScroll) : null;
+    ro?.observe(el);
+    return () => ro?.disconnect();
+  }, [onScroll]);
+
+  const total = rows.length;
+  const first = Math.max(0, Math.floor((scroll.top - headerHeight) / rowHeight) - overscan);
+  const last = Math.min(total, Math.ceil((scroll.top + scroll.height) / rowHeight) + overscan);
+  const shown = rows.slice(first, last);
+
+  const indexOf = useCallback((key) => rows.findIndex((r) => keyOf(r, rowKey) === key), [rows, rowKey]);
+
+  const scrollToIndex = useCallback(
+    (i, block = "nearest") => {
+      const el = box.current;
+      if (!el || i < 0) return;
+      const top = headerHeight + i * rowHeight;
+      const view = el.clientHeight;
+      if (block === "end") el.scrollTop = Math.max(0, top + rowHeight - view);
+      else if (top < el.scrollTop + headerHeight) el.scrollTop = Math.max(0, top - headerHeight);
+      else if (top + rowHeight > el.scrollTop + view) el.scrollTop = top + rowHeight - view;
+    },
+    [headerHeight, rowHeight],
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      scrollToRow: (key) => scrollToIndex(indexOf(key)),
+      scrollToEnd: () => {
+        const el = box.current;
+        if (el) el.scrollTop = el.scrollHeight;
+      },
+      focus: () => box.current?.focus({ preventScroll: true }),
+    }),
+    [indexOf, scrollToIndex],
+  );
+
+  // The active cell stays in view.
+  useEffect(() => {
+    if (active?.row != null) scrollToIndex(indexOf(active.row));
+  }, [active?.row, indexOf, scrollToIndex]);
+
+  const keys = columns.map((c) => c.key);
+  const onKeyDown = (e) => {
+    if (!rows.length || !keys.length) return;
+    const at = active ? indexOf(active.row) : -1;
+    const col = active ? Math.max(0, keys.indexOf(active.column)) : 0;
+    let next = null;
+    if (e.key === "ArrowDown") next = { i: Math.min(total - 1, at + 1), c: col };
+    else if (e.key === "ArrowUp") next = { i: Math.max(0, at < 0 ? 0 : at - 1), c: col };
+    else if (e.key === "ArrowRight") next = { i: Math.max(0, at), c: Math.min(keys.length - 1, col + 1) };
+    else if (e.key === "ArrowLeft") next = { i: Math.max(0, at), c: Math.max(0, col - 1) };
+    else if (e.key === "Home") next = { i: e.metaKey || e.ctrlKey ? 0 : Math.max(0, at), c: 0 };
+    else if (e.key === "End") next = { i: e.metaKey || e.ctrlKey ? total - 1 : Math.max(0, at), c: keys.length - 1 };
+    else if (e.key === "PageDown") next = { i: Math.min(total - 1, at + Math.max(1, Math.floor(scroll.height / rowHeight) - 1)), c: col };
+    else if (e.key === "PageUp") next = { i: Math.max(0, at - Math.max(1, Math.floor(scroll.height / rowHeight) - 1)), c: col };
+    else if (e.key === "Enter" && active) {
+      e.preventDefault();
+      const row = rows[at];
+      if (row) onOpen?.(row, active.column);
+      return;
+    }
+    if (!next) return;
+    e.preventDefault();
+    const row = rows[next.i];
+    if (row) onActiveChange?.({ row: keyOf(row, rowKey), column: keys[next.c] });
+  };
+
+  const stick = (i, head = false) => {
+    if (i >= stuck) return null;
+    return { position: "sticky", left: offsets.at[i], zIndex: head ? 3 : 1 };
+  };
+  const edge = (i) => i === stuck - 1 && scroll.left > 0;
+
+  return (
+    <div
+      ref={box}
+      role="grid"
+      aria-label={label}
+      aria-rowcount={total + 1}
+      aria-colcount={all.length}
+      tabIndex={0}
+      onScroll={onScroll}
+      onKeyDown={onKeyDown}
+      className={cx("relative h-full min-h-0 overflow-auto overscroll-contain outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring", className)}
+    >
+      <div style={{ width: offsets.width, minWidth: "100%", height: headerHeight + total * rowHeight + (after ? 48 : 0) }} className="relative">
+        <div role="row" aria-rowindex={1} className="sticky top-0 z-[2] flex bg-background" style={{ height: headerHeight, width: offsets.width }}>
+          {all.map((c, i) => (
+            <div
+              key={c.key}
+              role="columnheader"
+              aria-label={c.label}
+              className={cx(
+                "shrink-0 overflow-hidden border-b border-r border-border bg-background px-2 pb-1 pt-1.5 text-left align-top",
+                edge(i) && "shadow-[6px_0_8px_-6px_var(--color-foreground)]",
+                c.headerClassName,
+              )}
+              style={{ width: Number(c.width) || 120, ...stick(i, true) }}
+            >
+              {c.header}
+            </div>
+          ))}
+        </div>
+        {total === 0 ? (
+          <div className="px-3 py-6 text-sm text-muted-foreground">{empty ?? "Nothing here."}</div>
+        ) : null}
+        <div style={{ position: "absolute", top: headerHeight + first * rowHeight, left: 0, width: offsets.width }}>
+          {shown.map((row, j) => {
+            const index = first + j;
+            const key = keyOf(row, rowKey);
+            const mark = rowMark?.(row) ?? {};
+            const tint = mark.selected ? "bg-accent text-accent-foreground" : "bg-background";
+            return (
+              <div
+                key={key}
+                role="row"
+                aria-rowindex={index + 2}
+                aria-selected={mark.selected ? true : undefined}
+                className={cx("flex", mark.struck && "text-muted-foreground")}
+                style={{ height: rowHeight }}
+              >
+                {all.map((c, i) => {
+                  const on = active && active.row === key && active.column === c.key;
+                  return (
+                    <div
+                      key={c.key}
+                      role="gridcell"
+                      aria-selected={on ? true : undefined}
+                      onClick={c.lead ? undefined : () => {
+                        onActiveChange?.({ row: key, column: c.key });
+                        onCellClick?.(row, c.key);
+                      }}
+                      className={cx(
+                        "flex shrink-0 items-center overflow-hidden whitespace-nowrap border-b border-r border-border px-2",
+                        tint,
+                        !c.lead && onCellClick && "cursor-pointer",
+                        mark.dimmed && !c.lead && i >= stuck && "opacity-55",
+                        mark.struck && i === stuck - 1 && "line-through decoration-muted-foreground",
+                        mark.highlighted && i === 0 && "border-l-2 border-l-primary",
+                        edge(i) && "shadow-[6px_0_8px_-6px_var(--color-foreground)]",
+                        on && "outline outline-2 -outline-offset-2 outline-ring",
+                        c.className,
+                      )}
+                      style={{ width: Number(c.width) || 120, height: rowHeight, ...stick(i) }}
+                    >
+                      {c.cell ? c.cell(row, index) : row[c.key]}
+                    </div>
+                  );
+                })}
+              </div>
+            );
+          })}
+        </div>
+        {after && total ? (
+          <div className="absolute left-0 flex items-center px-3 text-sm text-muted-foreground" style={{ top: headerHeight + total * rowHeight, minHeight: 48, width: "100%" }}>
+            <div className="sticky left-3">{after}</div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+});

package/registry/blocks/run-history/README.md

@@ -0,0 +1,138 @@
+# RunHistory
+
+> **Superseded** (0.8.1, the automations engine, D26). A job's runs and the account of one, from `useRuns` and `useRun`. For an app whose jobs run on the automations engine, use `run-view`'s `RunsList` and `RunView` (`useAutomation`, `useAutomationRun`). Keep using this block for an app that has not moved: it works as it did.
+
+
+A job's runs, the account of one, and the overview of them all, drawn
+inside the app in its own look. Part of the agent kit (0.8.1): the app
+shows its agent's work itself, beside the rows that work wrote; the
+window's Runs tab stays as the full history.
+
+- `RunHistory` — the runs, newest first: each one's outcome as a mark
+  and a word, its title, one line of what it did, when and what it cost.
+  One is selected.
+- `RunAccount` — that run: its steps in order with how each ended, a row
+  of figures, and the account itself, one line a heading (Read,
+  Suggested, Drafted, Failed).
+- `RunOverview` — completed, failed and in progress, the average run
+  time, and the credits used against the week's cap as a bar.
+
+```jsx
+import { RunHistory, RunAccount, RunOverview } from "../components/blocks/run-history";   // a Makersclaw app
+import { RunHistory, RunAccount, RunOverview } from "@/components/makersclaw/blocks/run-history";   // a shadcn project
+```
+
+Client components. They format no time: each comes in as words. Their own
+width decides their layout: the account's figures run two to a row,
+four from about 672 px; its lines stack their heading over the text
+under about 384 px.
+
+## Props
+
+### RunHistory
+
+- `runs` — `[{ id, status, title, line, when?, cost? }]`, newest first.
+  `status` is `done` (or `ok`) · `failed` · `running` · `needs_you` ·
+  `stopped` · `skipped`: useRuns' `state` passes as it is. A failed
+  run's `line` is in the danger tone: write it as the reason ("Didn't
+  run: Google asked Nadia to sign in again").
+- `selected` — the id the account shows. `onSelect(run)`.
+- `empty` — what an empty history says: when the first run will be.
+- `label` — the list's name for a screen reader (default "Runs").
+- `className`.
+
+### RunAccount
+
+- `title`, `sub` — the run's time, and the muted line beside it.
+- `steps` — `[{ label, status, count? }]`: useRun's `steps` pass as they
+  are.
+- `figures` — `[{ label, value, note?, noteTone?, progress?,
+  progressTone? }]`: a tile each (`progress` 0 to 1 draws a bar;
+  `progressTone` `neutral` · `danger` · `info`).
+- `lines` — `[{ label, text }]`: the account.
+- `empty` — shown while there are no lines (a run still going).
+- `className`.
+
+### RunOverview
+
+- `completed`, `failed`, `running` — counts.
+- `avg` — the average run time, in words ("2 seconds").
+- `credits` — `{ used, of, words }`: the credits used, the week's cap,
+  and their words ("7 of 37,000 this week"); the bar is full in the
+  danger tone. Leave it out with no cap.
+- `title` — default "Overview"; `null` for none. `className`.
+
+## useRuns and useRun (lib/hooks.js)
+
+```js
+const { runs, overview } = useRuns({ job: wakeId, limit: 20 });
+const { run, steps, text, needs } = useRun(selectedId);
+```
+
+`useRuns` reads `GET _claw/runs`: each run's `id`, `title`, `state`
+(`running` · `done` · `failed` · `stopped` · `needs_you`), `job`,
+`trigger` (`schedule` · `manual` · `event` · `ask`), `by` (who pressed
+Run now), `number` (1 is the oldest), `started_at`, `duration_ms`,
+`credits`; and `overview` (`{ completed, failed, running, avg_ms,
+credits_week, cap_week_credits }`). It looks every 5 s while a run is
+going, else every 30 s, and at once after useJobs' Run now. `useRun`
+reads `GET _claw/runs/<id>`: the run, its `steps`, the agent's report
+(`text`) and what it waits on (`needs`), every 2.5 s while it runs. A
+claw from before the doors is `unavailable`: say "No runs yet", never an
+error.
+
+## Who may do what
+
+Any member reads the jobs' runs and their own asks. A teammate's ask is
+never listed: the door leaves it out. Running a job is the
+`schedule-card`'s or the `workflow-view`'s, never this block's.
+
+## Never
+
+- Never a run's outcome by colour alone: the mark and the word come
+  with it.
+- Never an Approve on a run that needs the member: "Needs you" opens the
+  desk, where the yes is given.
+- Never a time or a figure formatted here: the screen says it in the
+  app's words.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { useRun, useRuns } from "../lib/hooks";
+import { RunAccount, RunHistory, RunOverview } from "../components/blocks/run-history";
+
+const at = (iso) => new Date(iso).toLocaleString("en-GB", { weekday: "short", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit" });
+const cr = (n) => (n == null ? null : `${Math.round(n)} cr`);
+
+export default function ReadRuns({ jobId }) {
+  const { runs, overview } = useRuns({ job: jobId });
+  const [id, setId] = useState(null);
+  const open = id ?? runs[0]?.id;
+  const { run, steps, text } = useRun(open);
+  return (
+    <div className="@container grid @3xl:grid-cols-[320px_minmax(0,1fr)]">
+      <RunHistory
+        runs={runs.map((r) => ({ id: r.id, status: r.state, title: `Run #${r.number} · ${at(r.started_at)}`, line: r.trigger === "manual" ? `Run now, by ${r.by}` : r.job, cost: cr(r.credits) }))}
+        selected={open}
+        onSelect={(r) => setId(r.id)}
+        empty="No runs yet. The first runs Mon 12 Oct, 07:00."
+      />
+      <div className="grid content-start gap-4">
+        {run ? <RunAccount title={at(run.started_at)} sub={cr(run.credits)} steps={steps} lines={text ? [{ label: "Report", text }] : []} /> : null}
+        {overview ? (
+          <RunOverview
+            completed={overview.completed}
+            failed={overview.failed}
+            running={overview.running}
+            avg={overview.avg_ms == null ? null : `${Math.round(overview.avg_ms / 1000)} seconds`}
+            credits={overview.cap_week_credits ? { used: overview.credits_week, of: overview.cap_week_credits, words: `${overview.credits_week} of ${overview.cap_week_credits} this week` } : null}
+          />
+        ) : null}
+      </div>
+    </div>
+  );
+}
+```

package/registry/blocks/run-history/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "run-history",
+  "title": "RunHistory",
+  "description": "A job's runs and the account of one, drawn inside the app. RunHistory is the list, newest first: each run's outcome as a mark and a word (completed, failed, running, needs you, stopped, skipped), its title, one line of what it did, when and what it cost. RunAccount is one run: its steps in order with how each ended, a row of figures and the account itself, one line a heading. RunOverview is the summary: completed, failed, in progress, the average run time, and the credits used against the week's cap as a bar. They draw what useRuns() and useRun() return (lib/hooks.js, GET _claw/runs and _claw/runs/<id>). Their own width decides their layout.",
+  "useWhen": "Superseded by run-view for an app whose jobs run on the automations engine; still the block for an app that has not moved (its jobs are the agent's wakes). An app whose agent runs on a schedule, or does work on asks, accounts for itself inside the app: a morning read's page, a nightly import's log, the runs beside a job's card. For the job drawn as a graph with its runs beside it use workflow-view (it uses these); for who did what to the rows use activity-log; for one ask in progress use job-panel.",
+  "tags": ["runs", "history", "schedule", "automation", "agent", "account", "steps", "overview", "credits", "report", "log", "kit"],
+  "exports": ["RunHistory", "RunAccount", "RunOverview"],
+  "files": ["index.js", "run-history.jsx"],
+  "requires": []
+}

package/registry/blocks/run-history/demo.jsx

@@ -0,0 +1,74 @@
+"use client";
+
+// RunHistory, RunAccount and RunOverview with pretend runs — the
+// gallery's and the smoke test's surface. Not installed into apps. A busy
+// history (a run going, one that needs the member, one failed), the
+// account of the one selected, the overview, and an empty history; the
+// account at 368 px too, so its layout by its own width shows.
+import { useState } from "react";
+import { RunAccount, RunHistory, RunOverview } from "../components/blocks/run-history";
+
+const RUNS = [
+  { id: "r14", status: "running", title: "Run #14 · Wed 30 Sep, 07:00", line: "Reading mail · 12 of 40", when: "now" },
+  { id: "r13", status: "needs_you", title: "Run #13 · Tue 29 Sep, 16:10 · Read now, by Owen", line: "Waiting for your yes on the desk: send 3 follow-ups", when: "yesterday", cost: "420 cr" },
+  { id: "r12", status: "done", title: "Run #12 · Tue 29 Sep, 07:02", line: "38 emails, 3 meetings · 4 people, 3 details, 1 move", when: "yesterday", cost: "640 cr" },
+  { id: "r11", status: "failed", title: "Run #11 · Mon 28 Sep, 07:00", line: "Didn't run: Google asked Nadia to sign in again", when: "2 days ago", cost: "0 cr" },
+  { id: "r10", status: "stopped", title: "Run #10 · Fri 25 Sep, 07:00", line: "Stopped by Owen after 2 steps; what it wrote stays", when: "5 days ago", cost: "110 cr" },
+];
+
+const ACCOUNTS = {
+  r14: { title: "Wed 30 Sep, 07:00", sub: "Running · started 2 min ago", steps: [{ label: "Read mail", status: "running", count: "12 of 40" }, { label: "Find people", status: "skipped" }, { label: "Draft follow-ups", status: "skipped" }], lines: [] },
+  r13: { title: "Tue 29 Sep, 16:10", sub: "420 credits · Read now, by Owen", steps: [{ label: "Read mail", status: "done", count: "22 emails" }, { label: "Draft follow-ups", status: "needs_you", count: "3 drafts" }], lines: [{ label: "Drafted", text: "3 follow-ups, to Pennant, Harbor Seed and Lowline. They wait for your yes on the desk." }] },
+  r12: {
+    title: "Tue 29 Sep, 07:02",
+    sub: "640 credits · next Wed 30 Sep, 07:00",
+    steps: [{ label: "Read mail", status: "done", count: "38 emails" }, { label: "Find people", status: "done", count: "4 found" }, { label: "Draft follow-ups", status: "failed" }],
+    figures: [
+      { label: "Runs this month", value: "21", note: "20 completed", noteTone: "success" },
+      { label: "Failures", value: "1", note: "Mon 28 Sep", noteTone: "danger" },
+      { label: "Took", value: "1m 52s" },
+      { label: "Credits this week", value: "4,180", progress: 0.418, note: "of 10,000" },
+    ],
+    lines: [
+      { label: "Read", text: "38 emails and 3 meetings." },
+      { label: "Suggested", text: "4 people, 3 details, 1 deal move — on Today, in pencil." },
+      { label: "Failed", text: "Drafting follow-ups: the model timed out after 60 s. Nothing was sent." },
+    ],
+  },
+  r11: { title: "Mon 28 Sep, 07:00", sub: "0 credits", steps: [{ label: "Read mail", status: "failed" }], lines: [{ label: "Failed", text: "Google asked Nadia to sign in again. No mail was read and nothing was spent." }] },
+  r10: { title: "Fri 25 Sep, 07:00", sub: "110 credits", steps: [{ label: "Read mail", status: "done", count: "9 emails" }, { label: "Find people", status: "stopped" }], lines: [{ label: "Stopped", text: "By Owen. The 9 emails read stay filed." }] },
+};
+
+export default function RunHistoryDemo() {
+  const [id, setId] = useState("r12");
+  const account = ACCOUNTS[id];
+  return (
+    <div className="grid gap-6 p-4">
+      <div className="@container grid min-w-0 overflow-hidden rounded-[var(--radius)] border border-border @3xl:grid-cols-[320px_minmax(0,1fr)]">
+        <RunHistory runs={RUNS} selected={id} onSelect={(r) => setId(r.id)} className="border-border @3xl:border-r" />
+        <div className="grid min-w-0 content-start gap-4 pb-4">
+          <RunAccount {...account} empty={<p className="text-[13px] text-muted-foreground">It says here what it read and did once the run ends.</p>} />
+          <RunOverview
+            className="px-4"
+            completed={149}
+            failed={2}
+            running={1}
+            avg="1 min 52 s"
+            credits={{ used: 4180, of: 10000, words: "4,180 of 10,000 this week" }}
+          />
+        </div>
+      </div>
+      <div className="flex flex-wrap items-start gap-4">
+        <div className="w-full max-w-[368px] rounded-[var(--radius)] border border-border">
+          <RunAccount {...ACCOUNTS.r12} />
+        </div>
+        <div className="grid w-full max-w-[320px] gap-4">
+          <div className="rounded-[var(--radius)] border border-border">
+            <RunHistory runs={[]} empty="No runs yet. The first runs Mon 12 Oct, 07:00, once a mailbox is connected." />
+          </div>
+          <RunOverview completed={0} failed={0} running={0} avg={null} credits={{ used: 0, of: 10000, words: "0 of 10,000 this week" }} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/registry/blocks/run-history/index.js

@@ -0,0 +1,3 @@
+// The RunHistory block — `makersclaw add run-history`. Fixed: compose it
+// through its props (README.md beside this file).
+export { RunHistory, RunAccount, RunOverview } from "./run-history";