@anchrd/intel-ui 0.16.0 → 0.17.0

package/src/board/board-gantt/board-gantt.ts

@@ -0,0 +1,545 @@
+import type { BoardTask } from "@anchrd/intel-contract";
+import type { UpdateTask } from "@/board/board-data/board-data.types.ts";
+import {
+  addDays,
+  type BoardItem,
+  daysBetween,
+  dayValue,
+  rootedParents,
+} from "@/board/board-items/board-items.ts";
+
+/**
+ * Everything a Gantt of a board is, as arithmetic (anchrd/intel#293).
+ *
+ * ⚠️ The pixels are here and the DOM is next door. A timeline is one coordinate system — a day is an
+ * x, a row is a y, an arrow is a list of points between them — and keeping that in a component would
+ * make every one of the cases below only testable by rendering: a dependency that points backwards
+ * in time, a resize that would put the start after the due date, a drag that ended where it started.
+ * Those are the cases the picture is wrong about, and a picture is the one thing that cannot assert.
+ */
+
+// How wide a day is drawn, per scale. A board's dates are DAYS (contract), so pixels-per-day is the
+// whole of the zoom: every offset and every width below is a day count times this number.
+const DayWidth = { days: 34, weeks: 12, months: 4 } as const;
+
+export type GanttScale = keyof typeof DayWidth;
+export const GanttScales = ["days", "weeks", "months"] as const;
+
+export function dayWidth(scale: GanttScale): number {
+  return DayWidth[scale];
+}
+
+export interface GanttSpan {
+  startAt: Date;
+  endAt: Date;
+}
+
+/**
+ * A tick on the time axis, measured in DAYS rather than pixels.
+ *
+ * ⚠️ Deliberately not a column of fixed width. A month is 28 to 31 days wide and a week that starts
+ * mid-month is however many days are left of it, so a header built from equal columns drifts away
+ * from the bars underneath it — slowly, which is the kind of wrong nobody notices until a bar sits
+ * under the wrong month.
+ */
+export interface GanttTick {
+  key: string;
+  label: string;
+  days: number;
+}
+
+export interface GanttAxis {
+  // The first day drawn, always the first of a month so the header groups are whole.
+  start: Date;
+  days: number;
+  // The two header rows: the coarse one (months, or years at month scale) and the fine one.
+  groups: GanttTick[];
+  ticks: GanttTick[];
+  // Where today stands, as a day index, or `null` when the board is nowhere near it.
+  today: number | null;
+}
+
+function firstOfMonth(day: Date): Date {
+  return new Date(day.getFullYear(), day.getMonth(), 1);
+}
+
+/**
+ * The window the chart draws, from the work that is on it.
+ *
+ * ⚠️ A month of air on each side, and today is always inside it. A window cut exactly to the first
+ * and last bar leaves nowhere to drag a bar TO — the reader would have to make a task later before
+ * they could make it later — and a board whose work is all in the past would open with no clue that
+ * it is in the past.
+ */
+export function ganttAxis(
+  spans: GanttSpan[],
+  today: Date,
+  scale: GanttScale,
+  locale: string,
+): GanttAxis {
+  let min = today;
+  let max = today;
+  for (const span of spans) {
+    if (span.startAt < min) min = span.startAt;
+    if (span.endAt > max) max = span.endAt;
+  }
+  const first = firstOfMonth(min);
+  const last = firstOfMonth(max);
+  const start = new Date(first.getFullYear(), first.getMonth() - 1, 1);
+  const stop = new Date(last.getFullYear(), last.getMonth() + 2, 1);
+  const days = daysBetween(start, stop);
+  const todayIndex = daysBetween(start, today);
+  return {
+    start,
+    days,
+    groups: groupTicks(start, days, scale, locale),
+    ticks: fineTicks(start, days, scale, locale),
+    today: todayIndex >= 0 && todayIndex < days ? todayIndex : null,
+  };
+}
+
+// The coarse row: months over days and weeks, years over months.
+function groupTicks(start: Date, days: number, scale: GanttScale, locale: string): GanttTick[] {
+  const ticks: GanttTick[] = [];
+  if (scale === "months") {
+    const format = new Intl.DateTimeFormat(locale, { year: "numeric" });
+    for (let index = 0; index < days; ) {
+      const day = addDays(start, index);
+      const next = new Date(day.getFullYear() + 1, 0, 1);
+      const width = Math.min(daysBetween(day, next), days - index);
+      ticks.push({ key: `${day.getFullYear()}`, label: format.format(day), days: width });
+      index += width;
+    }
+    return ticks;
+  }
+  const format = new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" });
+  for (let index = 0; index < days; ) {
+    const day = addDays(start, index);
+    const next = new Date(day.getFullYear(), day.getMonth() + 1, 1);
+    const width = Math.min(daysBetween(day, next), days - index);
+    ticks.push({
+      key: `${day.getFullYear()}-${day.getMonth()}`,
+      label: format.format(day),
+      days: width,
+    });
+    index += width;
+  }
+  return ticks;
+}
+
+/**
+ * How many ticks may be drawn, whatever the dates say.
+ *
+ * ⚠️ The window comes from the board's own dates, and a `BoardTaskDate` is any ISO date — one task
+ * typed as `2226-08-07` (or written that way over MCP) makes a window of seventy thousand days. At
+ * day ticks that is seventy thousand header cells and as many grid lines, which is not a slow
+ * screen but a dead tab. The unit widens instead: the bars keep their exact day width, so the chart
+ * stays as precise as it was and only the ruler gets coarser.
+ */
+const MaxTicks = 1_200;
+
+function fineTicks(start: Date, days: number, scale: GanttScale, locale: string): GanttTick[] {
+  const unit: GanttScale =
+    days <= MaxTicks ? scale : days <= MaxTicks * 7 && scale !== "months" ? "weeks" : "months";
+  if (unit !== scale) return fineTicks(start, days, unit, locale);
+  if (scale === "days") {
+    const format = new Intl.DateTimeFormat(locale, { day: "numeric" });
+    return Array.from({ length: days }, (_, index) => {
+      const day = addDays(start, index);
+      return { key: `d${index}`, label: format.format(day), days: 1 };
+    });
+  }
+  if (scale === "months") {
+    const format = new Intl.DateTimeFormat(locale, { month: "short" });
+    const ticks: GanttTick[] = [];
+    for (let index = 0; index < days; ) {
+      const day = addDays(start, index);
+      const next = new Date(day.getFullYear(), day.getMonth() + 1, 1);
+      const width = Math.min(daysBetween(day, next), days - index);
+      ticks.push({ key: `m${index}`, label: format.format(day), days: width });
+      index += width;
+    }
+    return ticks;
+  }
+  const format = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short" });
+  const ticks: GanttTick[] = [];
+  for (let index = 0; index < days; index += 7) {
+    const day = addDays(start, index);
+    ticks.push({ key: `w${index}`, label: format.format(day), days: Math.min(7, days - index) });
+  }
+  return ticks;
+}
+
+/**
+ * A task with the tasks under it, and what the two of them span together.
+ *
+ * ⚠️ `span` is the subtree, `item` is the task's own dates. Keeping both is what lets an epic show a
+ * bar over its children without pretending those dates are its own — the derived one must not be
+ * dragged, because one bar cannot write five tasks.
+ */
+export interface GanttNode {
+  task: BoardTask;
+  item: BoardItem | null;
+  span: GanttSpan | null;
+  children: GanttNode[];
+}
+
+export interface GanttTree {
+  roots: GanttNode[];
+  /**
+   * The subtrees on which no date exists anywhere — the leftover column.
+   *
+   * ⚠️ Whole subtrees, not loose tasks. A dateless epic with two dateless children is three tasks
+   * the DoD says must not vanish, and listing only the epic would lose the other two just as
+   * quietly as dropping all three. A dateless task UNDER a dated one is not in here at all: it is a
+   * row in the chart with no bar, which is where it belongs.
+   */
+  undated: GanttNode[];
+}
+
+/** The board as the tree the chart draws, over the one dated reading of it (`board-items.ts`). */
+export function ganttTree(tasks: BoardTask[], items: Map<string, BoardItem>): GanttTree {
+  const parents = rootedParents(tasks);
+  const nodes = new Map<string, GanttNode>(
+    tasks.map((task) => [
+      task.id,
+      { task, item: items.get(task.id) ?? null, span: null, children: [] },
+    ]),
+  );
+  const roots: GanttNode[] = [];
+  for (const task of tasks) {
+    const node = nodes.get(task.id);
+    if (!node) continue;
+    const parent = parents.get(task.id) ?? null;
+    const target = parent === null ? undefined : nodes.get(parent);
+    if (target === undefined) roots.push(node);
+    else target.children.push(node);
+  }
+  for (const root of roots) fillSpan(root);
+  return {
+    roots: roots.filter((node) => node.span !== null),
+    undated: roots.filter((node) => node.span === null),
+  };
+}
+
+// Bottom-up, so a parent's span is its own dates and everything under it. Depth is capped at five
+// (#285), so the recursion is bounded, and `rootedParents` has already broken any cycle.
+function fillSpan(node: GanttNode): GanttSpan | null {
+  let span: GanttSpan | null =
+    node.item === null ? null : { startAt: node.item.startAt, endAt: node.item.endAt };
+  for (const child of node.children) {
+    const below = fillSpan(child);
+    if (below === null) continue;
+    span =
+      span === null
+        ? below
+        : {
+            startAt: below.startAt < span.startAt ? below.startAt : span.startAt,
+            endAt: below.endAt > span.endAt ? below.endAt : span.endAt,
+          };
+  }
+  node.span = span;
+  return span;
+}
+
+export interface GanttRow {
+  task: BoardTask;
+  depth: number;
+  item: BoardItem | null;
+  hasChildren: boolean;
+  collapsed: boolean;
+  /**
+   * The bar this row actually draws.
+   *
+   * ⚠️ `derived` is the load-bearing half. A derived bar is the subtree rolled into one — an epic
+   * over its children, or a collapsed parent standing in for everything beneath it — and dragging it
+   * would have to write every task it covers. One gesture, five writes, five versions and no way to
+   * say which of them the reader meant. It is drawn and never dragged; the tasks under it are.
+   */
+  bar: (GanttSpan & { derived: boolean }) | null;
+}
+
+/** The visible rows, in hierarchy order, with whatever is collapsed left out. */
+export function ganttRows(nodes: GanttNode[], collapsed: ReadonlySet<string>): GanttRow[] {
+  const rows: GanttRow[] = [];
+  const walk = (list: GanttNode[], depth: number) => {
+    for (const node of list) {
+      const hasChildren = node.children.length > 0;
+      const shut = hasChildren && collapsed.has(node.task.id);
+      rows.push({
+        task: node.task,
+        depth,
+        item: node.item,
+        hasChildren,
+        collapsed: shut,
+        bar: barOf(node, shut, hasChildren),
+      });
+      if (hasChildren && !shut) walk(node.children, depth + 1);
+    }
+  };
+  walk(nodes, 0);
+  return rows;
+}
+
+function barOf(
+  node: GanttNode,
+  shut: boolean,
+  hasChildren: boolean,
+): (GanttSpan & { derived: boolean }) | null {
+  // Its own dates, whenever they are the whole truth about this row. A parent that is shut is
+  // standing in for its children as well, so its own bar is not that.
+  if (node.item !== null && !shut) {
+    return { startAt: node.item.startAt, endAt: node.item.endAt, derived: false };
+  }
+  // Otherwise the subtree, which is what an epic spanning its children is — the DoD's first reading
+  // of "the outline is visible", with collapsing as the second. Both are here rather than one.
+  if (hasChildren && node.span !== null) {
+    return { startAt: node.span.startAt, endAt: node.span.endAt, derived: true };
+  }
+  return null;
+}
+
+/**
+ * One `dependsOn` as an arrow — the point of the ticket.
+ *
+ * ⚠️ `blocking` is `board.blockedBy` and nothing else (anchrd/intel#311), so an arrow means exactly
+ * what the "Blocked" chip on a card and the thick edge in the graph mean. A second reading of "still
+ * open" here would be the third one on the same screen, and the day they disagree is the day the
+ * picture stops being evidence.
+ */
+export interface GanttLink {
+  id: string;
+  fromId: string;
+  toId: string;
+  blocking: boolean;
+}
+
+export interface GanttLinks {
+  links: GanttLink[];
+  /**
+   * How many dependencies could not be drawn.
+   *
+   * ⚠️ Counted and said out loud, never dropped in silence. An arrow needs a bar at BOTH ends, and
+   * a dependency on a task with no date — or on one hidden inside a collapsed epic — has no second
+   * end to point at. Re-pointing it at the nearest visible ancestor would draw a relationship the
+   * board does not contain, which is worse than not drawing it; saying nothing would make a chart
+   * with three arrows look complete when the board has five.
+   */
+  hidden: number;
+}
+
+export function ganttLinks(
+  rows: GanttRow[],
+  blockedBy: (task: BoardTask) => BoardTask[],
+): GanttLinks {
+  const drawn = new Set(rows.filter((row) => row.bar !== null).map((row) => row.task.id));
+  const links: GanttLink[] = [];
+  let hidden = 0;
+  for (const row of rows) {
+    if (row.bar === null) {
+      // Its dependencies are not "hidden": this row has no bar of its own to point at either, so
+      // there was never an arrow to lose. Counting them would report a gap that does not exist.
+      continue;
+    }
+    const open = new Set(blockedBy(row.task).map((task) => task.id));
+    /**
+     * ⚠️ Once per pair, however often the list names it.
+     *
+     * Waiting twice for the same task is waiting for it once: two arrows on exactly the same path
+     * would draw nothing extra and hand React two children with one key.
+     *
+     * ⚠️ `dependsOn` carries a uniqueness rule since anchrd/intel#318 — the write path refuses a
+     * repeat and a stored one is folded away on read — so nothing arriving through Intel names a
+     * task twice any more. This stays for the same reason the graph view's copy of it does: a view
+     * takes whatever list it is handed, and it may not be the thing that turns odd data into a
+     * blank screen. Before that ticket the same duplicate made the graph THROW.
+     */
+    const seen = new Set<string>();
+    for (const fromId of row.task.dependsOn) {
+      if (seen.has(fromId)) continue;
+      seen.add(fromId);
+      if (!drawn.has(fromId)) {
+        hidden += 1;
+        continue;
+      }
+      links.push({
+        id: `${fromId}->${row.task.id}`,
+        fromId,
+        toId: row.task.id,
+        blocking: open.has(fromId),
+      });
+    }
+  }
+  return { links, hidden };
+}
+
+export interface GanttPoint {
+  x: number;
+  y: number;
+}
+
+/**
+ * The corners an arrow turns, from the end of what must finish to the start of what waits.
+ *
+ * ⚠️ Two shapes, because a dependency can point BACKWARDS in time — nothing stops a board from
+ * saying a task waits for something that ends after it starts, and that is precisely the state a
+ * reader needs to see. Drawn as the straight forward case it would be a line running right to left
+ * through both bars, which reads as a dependency in the other direction.
+ */
+export function linkPoints(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  gap: number,
+): GanttPoint[] {
+  if (to.x >= from.x + gap * 2) {
+    const turn = to.x - gap;
+    return [
+      { x: from.x, y: from.y },
+      { x: turn, y: from.y },
+      { x: turn, y: to.y },
+      { x: to.x, y: to.y },
+    ];
+  }
+  // Backwards: out to the right of the predecessor, along the seam between the two rows, back to
+  // the left of the dependent, and into it from the left — so the arrowhead still says "this waits
+  // for that" rather than the reverse.
+  const seam = (from.y + to.y) / 2;
+  return [
+    { x: from.x, y: from.y },
+    { x: from.x + gap, y: from.y },
+    { x: from.x + gap, y: seam },
+    { x: to.x - gap, y: seam },
+    { x: to.x - gap, y: to.y },
+    { x: to.x, y: to.y },
+  ];
+}
+
+export function pathOf(points: GanttPoint[]): string {
+  return points
+    .map(
+      (point, index) => `${index === 0 ? "M" : "L"}${Math.round(point.x)} ${Math.round(point.y)}`,
+    )
+    .join(" ");
+}
+
+// How tall a row is drawn. Here rather than in the component because the arrows are measured in it.
+export const GanttRowHeight = 34;
+
+// How far an arrow stands clear of a bar before it turns. Also the depth of the detour a backwards
+// dependency takes, so it cannot come out flush with the bar it points at.
+const LinkGap = 9;
+
+/** A span as the day index it starts on and the number of days it covers, ends included. */
+export function barDays(span: GanttSpan, start: Date): { from: number; days: number } {
+  return {
+    from: daysBetween(start, span.startAt),
+    // Ends included: a task that starts and is due on the same day is one day wide, not none.
+    days: daysBetween(span.startAt, span.endAt) + 1,
+  };
+}
+
+/**
+ * Every arrow, as the path it is drawn along.
+ *
+ * ⚠️ It leaves the END of what has to finish and arrives at the START of what waits — finish to
+ * start, which is the only reading `dependsOn` has (#285: a task waits for another task, not for a
+ * date). Anchoring either end anywhere else would draw a relationship the contract cannot express.
+ */
+export function linkGeometry(
+  links: GanttLink[],
+  rows: GanttRow[],
+  axisStart: Date,
+  width: number,
+  rowHeight: number,
+): { id: string; path: string; blocking: boolean }[] {
+  const placed = new Map<string, { index: number; bar: GanttSpan }>();
+  rows.forEach((row, index) => {
+    if (row.bar !== null) placed.set(row.task.id, { index, bar: row.bar });
+  });
+  const anchors = (id: string) => {
+    const found = placed.get(id);
+    if (found === undefined) return null;
+    const { from, days } = barDays(found.bar, axisStart);
+    return {
+      left: from * width,
+      right: (from + days) * width,
+      y: found.index * rowHeight + rowHeight / 2,
+    };
+  };
+  return links.flatMap((link) => {
+    const from = anchors(link.fromId);
+    const to = anchors(link.toId);
+    // `ganttLinks` has already counted anything that cannot be drawn; this is only the type saying
+    // the same thing again.
+    if (from === null || to === null) return [];
+    return [
+      {
+        id: link.id,
+        blocking: link.blocking,
+        path: pathOf(linkPoints({ x: from.right, y: from.y }, { x: to.left, y: to.y }, LinkGap)),
+      },
+    ];
+  });
+}
+
+export type GanttEdit = "move" | "start" | "end";
+
+/**
+ * What a finished drag is worth, as the one `board_task_update` it is — or as nothing.
+ *
+ * ⚠️ It answers `null` for a gesture that changed no date, and that is half of what it is for. A
+ * bar picked up and put back is the commonest drag there is; sent anyway it would mint a version,
+ * bump the board and stand in the audit as work that did not happen — the same rule `moveFromDrop`
+ * holds for a card dropped on its own place.
+ *
+ * ⚠️ A move shifts the dates the task HAS. A task with only a due date is drawn as the single day it
+ * is due on, and dragging that bar must not invent a start date for it: the reader moved a task, they
+ * did not say when it begins. Widening the bar from its left edge is how a task gets one, and that is
+ * a different gesture with a different handle.
+ *
+ * ⚠️ Neither edge may cross the other. The adapter already refuses to draw a backwards bar — a start
+ * after the due date is a board somebody typed wrong — so a resize that would produce one is pinned
+ * at the day it collides with instead. Writing it would store a span this chart cannot draw, which
+ * is the shape of a bug that survives a reload.
+ *
+ * ⚠️ "Changed" is measured against the edge that was DRAWN (`item`), never against the field that
+ * was stored (`task`), and the difference between those two is a real defect this once had. A task
+ * with no start date is drawn as the one day it is due on, so `item.startAt` is that day while
+ * `task.startDate` is `null`. Dragging the left grip to the RIGHT then pins at the due date, and
+ * comparing the pinned day against `null` says "changed" — for a gesture during which the bar does
+ * not move by a pixel, because the preview clamps at one day. The reader drags, watches nothing
+ * happen, lets go, and the task quietly acquires a start date. The rule that closes it is the one
+ * the preview already follows: a bar that ends where it was drawn is worth nothing.
+ */
+export function ganttWrite(
+  task: BoardTask,
+  item: BoardItem,
+  edit: GanttEdit,
+  deltaDays: number,
+): UpdateTask | null {
+  if (edit === "move") {
+    if (deltaDays === 0) return null;
+    const dueDate = dayValue(addDays(item.endAt, deltaDays));
+    // `startDate` travels only if there is one. `item.startAt` falls back to the due date, so
+    // sending it unconditionally would write a start date onto every task that never had one.
+    return task.startDate === null
+      ? { taskId: task.id, dueDate }
+      : { taskId: task.id, startDate: dayValue(addDays(item.startAt, deltaDays)), dueDate };
+  }
+  if (edit === "start") {
+    const moved = addDays(item.startAt, deltaDays);
+    const startDate = dayValue(moved > item.endAt ? item.endAt : moved);
+    return startDate === dayValue(item.startAt) ? null : { taskId: task.id, startDate };
+  }
+  const moved = addDays(item.endAt, deltaDays);
+  // ⚠️ Pinned at the bar's own left edge, which for a task with no start date is the due date
+  // itself — so the shortest a bar can be dragged is the one day it already is, and the gesture
+  // answers `null` instead of moving a task that was not picked up. The clamp has to be the one the
+  // reader SAW: a preview that stopped at one day and a write that carried on past it would store a
+  // date nobody dragged to.
+  const dueDate = dayValue(moved < item.startAt ? item.startAt : moved);
+  // Against the drawn edge, as above. `item.endAt` IS `task.dueDate` for everything that reaches a
+  // bar, so this changes no answer — it states the rule once instead of twice, which is what kept
+  // the other branch wrong.
+  return dueDate === dayValue(item.endAt) ? null : { taskId: task.id, dueDate };
+}