@anchrd/intel-ui 0.18.0 → 0.19.0

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

@@ -1,545 +0,0 @@
-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 `dropOutcome`
- * 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 };
-}