makersclaw 0.1.0 → 0.3.0

package/registry/blocks/calendar-view/calendar-model.js

@@ -0,0 +1,442 @@
+// The calendar's arithmetic — pure, no React. Where a task sits on a
+// calendar (a timed block on one day, or an all-day span), how
+// overlapping blocks share a column, how spans stack into lanes, the
+// patches a move or a resize saves, the window each mode shows, and the
+// available-time layer (working hours, open slots) booking-page builds
+// on. Dates are task-model's wall-calendar strings; minutes are minutes
+// after midnight.
+
+import {
+  addDays,
+  addMonths,
+  dayNumber,
+  dayOf,
+  diffDays,
+  formatDate,
+  formatTime,
+  minutesOf,
+  monthGrid,
+  shiftDates,
+  spanOf,
+  startOfWeek,
+  weekdayOf,
+  withTime,
+} from "../task-model";
+
+export const DAY_MINUTES = 1440;
+export const CALENDAR_MODES = ["month", "week", "day", "agenda"];
+export const MODE_LABELS = { month: "Month", week: "Week", day: "Day", agenda: "Agenda" };
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+
+/** Rounds minutes to the nearest `step` (default 15). */
+export function snapMinutes(minutes, step = 15) {
+  return Math.round(minutes / step) * step;
+}
+
+/** How long a timed block runs when the task says only when it starts:
+ *  its estimate (hours), else `fallback` minutes. */
+export function durationOf(task, fallback = 60) {
+  const est = Number(task?.estimate);
+  return est > 0 ? clamp(Math.round(est * 60), 15, 8 * 60) : fallback;
+}
+
+/**
+ * Where a task sits on a calendar, or null when it has no date.
+ *   { id, task, timed, start, end, from, to, deadline, startOnly }
+ * `start` / `end` are days (inclusive). A timed item lives on one day
+ * (`start === end`) from `from` to `to` minutes: a start and a due time
+ * on the same day; a start time alone (runs its estimate, else an hour);
+ * or a due time alone (a `deadline`: a half-hour block at the due time).
+ * Anything else — plain days, or a span over several days — is all-day.
+ */
+export function eventOf(task, { defaultMinutes = 60 } = {}) {
+  const span = spanOf(task);
+  if (!span) return null;
+  const base = { id: String(task.id), task, start: span.start, end: span.end, timed: false, from: null, to: null, deadline: false, startOnly: false };
+  if (span.start !== span.end) return base;
+  const sDay = dayOf(task.start);
+  const dDay = dayOf(task.due);
+  const sm = sDay ? minutesOf(task.start) : null;
+  const dm = dDay ? minutesOf(task.due) : null;
+  if (sm === null && dm === null) return base;
+  let from;
+  let to;
+  let deadline = false;
+  let startOnly = false;
+  if (sm !== null && dm !== null && dm > sm) [from, to] = [sm, dm];
+  else if (sm !== null) {
+    from = sm;
+    to = sm + durationOf(task, defaultMinutes);
+    startOnly = !dDay;
+  } else {
+    from = dm;
+    to = dm + 30;
+    deadline = true;
+  }
+  from = clamp(from, 0, DAY_MINUTES - 15);
+  to = clamp(to, from + 15, DAY_MINUTES);
+  return { ...base, timed: true, from, to, deadline, startOnly };
+}
+
+/** Every dated task as an event (in the order given). */
+export function eventsOf(tasks, options) {
+  const out = [];
+  for (const t of tasks ?? []) {
+    const e = eventOf(t, options);
+    if (e) out.push(e);
+  }
+  return out;
+}
+
+/** Tasks with neither a start nor a due date: the unscheduled tray. */
+export function unscheduledOf(tasks) {
+  return (tasks ?? []).filter((t) => !spanOf(t));
+}
+
+/**
+ * Side-by-side columns for the timed events of one day, the way Google
+ * Calendar lays a busy morning: events that overlap (directly or through
+ * a chain) share a cluster; each takes the first column free at its
+ * start; a block widens over the columns to its right that stay free for
+ * its whole run. Returns Map id → { col, cols, span }. `minMinutes` is
+ * the shortest block drawn (short ones still need room for a title).
+ */
+export function layoutTimed(events, { minMinutes = 20 } = {}) {
+  const list = [...events]
+    .filter((e) => e.timed)
+    .map((e) => ({ e, a: e.from, b: Math.max(e.to, e.from + minMinutes) }))
+    .sort((x, y) => x.a - y.a || y.b - x.b || String(x.e.task.title).localeCompare(String(y.e.task.title)));
+  const out = new Map();
+  let cluster = [];
+  let clusterEnd = -1;
+  const flush = () => {
+    if (!cluster.length) return;
+    const cols = Math.max(...cluster.map((c) => c.col)) + 1;
+    for (const c of cluster) {
+      let span = 1;
+      for (let k = c.col + 1; k < cols; k++) {
+        if (cluster.some((o) => o.col === k && o.a < c.b && c.a < o.b)) break;
+        span++;
+      }
+      out.set(c.e.id, { col: c.col, cols, span });
+    }
+    cluster = [];
+    clusterEnd = -1;
+  };
+  let ends = [];
+  for (const item of list) {
+    if (item.a >= clusterEnd) {
+      flush();
+      ends = [];
+    }
+    let col = ends.findIndex((end) => end <= item.a);
+    if (col < 0) col = ends.length;
+    ends[col] = item.b;
+    cluster.push({ ...item, col });
+    clusterEnd = Math.max(clusterEnd, item.b);
+  }
+  flush();
+  return out;
+}
+
+/**
+ * Spans stacked into lanes across a row of days (a month week, a week's
+ * all-day strip): longest first among those starting together, each in
+ * the first lane free for its days. Returns { items: [{ event, lane, col,
+ * span, clippedStart, clippedEnd }], lanes } — `col` / `span` in days
+ * from the row's first; `clipped*` when it runs past the row's ends.
+ */
+export function layoutLanes(events, days) {
+  const n = days.length;
+  if (!n) return { items: [], lanes: 0 };
+  const first = days[0];
+  const last = days[n - 1];
+  const list = events
+    .filter((e) => e.start <= last && e.end >= first)
+    .map((e) => {
+      const a = Math.max(0, diffDays(first, e.start));
+      const b = Math.min(n - 1, diffDays(first, e.end));
+      return { event: e, col: a, span: b - a + 1, clippedStart: e.start < first, clippedEnd: e.end > last };
+    })
+    .sort(
+      (x, y) =>
+        x.col - y.col ||
+        y.span - x.span ||
+        Number(x.event.timed) - Number(y.event.timed) ||
+        (x.event.from ?? -1) - (y.event.from ?? -1) ||
+        String(x.event.task.title).localeCompare(String(y.event.task.title)),
+    );
+  const lanes = [];
+  const items = [];
+  for (const it of list) {
+    let lane = lanes.findIndex((cells) => !cells.some((c) => c >= it.col && c < it.col + it.span));
+    if (lane < 0) {
+      lane = lanes.length;
+      lanes.push([]);
+    }
+    for (let k = it.col; k < it.col + it.span; k++) lanes[lane].push(k);
+    items.push({ ...it, lane });
+  }
+  return { items, lanes: lanes.length };
+}
+
+// ---- the patches a gesture saves -----------------------------------------
+
+/** A timed event moved to `day` at `from` minutes, keeping its length. */
+export function moveEventPatch(event, day, from) {
+  const len = event.to - event.from;
+  const a = clamp(snapMinutes(from, 1), 0, DAY_MINUTES - len);
+  if (event.deadline) return { due: withTime(day, a) };
+  if (event.startOnly) return { start: withTime(day, a) };
+  return { start: withTime(day, a), due: withTime(day, a + len) };
+}
+
+/** A timed event's end dragged to `to` minutes (at least 15 after it
+ *  starts). A deadline or a start-only task becomes a start–due block. */
+export function resizeEventPatch(event, to) {
+  const b = clamp(to, event.from + 15, DAY_MINUTES);
+  if (event.deadline || event.startOnly) return { start: withTime(event.start, event.from), due: withTime(event.start, b) };
+  return { due: withTime(event.start, b) };
+}
+
+/** A timed event given a new day and a new [from, to] (a keyboard nudge
+ *  that may move and resize at once). */
+export function placeEventPatch(event, day, from, to) {
+  if (to - from === event.to - event.from) return moveEventPatch(event, day, from);
+  const a = clamp(from, 0, DAY_MINUTES - 15);
+  const b = clamp(to, a + 15, DAY_MINUTES);
+  return { start: withTime(day, a), due: withTime(day, b) };
+}
+
+/** A task put on the time grid (from all-day, from the tray): a block
+ *  of `minutes` from `from`. */
+export function timedPatch(day, from, minutes = 60) {
+  const a = clamp(from, 0, DAY_MINUTES - 15);
+  return { start: withTime(day, a), due: withTime(day, Math.min(DAY_MINUTES, a + minutes)) };
+}
+
+/** A task dropped on a day (a month cell, the all-day strip). An all-day
+ *  span moves whole (by the days between where it was grabbed and where
+ *  it landed); a timed one keeps its times on the new day; an
+ *  unscheduled one gets that day as its due date. */
+export function dayPatch(task, day, { grabbed } = {}) {
+  const e = eventOf(task);
+  if (!e) return { due: day };
+  const shift = diffDays(grabbed ?? e.start, day);
+  return shift ? shiftDates(task, shift) : null;
+}
+
+/** A timed task made all-day on `day` (dropped on the all-day strip). */
+export function allDayPatch(day) {
+  return { start: null, due: day };
+}
+
+/** An all-day span's last day dragged to `end` (never before it starts). */
+export function extendPatch(event, end) {
+  const e = end < event.start ? event.start : end;
+  const task = event.task;
+  if (e === event.start && !dayOf(task.start)) return { due: withTime(e, minutesOf(task.due)) };
+  return { start: withTime(event.start, minutesOf(task.start)), due: withTime(e, minutesOf(task.due)) };
+}
+
+/** Takes a task off the calendar (dropped on the unscheduled tray). */
+export const UNSCHEDULE = Object.freeze({ start: null, due: null });
+
+// ---- what each mode shows ------------------------------------------------
+
+/**
+ * The days a mode shows around `anchor`: { from, to, days, weeks? }.
+ *   month   the weeks that hold the anchor's month (4–6 rows)
+ *   week    the anchor's week, or `count` days from the anchor (a phone's
+ *           three-day week)
+ *   day     the anchor
+ *   agenda  `agendaDays` days from the anchor
+ */
+export function rangeFor(mode, anchor, { weekStartsOn = 1, count = 7, agendaDays = 14 } = {}) {
+  const a = dayOf(anchor);
+  if (mode === "month") {
+    const weeks = monthGrid(a, { weekStartsOn });
+    return { from: weeks[0][0], to: weeks[weeks.length - 1][6], days: weeks.flat(), weeks };
+  }
+  if (mode === "week") {
+    const from = count >= 7 ? startOfWeek(a, weekStartsOn) : a;
+    const days = Array.from({ length: count >= 7 ? 7 : count }, (_, i) => addDays(from, i));
+    return { from: days[0], to: days[days.length - 1], days };
+  }
+  if (mode === "agenda") {
+    const days = Array.from({ length: agendaDays }, (_, i) => addDays(a, i));
+    return { from: days[0], to: days[days.length - 1], days };
+  }
+  return { from: a, to: a, days: [a] };
+}
+
+/** The anchor one step back (dir −1) or on (+1) in a mode. */
+export function stepAnchor(mode, anchor, dir, { count = 7, agendaDays = 14 } = {}) {
+  if (mode === "month") return addMonths(anchor, dir);
+  if (mode === "week") return addDays(anchor, dir * (count >= 7 ? 7 : count));
+  if (mode === "agenda") return addDays(anchor, dir * agendaDays);
+  return addDays(anchor, dir);
+}
+
+/** A range in words: "Sep 21 – 27, 2026", "Sep 28 – Oct 4, 2026",
+ *  "Dec 29, 2026 – Jan 4, 2027". */
+export function rangeLabel(from, to, { locale } = {}) {
+  if (from === to) return formatDate(from, { month: "short", day: "numeric", year: "numeric" }, { locale });
+  const sameYear = from.slice(0, 4) === to.slice(0, 4);
+  const sameMonth = sameYear && from.slice(5, 7) === to.slice(5, 7);
+  const a = formatDate(from, sameYear ? { month: "short", day: "numeric" } : { month: "short", day: "numeric", year: "numeric" }, { locale });
+  const b = formatDate(to, sameMonth ? { day: "numeric" } : { month: "short", day: "numeric" }, { locale });
+  return `${a} – ${b}, ${to.slice(0, 4)}`;
+}
+
+/** The heading a mode shows: "September 2026", a week's range, "Wednesday,
+ *  September 23" (with the year when it is not `today`'s). */
+export function titleFor(mode, range, anchor, { today, locale } = {}) {
+  if (mode === "month") return formatDate(anchor, { month: "long", year: "numeric" }, { locale });
+  if (mode === "day") {
+    const sameYear = !today || anchor.slice(0, 4) === today.slice(0, 4);
+    return formatDate(anchor, sameYear ? { weekday: "long", month: "long", day: "numeric" } : { weekday: "long", month: "long", day: "numeric", year: "numeric" }, { locale });
+  }
+  return rangeLabel(range.from, range.to, { locale });
+}
+
+/** "9 AM" / "21" — an hour on the grid's gutter. */
+export function hourLabel(hour, { locale } = {}) {
+  return new Intl.DateTimeFormat(locale, { hour: "numeric", timeZone: "UTC" }).format(new Date(hour * 3600000));
+}
+
+/** "9:30 AM" for minutes after midnight. */
+export function minutesLabel(minutes, { locale } = {}) {
+  return formatTime(withTime("2000-01-01", Math.min(minutes, DAY_MINUTES - 1)), { locale });
+}
+
+/** "9:30 – 11:00 AM"-ish words for a timed event, "All day", or "Due
+ *  5:00 PM" for a deadline. */
+export function eventTimeLabel(event, { locale } = {}) {
+  if (!event?.timed) return "All day";
+  if (event.deadline) return `Due ${minutesLabel(event.from, { locale })}`;
+  return `${minutesLabel(event.from, { locale })} – ${minutesLabel(event.to, { locale })}`;
+}
+
+// ---- the available-time layer --------------------------------------------
+
+const HHMM = /^(\d{1,2}):(\d{2})$/;
+const toMin = (v) => {
+  if (typeof v === "number") return v;
+  const m = HHMM.exec(String(v ?? ""));
+  return m ? +m[1] * 60 + +m[2] : null;
+};
+
+function intervals(list) {
+  return (list ?? [])
+    .map((r) => (Array.isArray(r) ? [toMin(r[0]), toMin(r[1])] : [toMin(r?.from), toMin(r?.to)]))
+    .filter(([a, b]) => a !== null && b !== null && b > a)
+    .map(([a, b]) => [clamp(a, 0, DAY_MINUTES), clamp(b, 0, DAY_MINUTES)])
+    .sort((x, y) => x[0] - y[0]);
+}
+
+/**
+ * The open hours on a day, as [[from, to], …] minutes. `availability` is
+ *   { days: [1,2,3,4,5], from: "09:00", to: "17:00" }        the simple week
+ *   { weekly: { 1: [["09:00","12:00"], ["13:00","17:00"]], … } }   per weekday (0 Sunday)
+ *   …either, plus dates: { "2026-12-24": [["09:00","12:00"]], "2026-12-25": [] }
+ *   or a function (day) → [[from, to], …]
+ * Nothing given → the whole day is open.
+ */
+export function availabilityOn(day, availability) {
+  if (!availability) return [[0, DAY_MINUTES]];
+  if (typeof availability === "function") return intervals(availability(day));
+  const d = dayOf(day);
+  if (availability.dates && Object.hasOwn(availability.dates, d)) return intervals(availability.dates[d]);
+  const wd = weekdayOf(d);
+  if (availability.weekly) return intervals(availability.weekly[wd] ?? availability.weekly[String(wd)]);
+  const days = availability.days ?? [1, 2, 3, 4, 5];
+  if (!days.includes(wd)) return [];
+  return intervals([[availability.from ?? "09:00", availability.to ?? "17:00"]]);
+}
+
+/** The closed stretches of a day: the complement of availabilityOn. */
+export function closedOn(day, availability) {
+  const open = availabilityOn(day, availability);
+  const out = [];
+  let cursor = 0;
+  for (const [a, b] of open) {
+    if (a > cursor) out.push([cursor, a]);
+    cursor = Math.max(cursor, b);
+  }
+  if (cursor < DAY_MINUTES) out.push([cursor, DAY_MINUTES]);
+  return out;
+}
+
+function busyIntervals(busy, day, buffer) {
+  const out = [];
+  for (const b of busy ?? []) {
+    let a;
+    let z;
+    if (b && Object.hasOwn(b, "end")) {
+      // an interval { start, end } (a booking, a meeting)
+      const sd = dayOf(b.start);
+      const ed = dayOf(b.end);
+      if (!sd || !ed || sd > day || ed < day) continue;
+      a = sd < day ? 0 : minutesOf(b.start) ?? 0;
+      z = ed > day ? DAY_MINUTES : minutesOf(b.end) ?? DAY_MINUTES;
+    } else {
+      // a task: only a timed block takes time; an all-day date does not
+      const e = eventOf(b);
+      if (!e?.timed || e.start !== day) continue;
+      a = e.from;
+      z = e.to;
+    }
+    out.push([a - buffer, z + buffer]);
+  }
+  return out;
+}
+
+/**
+ * Open slots between two days — what a booking page offers, and what a
+ * calendar's `getSlots` can return as is:
+ *   freeSlots({ from, to, availability, busy, minutes: 30, step, buffer, notice, now })
+ *   → [{ id, day, start: "2026-09-24T09:00", end: "2026-09-24T09:30", from: 540, to: 570 }]
+ * `busy` mixes tasks (their timed blocks) and { start, end } intervals;
+ * `buffer` minutes are kept free around each; `step` is how far apart
+ * slots start (default `minutes`); nothing starts before `now` plus
+ * `notice` minutes (`now` a "YYYY-MM-DDTHH:mm" string).
+ */
+export function freeSlots({ from, to, availability, busy = [], minutes = 30, step, buffer = 0, notice = 0, now } = {}) {
+  const a = dayNumber(from);
+  const z = dayNumber(to ?? from);
+  if (a === null || z === null) return [];
+  const inc = step > 0 ? step : minutes;
+  const nowDay = dayOf(now);
+  const earliest = nowDay ? (minutesOf(now) ?? 0) + notice : null;
+  const out = [];
+  for (let n = a; n <= z && out.length < 5000; n++) {
+    const day = addDays(from, n - a);
+    if (nowDay && day < nowDay) continue;
+    const taken = busyIntervals(busy, day, buffer);
+    for (const [open, close] of availabilityOn(day, availability)) {
+      for (let s = open; s + minutes <= close; s += inc) {
+        const e = s + minutes;
+        if (nowDay && day === nowDay && s < earliest) continue;
+        if (taken.some(([x, y]) => s < y && x < e)) continue;
+        out.push({ id: `${day}T${s}`, day, start: withTime(day, s), end: withTime(day, Math.min(e, DAY_MINUTES - 1)), from: s, to: e });
+      }
+    }
+  }
+  return out;
+}
+
+/** A slot list (from `slots` or `getSlots`) normalised to the shape the
+ *  grid draws: { id, day, from, to, start, end, …yours }. */
+export function normalizeSlots(slots) {
+  const out = [];
+  for (const s of slots ?? []) {
+    const day = s.day ?? dayOf(s.start);
+    const from = s.from ?? minutesOf(s.start);
+    const to = s.to ?? minutesOf(s.end) ?? (from !== null ? from + 30 : null);
+    if (!day || from === null || to === null) continue;
+    out.push({ ...s, id: String(s.id ?? `${day}T${from}`), day, from, to, start: s.start ?? withTime(day, from), end: s.end ?? withTime(day, to) });
+  }
+  return out;
+}