makersclaw 0.2.0 → 0.3.0

package/registry/blocks/gantt/gantt.jsx

@@ -0,0 +1,923 @@
+"use client";
+
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { Button, Empty, Icon, Input, Notice, Skeleton, Toggle, ToggleGroup, cx } from "../../ui";
+import {
+  DEFAULT_VIEW,
+  NONE,
+  TaskDragProvider,
+  ViewToolbar,
+  addDays,
+  applyView,
+  createTaskContext,
+  criticalPath,
+  dateConflicts,
+  deleteChange,
+  dependencyEdges,
+  descendantIds,
+  diffDays,
+  draftTask,
+  flattenTree,
+  formatDate,
+  isDone,
+  movePatch,
+  progressOf,
+  spanOf,
+  spanPatch,
+  toggleDoneChange,
+  useTaskChanges,
+  wouldCycle,
+} from "../task-model";
+import { ADD_ROW, Bar, GroupRow, ListRow, QuickAdd, ROW, TINTS, TimelineRow, Unscheduled, spanWords } from "./rows";
+import {
+  ZOOMS,
+  afterBlockersPatch,
+  arrowPath,
+  ganttRange,
+  headerTiers,
+  isMilestone,
+  lengthOf,
+  planMove,
+  summarySpan,
+  weekendBands,
+  xOf,
+  zoomOf,
+} from "./schedule";
+
+// Gantt — tasks on a timeline, like Linear's timeline or TeamGantt: the
+// task list on the left (groups that fold, subtasks under their parent),
+// the bars on the right under a two-tier date header. Drag a bar to move
+// it, an edge to change its start or end, the dot past its end onto
+// another bar to make that one wait on it; every task that waits on a
+// moved one slides along while you drag, and the finish date at the top
+// says what the move cost. Milestones are diamonds, parents are summary
+// brackets, dependencies are arrows (red when the dates disagree), and the
+// critical path lights up on demand. Zoom day · week · month · quarter;
+// a today line; the toolbar's search, filters, group and sort.
+//
+// Everything saves through one async `onChange(change)` answering { ok }
+// (task-model's change shapes); the timeline shows each change at once
+// and takes it back, with a notice, when the save fails.
+//
+// README.md beside this file lists every prop.
+
+const HEADER = 52;
+const ZOOM_ITEMS = Object.values(ZOOMS).map((z) => ({ value: z.key, label: z.label }));
+const GROUP_FIELDS = ["project", "status", "assignees", "priority"];
+
+function useControlled(value, fallback, onChange) {
+  const [own, setOwn] = useState(fallback);
+  const controlled = value !== undefined;
+  const set = useCallback(
+    (next) => {
+      if (!controlled) setOwn(next);
+      onChange?.(next);
+    },
+    [controlled, onChange],
+  );
+  return [controlled ? value : own, set];
+}
+
+export function Gantt({
+  tasks,
+  statuses,
+  people,
+  projects,
+  fields,
+  today,
+  weekStartsOn,
+  weekend,
+  holidays,
+  onChange,
+  onOpen,
+  view: viewProp,
+  defaultView,
+  onViewChange,
+  zoom: zoomProp,
+  defaultZoom = "week",
+  onZoomChange,
+  colorBy = "project",
+  pushDependents = true,
+  defaultCritical = false,
+  newTaskLength = 3,
+  toolbar = true,
+  toolbarExtra,
+  addLabel = "Add task",
+  starters,
+  emptyTitle = "Nothing on the timeline yet",
+  emptyBody = "Add the first task and give it dates, then drag it into place. Link tasks to see what waits on what.",
+  height = 560,
+  loading = false,
+  error: readError,
+  label = "Timeline",
+  locale,
+  className,
+}) {
+  const uid = useId();
+  const ctx = useMemo(
+    () => createTaskContext({ statuses, people, projects, fields, today, weekStartsOn, weekend, holidays }),
+    [statuses, people, projects, fields, today, weekStartsOn, weekend, holidays],
+  );
+  const editable = typeof onChange === "function";
+  const { tasks: all, commit, error, clearError } = useTaskChanges(tasks, onChange);
+  const [viewRaw, setViewRaw] = useControlled(viewProp, { ...DEFAULT_VIEW, groupBy: "project", sort: [{ key: "start", dir: "asc" }], ...defaultView }, onViewChange);
+  const view = useMemo(() => ({ ...DEFAULT_VIEW, ...viewRaw }), [viewRaw]);
+  const [zoom, setZoomRaw] = useControlled(zoomProp, ZOOMS[defaultZoom] ? defaultZoom : "week", onZoomChange);
+  const z = zoomOf(zoom);
+  const dw = z.dayWidth;
+
+  const [critical, setCritical] = useState(defaultCritical);
+  const [listOpen, setListOpen] = useState(null); // null: open from 640px, closed on a phone
+  const [narrow, setNarrow] = useState(false);
+  const [folded, setFolded] = useState(() => new Set());
+  const [collapsed, setCollapsed] = useState(() => new Set());
+  const [hot, setHot] = useState(null);
+  const [adding, setAdding] = useState(null);
+  const [drag, setDrag] = useState(null); // { id, kind, days, keys? }
+  const [linking, setLinking] = useState(false);
+  const [notice, setNotice] = useState(null);
+  const [announce, setAnnounce] = useState("");
+  const scrollRef = useRef(null);
+  const listRef = useRef(null);
+  const dragEndedAt = useRef(0);
+  const nudgeTimer = useRef(null);
+  const dragRef = useRef(null);
+  dragRef.current = drag;
+
+  useEffect(() => {
+    const mq = window.matchMedia("(max-width: 639px)");
+    const on = () => setNarrow(mq.matches);
+    on();
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, []);
+  const showList = listOpen ?? !narrow;
+
+  const say = (text) => setAnnounce(text);
+  const name = (t) => `“${t?.title || "Untitled"}”`;
+  const byIdAll = useMemo(() => new Map(all.map((t) => [t.id, t])), [all]);
+
+  // ---- what a drag shows before it saves -------------------------------
+  const plan = useMemo(() => (drag ? planMove(all, drag.id, drag.kind, drag.days, { push: pushDependents }) : []), [all, drag, pushDependents]);
+  const display = useMemo(() => {
+    if (!plan.length) return all;
+    const patches = new Map(plan.map((p) => [p.id, p.patch]));
+    return all.map((t) => (patches.has(t.id) ? { ...t, ...patches.get(t.id) } : t));
+  }, [all, plan]);
+  const byId = useMemo(() => new Map(display.map((t) => [t.id, t])), [display]);
+  const moved = useMemo(() => new Set(plan.map((p) => p.id)), [plan]);
+
+  // ---- the view ----------------------------------------------------------
+  const shown = useMemo(() => applyView(all, view, ctx), [all, view, ctx]);
+  const by = view.groupBy && view.groupBy !== "none" ? view.groupBy : null;
+  const range = useMemo(() => ganttRange(all, zoom, ctx.today, { weekStartsOn: ctx.weekStartsOn }), [all, zoom, ctx]);
+  const from = range.from;
+  const width = range.days * dw;
+  const tiers = useMemo(() => (from ? headerTiers(from, range.to, zoom, { today: ctx.today, weekStartsOn: ctx.weekStartsOn, locale }) : { top: [], bottom: [] }), [from, range.to, zoom, ctx, locale]);
+  const bands = useMemo(() => (from ? weekendBands(from, range.to, zoom, ctx.weekend) : []), [from, range.to, zoom, ctx]);
+
+  // Rows in reading order, each with its height and top: the list pane and
+  // the timeline draw the same list, so they always line up.
+  const rows = useMemo(() => {
+    const out = [];
+    let y = 0;
+    const push = (r, h) => {
+      out.push({ ...r, y, height: h });
+      y += h;
+    };
+    const single = !by;
+    for (const g of shown.groups) {
+      const shut = folded.has(g.key);
+      if (!single) push({ kind: "group", key: `g:${g.key}`, group: g }, ROW);
+      if (!shut || single) {
+        for (const r of flattenTree(g.tasks, { collapsed })) {
+          const task = byId.get(r.task.id) ?? r.task;
+          const milestone = isMilestone(task);
+          const span = r.hasChildren ? summarySpan(task, display) : spanOf(task);
+          push(
+            {
+              kind: "task",
+              key: `${g.key}::${task.id}`,
+              group: g.key,
+              task,
+              depth: r.depth,
+              hasChildren: r.hasChildren,
+              collapsed: r.collapsed,
+              milestone,
+              span,
+              done: isDone(task, ctx),
+              progress: progressOf(task, display, ctx),
+            },
+            ROW,
+          );
+        }
+        if (editable) push({ kind: "add", key: `add:${g.key}`, group: g }, ADD_ROW);
+      }
+    }
+    return { list: out, height: y };
+  }, [shown.groups, by, folded, collapsed, byId, display, ctx, editable]);
+
+  // Where each task's bar is (its first row, when it shows twice).
+  const boxes = useMemo(() => {
+    const m = new Map();
+    if (!from) return m;
+    for (const r of rows.list) {
+      if (r.kind !== "task" || !r.span || m.has(r.task.id)) continue;
+      const cy = r.y + ROW / 2;
+      if (r.milestone && !r.hasChildren) {
+        const cx = xOf(r.span.end, from, dw) + dw / 2;
+        m.set(r.task.id, { x0: cx - 8, x1: cx + 8, y: cy });
+      } else {
+        const x0 = xOf(r.span.start, from, dw);
+        m.set(r.task.id, { x0, x1: x0 + Math.max(lengthOf(r.span) * dw, 6), y: cy });
+      }
+    }
+    return m;
+  }, [rows, from, dw]);
+
+  const path = useMemo(() => (critical ? criticalPath(display) : new Set()), [critical, display]);
+  const conflicts = useMemo(() => new Set(dateConflicts(display).map((e) => `${e.from}>${e.to}`)), [display]);
+  const conflicted = useMemo(() => {
+    const m = new Map();
+    for (const k of conflicts) {
+      const [a, b] = k.split(">");
+      m.set(b, [...(m.get(b) ?? []), a]);
+    }
+    return m;
+  }, [conflicts]);
+  const edges = useMemo(() => dependencyEdges(display).filter((e) => boxes.has(e.from) && boxes.has(e.to)), [display, boxes]);
+
+  // The finish: the last day any shown task ends, and how a drag moves it.
+  const finish = useMemo(() => {
+    let base = null;
+    let now = null;
+    for (const t of shown.tasks) {
+      const a = spanOf(t);
+      const b = spanOf(byId.get(t.id));
+      if (a && (!base || a.end > base)) base = a.end;
+      if (b && (!now || b.end > now)) now = b.end;
+    }
+    return { day: now, delta: base && now ? diffDays(base, now) : 0 };
+  }, [shown.tasks, byId]);
+  const pathDays = useMemo(() => {
+    let lo = null;
+    let hi = null;
+    for (const id of path) {
+      const s = spanOf(byId.get(id));
+      if (!s) continue;
+      if (!lo || s.start < lo) lo = s.start;
+      if (!hi || s.end > hi) hi = s.end;
+    }
+    return lo ? diffDays(lo, hi) + 1 : 0;
+  }, [path, byId]);
+
+  // ---- scrolling ---------------------------------------------------------
+  const listWidth = () => (showList ? listRef.current?.offsetWidth ?? 0 : 0);
+  const scrollToDay = useCallback(
+    (day, { smooth = false, at = 1 / 3 } = {}) => {
+      const el = scrollRef.current;
+      if (!el || !from || !day) return;
+      const lw = showList ? listRef.current?.offsetWidth ?? 0 : 0;
+      const left = xOf(day, from, dw) - (el.clientWidth - lw) * at;
+      const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+      el.scrollTo({ left: Math.max(0, left), behavior: smooth && !reduced ? "smooth" : "auto" });
+    },
+    [from, dw, showList],
+  );
+  // Open on today, once there is a timeline.
+  const opened = useRef(false);
+  useEffect(() => {
+    if (opened.current || !from) return;
+    opened.current = true;
+    scrollToDay(ctx.today);
+  }, [from, ctx.today, scrollToDay]);
+  // A new zoom keeps the day in the middle where it was.
+  const anchor = useRef(null);
+  function setZoom(next) {
+    const el = scrollRef.current;
+    if (el && from) {
+      const lw = listWidth();
+      const mid = el.scrollLeft + (el.clientWidth - lw) / 2;
+      anchor.current = addDays(from, Math.round(mid / dw));
+    }
+    setZoomRaw(next);
+  }
+  useEffect(() => {
+    if (!anchor.current) return;
+    scrollToDay(anchor.current, { at: 1 / 2 });
+    anchor.current = null;
+  }, [zoom, scrollToDay]);
+
+  // ---- changes -----------------------------------------------------------
+  const commitPlan = useCallback(
+    (id, kind, days) => {
+      const steps = planMove(all, id, kind, days, { push: pushDependents });
+      if (!steps.length) return;
+      const task = byIdAll.get(id);
+      const family = new Set([id, ...descendantIds(all, id)]);
+      const pushed = steps.filter((s) => !family.has(s.id)).length;
+      const change = steps.length === 1 ? { type: "update", id: steps[0].id, patch: steps[0].patch } : { type: "batch", changes: steps.map((s) => ({ type: "update", id: s.id, patch: s.patch })) };
+      const after = spanOf({ ...task, ...steps.find((s) => s.id === id)?.patch }) ?? summarySpan({ ...task }, all);
+      commit(change, {
+        label: name(task),
+        undo: pushed ? `Moved ${name(task)} and ${pushed} task${pushed === 1 ? "" : "s"} waiting on it` : undefined,
+      }).then((r) => {
+        if (r?.ok !== false) say(`${name(task)} is now ${spanWords(after, locale)}${pushed ? `; ${pushed} waiting task${pushed === 1 ? "" : "s"} moved too` : ""}.`);
+      });
+    },
+    [all, byIdAll, commit, pushDependents, locale],
+  );
+
+  const onPreview = useCallback((id, kind, days) => {
+    setDrag((d) => (d && d.id === id && d.kind === kind && d.days === days ? d : { id, kind, days }));
+  }, []);
+
+  // Keyboard: each arrow adds a day to a pending move; it saves when the
+  // keys rest (or on Enter), Escape drops it.
+  const onNudge = useCallback(
+    (id, kind, step, action) => {
+      const d = dragRef.current;
+      clearTimeout(nudgeTimer.current);
+      const flush = (x) => {
+        setDrag(null);
+        if (x?.days) commitPlan(x.id, x.kind, x.days);
+      };
+      if (action === "flush") return flush(d);
+      if (action === "cancel") {
+        setDrag(null);
+        say("Move cancelled.");
+        return;
+      }
+      let next;
+      if (d && d.keys && d.id === id && d.kind === kind) next = { ...d, days: d.days + step };
+      else {
+        if (d?.keys) flush(d);
+        next = { id, kind, days: step, keys: true };
+      }
+      setDrag(next);
+      nudgeTimer.current = setTimeout(() => flush(dragRef.current), 800);
+    },
+    [commitPlan],
+  );
+  useEffect(() => () => clearTimeout(nudgeTimer.current), []);
+
+  function onDragStart({ active }) {
+    if (active?.data?.kind === "link") setLinking(true);
+  }
+
+  function onDragEnd({ active, over, delta }) {
+    dragEndedAt.current = Date.now();
+    setLinking(false);
+    const a = active?.data ?? {};
+    if (a.kind === "link") {
+      setDrag(null);
+      const to = over?.data?.task;
+      if (to && to.id !== a.task.id) link(a.task.id, to.id);
+      return;
+    }
+    const days = Math.round((delta?.x ?? 0) / dw);
+    setDrag(null);
+    if (a.task && days) commitPlan(a.task.id, a.kind, days);
+  }
+
+  function link(fromId, toId) {
+    const target = byIdAll.get(toId);
+    const source = byIdAll.get(fromId);
+    if (!target || !source) return;
+    if ((target.dependsOn ?? []).includes(fromId)) return;
+    if (wouldCycle(all, fromId, toId)) {
+      setNotice(`${name(source)} already waits on ${name(target)}, so ${name(target)} cannot wait on it.`);
+      return;
+    }
+    setNotice(null);
+    commit({ type: "update", id: toId, patch: { dependsOn: [...(target.dependsOn ?? []), fromId] } }, { label: name(target) }).then((r) => {
+      if (r?.ok !== false) say(`${name(target)} now waits on ${name(source)}.`);
+    });
+  }
+
+  function unlink(fromId, toId) {
+    const target = byIdAll.get(toId);
+    if (!target) return;
+    commit(
+      { type: "update", id: toId, patch: { dependsOn: (target.dependsOn ?? []).filter((d) => d !== fromId) } },
+      { label: name(target), undo: `${name(target)} no longer waits on ${name(byIdAll.get(fromId))}` },
+    );
+  }
+
+  function groupPatch(key) {
+    if (!by) return {};
+    return movePatch({ assignees: [], tags: [] }, by, NONE, key, ctx);
+  }
+
+  async function create(title, groupKey) {
+    const patch = groupPatch(groupKey);
+    if (patch === null) return { ok: false };
+    const start = ctx.today;
+    const task = draftTask(title, ctx, { ...patch, start, due: addDays(start, Math.max(1, newTaskLength) - 1) });
+    const r = await commit({ type: "create", task }, { label: name(task) });
+    if (r?.ok !== false) say(`Added ${name(task)}, starting today.`);
+    return r;
+  }
+
+  function schedule(task, dayIndex) {
+    const start = addDays(from, dayIndex);
+    const end = addDays(start, Math.max(1, isMilestone(task) ? 1 : newTaskLength) - 1);
+    commit({ type: "update", id: task.id, patch: spanPatch(task, start, end) }, { label: name(task) }).then((r) => {
+      if (r?.ok !== false) say(`${name(task)} is scheduled for ${spanWords({ start, end }, locale)}.`);
+    });
+  }
+
+  function remove(task) {
+    commit(deleteChange(all, [task.id]), { label: name(task), undo: `Deleted ${name(task)}` });
+  }
+
+  async function startFrom(s) {
+    let cursor = ctx.today;
+    let prev = null;
+    const made = [];
+    for (const item of s.tasks ?? []) {
+      const len = Math.max(1, item.milestone ? 1 : item.days ?? newTaskLength);
+      const start = item.parallel && prev ? prev.start : cursor;
+      const end = addDays(start, len - 1);
+      const t = draftTask(item.title, ctx, {
+        start: item.milestone ? undefined : start,
+        due: end,
+        ...(item.milestone ? { milestone: true } : {}),
+        dependsOn: prev && !item.parallel ? [prev.id] : [],
+      });
+      made.push(t);
+      if (!item.parallel) cursor = addDays(end, 1);
+      prev = { id: t.id, start };
+    }
+    await commit({ type: "create", tasks: made }, { label: s.label });
+  }
+
+  function clickGuard() {
+    return Date.now() - dragEndedAt.current < 250;
+  }
+
+  function menuFor(row) {
+    const t = row.task;
+    const items = [];
+    if (onOpen) items.push({ label: "Open", icon: "external", onSelect: () => onOpen(t) });
+    if (!editable) return items;
+    if (!row.span) items.push({ label: "Schedule from today", icon: "calendar", onSelect: () => schedule(t, diffDays(from, ctx.today)) });
+    const fix = conflicted.has(t.id) ? afterBlockersPatch(t, all) : null;
+    if (fix) items.push({ label: "Start after what it waits on", icon: "arrow-right", onSelect: () => commit({ type: "update", id: t.id, patch: fix }, { label: name(t) }) });
+    // "Waits on": what it waits on now, then the tasks nearest its start
+    // (a dozen; the dot on a bar links anything).
+    const mine = new Set(t.dependsOn ?? []);
+    const at = row.span?.start ?? ctx.today;
+    const near = (o) => Math.abs(diffDays(at, spanOf(o)?.start ?? at) ?? 0);
+    const others = shown.tasks
+      .filter((o) => o.id !== t.id && o.id !== t.parentId)
+      .sort((a, b) => (mine.has(b.id) ? 1 : 0) - (mine.has(a.id) ? 1 : 0) || near(a) - near(b))
+      .slice(0, Math.max(12, mine.size));
+    if (others.length) {
+      items.push({
+        label: "Waits on",
+        icon: "link",
+        items: others.map((o) => {
+          const on = (t.dependsOn ?? []).includes(o.id);
+          return {
+            type: "checkbox",
+            label: o.title || "Untitled",
+            checked: on,
+            disabled: !on && wouldCycle(all, o.id, t.id),
+            onCheckedChange: (next) => (next ? link(o.id, t.id) : unlink(o.id, t.id)),
+          };
+        }),
+      });
+    }
+    items.push({ label: row.done ? "Mark not done" : "Mark done", icon: "check", onSelect: () => commit(toggleDoneChange(t, ctx), { label: name(t) }) });
+    items.push({ type: "separator" });
+    items.push({ label: "Delete", icon: "trash", tone: "danger", onSelect: () => remove(t) });
+    return items;
+  }
+
+  function tintOf(task) {
+    if (colorBy === "status") {
+      const s = ctx.statusById.get(String(task.status));
+      return TINTS[s?.hue] ?? TINTS[s?.tone] ?? TINTS.neutral;
+    }
+    if (colorBy === "project") return TINTS[ctx.projectById.get(String(task.project))?.hue] ?? TINTS.primary;
+    return TINTS.primary;
+  }
+
+  const clearFilters = () => setViewRaw({ ...view, search: "", filters: {}, hideDone: false });
+  const firstGroup = shown.groups[0]?.key ?? "all";
+
+  // ---- render ------------------------------------------------------------
+  const addButton = editable ? (
+    <Button
+      variant="primary"
+      size="sm"
+      icon="plus"
+      onClick={() => {
+        setListOpen(true);
+        setFolded((s) => (s.has(firstGroup) ? new Set([...s].filter((k) => k !== firstGroup)) : s));
+        setAdding(firstGroup);
+      }}
+    >
+      <span className="sr-only sm:not-sr-only">{addLabel}</span>
+    </Button>
+  ) : null;
+
+  const bar = (
+    <div className="flex flex-wrap items-center gap-2 border-b border-border px-2 py-2">
+      <Toggle
+        size="sm"
+        variant="quiet"
+        icon="panel-left"
+        label={showList ? "Hide the task list" : "Show the task list"}
+        pressed={showList}
+        onPressedChange={(on) => setListOpen(on)}
+      />
+      <Button size="sm" variant="quiet" onClick={() => scrollToDay(ctx.today, { smooth: true })}>
+        Today
+      </Button>
+      <ToggleGroup aria-label="Zoom" size="sm" items={ZOOM_ITEMS} value={zoom} onChange={setZoom} className="order-last w-full sm:order-none sm:w-auto" />
+      <div className="ms-auto flex min-w-0 items-center gap-2">
+        {finish.day ? (
+          <p className="hidden items-center gap-1.5 text-sm text-muted-foreground md:flex">
+            Finishes <span className="font-medium text-foreground">{formatDate(finish.day, { weekday: "short", month: "short", day: "numeric" }, { locale })}</span>
+            {drag && finish.delta ? (
+              <span data-nums className={cx("rounded-full px-1.5 text-xs font-medium tabular-nums", finish.delta > 0 ? "bg-warning/15 text-warning" : "bg-success/15 text-success")}>
+                {finish.delta > 0 ? "+" : "−"}
+                {Math.abs(finish.delta)} {Math.abs(finish.delta) === 1 ? "day" : "days"}
+              </span>
+            ) : null}
+          </p>
+        ) : null}
+        <Toggle size="sm" variant="quiet" icon="zap" pressed={critical} onPressedChange={setCritical}>
+          <span className="sr-only sm:not-sr-only">Critical path</span>
+        </Toggle>
+      </div>
+    </div>
+  );
+
+  let content;
+  if (loading) {
+    content = (
+      <div aria-busy="true" className="grid gap-3 p-4" style={{ height: Math.min(height, 320) }}>
+        {[64, 48, 72, 40, 56].map((w, i) => (
+          <div key={i} className="flex items-center gap-4">
+            <Skeleton className="w-28 shrink-0 sm:w-56" />
+            <div className="min-w-0 flex-1" style={{ paddingInlineStart: `${i * 6}%`, paddingInlineEnd: `${100 - w - i * 6}%` }}>
+              <Skeleton shape="rect" className="h-6 w-full" />
+            </div>
+          </div>
+        ))}
+        <span className="sr-only">Loading the timeline</span>
+      </div>
+    );
+  } else if (!all.length) {
+    content = (
+      <div className="p-4">
+        <Empty
+          icon="calendar"
+          title={emptyTitle}
+          body={emptyBody}
+          action={editable ? <FirstTask onCreate={(title) => create(title, firstGroup)} starters={starters} onStarter={startFrom} addLabel={addLabel} uid={uid} /> : null}
+        />
+      </div>
+    );
+  } else if (!shown.tasks.length) {
+    content = (
+      <div className="p-4">
+        <Empty
+          icon="filter"
+          title="No tasks match"
+          body="Nothing on this timeline fits the search and filters."
+          action={
+            <Button size="sm" variant="secondary" onClick={clearFilters}>
+              Clear filters
+            </Button>
+          }
+        />
+      </div>
+    );
+  } else {
+    const tx = from ? xOf(ctx.today, from, dw) : null;
+    const todayIn = tx !== null && tx >= 0 && tx < width;
+    content = (
+      <TaskDragProvider collision="pointer" onDragStart={onDragStart} onDragEnd={onDragEnd} onDragCancel={() => (setDrag(null), setLinking(false))} disabled={!editable}>
+        <div
+          ref={scrollRef}
+          className={cx("relative overflow-auto overscroll-x-contain", showList ? "[--gantt-list:11rem] sm:[--gantt-list:18rem]" : "[--gantt-list:0px]")}
+          style={{ maxHeight: `min(${height}px, 75vh)` }}
+          onPointerLeave={() => setHot(null)}
+        >
+          <div className="w-max min-w-full">
+            {/* The header: the list's heading, then months over days (or
+                years over months). Sticky to the top. */}
+            <div className="sticky top-0 z-40 flex border-b border-border bg-card" style={{ height: HEADER }}>
+              {showList ? (
+                <div className="sticky left-0 z-10 flex w-44 shrink-0 items-end border-e border-border bg-card px-3 pb-1.5 sm:w-72">
+                  <span className="text-xs font-medium text-muted-foreground">
+                    Task{" "}
+                    <span data-nums className="tabular-nums">
+                      · {shown.tasks.length}
+                    </span>
+                  </span>
+                </div>
+              ) : null}
+              <div className="relative shrink-0" style={{ width }} aria-hidden="true">
+                {tiers.top.map((c) => (
+                  <div key={c.key} className="absolute top-0 flex h-6 items-center border-s border-border px-2 first:border-s-0" style={{ left: c.x, width: c.w }}>
+                    <span className="sticky left-[calc(var(--gantt-list)+8px)] truncate text-xs font-medium text-foreground">
+                      {c.label}
+                    </span>
+                  </div>
+                ))}
+                {tiers.bottom.map((c) => (
+                  <div
+                    key={c.key}
+                    className={cx("absolute bottom-0 flex h-7 items-center justify-center border-s border-border/60 first:border-s-0", c.weekend ? "text-muted-foreground/60" : "text-muted-foreground")}
+                    style={{ left: c.x, width: c.w }}
+                  >
+                    {c.today && z.unit === "day" ? (
+                      <span data-nums className="rounded-full bg-primary px-1.5 text-2xs font-semibold tabular-nums text-primary-foreground">
+                        {c.label}
+                      </span>
+                    ) : c.w >= 22 ? (
+                      <span data-nums className={cx("truncate text-2xs tabular-nums", c.today && "font-semibold text-foreground")}>
+                        {c.label}
+                      </span>
+                    ) : null}
+                  </div>
+                ))}
+                {todayIn && z.unit !== "day" ? <span className="absolute bottom-0 size-1.5 -translate-x-1/2 translate-y-1/2 rounded-full bg-primary" style={{ left: tx + dw / 2 }} /> : null}
+              </div>
+            </div>
+
+            <div className="relative flex">
+              {/* The list pane: sticky to the left while the timeline scrolls. */}
+              {showList ? (
+                <div ref={listRef} className="sticky left-0 z-30 w-44 shrink-0 border-e border-border bg-card sm:w-72">
+                  {rows.list.map((r) =>
+                    r.kind === "group" ? (
+                      <GroupRow
+                        key={r.key}
+                        group={r.group}
+                        by={by}
+                        ctx={ctx}
+                        count={r.group.tasks.length}
+                        folded={folded.has(r.group.key)}
+                        hot={hot === r.key}
+                        onHot={() => setHot(r.key)}
+                        onFold={() =>
+                          setFolded((s) => {
+                            const n = new Set(s);
+                            if (n.has(r.group.key)) n.delete(r.group.key);
+                            else n.add(r.group.key);
+                            return n;
+                          })
+                        }
+                      />
+                    ) : r.kind === "task" ? (
+                      <ListRow
+                        key={r.key}
+                        row={r}
+                        ctx={ctx}
+                        hot={hot === r.key}
+                        onHot={() => setHot(r.key)}
+                        onOpen={onOpen}
+                        menu={menuFor(r)}
+                        conflict={conflicted.has(r.task.id)}
+                        blockers={(conflicted.get(r.task.id) ?? []).map((id) => name(byIdAll.get(id))).join(" and ")}
+                        onFold={() =>
+                          setCollapsed((s) => {
+                            const n = new Set(s);
+                            if (n.has(r.task.id)) n.delete(r.task.id);
+                            else n.add(r.task.id);
+                            return n;
+                          })
+                        }
+                      />
+                    ) : (
+                      <QuickAdd
+                        key={r.key}
+                        uid={uid}
+                        group={r.group}
+                        addLabel={addLabel}
+                        open={adding === r.group.key}
+                        onOpen={() => setAdding(r.group.key)}
+                        onClose={() => setAdding((a) => (a === r.group.key ? null : a))}
+                        onCreate={create}
+                      />
+                    ),
+                  )}
+                </div>
+              ) : null}
+
+              {/* The timeline. */}
+              <div className="relative shrink-0" style={{ width, height: rows.height }}>
+                <div aria-hidden="true" className="pointer-events-none absolute inset-0">
+                  {bands.map((b) => (
+                    <span key={b.start} className="absolute inset-y-0 bg-muted/50" style={{ left: b.x, width: b.w }} />
+                  ))}
+                  {tiers.bottom.slice(1).map((c) => (
+                    <span key={c.key} className="absolute inset-y-0 w-px bg-border/50" style={{ left: c.x }} />
+                  ))}
+                  {rows.list
+                    .filter((r) => r.kind === "group")
+                    .map((r) => (
+                      <span key={r.key} className={cx("absolute inset-x-0 bg-muted/40", r.y > 0 && "border-t border-border")} style={{ top: r.y, height: ROW }} />
+                    ))}
+                </div>
+
+                {rows.list.map((r) => {
+                  if (r.kind === "add") return <div key={r.key} style={{ height: ADD_ROW }} />;
+                  if (r.kind === "group") {
+                    const s = groupSpan(r.group.tasks, byId);
+                    return (
+                      <div key={r.key} className={cx("relative", hot === r.key && "bg-accent/40")} style={{ height: ROW }} onPointerEnter={() => setHot(r.key)}>
+                        {s ? (
+                          <span
+                            aria-hidden="true"
+                            className="absolute top-1/2 h-1.5 -translate-y-1/2 rounded-full bg-muted-foreground/25"
+                            style={{ left: xOf(s.start, from, dw), width: Math.max(lengthOf(s) * dw, 6) }}
+                          />
+                        ) : null}
+                      </div>
+                    );
+                  }
+                  const box = boxes.get(r.task.id);
+                  const first = box && Math.abs(box.y - (r.y + ROW / 2)) < 1;
+                  return (
+                    <TimelineRow key={r.key} row={r} hot={hot === r.key} onHot={() => setHot(r.key)} linking={linking && editable}>
+                      {(over) =>
+                        r.span ? (
+                          <Bar
+                            row={r}
+                            x={r.milestone && !r.hasChildren ? xOf(r.span.end, from, dw) : xOf(r.span.start, from, dw)}
+                            w={r.milestone && !r.hasChildren ? dw : Math.max(lengthOf(r.span) * dw, 6)}
+                            dayWidth={dw}
+                            tint={tintOf(r.task)}
+                            shape={r.hasChildren ? "summary" : r.milestone ? "milestone" : "bar"}
+                            editable={editable && first !== false}
+                            onOpen={onOpen}
+                            onPreview={onPreview}
+                            onNudge={onNudge}
+                            clickGuard={clickGuard}
+                            dim={critical && path.size > 0 && !path.has(r.task.id)}
+                            critical={critical && path.has(r.task.id)}
+                            over={over}
+                            moving={Boolean(drag && moved.has(r.task.id))}
+                            hintId={`${uid}-hint`}
+                            locale={locale}
+                          />
+                        ) : editable ? (
+                          <Unscheduled row={r} dayWidth={dw} length={r.milestone ? 1 : newTaskLength} onSchedule={schedule} />
+                        ) : null
+                      }
+                    </TimelineRow>
+                  );
+                })}
+
+                {/* raw: an SVG drawing — the dependency arrows over the
+                    bars; no kit part draws them. */}
+                <svg aria-hidden="true" className="pointer-events-none absolute inset-0 z-[5] overflow-visible" width={width} height={rows.height}>
+                  {edges.map((e) => {
+                    const a = boxes.get(e.from);
+                    const b = boxes.get(e.to);
+                    const { d, head } = arrowPath(a, b, { rowHeight: ROW });
+                    const bad = conflicts.has(`${e.from}>${e.to}`);
+                    const hotPath = critical && path.has(e.from) && path.has(e.to);
+                    const faded = critical && path.size > 0 && !hotPath;
+                    const stroke = bad ? "stroke-destructive" : hotPath ? "stroke-primary" : "stroke-muted-foreground/70";
+                    const fill = bad ? "fill-destructive" : hotPath ? "fill-primary" : "fill-muted-foreground/70";
+                    return (
+                      <g key={`${e.from}>${e.to}`} className={cx(faded && "opacity-30", "motion-safe:transition-opacity motion-safe:duration-150")}>
+                        <path d={d} fill="none" className={stroke} strokeWidth={hotPath ? 2 : 1.25} strokeDasharray={bad ? "4 3" : undefined} strokeLinecap="round" />
+                        <path d={head} className={fill} />
+                      </g>
+                    );
+                  })}
+                </svg>
+
+                {todayIn ? (
+                  <span aria-hidden="true" className="pointer-events-none absolute inset-y-0 z-[4] w-px bg-primary/70" style={{ left: tx + dw / 2 }} />
+                ) : null}
+              </div>
+            </div>
+          </div>
+        </div>
+      </TaskDragProvider>
+    );
+  }
+
+  return (
+    <section aria-label={label} className={cx("grid min-w-0 gap-3", className)}>
+      {toolbar && all.length ? (
+        <ViewToolbar
+          view={view}
+          onViewChange={setViewRaw}
+          ctx={ctx}
+          tasks={all}
+          controls={["search", "filter", "group", "sort"]}
+          groupFields={GROUP_FIELDS}
+          count={shown.tasks.length}
+          extra={
+            toolbarExtra || addButton ? (
+              <>
+                {toolbarExtra}
+                {addButton}
+              </>
+            ) : null
+          }
+        />
+      ) : null}
+      {readError ? <Notice tone="danger">{readError}</Notice> : null}
+      {error ? (
+        <Notice tone="danger" onDismiss={clearError}>
+          {error}
+        </Notice>
+      ) : null}
+      {notice ? (
+        <Notice tone="warning" onDismiss={() => setNotice(null)}>
+          {notice}
+        </Notice>
+      ) : null}
+      <div className="min-w-0 overflow-hidden rounded-lg border border-border bg-card text-card-foreground">
+        {all.length && !loading ? bar : null}
+        {content}
+        {critical && all.length && !loading ? (
+          <p className="border-t border-border px-3 py-2 text-xs text-muted-foreground" aria-live="polite">
+            {path.size > 1 ? (
+              <>
+                <Icon name="zap" size={12} className="me-1 inline-block align-[-2px] text-primary" />
+                The critical path: {path.size} linked tasks, {pathDays} days end to end. Any day they slip, the finish slips.
+              </>
+            ) : (
+              "No critical path yet: link tasks (drag the dot past a bar's end onto another bar) to see the chain that sets the finish."
+            )}
+          </p>
+        ) : null}
+      </div>
+      <p id={`${uid}-hint`} className="sr-only">
+        Left and right arrows move it a day; with Shift they change its end, with Alt its start. Enter saves at once or opens it; Escape cancels a move.
+      </p>
+      <p className="sr-only" role="status" aria-live="polite">
+        {announce}
+      </p>
+    </section>
+  );
+}
+
+function groupSpan(tasks, byId) {
+  let s = null;
+  for (const t of tasks) {
+    const x = spanOf(byId.get(t.id) ?? t);
+    if (!x) continue;
+    s = s ? { start: x.start < s.start ? x.start : s.start, end: x.end > s.end ? x.end : s.end } : x;
+  }
+  return s;
+}
+
+// The empty state's action: name the first task (it starts today), or
+// start from a template.
+function FirstTask({ onCreate, starters, onStarter, addLabel, uid }) {
+  const [draft, setDraft] = useState("");
+  const [busy, setBusy] = useState(false);
+  async function submit() {
+    const title = draft.trim();
+    if (!title || busy) return;
+    setBusy(true);
+    await onCreate(title);
+    setBusy(false);
+    setDraft("");
+  }
+  return (
+    <div className="grid w-full max-w-sm justify-items-center gap-3">
+      <form
+        className="flex w-full items-center gap-2"
+        onSubmit={(e) => {
+          e.preventDefault();
+          submit();
+        }}
+      >
+        <label htmlFor={`${uid}-first`} className="sr-only">
+          The first task
+        </label>
+        <Input id={`${uid}-first`} value={draft} placeholder="What needs doing first?" onChange={(e) => setDraft(e.target.value)} />
+        <Button type="submit" variant="primary" icon="plus" loading={busy} disabled={!draft.trim()}>
+          {addLabel}
+        </Button>
+      </form>
+      {starters?.length ? (
+        <div className="grid justify-items-center gap-1.5">
+          <span className="text-xs text-muted-foreground">Or start from a plan</span>
+          <div className="flex flex-wrap justify-center gap-2">
+            {starters.map((s) => (
+              <Button key={s.label} size="sm" variant="secondary" icon={s.icon ?? "sparkles"} onClick={() => onStarter(s)}>
+                {s.label}
+              </Button>
+            ))}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}