makersclaw 0.2.0 → 0.3.0

package/registry/blocks/task-model/model.js

@@ -0,0 +1,919 @@
+// The work-item model every view reads — pure, no React.
+//
+// One shape (a task), one context (its statuses, people, projects, custom
+// fields and today), and the arithmetic every view repeats: search,
+// filter, group by any field, sort, subtask trees, capacity, dependencies,
+// and the Change a view sends out when the founder moves something. List,
+// board, table, calendar, gantt, workload, portfolio and roadmap all run
+// through these, so a task filtered out of one is filtered out of all.
+//
+// README.md beside this file is the contract; this file is the proof.
+
+import {
+  DUE_BUCKETS,
+  addDays,
+  dayForBucket,
+  dayOf,
+  daysBetween,
+  diffDays,
+  dueBucket,
+  isWorkingDay,
+  minutesOf,
+  shiftDates,
+  spanOf,
+  startOfWeek,
+  todayDay,
+  withTime,
+} from "./dates";
+
+/** The group / filter value of "no value": Unassigned, No date, … */
+export const NONE = "__none";
+
+export const PRIORITIES = [
+  { id: "urgent", label: "Urgent", tone: "danger" },
+  { id: "high", label: "High", tone: "warning" },
+  { id: "medium", label: "Medium", tone: "info" },
+  { id: "low", label: "Low", tone: "neutral" },
+];
+
+/** A sensible set when the surface has none of its own. */
+export const DEFAULT_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 },
+];
+
+/** The fields every task has. Custom fields join through `fields`. */
+export const TASK_FIELDS = [
+  { key: "title", label: "Name", kind: "text", groupable: false },
+  { key: "status", label: "Status", kind: "status" },
+  { key: "assignees", label: "Assignee", kind: "people", multi: true },
+  { key: "due", label: "Due date", kind: "date" },
+  { key: "start", label: "Start date", kind: "date" },
+  { key: "priority", label: "Priority", kind: "priority" },
+  { key: "project", label: "Project", kind: "project" },
+  { key: "tags", label: "Tags", kind: "tags", multi: true },
+  { key: "estimate", label: "Estimate", kind: "number", unit: "h", groupable: false },
+  { key: "progress", label: "Progress", kind: "progress", groupable: false },
+];
+
+const EMPTY_WORDS = {
+  status: "No status",
+  people: "Unassigned",
+  priority: "No priority",
+  project: "No project",
+  tags: "No tags",
+  date: "No date",
+  select: "None",
+  text: "None",
+  number: "None",
+  checkbox: "No",
+};
+
+const isBlank = (v) => v === null || v === undefined || v === "";
+const asList = (v) => (Array.isArray(v) ? v.filter((x) => !isBlank(x)).map(String) : isBlank(v) ? [] : [String(v)]);
+
+// ---- the shape ---------------------------------------------------------
+
+/** A task with its lists always lists and its id a string: what every
+ *  helper assumes. Unknown keys are kept (`…extra`). */
+export function normalizeTask(t) {
+  return {
+    ...t,
+    id: String(t?.id ?? ""),
+    title: String(t?.title ?? t?.name ?? ""),
+    assignees: asList(t?.assignees ?? t?.assignee),
+    tags: asList(t?.tags),
+    dependsOn: asList(t?.dependsOn),
+    parentId: isBlank(t?.parentId) ? null : String(t.parentId),
+  };
+}
+
+export function normalizeTasks(list) {
+  return (list ?? []).map(normalizeTask);
+}
+
+/** Everything a helper needs beside the tasks, built once per render
+ *  (useMemo it). `statuses` in order ({ id, label, tone?: neutral · info
+ *  · warning · success · danger · primary, hue?: 1–5, done? }); `people`
+ *  ({ id, name, src?, capacity? hours a day }); `projects` ({ id, name,
+ *  hue? }); `fields` (custom: { key, label, kind: text · number · select
+ *  · date · checkbox, options? }); `today` ("YYYY-MM-DD", fixed in a
+ *  demo); `weekStartsOn` (0–6, default Monday). */
+export function createTaskContext({ statuses, people, projects, fields, today, weekStartsOn = 1, weekend, holidays } = {}) {
+  const st = (statuses?.length ? statuses : DEFAULT_STATUSES).map((s) => ({ ...s, id: String(s.id), label: s.label ?? String(s.id) }));
+  const pp = (people ?? []).map((p) => ({ ...p, id: String(p.id), name: p.name ?? String(p.id) }));
+  const pj = (projects ?? []).map((p) => ({ ...p, id: String(p.id), name: p.name ?? String(p.id) }));
+  const custom = (fields ?? []).map((f) => ({ ...f, label: f.label ?? f.key, custom: true }));
+  const known = new Set(TASK_FIELDS.map((f) => f.key));
+  return {
+    statuses: st,
+    people: pp,
+    projects: pj,
+    fields: [...TASK_FIELDS, ...custom.filter((f) => !known.has(f.key))],
+    statusById: new Map(st.map((s, i) => [s.id, { ...s, index: i }])),
+    personById: new Map(pp.map((p) => [p.id, p])),
+    projectById: new Map(pj.map((p) => [p.id, p])),
+    doneIds: new Set(st.filter((s) => s.done).map((s) => s.id)),
+    today: dayOf(today) ?? todayDay(),
+    weekStartsOn,
+    weekend,
+    holidays,
+  };
+}
+
+const ctxOf = (ctx) => (ctx && ctx.statusById ? ctx : createTaskContext(ctx ?? {}));
+
+export function fieldOf(key, ctx) {
+  return ctxOf(ctx).fields.find((f) => f.key === key) ?? { key, label: key, kind: "text", custom: true };
+}
+
+export function isDone(task, ctx) {
+  const c = ctxOf(ctx);
+  return c.doneIds.has(String(task?.status)) || task?.done === true;
+}
+
+/** The first "done" status, and the first that is not. */
+export function doneStatusId(ctx) {
+  return ctxOf(ctx).statuses.find((s) => s.done)?.id ?? null;
+}
+export function openStatusId(ctx) {
+  return ctxOf(ctx).statuses.find((s) => !s.done)?.id ?? null;
+}
+
+/** The change a completion checkbox saves: to the first done status, or
+ *  back to the first open one. */
+export function toggleDoneChange(task, ctx) {
+  const done = isDone(task, ctx);
+  return { type: "update", id: task.id, patch: { status: done ? openStatusId(ctx) : doneStatusId(ctx) } };
+}
+
+let seq = 0;
+/** A client id for a task being created; the page may swap it for the
+ *  database's (answer `{ ok: true, id }`). */
+export function newTaskId() {
+  seq += 1;
+  return `new-${Date.now().toString(36)}-${seq}`;
+}
+
+/** A new task with the defaults a quick-add needs: first open status, an
+ *  `order` after `after` (a list's last task), and the patch of the group
+ *  it was added in. */
+export function draftTask(title, ctx, patch = {}, { after } = {}) {
+  return normalizeTask({
+    id: newTaskId(),
+    title: String(title ?? "").trim(),
+    status: openStatusId(ctx),
+    order: rankBetween(orderOf(after), null),
+    ...patch,
+  });
+}
+
+// ---- values of a field -------------------------------------------------
+
+/** The keys a task is filed under for a field (one, or several for
+ *  assignees and tags; `NONE` when it has none). Dates are due buckets. */
+export function valuesOf(task, key, ctx) {
+  const c = ctxOf(ctx);
+  const field = fieldOf(key, c);
+  const v = task?.[field.key];
+  switch (field.kind) {
+    case "people":
+    case "tags": {
+      const list = asList(v);
+      return list.length ? list : [NONE];
+    }
+    case "date":
+      return [dueBucket(v, c.today, { done: isDone(task, c), weekStartsOn: c.weekStartsOn })];
+    case "checkbox":
+      return [v ? "yes" : "no"];
+    default:
+      return [isBlank(v) ? NONE : String(v)];
+  }
+}
+
+/** A field's choices in order, as { id, label, tone?, hue?, person?,
+ *  project? } — the groups of "group by" and the chips of a filter. The
+ *  "none" choice comes last. Tags and plain values are read from `tasks`. */
+export function optionsOf(key, ctx, tasks = []) {
+  const c = ctxOf(ctx);
+  const field = fieldOf(key, c);
+  let out;
+  switch (field.kind) {
+    case "status":
+      out = c.statuses.map((s) => ({ id: s.id, label: s.label, tone: s.tone, hue: s.hue, done: Boolean(s.done) }));
+      break;
+    case "people":
+      out = c.people.map((p) => ({ id: p.id, label: p.name, person: p }));
+      break;
+    case "priority":
+      out = PRIORITIES.map((p) => ({ ...p }));
+      break;
+    case "project":
+      out = c.projects.map((p) => ({ id: p.id, label: p.name, hue: p.hue, project: p }));
+      break;
+    case "date":
+      out = DUE_BUCKETS.filter((b) => b.id !== "none").map((b) => ({ ...b }));
+      break;
+    case "checkbox":
+      return [
+        { id: "yes", label: "Yes" },
+        { id: "no", label: "No" },
+      ];
+    case "select":
+      out = (field.options ?? []).map((o) => (typeof o === "object" ? { ...o, id: String(o.id ?? o.value), label: o.label ?? String(o.id ?? o.value) } : { id: String(o), label: String(o) }));
+      break;
+    default: {
+      const seen = new Set();
+      for (const t of tasks) for (const v of valuesOf(t, key, c)) if (v !== NONE) seen.add(v);
+      out = [...seen].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).map((v) => ({ id: v, label: v }));
+    }
+  }
+  return [...out, { id: NONE, label: EMPTY_WORDS[field.kind] ?? "None", none: true }];
+}
+
+/** The words for one value of a field: labelOf("status", "doing") → "In progress". */
+export function labelOf(key, value, ctx, tasks) {
+  const o = optionsOf(key, ctx, tasks).find((x) => x.id === String(value ?? NONE));
+  return o?.label ?? String(value ?? "");
+}
+
+// ---- search, filter, sort ---------------------------------------------
+
+/** The words a task can be found by: its title, tags, people, project,
+ *  status, and any string field. */
+export function searchText(task, ctx) {
+  const c = ctxOf(ctx);
+  const parts = [task.title, task.description, ...(task.tags ?? [])];
+  for (const id of task.assignees ?? []) parts.push(c.personById.get(id)?.name);
+  parts.push(c.projectById.get(String(task.project))?.name, c.statusById.get(String(task.status))?.label);
+  for (const f of c.fields) if (f.custom && typeof task[f.key] === "string") parts.push(task[f.key]);
+  return parts.filter(Boolean).join(" \u0001 ").toLowerCase();
+}
+
+/** Tasks that hold every word of `query`. */
+export function searchTasks(tasks, query, ctx) {
+  const words = String(query ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (!words.length) return tasks;
+  const c = ctxOf(ctx);
+  return tasks.filter((t) => {
+    const text = searchText(t, c);
+    return words.every((w) => text.includes(w));
+  });
+}
+
+/** Tasks that match `filters` — { status: ["todo", "doing"], assignees:
+ *  ["maya", NONE], due: ["overdue"] }: any value within a field, every
+ *  field. An empty list is no filter. */
+export function filterTasks(tasks, filters, ctx) {
+  const c = ctxOf(ctx);
+  const active = Object.entries(filters ?? {}).filter(([, v]) => Array.isArray(v) && v.length);
+  if (!active.length) return tasks;
+  return tasks.filter((t) => active.every(([key, want]) => valuesOf(t, key, c).some((v) => want.includes(v))));
+}
+
+/** A task's place in a hand-made order (`order`), or null. */
+export function orderOf(task) {
+  return typeof task?.order === "number" && Number.isFinite(task.order) ? task.order : null;
+}
+
+function sortValue(task, key, c) {
+  if (key === "manual") return orderOf(task);
+  const field = fieldOf(key, c);
+  const v = task[field.key];
+  switch (field.kind) {
+    case "status":
+      return c.statusById.get(String(v))?.index ?? null;
+    case "priority": {
+      const i = PRIORITIES.findIndex((p) => p.id === v);
+      return i < 0 ? null : i;
+    }
+    case "people":
+      return c.personById.get(asList(v)[0])?.name ?? (asList(v)[0] || null);
+    case "project":
+      return c.projectById.get(String(v))?.name ?? (isBlank(v) ? null : String(v));
+    case "tags":
+      return asList(v)[0] ?? null;
+    case "date": {
+      const d = dayOf(v);
+      return d ? `${d}T${String(minutesOf(v) ?? 0).padStart(4, "0")}` : null;
+    }
+    case "select": {
+      const i = (field.options ?? []).findIndex((o) => String(typeof o === "object" ? o.id ?? o.value : o) === String(v));
+      return i < 0 ? (isBlank(v) ? null : String(v)) : i;
+    }
+    default:
+      return isBlank(v) ? null : v;
+  }
+}
+
+function compare(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+
+/** Tasks by `sort` ([{ key, dir: "asc" | "desc" }], first wins; key
+ *  "manual" is the hand-made `order`). Blanks last either way; stable. An
+ *  empty sort is the manual order. */
+export function sortTasks(tasks, sort, ctx) {
+  const c = ctxOf(ctx);
+  const keys = sort?.length ? sort : [{ key: "manual", dir: "asc" }];
+  return tasks
+    .map((task, i) => ({ task, i }))
+    .sort((x, y) => {
+      for (const { key, dir } of keys) {
+        const a = sortValue(x.task, key, c);
+        const b = sortValue(y.task, key, c);
+        if (a === null || b === null) {
+          if (a === null && b === null) continue;
+          return a === null ? 1 : -1;
+        }
+        const r = compare(a, b);
+        if (r !== 0) return dir === "desc" ? -r : r;
+      }
+      return x.i - y.i;
+    })
+    .map((x) => x.task);
+}
+
+/** The sorts a view offers: "manual" and every sortable field. */
+export function sortOptions(ctx) {
+  return [{ key: "manual", label: "Manual" }, ...ctxOf(ctx).fields.filter((f) => f.sortable !== false).map((f) => ({ key: f.key, label: f.label }))];
+}
+
+// ---- group -------------------------------------------------------------
+
+/** Tasks filed under a field's values, in the field's order:
+ *  [{ key, label, tone?, hue?, option, tasks }]. A task with several
+ *  assignees (or tags) is in each of their groups. `by` null / "none" →
+ *  one group of everything. Empty groups show for status and priority
+ *  (somewhere to drop), or always with `showEmpty: true`; the "none" group
+ *  only when it holds something. */
+export function groupTasks(tasks, by, ctx, { showEmpty } = {}) {
+  const c = ctxOf(ctx);
+  if (!by || by === "none") return [{ key: "all", label: "All tasks", option: null, tasks: [...tasks] }];
+  const field = fieldOf(by, c);
+  const keepEmpty = showEmpty ?? (field.kind === "status" || field.kind === "priority");
+  const options = optionsOf(by, c, tasks);
+  const map = new Map(options.map((o) => [o.id, []]));
+  for (const t of tasks) {
+    for (const v of valuesOf(t, by, c)) {
+      if (!map.has(v)) {
+        map.set(v, []);
+        options.splice(options.length - 1, 0, { id: v, label: v });
+      }
+      map.get(v).push(t);
+    }
+  }
+  return options
+    .map((o) => ({ key: o.id, label: o.label, tone: o.tone, hue: o.hue, option: o, tasks: map.get(o.id) ?? [] }))
+    .filter((g) => g.tasks.length > 0 || (keepEmpty && g.key !== NONE && g.key !== "past"));
+}
+
+/** The fields a view can group by. */
+export function groupOptions(ctx) {
+  return [{ key: "none", label: "None" }, ...ctxOf(ctx).fields.filter((f) => f.groupable !== false).map((f) => ({ key: f.key, label: f.label }))];
+}
+
+/** The patch that moves a task from one group to another when grouped by
+ *  `by`: a new status, an assignee swapped for another (the others stay),
+ *  a due date for a due bucket (a start moves with it). null when the
+ *  group is not a place to drop (Overdue). */
+export function movePatch(task, by, fromKey, toKey, ctx) {
+  const c = ctxOf(ctx);
+  if (!by || by === "none" || fromKey === toKey) return {};
+  const field = fieldOf(by, c);
+  const to = toKey === NONE ? null : toKey;
+  switch (field.kind) {
+    case "people":
+    case "tags": {
+      const list = asList(task[field.key]).filter((v) => v !== fromKey);
+      return { [field.key]: to && !list.includes(to) ? [...list, to] : list };
+    }
+    case "date": {
+      const day = dayForBucket(toKey, c.today, { weekStartsOn: c.weekStartsOn });
+      if (day === undefined) return null;
+      if (day === null) return { [field.key]: null };
+      const from = dayOf(task[field.key]);
+      if (field.key === "due" && from && dayOf(task.start)) return shiftDates(task, diffDays(from, day));
+      return { [field.key]: withTime(day, minutesOf(task[field.key])) };
+    }
+    case "checkbox":
+      return { [field.key]: toKey === "yes" };
+    case "number":
+    case "progress":
+      return { [field.key]: to === null ? null : Number(to) };
+    default:
+      return { [field.key]: to };
+  }
+}
+
+// ---- views -------------------------------------------------------------
+
+/** What a view remembers: work-views saves one per tab. */
+export const DEFAULT_VIEW = {
+  search: "",
+  filters: {},
+  groupBy: "status",
+  sort: [],
+  fields: ["assignees", "due", "priority"],
+  hideDone: false,
+};
+
+/** A view's answer: the tasks it shows (searched, filtered, sorted) and
+ *  their groups. `hideDone` drops done tasks. */
+export function applyView(tasks, view, ctx) {
+  const c = ctxOf(ctx);
+  const v = { ...DEFAULT_VIEW, ...view };
+  let list = normalizeTasks(tasks);
+  if (v.hideDone) list = list.filter((t) => !isDone(t, c));
+  list = filterTasks(searchTasks(list, v.search, c), v.filters, c);
+  list = sortTasks(list, v.sort, c);
+  return { tasks: list, groups: groupTasks(list, v.groupBy, c), total: (tasks ?? []).length };
+}
+
+/** How many filters are on (for a "Filter · 2" button). */
+export function activeFilterCount(view) {
+  return Object.values(view?.filters ?? {}).filter((v) => Array.isArray(v) && v.length).length + (view?.hideDone ? 1 : 0);
+}
+
+// ---- manual order ------------------------------------------------------
+
+const GAP = 1024;
+
+/** A number between two orders (either may be null: the list's end). */
+export function rankBetween(a, b) {
+  if (a == null && b == null) return GAP;
+  if (a == null) return b - GAP;
+  if (b == null) return a + GAP;
+  return (a + b) / 2;
+}
+
+/** The change that puts `task` at `index` of `list` (the target group's
+ *  tasks as shown, without the task itself), with `patch` (a new group)
+ *  merged in. A midpoint `order` when the neighbours have room; else the
+ *  list is renumbered in one batch, so the order always holds. */
+export function placeChange(list, task, index, patch = {}) {
+  const others = list.filter((t) => t.id !== task.id);
+  const i = Math.max(0, Math.min(index, others.length));
+  const orders = others.map(orderOf);
+  const increasing = orders.every((o, k) => o !== null && (k === 0 || o > orders[k - 1]));
+  const prev = i > 0 ? orders[i - 1] : null;
+  const next = i < others.length ? orders[i] : null;
+  if (increasing && (prev === null || next === null || next - prev > 1e-6)) {
+    return { type: "update", id: task.id, patch: { ...patch, order: rankBetween(prev, next) } };
+  }
+  const seqd = [...others.slice(0, i), task, ...others.slice(i)];
+  return {
+    type: "batch",
+    changes: seqd.map((t, k) =>
+      t.id === task.id ? { type: "update", id: t.id, patch: { ...patch, order: (k + 1) * GAP } } : { type: "update", id: t.id, patch: { order: (k + 1) * GAP } },
+    ),
+  };
+}
+
+// ---- trees (subtasks) --------------------------------------------------
+
+/** parentId → its children, in the order given. */
+export function childrenMap(tasks) {
+  const ids = new Set(tasks.map((t) => String(t.id)));
+  const map = new Map();
+  for (const t of tasks) {
+    const p = t.parentId == null ? null : String(t.parentId);
+    const key = p && ids.has(p) && p !== String(t.id) ? p : null;
+    if (!map.has(key)) map.set(key, []);
+    map.get(key).push(t);
+  }
+  return map;
+}
+
+/** Tasks as a tree: [{ task, children: [node…], depth }]. A task whose
+ *  parent is not in `tasks` (filtered out) is a root. Cycles are cut. */
+export function buildTree(tasks) {
+  const map = childrenMap(tasks);
+  const seen = new Set();
+  const walk = (list, depth) =>
+    (list ?? [])
+      .filter((t) => !seen.has(t.id) && seen.add(t.id))
+      .map((task) => ({ task, depth, children: walk(map.get(String(task.id)), depth + 1) }));
+  return walk(map.get(null), 0);
+}
+
+/** The tree as rows in reading order: [{ task, depth, childCount,
+ *  hasChildren, collapsed }]; the children of an id in `collapsed` are
+ *  left out. */
+export function flattenTree(tasks, { collapsed } = {}) {
+  const shut = collapsed instanceof Set ? collapsed : new Set(collapsed ?? []);
+  const out = [];
+  const walk = (nodes) => {
+    for (const n of nodes) {
+      const closed = shut.has(n.task.id);
+      out.push({ task: n.task, depth: n.depth, childCount: n.children.length, hasChildren: n.children.length > 0, collapsed: closed });
+      if (!closed) walk(n.children);
+    }
+  };
+  walk(buildTree(tasks));
+  return out;
+}
+
+/** Every id under `id` (children, their children…). */
+export function descendantIds(tasks, id) {
+  const map = childrenMap(tasks);
+  const out = [];
+  const stack = [...(map.get(String(id)) ?? [])];
+  const seen = new Set([String(id)]);
+  while (stack.length) {
+    const t = stack.pop();
+    if (seen.has(t.id)) continue;
+    seen.add(t.id);
+    out.push(t.id);
+    stack.push(...(map.get(String(t.id)) ?? []));
+  }
+  return out;
+}
+
+/** The ids above `id`, nearest first. */
+export function ancestorIds(tasks, id) {
+  const byId = new Map(tasks.map((t) => [String(t.id), t]));
+  const out = [];
+  let cur = byId.get(String(id));
+  while (cur?.parentId && byId.has(cur.parentId) && !out.includes(cur.parentId) && cur.parentId !== String(id)) {
+    out.push(cur.parentId);
+    cur = byId.get(cur.parentId);
+  }
+  return out;
+}
+
+/** id → { total, done } of its direct subtasks ("2/5" on a row). */
+export function subtaskCounts(tasks, ctx) {
+  const c = ctxOf(ctx);
+  const out = new Map();
+  for (const [parent, kids] of childrenMap(tasks)) {
+    if (parent === null) continue;
+    out.set(parent, { total: kids.length, done: kids.filter((k) => isDone(k, c)).length });
+  }
+  return out;
+}
+
+/** A parent's figures from everything under it: count, done, estimate
+ *  (hours), and progress (0–100: its own, else the share done, weighted
+ *  by estimate when there are estimates). */
+export function rollup(tasks, id, ctx) {
+  const c = ctxOf(ctx);
+  const ids = new Set(descendantIds(tasks, id));
+  const under = tasks.filter((t) => ids.has(t.id));
+  const done = under.filter((t) => isDone(t, c));
+  const estimate = under.reduce((s, t) => s + (Number(t.estimate) || 0), 0);
+  const doneEstimate = done.reduce((s, t) => s + (Number(t.estimate) || 0), 0);
+  const progress = under.length === 0 ? null : estimate > 0 ? Math.round((doneEstimate / estimate) * 100) : Math.round((done.length / under.length) * 100);
+  return { count: under.length, done: done.length, estimate, progress };
+}
+
+/** A task's progress, 0–100: `progress`, else 100 when done, else from
+ *  its subtasks, else 0. */
+export function progressOf(task, tasks, ctx) {
+  if (typeof task?.progress === "number") return Math.max(0, Math.min(100, task.progress));
+  if (isDone(task, ctx)) return 100;
+  return rollup(tasks ?? [], task.id, ctx).progress ?? 0;
+}
+
+// ---- dependencies ------------------------------------------------------
+
+/** [{ from, to }]: `to` depends on `from` (from must finish first). Ids
+ *  not in `tasks` are skipped. */
+export function dependencyEdges(tasks) {
+  const ids = new Set(tasks.map((t) => t.id));
+  const out = [];
+  for (const t of tasks) for (const d of t.dependsOn ?? []) if (ids.has(d) && d !== t.id) out.push({ from: d, to: t.id });
+  return out;
+}
+
+/** The tasks `task` waits on that are not done. */
+export function blockersOf(task, tasks, ctx) {
+  const want = new Set(task?.dependsOn ?? []);
+  return tasks.filter((t) => want.has(t.id) && !isDone(t, ctx));
+}
+
+/** Whether "to depends on from" would close a loop. */
+export function wouldCycle(tasks, fromId, toId) {
+  if (fromId === toId) return true;
+  const deps = new Map(tasks.map((t) => [t.id, t.dependsOn ?? []]));
+  const stack = [fromId];
+  const seen = new Set();
+  while (stack.length) {
+    const id = stack.pop();
+    if (id === toId) return true;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    stack.push(...(deps.get(id) ?? []));
+  }
+  return false;
+}
+
+/** Dependency edges whose dates disagree: `to` starts on or before
+ *  `from` ends. A gantt draws these arrows in the danger tone. */
+export function dateConflicts(tasks) {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  return dependencyEdges(tasks).filter(({ from, to }) => {
+    const a = spanOf(byId.get(from));
+    const b = spanOf(byId.get(to));
+    return a && b && b.start <= a.end;
+  });
+}
+
+/** The ids on the longest chain of dependent, scheduled work (length in
+ *  days, span to span): the critical path a gantt highlights. */
+export function criticalPath(tasks) {
+  const scheduled = tasks.filter((t) => spanOf(t));
+  const byId = new Map(scheduled.map((t) => [t.id, t]));
+  const memo = new Map();
+  const visiting = new Set();
+  const best = (id) => {
+    if (memo.has(id)) return memo.get(id);
+    if (visiting.has(id)) return { len: 0, path: [] };
+    visiting.add(id);
+    const t = byId.get(id);
+    const s = spanOf(t);
+    const own = diffDays(s.start, s.end) + 1;
+    let top = { len: 0, path: [] };
+    for (const d of t.dependsOn ?? []) {
+      if (!byId.has(d)) continue;
+      const r = best(d);
+      if (r.len > top.len) top = r;
+    }
+    visiting.delete(id);
+    const r = { len: top.len + own, path: [...top.path, id] };
+    memo.set(id, r);
+    return r;
+  };
+  let winner = { len: 0, path: [] };
+  for (const t of scheduled) {
+    const r = best(t.id);
+    if (r.path.length > 1 && r.len > winner.len) winner = r;
+  }
+  return new Set(winner.path);
+}
+
+// ---- capacity ----------------------------------------------------------
+
+/** A task's hours on each working day of its span: estimate ÷ working
+ *  days, split evenly between its assignees. { day → hours } per person
+ *  is what workload() adds up. */
+export function hoursPerDay(task, ctx) {
+  const c = ctxOf(ctx);
+  const s = spanOf(task);
+  const est = Number(task?.estimate) || 0;
+  if (!s || est <= 0) return 0;
+  const opts = { weekend: c.weekend, holidays: c.holidays };
+  const days = daysBetween(s.start, s.end).filter((d) => isWorkingDay(d, opts)).length || 1;
+  return est / days / Math.max(1, (task.assignees ?? []).length);
+}
+
+/** Load against capacity per person over [from, to], by day or week:
+ *  { rows: [{ person, total, capacity, buckets: [{ key, start, end, hours,
+ *  capacity, over, tasks: [{ task, hours }] }] }], unassigned, unscheduled }.
+ *  `capacity` is the person's hours a day (default `defaultCapacity`, 8)
+ *  times the bucket's working days. Done tasks are left out unless
+ *  `includeDone`. */
+export function workload(tasks, ctx, { from, to, unit = "day", defaultCapacity = 8, includeDone = false } = {}) {
+  const c = ctxOf(ctx);
+  const opts = { weekend: c.weekend, holidays: c.holidays };
+  const start = dayOf(from) ?? c.today;
+  const end = dayOf(to) ?? addDays(start, 13);
+  const days = daysBetween(start, end);
+  const bucketOf = (d) => (unit === "week" ? startOfWeek(d, c.weekStartsOn) : d);
+  const bucketKeys = [...new Set(days.map(bucketOf))];
+  const list = normalizeTasks(tasks).filter((t) => includeDone || !isDone(t, c));
+  const rows = c.people.map((person) => {
+    const cap = Number(person.capacity ?? defaultCapacity);
+    const buckets = bucketKeys.map((key) => {
+      const inside = days.filter((d) => bucketOf(d) === key);
+      return { key, start: inside[0], end: inside[inside.length - 1], hours: 0, capacity: inside.filter((d) => isWorkingDay(d, opts)).length * cap, tasks: [] };
+    });
+    const byKey = new Map(buckets.map((b) => [b.key, b]));
+    for (const t of list) {
+      if (!t.assignees.includes(person.id)) continue;
+      const s = spanOf(t);
+      const per = hoursPerDay(t, c);
+      if (!s || per === 0) continue;
+      for (const d of daysBetween(s.start > start ? s.start : start, s.end < end ? s.end : end)) {
+        if (!isWorkingDay(d, opts)) continue;
+        const b = byKey.get(bucketOf(d));
+        if (!b) continue;
+        b.hours += per;
+        const hit = b.tasks.find((x) => x.task.id === t.id);
+        if (hit) hit.hours += per;
+        else b.tasks.push({ task: t, hours: per });
+      }
+    }
+    for (const b of buckets) {
+      b.hours = Math.round(b.hours * 100) / 100;
+      b.over = b.hours > b.capacity + 1e-9;
+    }
+    const total = buckets.reduce((s, b) => s + b.hours, 0);
+    return { person, total: Math.round(total * 100) / 100, capacity: buckets.reduce((s, b) => s + b.capacity, 0), buckets };
+  });
+  return {
+    rows,
+    buckets: bucketKeys,
+    unassigned: list.filter((t) => t.assignees.length === 0 && spanOf(t)),
+    unscheduled: list.filter((t) => !spanOf(t)),
+  };
+}
+
+/** The sum of a number field over tasks (estimate by default). */
+export function sumOf(tasks, key = "estimate") {
+  return (tasks ?? []).reduce((s, t) => s + (Number(t?.[key]) || 0), 0);
+}
+
+// ---- changes -----------------------------------------------------------
+//
+// A view never edits tasks. It builds a Change and hands it to
+// `onChange(change)` (async, answering { ok } — see useTaskChanges):
+//
+//   { type: "create", task }              or { type: "create", tasks: [...] }
+//   { type: "update", id, patch }         or { type: "update", ids: [...], patch }
+//   { type: "delete", id }                or { type: "delete", ids: [...] }
+//   { type: "batch", changes: [...] }     several at once (a renumber)
+
+/** The tasks after a change — what the screen shows before the save
+ *  answers. A create whose id exists is skipped (the page already has it). */
+export function applyChange(tasks, change) {
+  if (!change) return tasks;
+  switch (change.type) {
+    case "create": {
+      const add = (change.tasks ?? [change.task]).filter(Boolean).map(normalizeTask);
+      const ids = new Set(tasks.map((t) => String(t.id)));
+      const fresh = add.filter((t) => !ids.has(t.id));
+      return fresh.length ? [...tasks, ...fresh] : tasks;
+    }
+    case "update": {
+      const ids = new Set((change.ids ?? [change.id]).map(String));
+      return tasks.map((t) => (ids.has(String(t.id)) ? normalizeTask({ ...t, ...change.patch }) : t));
+    }
+    case "delete": {
+      const ids = new Set((change.ids ?? [change.id]).map(String));
+      return tasks.filter((t) => !ids.has(String(t.id)));
+    }
+    case "batch":
+      return (change.changes ?? []).reduce(applyChange, tasks);
+    default:
+      return tasks;
+  }
+}
+
+/** The change that undoes `change`, read against the tasks BEFORE it:
+ *  what an Undo in a toast commits. */
+export function invertChange(tasks, change) {
+  if (!change) return null;
+  switch (change.type) {
+    case "create":
+      return { type: "delete", ids: (change.tasks ?? [change.task]).filter(Boolean).map((t) => String(t.id)) };
+    case "update": {
+      const ids = new Set((change.ids ?? [change.id]).map(String));
+      const keys = Object.keys(change.patch ?? {});
+      const changes = tasks
+        .filter((t) => ids.has(String(t.id)))
+        .map((t) => ({ type: "update", id: t.id, patch: Object.fromEntries(keys.map((k) => [k, t[k] ?? null])) }));
+      return changes.length === 1 ? changes[0] : { type: "batch", changes };
+    }
+    case "delete": {
+      const ids = new Set((change.ids ?? [change.id]).map(String));
+      return { type: "create", tasks: tasks.filter((t) => ids.has(String(t.id))) };
+    }
+    case "batch": {
+      const inverses = [];
+      let state = tasks;
+      for (const c of change.changes ?? []) {
+        inverses.unshift(invertChange(state, c));
+        state = applyChange(state, c);
+      }
+      return { type: "batch", changes: inverses.filter(Boolean) };
+    }
+    default:
+      return null;
+  }
+}
+
+/** A change as plain writes, one per row, in order — the loop a page runs
+ *  over insertRow / updateRow / deleteRow:
+ *  [{ op: "insert", values } | { op: "update", id, patch } | { op: "delete", id }].
+ *  `columns` keeps only the keys your table has (a new task carries
+ *  empty lists — tags, dependsOn — your table may not); `keepNewIds:
+ *  false` drops a created task's client id (`new-…`) so the table makes
+ *  its own. */
+export function changeWrites(change, { columns, keepNewIds = true } = {}) {
+  if (!change) return [];
+  const pick = (obj) => (columns ? Object.fromEntries(Object.entries(obj ?? {}).filter(([k]) => columns.includes(k))) : obj);
+  switch (change.type) {
+    case "create":
+      return (change.tasks ?? [change.task]).filter(Boolean).map((t) => {
+        const { _sample, ...rest } = t;
+        const values = pick(rest);
+        if (!keepNewIds && isNewId(values.id)) delete values.id;
+        return { op: "insert", values };
+      });
+    case "update":
+      return (change.ids ?? [change.id]).map((id) => ({ op: "update", id, patch: pick(change.patch) }));
+    case "delete":
+      return (change.ids ?? [change.id]).map((id) => ({ op: "delete", id }));
+    case "batch":
+      return (change.changes ?? []).flatMap((c) => changeWrites(c, { columns, keepNewIds }));
+    default:
+      return [];
+  }
+}
+
+/** Whether an id is one newTaskId() made (not yet the database's). */
+export function isNewId(id) {
+  return typeof id === "string" && id.startsWith("new-");
+}
+
+/** The ids a change touches. */
+export function changedIds(change) {
+  return [...new Set(changeWrites(change).map((w) => String(w.id ?? w.values?.id)))];
+}
+
+/** A delete that takes the subtasks with it. */
+export function deleteChange(tasks, ids) {
+  const all = new Set();
+  for (const id of ids) {
+    all.add(String(id));
+    for (const d of descendantIds(tasks, id)) all.add(d);
+  }
+  return { type: "delete", ids: [...all] };
+}
+
+// ---- adapters for the existing blocks ----------------------------------
+
+/** Board props from tasks: `toBoard(tasks, { groupBy: "status", ctx })` →
+ *  { rows, groupBy, columns, otherLabel, moveChange(row, to, from) }.
+ *  One card per task, under its first value (a task with two assignees
+ *  sits under the first). Spread rows / groupBy / columns / otherLabel
+ *  onto <Board> and send `moveChange` through your onChange:
+ *  onMove={(row, to, from) => commit(board.moveChange(row, to, from))}. */
+export function toBoard(tasks, { groupBy = "status", ctx } = {}) {
+  const c = ctxOf(ctx);
+  const list = normalizeTasks(tasks);
+  const options = optionsOf(groupBy, c, list);
+  const none = options.find((o) => o.id === NONE);
+  const date = fieldOf(groupBy, c).kind === "date";
+  const columns = options.filter((o) => o.id !== NONE && !(date && (o.id === "past" || o.id === "overdue"))).map((o) => ({ key: o.id, label: o.label }));
+  const rows = list.map((t) => ({ ...t, __group: valuesOf(t, groupBy, c)[0] }));
+  return {
+    rows,
+    groupBy: "__group",
+    columns,
+    otherLabel: none?.label ?? "None",
+    moveChange(row, to, from) {
+      const task = list.find((t) => t.id === String(row.id)) ?? row;
+      const patch = movePatch(task, groupBy, from ?? NONE, to, c);
+      return patch ? { type: "update", id: task.id, patch } : null;
+    },
+  };
+}
+
+/** Flat rows for DataTable (or a CSV): the task plus its words —
+ *  statusLabel, statusIndex, assigneeNames, projectName, priorityLabel,
+ *  priorityRank, dueDay, dueBucket, parentTitle, subtasks ("2/5"), done.
+ *  DataTable sorts and searches these without knowing the model. */
+export function toTableRows(tasks, ctx) {
+  const c = ctxOf(ctx);
+  const list = normalizeTasks(tasks);
+  const byId = new Map(list.map((t) => [t.id, t]));
+  const counts = subtaskCounts(list, c);
+  return list.map((t) => {
+    const st = c.statusById.get(String(t.status));
+    const pr = PRIORITIES.findIndex((p) => p.id === t.priority);
+    const sub = counts.get(t.id);
+    return {
+      ...t,
+      statusLabel: st?.label ?? "",
+      statusIndex: st?.index ?? null,
+      assigneeNames: t.assignees.map((id) => c.personById.get(id)?.name ?? id).join(", "),
+      projectName: c.projectById.get(String(t.project))?.name ?? "",
+      priorityLabel: pr < 0 ? "" : PRIORITIES[pr].label,
+      priorityRank: pr < 0 ? null : pr,
+      dueDay: dayOf(t.due),
+      dueBucket: valuesOf(t, "due", c)[0],
+      parentTitle: t.parentId ? byId.get(t.parentId)?.title ?? "" : "",
+      subtasks: sub ? `${sub.done}/${sub.total}` : "",
+      done: isDone(t, c),
+    };
+  });
+}
+
+/** DataTable facets for toTableRows rows: status, assignee (first),
+ *  priority, project — each with the model's options and words. */
+export function taskFacets(ctx, { keys = ["status", "assignees", "priority", "project"] } = {}) {
+  const c = ctxOf(ctx);
+  const facet = {
+    status: { key: "status", label: "Status", options: c.statuses.map((s) => ({ value: s.id, label: s.label })) },
+    assignees: { key: "assignees", label: "Assignee", value: (r) => r.assignees?.[0] ?? "", options: [...c.people.map((p) => ({ value: p.id, label: p.name })), { value: "", label: "Unassigned" }] },
+    priority: { key: "priority", label: "Priority", options: [...PRIORITIES.map((p) => ({ value: p.id, label: p.label })), { value: "", label: "No priority" }] },
+    project: { key: "project", label: "Project", options: [...c.projects.map((p) => ({ value: p.id, label: p.name })), { value: "", label: "No project" }] },
+  };
+  return keys.map((k) => facet[k]).filter(Boolean);
+}