makersclaw 0.2.0 → 0.3.1

package/registry/blocks/gantt/README.md

@@ -0,0 +1,220 @@
+# Gantt
+
+The Gantt view of work, like Linear's timeline or TeamGantt. The task list
+sits on the left — groups that fold, subtasks indented under their parent
+— and the timeline on the right, under a two-tier date header (months over
+days, or years over months). Each task is a bar in its project's colour,
+filled as far as it is done; a parent is a summary bracket over its
+subtasks; a milestone is a diamond on its day; arrows run from each task to
+the ones waiting on it, red and dashed when the dates disagree. A line marks
+today; weekends are shaded.
+
+Drag a bar to move it, an edge to change its start or end, and the dot past
+its end onto another bar to make that one wait on it. Every task waiting on
+a moved one slides along *while you drag*, and "Finishes Fri, Oct 16 +3
+days" at the top says what the move cost. Zoom by day, week, month or
+quarter; switch on the critical path and the chain that sets the finish
+lights up while the rest fades. A task with no dates shows a ghost bar under
+the pointer: click to schedule it there. Search, filters, group and sort
+live in the shared toolbar above.
+
+Every change saves through one async `onChange` and shows at once; when the
+save fails the timeline puts it back and says why.
+
+```jsx
+import { Gantt } from "../components/blocks/gantt";   // a Makersclaw app ("./blocks/gantt" from components/)
+import { Gantt } from "@/components/makersclaw/blocks/gantt";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the tasks in the server surface (README §4). It is built on
+`task-model` (added with it): the task shape, the change shapes and the
+helpers are documented there.
+
+## The data
+
+Tasks in task-model's shape — `{ id, title, status, assignees, start?,
+due?, progress?, parentId?, dependsOn?, project?, … }` — with the statuses,
+people and projects they refer to. What the gantt reads:
+
+- `start` · `due` — the bar runs from start to due, both days included. One
+  of them alone is a one-day bar; neither is an undated task (a row with no
+  bar, scheduled by a click).
+- `milestone: true` (or `type: "milestone"`) — a diamond on its `due` day
+  (else its `start`).
+- `dependsOn: ["t7"]` — this task waits on t7: an arrow from t7's end to
+  its start (finish to start).
+- `progress` (0–100) — the bar's fill; without it, 100 when done, else
+  from its subtasks (task-model's `progressOf`).
+- `parentId` — a subtask, drawn under its parent; the parent's bar is a
+  summary bracket over all of them and moves them together.
+- `project` — the bar's colour (the project's `hue`, chart-1…5) when
+  `colorBy` is `"project"`.
+
+A drag saves only `start` and `due` (and, for a link, `dependsOn`).
+
+## Props
+
+- `tasks` — the tasks. Pass `useFixture(rows, SAMPLE).rows` and the
+  examples change on screen and save nothing (they are not rows).
+- `statuses` — `[{ id, label, tone?, hue?, done? }]` in order. Default: To
+  do, In progress, In review, Done.
+- `people` — `[{ id, name, src? }]`.
+- `projects` — `[{ id, name, hue? }]`: `hue` 1–5 colours the bars.
+- `fields` — custom fields (`{ key, label, kind, options? }`), for the
+  toolbar's filters and grouping.
+- `onChange(change)` — save a change; return `{ ok: true }` or
+  `{ ok: false, error }` (a throw counts as failed). A move that pushes
+  waiting tasks is one `batch` change; a link is an `update` of
+  `dependsOn`. In a Makersclaw app, loop over `changeWrites(change)` into
+  insertRow / updateRow / deleteRow (task-model README, "A change").
+  Without `onChange` the timeline only shows: no drag, links, quick-add or
+  menus beyond Open.
+- `onOpen(task)` — a click on a bar or a title (Enter on a focused bar),
+  and "Open" in the row's menu: open your `Sheet` with the task.
+- `view` · `defaultView` · `onViewChange(view)` — search, filters, group
+  and sort (task-model's view). The gantt's default: grouped by project,
+  sorted by start date. Group by project, status, assignee, priority or
+  none.
+- `zoom` · `defaultZoom` (`"week"`) · `onZoomChange(zoom)` — `"day"` ·
+  `"week"` · `"month"` · `"quarter"`.
+- `colorBy` — `"project"` (default; the project's hue, else the primary
+  colour) · `"status"` (the status's tone) · `"none"`.
+- `pushDependents` — default true: moving or stretching a task later slides
+  every task waiting on it (and theirs) just far enough to start the day
+  after it ends, keeping their lengths. Nothing is pulled earlier. False:
+  only the dragged task moves, and conflicts show as red arrows.
+- `defaultCritical` — default false: start with the critical path on.
+- `newTaskLength` — default 3: the days a quick-added or click-scheduled
+  task spans (a quick-added task starts today).
+- `today` — `"YYYY-MM-DD"`: the today line and where the timeline opens.
+  Default the browser's today; fix it in a demo.
+- `weekStartsOn` (default 1, Monday) · `weekend` (default `[0, 6]`) ·
+  `holidays` — the header's weeks and the shaded days.
+- `toolbar` — default true; false hides search, filter, group, sort and
+  "Add task". `toolbarExtra` — your controls before "Add task".
+- `addLabel` — default `"Add task"`.
+- `starters` — plans the empty state offers:
+  `[{ label, icon?, tasks: [{ title, days?, milestone?, parallel? }] }]`.
+  Tasks run one after another from today, each waiting on the one before;
+  `parallel: true` starts with the previous one instead. One press
+  creates them all in one change.
+- `emptyTitle` · `emptyBody` — the empty state's words.
+- `height` — default 560: the timeline's most height in pixels (never
+  more than 75% of the window); it scrolls inside.
+- `loading` — skeleton bars in place of the timeline.
+- `error` — a danger Notice above it (a failed read).
+- `label` — what it is called to a screen reader, default `"Timeline"`.
+- `locale` — dates in the header and labels; default the browser's.
+- `className` — layout around it (width, margin). Never colour.
+
+The helpers it draws with are exported for a view of your own:
+`ZOOMS`, `ganttRange(tasks, zoom, today)`, `headerTiers(from, to, zoom)`,
+`planMove(tasks, id, "move" | "start" | "end", days, { push })` (what a
+drag saves, as `[{ id, patch }]`), `afterBlockersPatch(task, tasks)`,
+`isMilestone`, `summarySpan`, `arrowPath(boxA, boxB)`.
+
+## What it does, precisely
+
+- Moving snaps to whole days at every zoom; the dates show beside the bar
+  while it moves. Resizing never crosses the other edge (a bar is at least
+  one day). A milestone and a summary bracket move but do not resize; a
+  summary moves its whole family.
+- Linking: drag the dot past a bar's end onto another row. A link that
+  would loop is refused with a notice. The row menu's "Waits on" ticks and
+  unticks links from the keyboard.
+- A red, dashed arrow means the waiting task starts before the other ends;
+  its row shows a warning and its menu offers "Start after what it waits
+  on".
+- The critical path is the longest chain of linked, dated work
+  (task-model's `criticalPath`): its bars ring in the primary colour, its
+  arrows thicken, everything else fades, and a line under the chart says
+  how long it is.
+- A task in two groups (two assignees, grouped by person) shows in both;
+  the first row drags, the second only opens.
+- Keyboard: Tab reaches the titles, menus and bars. On a bar, ← → move it a
+  day, Shift + ← → change its end, Alt + ← → its start; the move saves when
+  the keys rest (or on Enter); Escape drops it. Enter opens a bar at rest.
+- On a phone the list pane starts hidden (the bars carry their titles);
+  the list button in the chart's bar shows it at 176px. Zoom takes its own
+  line. Bars scroll under a finger and drag after a short press; edge grips
+  and the link dot are pointer-only (the keyboard and the menu cover them).
+- Delete (row menu) takes the subtasks too; Undo in the toast brings them
+  back. A move that pushed other tasks also offers Undo.
+
+## Example
+
+```jsx
+// surfaces/plan.jsx — server: load, hand over
+import { loadRows } from "../lib/data";
+import Plan from "../components/Plan";
+
+export default async function PlanSurface() {
+  const { rows, error } = await loadRows({ source: "public.tasks", orderBy: "start asc" });
+  const people = await loadRows({ source: "public.people" });
+  const projects = await loadRows({ source: "public.projects" });
+  return <Plan tasks={rows} people={people.rows} projects={projects.rows} error={error} />;
+}
+```
+
+```jsx
+// components/Plan.jsx — client: the timeline, the task sheet
+"use client";
+import { useState } from "react";
+import { deleteRow, insertRow, updateRow } from "../lib/actions";
+import { Sheet } from "./ui";
+import { Gantt } from "./blocks/gantt";
+import { changeWrites } from "./blocks/task-model";
+
+const COLUMNS = ["id", "title", "status", "assignees", "start", "due", "progress", "parentId", "dependsOn", "project", "milestone"];
+
+async function save(change) {
+  for (const w of changeWrites(change, { columns: COLUMNS, keepNewIds: false })) {
+    const r =
+      w.op === "insert" ? await insertRow({ source: "public.tasks", values: w.values, detail: w.values.title })
+      : w.op === "update" ? await updateRow({ source: "public.tasks", id: w.id, patch: w.patch })
+      : await deleteRow({ source: "public.tasks", id: w.id });
+    if (r?.ok === false) return r;
+  }
+  return { ok: true };
+}
+
+export default function Plan({ tasks, people, projects, error }) {
+  const [open, setOpen] = useState(null);
+  return (
+    <>
+      <Gantt tasks={tasks} people={people} projects={projects} onChange={save} onOpen={setOpen} error={error}
+        starters={[{ label: "Product launch", tasks: [{ title: "Scope", days: 2 }, { title: "Build", days: 10 }, { title: "Launch", milestone: true }] }]} />
+      <Sheet open={Boolean(open)} onClose={() => setOpen(null)} title={open?.title}>{/* the task's fields */}</Sheet>
+    </>
+  );
+}
+```
+
+`keepNewIds: false` lets the table make a new task's id. A link made
+between two tasks created in the same change (a starter) refers to their
+client ids: keep them (`keepNewIds: true`, a text id column) when you
+offer starters.
+
+By person, zoomed to days, coloured by status:
+
+```jsx
+<Gantt tasks={tasks} people={people} onChange={save} defaultZoom="day" colorBy="status" defaultView={{ groupBy: "assignees" }} />
+```
+
+## What it will not do
+
+- Start-to-start, finish-to-finish or lag on links: every link is finish to
+  start, the next day.
+- Count working days: a bar spans calendar days; weekends are shaded, not
+  skipped.
+- Baselines, resource levelling or costs.
+- Reorder rows by drag: the order is the view's sort (start date by
+  default); change it in the toolbar.
+- Virtualise thousands of rows: filter, or page them in the surface.
+- Fetch: tasks come in as props; the page re-reads after a save.
+
+A timeline it cannot be is your own component in `components/`, built
+from task-model's parts and helpers and the ones above — not an edit to
+this block. Its files are fixed: `npm run check` refuses a change, and
+`makersclaw add gantt` restores them.

package/registry/blocks/gantt/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "gantt",
+  "title": "Gantt",
+  "description": "The Gantt view of work, like Linear's timeline or TeamGantt: a task list on the left (groups that fold, subtasks indented under a summary bar) beside a timeline with a two-tier date header, bars coloured by project or status with their progress, milestones as diamonds, dependency arrows (red when the dates disagree), a today line and weekend shading. Drag a bar to move it, an edge to change its start or end, the dot past its end onto another bar to link them; tasks waiting on a moved one slide along while you drag and the finish date shows what the move cost. Zoom day, week, month or quarter; highlight the critical path; click an empty row to schedule an undated task; quick-add per group; arrow keys move a focused bar; search, filters, group and sort from the shared toolbar. One async onChange saves every change; failures roll back with a notice.",
+  "useWhen": "A screen that plans dated work and shows what waits on what: a launch plan, a project schedule, a content calendar with lead times, an office move, a release. Not for an undated to-do list (task-list), stage columns (board), or days on a month grid (calendar).",
+  "tags": ["gantt", "timeline", "schedule", "project plan", "roadmap", "dependencies", "critical path", "milestones", "teamgantt", "linear", "clickup", "ms project", "drag", "resize", "zoom", "tasks", "project management"],
+  "exports": ["Gantt", "ZOOMS", "ganttRange", "headerTiers", "planMove", "afterBlockersPatch", "isMilestone", "summarySpan", "arrowPath"],
+  "files": ["index.js", "gantt.jsx", "rows.jsx", "schedule.js"],
+  "requires": ["task-model"]
+}

package/registry/blocks/gantt/demo.jsx

@@ -0,0 +1,148 @@
+"use client";
+
+// Gantt three ways — the gallery's and the smoke test's surface. Not
+// installed into apps: `makersclaw add gantt` lays index.js, gantt.jsx,
+// rows.jsx and schedule.js only.
+//   Plan       a website relaunch and a campaign: bars, subtasks under a
+//              summary, links (one in conflict), a milestone, an undated
+//              task; saves in memory (a switch makes them fail, to show the
+//              rollback); a bar or a title opens a sheet.
+//   Empty      no tasks yet: name the first one, or start from a plan.
+//   Read-only  the same plan by person, zoomed to days, no onChange.
+import { useState } from "react";
+import { Sheet, Switch, TabPanel, Tabs } from "../components/ui";
+import { Gantt } from "../components/blocks/gantt";
+import { applyChange, formatDay } from "../components/blocks/task-model";
+
+const TODAY = "2026-09-23";
+
+const STATUSES = [
+  { id: "todo", label: "To do", tone: "neutral" },
+  { id: "doing", label: "In progress", tone: "info" },
+  { id: "review", label: "In review", tone: "warning" },
+  { id: "done", label: "Done", tone: "success", done: true },
+];
+
+const PEOPLE = [
+  { id: "maya", name: "Maya Chen" },
+  { id: "leo", name: "Leo Park" },
+  { id: "priya", name: "Priya Nair" },
+  { id: "sam", name: "Sam Okafor" },
+];
+
+const PROJECTS = [
+  { id: "site", name: "Website relaunch", hue: 1 },
+  { id: "q4", name: "Q4 campaign", hue: 3 },
+];
+
+const PLAN = [
+  { id: "s1", title: "Content audit", status: "done", assignees: ["maya"], project: "site", start: "2026-09-07", due: "2026-09-11" },
+  { id: "s2", title: "Design the new pages", status: "doing", assignees: ["priya"], project: "site", start: "2026-09-14", due: "2026-09-25", dependsOn: ["s1"] },
+  { id: "s2a", title: "Home and pricing", status: "done", parentId: "s2", assignees: ["priya"], project: "site", start: "2026-09-14", due: "2026-09-18" },
+  { id: "s2b", title: "Product pages", status: "doing", parentId: "s2", assignees: ["priya"], project: "site", start: "2026-09-21", due: "2026-09-25", progress: 40 },
+  { id: "s3", title: "Build the templates", status: "todo", assignees: ["leo"], project: "site", start: "2026-09-28", due: "2026-10-09", dependsOn: ["s2"] },
+  { id: "s4", title: "Write the page copy", status: "doing", assignees: ["maya"], project: "site", start: "2026-09-21", due: "2026-10-02", progress: 60 },
+  { id: "s5", title: "Redirects and SEO checks", status: "todo", assignees: ["leo"], project: "site", start: "2026-10-12", due: "2026-10-14", dependsOn: ["s3"] },
+  { id: "s6", title: "Site goes live", status: "todo", assignees: ["sam"], project: "site", due: "2026-10-16", milestone: true, dependsOn: ["s5", "s4"] },
+  { id: "c1", title: "Brief the agency", status: "done", assignees: ["sam"], project: "q4", start: "2026-09-15", due: "2026-09-17" },
+  { id: "c2", title: "Shoot the product photos", status: "todo", assignees: ["leo", "priya"], project: "q4", start: "2026-09-29", due: "2026-10-01", dependsOn: ["c1"] },
+  { id: "c3", title: "Launch email and ads", status: "todo", assignees: ["sam"], project: "q4", start: "2026-09-30", due: "2026-10-07", dependsOn: ["c2"] },
+  { id: "c4", title: "Customer story with Northwind", status: "todo", assignees: [], project: "q4" },
+];
+
+const STARTERS = [
+  {
+    label: "Product launch",
+    icon: "sparkles",
+    tasks: [
+      { title: "Agree the launch date and scope", days: 2 },
+      { title: "Write the announcement", days: 4 },
+      { title: "Record the demo video", days: 3, parallel: true },
+      { title: "Line up three customer quotes", days: 5 },
+      { title: "Launch day", milestone: true },
+    ],
+  },
+  {
+    label: "Hiring round",
+    icon: "users",
+    tasks: [
+      { title: "Write the job description", days: 2 },
+      { title: "Source candidates", days: 10 },
+      { title: "First interviews", days: 7 },
+      { title: "Offer out", milestone: true },
+    ],
+  },
+];
+
+function usePlan(start, failRef) {
+  const [tasks, setTasks] = useState(start);
+  const onChange = async (change) => {
+    await new Promise((r) => setTimeout(r, 350));
+    if (failRef?.current) return { ok: false, error: "the server did not answer" };
+    setTasks((all) => applyChange(all, change));
+    return { ok: true };
+  };
+  return [tasks, onChange];
+}
+
+export default function GanttDemo() {
+  const [fail, setFail] = useState(false);
+  const failRef = { current: fail };
+  const [tasks, onChange] = usePlan(PLAN, failRef);
+  const [none, onChangeNone] = usePlan([]);
+  const [open, setOpen] = useState(null);
+  const [tab, setTab] = useState("plan");
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="Gantt examples"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "plan", label: "Plan" },
+          { key: "empty", label: "Empty" },
+          { key: "read", label: "Read-only" },
+        ]}
+      />
+      <TabPanel tab="plan" value={tab}>
+        <div className="grid gap-4">
+          <Switch id="gantt-fail" label="Make saves fail" checked={fail} onChange={(e) => setFail(e.target.checked)} />
+          <Gantt
+            label="Relaunch plan"
+            tasks={tasks}
+            statuses={STATUSES}
+            people={PEOPLE}
+            projects={PROJECTS}
+            today={TODAY}
+            onChange={onChange}
+            onOpen={setOpen}
+          />
+          <Sheet
+            open={Boolean(open)}
+            onClose={() => setOpen(null)}
+            title={open?.title}
+            description={open?.due ? `Due ${formatDay(open.due, TODAY)}` : "No dates yet"}
+          >
+            <p className="text-sm text-muted-foreground">The task's own page goes here: its description, comments and history.</p>
+          </Sheet>
+        </div>
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        <Gantt label="New plan" tasks={none} statuses={STATUSES} people={PEOPLE} today={TODAY} onChange={onChangeNone} starters={STARTERS} />
+      </TabPanel>
+      <TabPanel tab="read" value={tab}>
+        <Gantt
+          label="Plan by person"
+          tasks={tasks}
+          statuses={STATUSES}
+          people={PEOPLE}
+          projects={PROJECTS}
+          today={TODAY}
+          defaultZoom="day"
+          colorBy="status"
+          defaultView={{ groupBy: "assignees" }}
+        />
+      </TabPanel>
+    </div>
+  );
+}