construction-gantt 0.1.0

package/src/types.ts

@@ -0,0 +1,254 @@
+// Core data model for construction-gantt.
+//
+// Designed to overlap with MS Project's data shape where it matters for
+// MSPDI XML round-trip (ADR-003): all 8 constraint types, manual/auto
+// scheduling per task, multi-baseline (0-10), working-time calendars with
+// partial-day shifts.
+//
+// These types are public API and SVAR-agnostic per ADR-002. The wrapper
+// converts them to SVAR's ITask before handing to the renderer.
+
+export type TaskId = string | number;
+export type LinkId = string | number;
+export type ResourceId = string | number;
+export type CalendarId = string | number;
+export type AssignmentId = string | number;
+
+// ---------------------------------------------------------------------------
+// Tasks
+// ---------------------------------------------------------------------------
+
+export type TaskType = 'task' | 'summary' | 'milestone';
+
+export type ScheduleMode = 'auto' | 'manual';
+
+/**
+ * MS Project's 8 constraint types.
+ *
+ * - ASAP / ALAP: scheduling preferences, no date required.
+ * - MSO / MFO:   hard constraints, pin the date; override predecessor logic.
+ * - SNET / SNLT / FNET / FNLT: soft date bounds.
+ *
+ * Hard constraints can produce negative slack — the contract-trouble
+ * signal we surface rather than silently clip to zero (ADR-003).
+ */
+export type ConstraintType = 'ASAP' | 'ALAP' | 'MSO' | 'MFO' | 'SNET' | 'SNLT' | 'FNET' | 'FNLT';
+
+export interface Constraint {
+  type: ConstraintType;
+  /** Required for all types except ASAP and ALAP. */
+  date?: Date;
+}
+
+export interface Task {
+  id: TaskId;
+  text: string;
+  /** Hierarchy parent. Undefined = top-level. */
+  parent?: TaskId;
+  type: TaskType;
+  scheduleMode: ScheduleMode;
+
+  /**
+   * For summary tasks: are children currently expanded?
+   * Default true (expanded). Toggled by the user via the renderer's
+   * collapse/expand chevron.
+   */
+  open?: boolean;
+
+  /** Working-time duration in minutes. For milestones this is 0. */
+  duration: number;
+
+  /**
+   * User-set start / end. For manual-scheduled tasks these are authoritative.
+   * For auto-scheduled tasks the engine recomputes them and writes the
+   * result back. Either way, the engine populates `computed` with the
+   * full forward/backward-pass data.
+   */
+  start: Date;
+  end: Date;
+
+  /** Percent complete, 0-100. */
+  progress: number;
+
+  constraint?: Constraint;
+
+  /** Resource assignments. Order is not meaningful. */
+  resourceIds?: ResourceId[];
+
+  /**
+   * Calendar override. If unset, the task uses the project default calendar.
+   * If a resource on the task has a calendar, the engine reconciles them
+   * (resource calendar wins for activities depending on that resource).
+   */
+  calendarId?: CalendarId;
+
+  /** Populated by the scheduling engine. Read-only for user code. */
+  computed?: TaskComputed;
+}
+
+/**
+ * Forward/backward-pass output. Filled in by `schedule()`.
+ *
+ * `totalSlack` is the contract-trouble signal: when negative, the task is
+ * already late against a downstream constraint and the schedule is
+ * infeasible without intervention. We display this; we don't clip it.
+ */
+export interface TaskComputed {
+  earlyStart: Date;
+  earlyFinish: Date;
+  lateStart: Date;
+  lateFinish: Date;
+  /** Working-minutes of total float. Can be negative. */
+  totalSlack: number;
+  /** Working-minutes of free float (slack against the earliest successor). */
+  freeSlack: number;
+  isCritical: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Links
+// ---------------------------------------------------------------------------
+
+/**
+ * Dependency type, matching MS Project notation:
+ * - FS = Finish-to-Start (most common in construction)
+ * - SS = Start-to-Start (concurrent activities sharing a start trigger)
+ * - FF = Finish-to-Finish (concurrent activities sharing a finish gate)
+ * - SF = Start-to-Finish (rare; reverse-direction)
+ */
+export type DependencyType = 'FS' | 'SS' | 'FF' | 'SF';
+
+export interface Link {
+  id: LinkId;
+  source: TaskId;
+  target: TaskId;
+  type: DependencyType;
+  /**
+   * Lag in working-minutes. Positive = delay, negative = lead.
+   * Construction example: 3-day cure time on a FS link = lag of 3 working days
+   * converted to minutes via the calendar.
+   */
+  lag: number;
+}
+
+// ---------------------------------------------------------------------------
+// Calendars (working-time)
+// ---------------------------------------------------------------------------
+
+/** Minutes-from-midnight working interval. e.g. 8am-5pm = {480, 1020}. */
+export interface WorkInterval {
+  startMinutes: number;
+  endMinutes: number;
+}
+
+export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6; // Sun=0 … Sat=6
+
+/**
+ * A calendar describes when work happens.
+ *
+ * - `workWeek` is the recurring base: 7 entries, each an array of intervals.
+ *   Empty array = non-working day. Multiple intervals = split shift
+ *   (e.g. 7-12 + 13-15 for concreting with a lunch break).
+ * - `exceptions` override specific dates: holidays, weather days, site
+ *   shutdown periods, or "this Saturday is a working day."
+ * - `baseCalendarId` lets resource/task calendars inherit from a base
+ *   and override only the differences.
+ */
+export interface Calendar {
+  id: CalendarId;
+  name: string;
+  workWeek: WorkInterval[][];
+  exceptions: CalendarException[];
+  baseCalendarId?: CalendarId;
+}
+
+export interface CalendarException {
+  date: Date;
+  /** false = non-working day (holiday). true = working with given intervals. */
+  isWorking: boolean;
+  intervals?: WorkInterval[];
+  /** Display name. NZ Anzac Day, Auckland Anniversary, weather day, etc. */
+  name?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+
+export interface Resource {
+  id: ResourceId;
+  name: string;
+  /** Optional per-resource calendar override (plasterer's 4-day week, etc.). */
+  calendarId?: CalendarId;
+}
+
+// ---------------------------------------------------------------------------
+// Assignments
+// ---------------------------------------------------------------------------
+
+/**
+ * Allocates a Resource to a Task. v0.2 first cut carries only the core
+ * triple (taskId + resourceId + units) — enough to round-trip MSPDI
+ * <Assignment> elements without losing the allocation graph.
+ *
+ * Per-day timephased work data + cost tracking + EV fields are MSPDI-side
+ * concerns that we don't yet model internally; they appear in
+ * `droppedFields` on parse rather than entering our model.
+ *
+ * The eventual v0.4 editing-model expansion will likely add `actualWork`,
+ * `plannedWork`, and `progress` fields here, plus a separate
+ * `TimephasedSpread` type for per-day allocations.
+ */
+export interface Assignment {
+  id: AssignmentId;
+  taskId: TaskId;
+  resourceId: ResourceId;
+  /**
+   * Allocation share. 1.0 = 100% (fully assigned). 0.5 = part-time. >1.0
+   * is over-allocated (MS Project allows this — the renderer surfaces it
+   * with the OverAllocated flag). Default 1.0 if omitted.
+   */
+  units?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Baselines
+// ---------------------------------------------------------------------------
+
+/** MS Project supports 11 baselines (Baseline 0-10). We match. */
+export type BaselineIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+
+export interface Baseline {
+  index: BaselineIndex;
+  /** Display name. "Original contract programme", "Variation 1 reprogramme", etc. */
+  name?: string;
+  capturedAt: Date;
+  /** Snapshot of task dates + durations at capture time. */
+  tasks: Map<TaskId, BaselineTaskSnapshot>;
+}
+
+export interface BaselineTaskSnapshot {
+  start: Date;
+  end: Date;
+  duration: number;
+}
+
+// ---------------------------------------------------------------------------
+// Project
+// ---------------------------------------------------------------------------
+
+export interface Project {
+  /** Project start anchor. Forward pass starts here. */
+  start: Date;
+  /** Optional finish anchor. If set, backward pass terminates here instead of latest task EarlyFinish. */
+  end?: Date;
+  defaultCalendarId: CalendarId;
+  tasks: Task[];
+  links: Link[];
+  resources: Resource[];
+  calendars: Calendar[];
+  /** Up to 11 entries (Baseline 0-10). */
+  baselines: Baseline[];
+  /** Resource-to-task allocations. Empty array if no resources are allocated. */
+  assignments: Assignment[];
+}

package/src/visibility.ts

@@ -0,0 +1,35 @@
+// Render-only visibility filter for <Gantt> tasks.
+//
+// Per ADR-005 (engine-first; no BYO-CPM mode), consumer domain rules around
+// hiding tasks must surface as render-time props, never as engine bypasses.
+// This is the canonical example: the engine always runs on the full task
+// set; the visibility filter applies only to the rendered output.
+//
+// Direct lift from the CM domain rule (FrappeGanttView.tsx:366-371 in
+// Bode-Builds): "Hiding a predecessor would otherwise make a dependent
+// task's early-start collapse to 0, which is wrong." We honour the rule
+// by structure — the filter sits AFTER schedule() in the pipeline, so
+// computed fields on the visible tasks reflect the full schedule.
+
+import type { Task, TaskId } from './types.js';
+
+/**
+ * Return the subset of `tasks` whose ids appear in `visibleTaskIds`.
+ *
+ * - `undefined` → no filter; the original array reference is returned
+ *   so React's `useMemo` identity stays stable on the noop path.
+ * - empty set → returns an empty array (hide everything).
+ * - set containing ids not present in `tasks` → unknown ids ignored;
+ *   only matching tasks survive.
+ *
+ * Crucially: this is a pure projection. `task.computed` is preserved
+ * exactly — no recomputation, no clipping, no slack adjustment. The
+ * engine already ran on the full set; we trust its result.
+ */
+export function filterTasksByVisibility(
+  tasks: Task[],
+  visibleTaskIds: ReadonlySet<TaskId> | undefined,
+): Task[] {
+  if (visibleTaskIds === undefined) return tasks;
+  return tasks.filter((t) => visibleTaskIds.has(t.id));
+}

package/src/working-time.ts

@@ -0,0 +1,235 @@
+import type { Calendar, CalendarException, WorkInterval } from './types';
+
+export function isWorkingDay(date: Date, calendar: Calendar): boolean {
+  return getIntervalsForDay(date, calendar).length > 0;
+}
+
+export function getDayWorkingMinutes(date: Date, calendar: Calendar): number {
+  return getIntervalsForDay(date, calendar).reduce(
+    (sum, iv) => sum + (iv.endMinutes - iv.startMinutes),
+    0,
+  );
+}
+
+/**
+ * Add `minutes` of working time to `start`, skipping non-working time
+ * (weekends, holidays, partial-day shift gaps). The result is the wall-clock
+ * Date exactly `minutes` working-time-minutes after `start`.
+ *
+ * If `start` falls in a non-working moment (weekend, after-hours, lunch
+ * break), the working-time clock begins from the next working interval.
+ *
+ * Note: not DST-aware. Working hours are wall-clock; cross-DST scheduling
+ * is approximate. Real DST handling is a future enhancement.
+ */
+export function addWorkingMinutes(start: Date, minutes: number, calendar: Calendar): Date {
+  if (minutes <= 0) return new Date(start);
+
+  let current = new Date(start);
+  let remaining = minutes;
+
+  while (remaining > 0) {
+    const interval = findNextWorkingInterval(current, calendar);
+    if (!interval) {
+      throw new Error('Calendar has no working time within ~1 year after the given date');
+    }
+
+    if (current < interval.start) current = new Date(interval.start);
+
+    const availableMinutes = (interval.end.getTime() - current.getTime()) / 60_000;
+
+    if (remaining <= availableMinutes) {
+      return new Date(current.getTime() + remaining * 60_000);
+    }
+
+    remaining -= availableMinutes;
+    current = new Date(interval.end);
+  }
+
+  return current;
+}
+
+/**
+ * Subtract `minutes` of working time from `end`, walking backward through
+ * working intervals. Backward-pass mirror of {@link addWorkingMinutes}.
+ *
+ * If `end` falls in a non-working moment, the clock begins from the end of
+ * the most recent working interval.
+ */
+export function subtractWorkingMinutes(end: Date, minutes: number, calendar: Calendar): Date {
+  if (minutes <= 0) return new Date(end);
+
+  let current = new Date(end);
+  let remaining = minutes;
+
+  while (remaining > 0) {
+    const interval = findPreviousWorkingInterval(current, calendar);
+    if (!interval) {
+      throw new Error('Calendar has no working time within ~1 year before the given date');
+    }
+
+    if (current > interval.end) current = new Date(interval.end);
+
+    const availableMinutes = (current.getTime() - interval.start.getTime()) / 60_000;
+
+    if (remaining <= availableMinutes) {
+      return new Date(current.getTime() - remaining * 60_000);
+    }
+
+    remaining -= availableMinutes;
+    current = new Date(interval.start);
+  }
+
+  return current;
+}
+
+/**
+ * Return the next working moment at or after `date`. If `date` already falls
+ * inside a working interval, returns it unchanged. If it falls in non-working
+ * time (weekend, after-hours, lunch break, holiday), returns the start of the
+ * next working interval.
+ */
+export function snapToNextWorkingMoment(date: Date, calendar: Calendar): Date {
+  const interval = findNextWorkingInterval(date, calendar);
+  if (!interval) {
+    throw new Error('Calendar has no working time within ~1 year after the given date');
+  }
+  return date < interval.start ? new Date(interval.start) : new Date(date);
+}
+
+/**
+ * Return the previous working moment at or before `date`. Mirror of
+ * {@link snapToNextWorkingMoment} for backward-pass scheduling.
+ */
+export function snapToPreviousWorkingMoment(date: Date, calendar: Calendar): Date {
+  const interval = findPreviousWorkingInterval(date, calendar);
+  if (!interval) {
+    throw new Error('Calendar has no working time within ~1 year before the given date');
+  }
+  return date > interval.end ? new Date(interval.end) : new Date(date);
+}
+
+/**
+ * Working-minute distance from `a` to `b`. Positive if `a` is earlier than
+ * `b`, negative if `a` is later. Used to compute slack (lateStart - earlyStart
+ * in working time).
+ */
+export function workingMinutesBetween(a: Date, b: Date, calendar: Calendar): number {
+  if (a.getTime() === b.getTime()) return 0;
+  const reverse = a > b;
+  const start = reverse ? b : a;
+  const end = reverse ? a : b;
+
+  let current = new Date(start);
+  let total = 0;
+  while (current < end) {
+    const interval = findNextWorkingInterval(current, calendar);
+    if (!interval) break;
+    if (current < interval.start) current = new Date(interval.start);
+    if (current >= end) break;
+
+    if (interval.end >= end) {
+      total += (end.getTime() - current.getTime()) / 60_000;
+      break;
+    }
+    total += (interval.end.getTime() - current.getTime()) / 60_000;
+    current = new Date(interval.end);
+  }
+
+  return reverse ? -total : total;
+}
+
+interface DatedInterval {
+  start: Date;
+  end: Date;
+}
+
+/**
+ * Find the earliest working interval whose end is strictly after `date`.
+ * Walks forward up to ~1 year before giving up.
+ */
+function findNextWorkingInterval(date: Date, calendar: Calendar): DatedInterval | null {
+  const msPerDay = 24 * 60 * 60 * 1000;
+  let day = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+
+  for (let i = 0; i < 366; i++) {
+    const intervals = getIntervalsForDay(day, calendar);
+    for (const iv of intervals) {
+      const intervalStart = new Date(
+        day.getFullYear(),
+        day.getMonth(),
+        day.getDate(),
+        0,
+        iv.startMinutes,
+      );
+      const intervalEnd = new Date(
+        day.getFullYear(),
+        day.getMonth(),
+        day.getDate(),
+        0,
+        iv.endMinutes,
+      );
+      if (intervalEnd > date) {
+        return { start: intervalStart, end: intervalEnd };
+      }
+    }
+    day = new Date(day.getTime() + msPerDay);
+  }
+  return null;
+}
+
+/**
+ * Find the latest working interval whose start is strictly before `date`.
+ * Walks backward up to ~1 year before giving up.
+ */
+function findPreviousWorkingInterval(date: Date, calendar: Calendar): DatedInterval | null {
+  const msPerDay = 24 * 60 * 60 * 1000;
+  let day = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+
+  for (let i = 0; i < 366; i++) {
+    const intervals = getIntervalsForDay(day, calendar);
+    for (let j = intervals.length - 1; j >= 0; j--) {
+      const iv = intervals[j];
+      if (!iv) continue;
+      const intervalStart = new Date(
+        day.getFullYear(),
+        day.getMonth(),
+        day.getDate(),
+        0,
+        iv.startMinutes,
+      );
+      const intervalEnd = new Date(
+        day.getFullYear(),
+        day.getMonth(),
+        day.getDate(),
+        0,
+        iv.endMinutes,
+      );
+      if (intervalStart < date) {
+        return { start: intervalStart, end: intervalEnd };
+      }
+    }
+    day = new Date(day.getTime() - msPerDay);
+  }
+  return null;
+}
+
+function getIntervalsForDay(date: Date, calendar: Calendar): WorkInterval[] {
+  const exception = findException(date, calendar);
+  if (exception) {
+    return exception.isWorking ? (exception.intervals ?? []) : [];
+  }
+  return calendar.workWeek[date.getDay()] ?? [];
+}
+
+function findException(date: Date, calendar: Calendar): CalendarException | undefined {
+  return calendar.exceptions.find((ex) => isSameCalendarDay(ex.date, date));
+}
+
+function isSameCalendarDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}