makersclaw 0.8.0 → 0.8.1

package/registry/blocks/schedule-card/schedule-card.jsx

@@ -0,0 +1,136 @@
+"use client";
+
+// One scheduled job on a card. Props in, callbacks out; the block never
+// reads the schedule or the runs itself, and formats nothing (each line
+// comes in as words). Tokens only. The state is a mark and a word, never
+// a colour alone. Its own width decides its layout (@container): under
+// about 320 px the next run and Run now stack, the button full width.
+// With an `href` the WHOLE card opens the job: the chevron is a stretched
+// link over the card, and the switch, the Run button and any link or
+// button in `children` sit above it and keep their own press.
+//
+// Moved from the CRM (makersclaw-store packages/crm 0.7.0) into the
+// template's kit (0.8.1, D15), with the on/off switch.
+
+import { Button, Icon, IconButton, Switch, cx } from "../../ui";
+
+const STATE = {
+  ok: { icon: "circle-check", text: "text-success" },
+  failed: { icon: "circle-x", text: "text-destructive" },
+  running: { icon: "loader", text: "text-info" },
+  off: { icon: "pause", text: "text-warning" },
+  none: { icon: "circle-dashed", text: "text-muted-foreground" },
+};
+
+/**
+ *   title      "Morning read"
+ *   icon       a kit Icon name (default "clock")
+ *   state      { tone: ok|failed|running|off|none, words: "Ran 07:02" }
+ *   summary    what the last run did, one or two lines
+ *   cost       "640 credits" (this run)
+ *   allowance  { used: 4180, of: 10000, words: "4,180 of 10,000 this week" }
+ *   next       "Next: Wed 30 Sep, 07:00"
+ *   run        { label: "Read now", price: "about 700 cr", onRun, loading, disabled, why }
+ *   enabled    the job is on (the switch's state)
+ *   onToggle(next)  the switch: drawn only when given
+ *   toggleLabel     the switch's words (default "On" / "Off")
+ *   toggleBusy      the switch's press is out: it waits
+ *   href       the job's page: a chevron at the card's head opens it
+ *   children   anything more, under the summary (a reason, a desk link)
+ */
+export function ScheduleCard({
+  title,
+  icon = "clock",
+  state,
+  summary,
+  cost,
+  allowance,
+  next,
+  run,
+  enabled,
+  onToggle,
+  toggleLabel,
+  toggleBusy = false,
+  href,
+  className,
+  children,
+}) {
+  const s = STATE[state?.tone] ?? STATE.none;
+  const pct = allowance && allowance.of > 0 ? Math.max(0, Math.min(1, allowance.used / allowance.of)) : null;
+  const full = pct != null && pct >= 1;
+  const on = Boolean(enabled);
+  return (
+    <section
+      aria-label={title}
+      className={cx(
+        "@container grid min-w-0 gap-2 rounded-[var(--radius)] border border-border bg-card p-3 text-[13px] text-card-foreground",
+        href && "relative transition-colors hover:bg-accent/30 [&_:is(a,button):not([data-card-link])]:relative [&_:is(a,button):not([data-card-link])]:z-10",
+        className,
+      )}
+    >
+      <div className="flex min-w-0 items-start gap-2">
+        <Icon name={icon} size={16} className="mt-0.5 shrink-0 text-muted-foreground" />
+        <div className="grid min-w-0 flex-1 gap-0.5">
+          <b className="min-w-0 truncate font-semibold">{title}</b>
+          {state?.words ? (
+            <span className={cx("inline-flex min-w-0 items-center gap-1.5 text-xs", s.text)}>
+              <Icon name={s.icon} size={12} className={cx("shrink-0", state?.tone === "running" && "animate-spin motion-reduce:animate-none")} />
+              <span className="min-w-0 truncate">{state.words}</span>
+            </span>
+          ) : null}
+        </div>
+        {onToggle ? (
+          <Switch
+            checked={on}
+            disabled={toggleBusy}
+            onChange={(e) => onToggle(Boolean(e?.target?.checked))}
+            label={toggleLabel ?? (on ? "On" : "Off")}
+            className="relative z-10 -my-2 shrink-0 text-xs"
+          />
+        ) : null}
+        {href ? (
+          <IconButton
+            icon="chevron-right"
+            size="sm"
+            href={href}
+            label={`Open ${title}`}
+            data-card-link=""
+            className="-my-1.5 -mr-1.5 after:absolute after:inset-0 after:rounded-[var(--radius)] after:content-['']"
+          />
+        ) : null}
+      </div>
+      {summary ? <p className="text-xs leading-snug">{summary}</p> : null}
+      {children}
+      {cost || allowance ? (
+        <div className="grid gap-1">
+          <span className={cx("text-xs", full ? "text-destructive" : "text-muted-foreground")}>{[cost, allowance?.words].filter(Boolean).join(" · ")}</span>
+          {pct != null ? (
+            <span aria-hidden="true" className="block h-1 overflow-hidden rounded-sm bg-border">
+              <span className={cx("block h-full", full ? "bg-destructive" : "bg-muted-foreground")} style={{ width: `${pct * 100}%` }} />
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+      {next || run ? (
+        <div className="flex flex-col items-stretch gap-1.5 text-xs @xs:flex-row @xs:flex-wrap @xs:items-center">
+          {next ? <span className="min-w-0 text-muted-foreground">{next}</span> : null}
+          <span className="hidden flex-1 @xs:block" />
+          {run ? (
+            <Button
+              size="sm"
+              icon="play"
+              loading={run.loading}
+              disabled={run.disabled}
+              onClick={run.onRun}
+              title={run.why}
+              className="max-w-full"
+            >
+              <span className="truncate">{run.label ?? "Run now"}</span>
+              {run.price ? <span className="font-normal text-muted-foreground">{run.price}</span> : null}
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/registry/blocks/schedule-engine/README.md

@@ -0,0 +1,137 @@
+# Schedule engine
+
+The rules a dated plan follows, as plain functions over plain rows. No
+React, no I/O: the browser runs them on every pointer move of a drag, a
+script runs them for an agent, and the tests run them under node. The same
+dates everywhere.
+
+Born in a Gantt planner's app, which carried 770 lines of it (and an SQL
+copy that the tests pin to it). It is the engine under the `schedule-gantt`
+block, and it works alone.
+
+```js
+import { schedule, shiftDependents, replanFromToday } from "../components/blocks/schedule-engine"; // a Makersclaw app ("./blocks/schedule-engine" from components/)
+// shadcn project: import { schedule } from "@/components/makersclaw/blocks/schedule-engine"
+```
+
+## The model
+
+- A task runs `d` working days (Monday to Friday; `calendar: "everyday"`
+  counts all seven). A milestone takes none and sits at the end of its day.
+- A task's planned start is a floor: the forward pass only ever moves work
+  later. **Finished work** (status `done`, or progress 100) stays where it
+  happened.
+- A task with sub-tasks is a **summary**: its dates are its leaves' span. A
+  link **to** a summary binds every leaf under it; a link **from** one reads
+  its span (last finish, or first start for start links).
+- Cancelled tasks and tasks with no dates are off the plan, and so are
+  their links.
+- **Slack** is the latest finish minus the earliest finish, in working days.
+  Slack 0 is critical. The **long pole** is the unfinished critical task
+  with the most work left; the later wins a tie.
+
+## Rows in
+
+- task: `{ id, parent_id, title, start_date, due_date, is_milestone,
+  progress, status, position }` (dates `'YYYY-MM-DD'`).
+- link: `{ id, task_id, depends_on_id, kind, lag_days }`: `task_id` waits on
+  `depends_on_id`. `kind`: `finish_to_start` (default), `start_to_start`,
+  `finish_to_finish`, `start_to_finish`, or `FS` / `SS` / `FF` / `SF`.
+
+## The plan
+
+- `schedule(tasks, links, { calendar })` → `{ rows, links, start, finish,
+  critical, stuck, violations }`.
+  - `rows`: `Map(id → { id, parentId, summary, milestone, pinned, dated,
+    stuck, start, due, planStart, planDue, lateStart, lateDue, duration,
+    slack, critical, progress, shifted, drivers, leafIds })`. `start` / `due`
+    are the stored dates (a summary: its leaves' span); `plan*` where the
+    forward pass puts it; `shifted` is true when the stored dates break a
+    link.
+  - `links`: `Map(id → { id, taskId, dependsOnId, kind, lag, valid, reason,
+    slack, critical, violated, violation })`.
+  - `critical`: critical leaf ids in plan order. `stuck`: ids in or behind
+    a loop. `violations`: link ids whose stored dates break them.
+- `shiftDependents(tasks, links, moves, { nextLinks, nextTasks })` → `{
+  changes: [{ id, start_date, due_date, from, summary? }], clamped, before,
+  after, finishBefore, finishAfter }`. `moves`: `[{ id, start, due }]`; a
+  summary's `start` moves its unfinished leaves as a block. Only tasks the
+  move affects are in `changes`.
+- `replanFromToday(tasks, links, today)`: not started and its start has
+  passed → today; started and overdue → its remaining share from today;
+  a passed milestone → today. Then the dependents shift. Adds `moves`.
+- `alignConflicts(tasks, links)`: every task that starts before its links
+  allow moves to its earliest date. Adds `moves`.
+- `linkProblem(tasks, links, taskId, dependsOnId)` → why the link can't be
+  made, in words, or `null`.
+- `longPole(plan)` → the id.
+- Lower level: `buildNetwork`, `forwardPass`, `backwardPass`,
+  `criticalPath`, `makeCalendar`, `spanOf`, `datesOf`, `dayOf`, `isoOf`,
+  `addWorkdays`, `workdaysBetween`, `durationOf`, `linkKind`, `LINK_KINDS`.
+- The tree: `taskTree(tasks)` → `{ order: [{ id, parentId, depth, outline,
+  childCount, index }], byId }`, `descendantsOf`, `positionBetween`,
+  `siblingOrder`.
+
+## Planning a write
+
+None of these writes. Each returns the values a save needs.
+
+- `placeNew(tasks, { add: { parent_id, after_id, start, due, days,
+  milestone }, today, project })` → `{ parent_id, sort_order, start_date,
+  due_date, is_milestone, resum }`.
+- `outlineChange(tasks, links, { id, kind: "in" | "out" | "up" | "down" |
+  "under", parent_id })` → `{ ok, parent_id, old_parent_id, sort_order,
+  order_only, changes, summaries, finishBefore, finishAfter, words }` or
+  `{ ok: false, error }`.
+- `lengthChange(tasks, links, { id, days, project })`.
+- `summaryChanges(tasks, links, ids)` → the summaries to re-span.
+- `overlapsOf(tasks, plan, { ownerOf })` → who is on two things at once,
+  `[{ owner, from, to, count, ids }]`.
+- `snapshotOf(tasks, links)` → `{ finish_date, data }`, the rows a baseline
+  keeps.
+
+## The short form of a link
+
+`2.5FS`, `6.3SS+5d`, `3.4SF-2d`, several joined with a semicolon: an outline
+number, the kind (finish to start when left out), a signed lag in working
+days. `shortForm(outline, kind, lag)`, `waitsWords(links, taskId,
+outlineOf)`, `parseWaits(text, idOf)` → `{ links, problems }`, `lagWords`,
+`KIND_WORDS` (the four kinds named in full, each with a clause).
+
+## One entry for an agent
+
+`operate({ operation, tasks, links, ... })` answers `schedule`, `move`,
+`replan`, `mend`, `place`, `outline`, `length`, `link`, `snapshot` and
+`load` as plain JSON (a Map is an object keyed by id, a Set a list). A
+package's `references/plan.mjs` is ten lines around it:
+
+```js
+import { operate } from "../app/components/blocks/schedule-engine/ops.js";
+let input = "";
+for await (const chunk of process.stdin) input += chunk;
+process.stdout.write(JSON.stringify(operate(JSON.parse(input))) + "\n");
+```
+
+## Example
+
+```js
+const plan = schedule(tasks, links);
+plan.finish;                    // "2026-11-03"
+plan.rows.get("t7").slack;      // 0 = on the critical path
+const moved = shiftDependents(tasks, links, [{ id: "t7", start: "2026-10-12", due: "2026-10-16" }]);
+moved.finishAfter;              // what the move cost the finish
+moved.changes;                  // every date to save, in one write
+```
+
+## States and edges
+
+An empty plan has no finish (`null`) and no critical path. A loop leaves the
+tasks in it where they were (`stuck`) and everything else is planned. A
+weekend date counts from the Monday after (a start) or back to the Friday
+(a finish). A link to a task with no dates is `valid: false, reason:
+"undated"`. A parent that is not in the list makes a root.
+
+## Tests
+
+`test/schedule-engine.test.mjs` (the rules, every expected date worked out
+by hand on a real calendar) and `test/schedule-engine-writes.test.mjs`.

package/registry/blocks/schedule-engine/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "schedule-engine",
+  "title": "Schedule engine",
+  "description": "The rules a dated plan follows, as pure functions over plain rows: working days (Monday to Friday), the four link kinds (finish to start, start to start, finish to finish, start to finish) with lag and lead, the forward and backward pass, slack, the critical path and the long pole, shifting every dependent when a task moves, re-planning unfinished work from today, mending links the dates ignore, summaries that span their sub-tasks, finished work pinned in place, and the outline tree with its 1, 1.1, 1.2 numbers. Also the plans for a write: where a new task goes and with what dates, what an indent, outdent, move or reorder changes, a task's length, who is on two things at once, the rows a baseline keeps, and the short form of a link (2.4FS+2d) both ways. One entry, operate(), answers all of it as JSON so an agent's script and a screen get the same dates.",
+  "useWhen": "A plan with tasks that wait on each other and dates that must follow: a project schedule, a launch plan, a roadmap whose slips ripple, an agent that re-plans or answers 'when do we finish and what decides it'. The engine under the schedule-gantt block, usable alone with no chart. Not for undated to-dos (task-list) or stages (board).",
+  "tags": ["schedule", "gantt", "critical path", "slack", "dependencies", "working days", "lag", "baseline", "re-plan", "outline", "project plan", "milestones", "ms project", "pure", "agent"],
+  "exports": ["dayOf", "isoOf", "weekdayOf", "makeCalendar", "LINK_KINDS", "linkKind", "spanOf", "datesOf", "workdaysBetween", "addWorkdays", "durationOf", "buildNetwork", "forwardPass", "backwardPass", "criticalPath", "schedule", "shiftDependents", "replanFromToday", "alignConflicts", "linkProblem", "longPole", "taskTree", "descendantsOf", "positionBetween", "siblingOrder", "KIND_WORDS", "lagWords", "shortForm", "waitsWords", "parseWaits", "nextWorkday", "summaryChanges", "placeNew", "familyLinkProblem", "outlineChange", "lengthChange", "overlapsOf", "snapshotOf", "operate", "plain", "OPERATIONS"],
+  "files": ["index.js", "engine.js", "tree.js", "waits.js", "place.js", "ops.js"],
+  "requires": []
+}

package/registry/blocks/schedule-engine/demo.jsx

@@ -0,0 +1,82 @@
+"use client";
+
+// schedule-engine in the gallery — the gallery's and the smoke test's
+// surface. Not installed into apps. The block is pure functions, so the
+// demo is a small plan, a "slip" control and what the rules say it costs:
+//   Plan     five tasks with their dates, slack and the critical path
+//   Slip     push the design back and read the new finish, the tasks that
+//            move with it and the ones with slack that do not
+//   Links    the short form, written and read back
+import { useMemo, useState } from "react";
+import { Button, Card, Notice } from "../components/ui";
+import { addWorkdays, lagWords, parseWaits, schedule, shiftDependents, waitsWords, taskTree } from "../components/blocks/schedule-engine";
+
+const TASKS = [
+  { id: "d", parent_id: null, title: "Design", start_date: "2026-10-05", due_date: "2026-10-09", is_milestone: false, progress: 100, status: "done", position: 1 },
+  { id: "b", parent_id: null, title: "Build", start_date: "2026-10-12", due_date: "2026-10-23", is_milestone: false, progress: 20, status: "in_progress", position: 2 },
+  { id: "w", parent_id: null, title: "Write the docs", start_date: "2026-10-12", due_date: "2026-10-14", is_milestone: false, progress: 0, status: "todo", position: 3 },
+  { id: "t", parent_id: null, title: "Test", start_date: "2026-10-26", due_date: "2026-10-30", is_milestone: false, progress: 0, status: "todo", position: 4 },
+  { id: "l", parent_id: null, title: "Launch", start_date: "2026-11-02", due_date: "2026-11-02", is_milestone: true, progress: 0, status: "todo", position: 5 },
+];
+const LINKS = [
+  { id: "1", task_id: "b", depends_on_id: "d", kind: "finish_to_start", lag_days: 0 },
+  { id: "2", task_id: "w", depends_on_id: "d", kind: "finish_to_start", lag_days: 0 },
+  { id: "3", task_id: "t", depends_on_id: "b", kind: "finish_to_start", lag_days: 0 },
+  { id: "4", task_id: "t", depends_on_id: "w", kind: "finish_to_finish", lag_days: 5 },
+  { id: "5", task_id: "l", depends_on_id: "t", kind: "finish_to_start", lag_days: 0 },
+];
+
+export default function ScheduleEngineDemo() {
+  const [slip, setSlip] = useState(0);
+  const tree = useMemo(() => taskTree(TASKS), []);
+  const outlineOf = (id) => tree.byId.get(id)?.outline;
+  const moves = slip ? [{ id: "b", start: "2026-10-12", due: addWorkdays("2026-10-23", slip) }] : [];
+  const result = useMemo(() => shiftDependents(TASKS, LINKS, moves), [slip]); // eslint-disable-line react-hooks/exhaustive-deps
+  const plan = result.before;
+  const text = waitsWords(LINKS, "t", outlineOf);
+  const back = parseWaits(text, (o) => tree.order.find((e) => e.outline === o)?.id ?? null);
+  return (
+    <div className="grid gap-4 p-4">
+      <Card>
+        <div className="grid gap-3 p-4">
+          <p className="text-sm">
+            Finish <b>{plan.finish}</b>. Critical: {plan.critical.map((id) => TASKS.find((t) => t.id === id).title).join(", ")}.
+          </p>
+          <div className="flex flex-wrap items-center gap-2">
+            <Button size="sm" onClick={() => setSlip((n) => n + 1)}>Slip Build a day</Button>
+            <Button size="sm" variant="ghost" onClick={() => setSlip(0)}>Put it back</Button>
+            <span className="text-xs text-muted-foreground">{slip ? `Build slipped ${slip} working ${slip === 1 ? "day" : "days"}` : "Nothing has slipped"}</span>
+          </div>
+          {slip ? (
+            <Notice>
+              The finish goes from {result.finishBefore} to {result.finishAfter}. Moves: {result.changes.map((c) => `${TASKS.find((t) => t.id === c.id).title} to ${c.start_date}`).join("; ") || "none"}.
+            </Notice>
+          ) : null}
+        </div>
+      </Card>
+      <Card>
+        <div className="grid gap-1 p-4 text-sm">
+          {tree.order.map((e) => {
+            const t = TASKS.find((x) => x.id === e.id);
+            const r = plan.rows.get(e.id);
+            return (
+              <div key={e.id} className="flex flex-wrap items-baseline gap-3 tabular-nums">
+                <span className="w-8 text-muted-foreground">{e.outline}</span>
+                <span className="w-40">{t.title}</span>
+                <span className="w-44 text-muted-foreground">{r.planStart} to {r.planDue}</span>
+                <span className={r.critical ? "font-semibold text-destructive" : "text-muted-foreground"}>{r.critical ? "0 wd slack" : `${r.slack} wd slack`}</span>
+              </div>
+            );
+          })}
+        </div>
+      </Card>
+      <Card>
+        <div className="grid gap-1 p-4 text-sm">
+          <p>
+            Test waits on: <code>{text}</code> (lag {lagWords(5) || "none"} on the second). Read back: {back.links.map((l) => `${l.outline} ${l.kind} ${l.lag_days}`).join("; ")}.
+          </p>
+        </div>
+      </Card>
+    </div>
+  );
+}