makersclaw 0.8.0 → 0.8.1

package/registry/blocks/pace-bar/pace-model.js

@@ -0,0 +1,288 @@
+// The pace bar's arithmetic: a period on a clock, how much of it is gone,
+// how a piece of work stands against that, the gap said in weeks (or days,
+// or points), the words for it, the axis (month names, a tick each Monday,
+// a today line) and the weeks of a strip. Pure: no React, no DOM, no clock
+// of its own (`today` always comes in). The components (pace-bar.jsx) draw
+// what this returns; test/pace-bar.test.mjs pins it.
+//
+// A "day" is a whole number: days since 1970-01-01 in UTC, so a date string
+// means the same day on the server and in the browser. A period includes
+// both its first and its last day, and TODAY COUNTS AS GONE: on the 23rd of
+// a quarter that began on the 1st of July and ends on the 30th of
+// September, 85 of its 92 days are gone, and 92% of the time is gone.
+
+export const DAY_MS = 86400000;
+export const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export const WEEKDAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+
+/** 'YYYY-MM-DD' (or an ISO time) to a day number; null when it is not a date. */
+export function dayNumber(iso) {
+  if (typeof iso === "number" && Number.isFinite(iso)) return Math.round(iso);
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso ?? ""));
+  if (!m) return null;
+  const t = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  // 2026-02-31 is not a day: Date rolls it over, and the roll-over shows.
+  if (new Date(t).getUTCMonth() !== Number(m[2]) - 1) return null;
+  return Math.round(t / DAY_MS);
+}
+
+/** A day number back to 'YYYY-MM-DD'. */
+export function isoOf(day) {
+  const d = new Date(day * DAY_MS);
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+
+/** 0 is Monday, 6 is Sunday. */
+export const weekdayOf = (day) => (new Date(day * DAY_MS).getUTCDay() + 6) % 7;
+export const dateOfMonth = (day) => new Date(day * DAY_MS).getUTCDate();
+export const monthOf = (day) => new Date(day * DAY_MS).getUTCMonth();
+
+/** "23 Sep" */
+export const shortDay = (day) => `${dateOfMonth(day)} ${MONTHS[monthOf(day)]}`;
+/** "Wed 23 Sep" */
+export const dayName = (day) => `${WEEKDAYS[weekdayOf(day)]} ${shortDay(day)}`;
+
+/** A number as a 0..1 share, clamped; null when it is not a number. */
+export function share(x) {
+  if (x == null || x === "") return null;
+  const v = Number(x);
+  return Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : null;
+}
+
+/** A share as a whole percent; null stays null. */
+export const percent = (x) => (x == null ? null : Math.round(x * 100));
+
+/**
+ * The period and where today stands in it.
+ *   total   days in it, both ends counted
+ *   gone    days gone, today counted (0 before it starts, total after it ends)
+ *   share   gone / total, 0..1
+ *   left    days after today (0 on the last day)
+ *   where   "before" | "in" | "after"
+ * Null when either end is missing or the end is before the start. With no
+ * `today`, `where` is "in" with nothing gone and `share` is null: the
+ * period is known but the clock is not.
+ */
+export function periodOf({ start, end, today } = {}) {
+  const s = dayNumber(start);
+  const e = dayNumber(end);
+  if (s == null || e == null || e < s) return null;
+  const t = dayNumber(today);
+  const total = e - s + 1;
+  if (t == null) return { s, e, t: null, total, gone: null, share: null, left: null, where: "in" };
+  if (t < s) return { s, e, t, total, gone: 0, share: 0, left: total, where: "before" };
+  if (t > e) return { s, e, t, total, gone: total, share: 1, left: 0, where: "after" };
+  const gone = t - s + 1;
+  return { s, e, t, total, gone, share: gone / total, left: e - t, where: "in" };
+}
+
+/**
+ * How a piece of work stands against the clock.
+ *
+ *   value      how far along: 0..1 (a spend: how much is used). Null: not known.
+ *   pace       where it should be by now, 0..1. Left out, it is worked out
+ *              from `start`, `end` and `today` (the share of the time gone).
+ *              `null` on purpose: pace is not judged.
+ *   kind       "progress" (default: short of the pace is the gap) or
+ *              "spend" (over the pace is the gap: hours burned against
+ *              time gone)
+ *   tolerance  whole points of the period inside which it is "on pace" (5)
+ *   graceDays  days from the start in which it is not judged yet (0)
+ *   graceFraction  the same as a share of the period, 0..1 (0.2: the first
+ *              fifth; 19 days of a 92-day quarter). The longer of the two
+ *              counts. Without a period it does nothing.
+ *   unit       "week" · "day" · "point". Default "week" when the period is
+ *              known and the kind is progress; otherwise "point".
+ *
+ * Returns
+ *   state      "done" · "unjudged" · "better" · "on" · "worse"
+ *              better/worse mean ahead/behind for progress, under/over for a spend
+ *   value, pace            0..1 (pace null when not judged)
+ *   valuePct, pacePct      whole percents
+ *   gapPts     whole points between them, always >= 0
+ *   amount     the gap in `unit`s (whole, at least 1 when it is not "on"),
+ *              null when on pace or not judged
+ *   unit
+ *   period     periodOf(), or null
+ */
+export function paceOf({ value, pace, start, end, today, kind = "progress", tolerance = 5, graceDays = 0, graceFraction = 0, unit } = {}) {
+  const period = periodOf({ start, end, today });
+  const v = share(value);
+  // pace: undefined → from the clock; null → none.
+  const p = pace === undefined ? (period && period.where !== "before" ? period.share : null) : share(pace);
+  const spend = kind === "spend";
+  const u = unit ?? (period && !spend ? "week" : "point");
+  const valuePct = percent(v);
+  const pacePct = percent(p);
+  const base = { kind, value: v, pace: p, valuePct, pacePct, gapPts: 0, amount: null, unit: u, period };
+  if (!spend && v != null && v >= 1) return { ...base, state: "done" };
+  const fraction = Number.isFinite(graceFraction) && graceFraction > 0 ? Math.min(1, graceFraction) : 0;
+  const graceUntil = period ? Math.max(Number(graceDays) || 0, Math.ceil(fraction * period.total)) : 0;
+  const grace = period && period.gone != null && period.where === "in" && period.gone <= graceUntil;
+  if (v == null || p == null || grace) return { ...base, state: "unjudged" };
+  const diff = spend ? valuePct - pacePct : pacePct - valuePct; // positive: worse
+  const gapPts = Math.abs(diff);
+  if (gapPts <= tolerance) return { ...base, state: "on", gapPts };
+  let amount = gapPts;
+  if (u === "day" && period) amount = Math.max(1, Math.round((gapPts / 100) * period.total));
+  else if (u === "week" && period) amount = Math.max(1, Math.round(((gapPts / 100) * period.total) / 7));
+  return { ...base, state: diff > 0 ? "worse" : "better", gapPts, amount, unit: period || u === "point" ? u : "point" };
+}
+
+export const WORDS = {
+  on: "On pace",
+  unjudged: "Not judged yet",
+  done: "Done",
+  today: "Today",
+  before: "Not started",
+  after: "Ended",
+  units: { week: "wk", day: "d", point: "pts" },
+  behind: (n, unit) => `${n} ${unit} behind`,
+  ahead: (n, unit) => `${n} ${unit} ahead`,
+  over: (n, unit) => `${n} ${unit} over`,
+  under: (n, unit) => `${n} ${unit} under`,
+  sentence: ({ done, gone }) => `${done}% done, ${gone}% of the time gone`,
+  spendSentence: ({ done, gone }) => `${done}% used, ${gone}% of the time gone`,
+  gone: (n) => `${n}% gone`,
+};
+
+const merge = (words) => ({ ...WORDS, ...words, units: { ...WORDS.units, ...(words?.units ?? {}) } });
+
+/** The gap in words: "4 wk behind", "On pace", "2 wk ahead", "Not judged yet", "Done". */
+export function paceWords(p, words) {
+  if (!p) return "";
+  const w = merge(words);
+  if (p.state === "done") return w.done;
+  if (p.state === "unjudged") return w.unjudged;
+  if (p.state === "on") return w.on;
+  const unit = w.units[p.unit] ?? p.unit;
+  const spend = p.kind === "spend";
+  const say = p.state === "worse" ? (spend ? w.over : w.behind) : spend ? w.under : w.ahead;
+  return say(p.amount, unit);
+}
+
+/** The sum in words: "57% done, 88% of the time gone". Empty when either number is missing. */
+export function paceSentence(p, words) {
+  if (!p || p.valuePct == null) return "";
+  const w = merge(words);
+  const gone = p.period?.share != null ? percent(p.period.share) : p.pacePct;
+  if (gone == null) return `${p.valuePct}%`;
+  return (p.kind === "spend" ? w.spendSentence : w.sentence)({ done: p.valuePct, gone });
+}
+
+/**
+ * A tone for a state, for a screen that has no status of its own to say:
+ * on pace or better is "ink", worse by `warnAt` points is "warning", by
+ * `dangerAt` points "danger"; not judged yet is "quiet"; done is "success".
+ */
+export function toneOf(p, { warnAt = 10, dangerAt = 25 } = {}) {
+  if (!p) return "ink";
+  if (p.state === "done") return "success";
+  if (p.state === "unjudged") return "quiet";
+  if (p.state !== "worse") return "ink";
+  if (p.gapPts >= dangerAt) return "danger";
+  if (p.gapPts >= warnAt) return "warning";
+  return "ink";
+}
+
+/** Where a day's left edge falls on the period, 0..1 (can be outside it). */
+export const atDay = (period, day) => (day - period.s) / period.total;
+
+/**
+ * The axis of a period: the share each Monday's left edge falls at (a tick
+ * each, while the period is short enough to read them), each month's 1st
+ * with its name (the period's first day names its month unless the next
+ * month starts right after it), and today.
+ *
+ *   weeks   [{ n, day, at }]  n counts the weeks from 1; `at` is 0..1
+ *   months  [{ day, label, at }]
+ *   todayAt the share the today line stands at (the end of today), or null
+ *   where   "before" | "in" | "after" (as periodOf)
+ */
+export function axisOf({ start, end, today, weekStartsOn = 0 } = {}) {
+  const period = periodOf({ start, end, today });
+  if (!period) return null;
+  const { s, e, total } = period;
+  const weeks = [];
+  if (total <= 200) {
+    let n = 0;
+    for (let d = s; d <= e; d += 1) {
+      if ((weekdayOf(d) - weekStartsOn + 7) % 7 === 0) {
+        n += 1;
+        weeks.push({ n, day: d, at: atDay(period, d) });
+      }
+    }
+  }
+  const months = [];
+  for (let d = s; d <= e; d += 1) if (dateOfMonth(d) === 1) months.push({ day: d, label: MONTHS[monthOf(d)], at: atDay(period, d) });
+  const startsOnFirst = dateOfMonth(s) === 1;
+  const crowded = !startsOnFirst && months.length > 0 && months[0].at < 0.09;
+  if (!startsOnFirst && !crowded) months.unshift({ day: s, label: MONTHS[monthOf(s)], at: 0 });
+  else if (!months.length) months.push({ day: s, label: MONTHS[monthOf(s)], at: 0 });
+  const todayAt = period.where === "in" && period.share != null ? period.share : period.where === "after" ? 1 : null;
+  return { period, weeks, months, todayAt, where: period.where };
+}
+
+/**
+ * The weeks of a strip: one for each week start (Monday by default) in the
+ * period. The days before the first week start belong to week 1, the last
+ * week runs to the period's end. Each week says whether it is gone, current
+ * or still to come.
+ *
+ *   [{ n, from, to, current, state }]  state: "past" · "current" · "future"
+ */
+export function weeksOf({ start, end, today, weekStartsOn = 0 } = {}) {
+  const period = periodOf({ start, end, today });
+  if (!period) return [];
+  const { s, e } = period;
+  const starts = [];
+  for (let d = s; d <= e; d += 1) if ((weekdayOf(d) - weekStartsOn + 7) % 7 === 0) starts.push(d);
+  if (!starts.length) starts.push(s);
+  else starts[0] = s;
+  return starts.map((from, i) => {
+    const to = i + 1 < starts.length ? starts[i + 1] - 1 : e;
+    const t = period.t;
+    const state = t == null ? "future" : t > to ? "past" : t >= from ? "current" : "future";
+    return { n: i + 1, from, to, state, current: state === "current" };
+  });
+}
+
+/**
+ * Marks on the weeks: each mark `{ id, date, by, label }` lands on the week
+ * its date falls in (a date before the first week goes to the first, after
+ * the last to the last; no date is left off, and counted in `skipped`).
+ * `by` is "person", "agent" or nothing.
+ * Returns { weeks: [{ ...week, marks: [...] }], skipped }.
+ */
+export function marksOnWeeks(weeks, marks) {
+  const out = weeks.map((w) => ({ ...w, marks: [] }));
+  let skipped = 0;
+  for (const [i, m] of (marks ?? []).entries()) {
+    const d = dayNumber(m?.date);
+    if (d == null || !out.length) {
+      skipped += 1;
+      continue;
+    }
+    const at = d < out[0].from ? 0 : out.findLastIndex((w) => w.from <= d);
+    out[Math.max(0, at)].marks.push({ ...m, id: m.id ?? `mark-${i}`, day: d, by: m.by === "person" || m.by === "agent" ? m.by : null });
+  }
+  for (const w of out) w.marks.sort((a, b) => a.day - b.day);
+  return { weeks: out, skipped };
+}
+
+/**
+ * Rows in groups. `groups` is `[{ id, ... }]` in the order to draw; a row
+ * names its group with `group`. A row whose group is not listed (or has
+ * none) goes in a trailing group with no heading when any group exists.
+ * With no `groups` there is one headless group of everything.
+ * Returns [{ group | null, rows }].
+ */
+export function groupRows(rows, groups) {
+  const list = rows ?? [];
+  if (!groups?.length) return [{ group: null, rows: list }];
+  const known = new Set(groups.map((g) => g.id));
+  const out = groups.map((g) => ({ group: g, rows: list.filter((r) => r.group === g.id) }));
+  const rest = list.filter((r) => !known.has(r.group));
+  if (rest.length) out.push({ group: null, rows: rest });
+  return out;
+}

package/registry/blocks/record-grid/README.md

@@ -0,0 +1,100 @@
+# RecordGrid
+
+A dense grid for reading many records at once. Each row starts with what
+you put in `lead` (a row number, a tick), then the pinned columns (the
+name), then the rest, which scroll sideways under a sticky header. Every
+header and every cell is yours to draw: a column whose header carries its
+live progress, its price and its own menu; a cell that draws an answer
+with its mark. Whole rows take marks (selected, highlighted, struck,
+dimmed), one cell is active (an outline), the arrow keys move it, Enter
+opens it, a click opens it. Only the rows in the window are drawn, at a
+fixed height, so 2,000 rows scroll like twenty. It scrolls itself: put it
+in a bounded parent (`h-full`, `flex-1 min-h-0`, an AppLayout's content
+with `contentMode="fill"`) that can also shrink sideways: in a grid or
+flex row give that parent `min-w-0`, or the grid's columns widen the
+parent instead of scrolling inside it.
+
+Born in Data Enrichment (0.5.0), moved into the template with the app kit: the list, with
+each agent column a job whose header says how far it got and what a row
+costs, and the receipt of an answer opened beside it.
+
+```jsx
+import { RecordGrid } from "../components/blocks/record-grid";   // a Makersclaw app ("./blocks/record-grid" from components/)
+import { RecordGrid } from "@/components/makersclaw/blocks/record-grid";   // a shadcn project
+```
+
+## Props
+
+- `rows` — the records, in order. Each has a key (`rowKey`).
+- `columns` — `[{ key, width, header, cell(row, index), className?,
+  headerClassName?, label? }]`. `width` in px (default 120). `header` is
+  any node, drawn at the top of a `headerHeight` cell; `cell(row, index)`
+  any node, in a one-line cell of `rowHeight` (it clips: truncate your
+  text). `label` names the column for a screen reader when the header is
+  not words.
+- `lead` — columns before the pinned ones, the same shape: a row number,
+  a tick. They are pinned too, and a click on them is theirs (no active
+  cell).
+- `pinned` — how many of `columns` stay put beside `lead` (default 1).
+  When the grid has scrolled sideways the last pinned column casts an
+  edge.
+- `rowKey` — a key or `(row) => key` (default `"id"`).
+- `rowHeight` (32) · `headerHeight` (50) · `overscan` (8 rows drawn past
+  each end of the window).
+- `rowMark(row)` — `{ selected, highlighted, struck, dimmed }`: selected
+  tints the row with `accent`; highlighted draws a bar in `primary` at
+  its start (the rows a fill will work on); struck lines through the
+  last pinned column and quiets the row (a skipped row); dimmed fades the
+  unpinned cells.
+- `active` — `{ row, column }`, the cell with the outline, or null.
+- `onActiveChange(next)` — a click or a key moved it. Keep it in state.
+- `onCellClick(row, columnKey)` — a click on an unpinned or pinned
+  (not `lead`) cell: open what it shows.
+- `onOpen(row, columnKey)` — Enter on the active cell.
+- `after` — a node in a row of its own after the last row ("+ Add rows").
+- `empty` — what an empty grid says.
+- `label` — what a screen reader calls the grid (`"Records"`).
+- `className` — layout around it. Never colour.
+- `ref` — `{ scrollToRow(key), scrollToEnd(), focus() }`.
+
+Keys, with the grid focused: ↑ ↓ ← → move the active cell · Home / End
+the row's ends (⌘ for the grid's) · Page Up / Down · Enter opens. Your
+own keys (J and K for the next answer to check) go on a parent.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { RecordGrid } from "./blocks/record-grid";
+
+export function Companies({ rows, open }) {
+  const [active, setActive] = useState(null);
+  return (
+    <div className="h-full min-h-0">
+      <RecordGrid
+        label="Companies"
+        rows={rows}
+        lead={[{ key: "n", width: 44, header: "#", cell: (r, i) => i + 1 }]}
+        columns={[
+          { key: "name", width: 180, header: <b>Company</b>, cell: (r) => <span className="truncate">{r.name}</span> },
+          { key: "headcount", width: 120, header: <b>Headcount</b>, cell: (r) => r.headcount },
+        ]}
+        active={active}
+        onActiveChange={setActive}
+        onCellClick={(r, key) => open(r, key)}
+        onOpen={(r, key) => open(r, key)}
+        rowMark={(r) => ({ selected: active?.row === r.id })}
+      />
+    </div>
+  );
+}
+```
+
+## What it will not do
+
+- Edit a cell, sort, filter or page: the rows come in as you want them
+  shown, and your cells' buttons do the work.
+- Rows of their own heights: one height keeps 2,000 rows smooth.
+- Draw a phone layout: below 768px draw your own cards, or let it scroll
+  sideways inside its box.

package/registry/blocks/record-grid/block.json

@@ -0,0 +1,28 @@
+{
+  "name": "record-grid",
+  "title": "RecordGrid",
+  "description": "A dense grid for reading many records at once: a row number and a tick at the start of each row, the name column pinned beside them while the rest scrolls sideways, headers and cells you draw yourself (a column's live progress, its cost, its menu; an answer with its mark), whole-row marks (selected, highlighted, struck, dimmed), one active cell moved by the arrow keys and opened with Enter, and a line after the last row. Only the rows in the window are drawn, so 2,000 rows of 32px scroll smoothly. It scrolls itself inside a bounded parent.",
+  "useWhen": "A list that is read and worked rather than typed into, where each column needs its own header (an agent's column with its progress and price, a column with a menu) and each cell its own drawing: a research list being enriched, a review queue across many records, a report of a long job's rows. Not for editing cells like a sheet (spreadsheet) or a few dozen rows with sort and filters built in (data-table).",
+  "tags": [
+    "grid",
+    "table",
+    "records",
+    "virtual",
+    "pinned column",
+    "header",
+    "dense",
+    "keyboard",
+    "rows",
+    "review",
+    "enrichment",
+    "list"
+  ],
+  "exports": [
+    "RecordGrid"
+  ],
+  "files": [
+    "index.js",
+    "record-grid.jsx"
+  ],
+  "requires": []
+}

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

@@ -0,0 +1,43 @@
+"use client";
+// RecordGrid over 480 rows, and empty — the gallery's and the smoke
+// test's surface. Not installed into apps.
+import { useState } from "react";
+import { RecordGrid } from "../components/blocks/record-grid";
+
+const ROWS = Array.from({ length: 480 }, (_, i) => ({ id: `r${i + 1}`, n: i + 1, name: `Company ${i + 1}`, domain: `company${i + 1}.de`, people: 20 + ((i * 7) % 180), right: i % 5 === 0 }));
+
+export default function Demo() {
+  const [active, setActive] = useState(null);
+  return (
+    <div className="grid grid-cols-[minmax(0,1fr)] gap-6 p-6">
+    <div className="h-96 min-w-0 border border-border">
+      <RecordGrid
+        label="Companies"
+        rows={ROWS}
+        lead={[
+          { key: "n", width: 44, header: <span className="text-xs text-muted-foreground">#</span>, cell: (r) => <span className="ml-auto text-xs text-muted-foreground">{r.n}</span> },
+          { key: "tick", width: 28, header: null, cell: (r) => (r.right ? "✓" : "") },
+        ]}
+        columns={[
+          { key: "name", width: 180, header: <b>Company</b>, cell: (r) => <span className="truncate font-medium">{r.name}</span> },
+          { key: "domain", width: 180, header: <b>Domain</b>, cell: (r) => <span className="truncate">{r.domain}</span> },
+          { key: "people", width: 120, header: <b>Headcount</b>, cell: (r) => r.people },
+        ]}
+        rowMark={(r) => ({ selected: active?.row === r.id, struck: r.n === 4 })}
+        active={active}
+        onActiveChange={setActive}
+        onOpen={(r, key) => setActive({ row: r.id, column: key })}
+        after={<span>+ Add rows</span>}
+      />
+    </div>
+    <div className="h-40 w-80 max-w-full border border-border">
+      <RecordGrid
+        label="No companies yet"
+        rows={[]}
+        columns={[{ key: "name", width: 180, header: <b>Company</b>, cell: (r) => r.name }]}
+        after={<span>No companies yet. Import a CSV, or ask the agent to find some.</span>}
+      />
+    </div>
+    </div>
+  );
+}

package/registry/blocks/record-grid/index.js

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