@jorgerdz/timeview 0.1.0

package/src/timeview/core/aggregate.ts

@@ -0,0 +1,317 @@
+// aggregate.ts — shared bucketing + aggregation for summary visualizers.
+//
+// Turns a TimeDataset into a {groups × buckets} matrix. Rendering components
+// can consume this directly without mutating source events or intervals.
+
+import { DAY_MS, domainOf, fmt, tvWeeks } from "./time";
+import type { HeatmapGroupBy, HeatmapMeasure, TimeBucketMode, TimeDataset } from "../types";
+
+export interface TimeBucket {
+  key: string;
+  index: number;
+  start: number;
+  end: number;
+  label: string;
+  sub: string;
+  range: [number, number];
+  mode: TimeBucketMode;
+  isMonday?: boolean;
+  isWeekend?: boolean;
+}
+
+export interface AggregateGroup {
+  id: string;
+  name: string;
+  labelId: string | null;
+}
+
+export type AggregateItem =
+  | { id: string; kind: "interval"; title: string; overlapMs: number; labelId?: string }
+  | { id: string; kind: "event"; title: string; labelId?: string };
+
+export interface AggregateCell {
+  count: number;
+  durationMs: number;
+  items: AggregateItem[];
+}
+
+export interface AggregateOptions {
+  bucket?: TimeBucketMode;
+  measure?: HeatmapMeasure;
+  groupBy?: HeatmapGroupBy;
+}
+
+export interface AggregateMatrix {
+  t0: number;
+  t1: number;
+  buckets: TimeBucket[];
+  groups: AggregateGroup[];
+  cells: Record<string, Record<string, AggregateCell>>;
+  max: number;
+  totals: Record<string, { value: number; count: number; durationMs: number }>;
+  totalMax: number;
+  measure: HeatmapMeasure;
+  bucket: TimeBucketMode;
+  groupBy: HeatmapGroupBy;
+  value: (cell: AggregateCell | undefined) => number;
+}
+
+export type SpanMatrixIntervalItem = Extract<AggregateItem, { kind: "interval" }>;
+export type SpanMatrixEventItem = Extract<AggregateItem, { kind: "event" }>;
+
+export interface SpanMatrixCell {
+  bucketKey: string;
+  index: number;
+  spanCount: number;
+  present: boolean;
+  overlap: boolean;
+  runStart: boolean;
+  runEnd: boolean;
+  eventCount: number;
+  intervals: SpanMatrixIntervalItem[];
+  events: SpanMatrixEventItem[];
+}
+
+export interface SpanMatrixRun {
+  c0: number;
+  c1: number;
+  cells: SpanMatrixCell[];
+  peak: number;
+  title: string;
+  labelId: string | null;
+  span: number;
+}
+
+export interface SpanMatrixRow {
+  id: string;
+  name: string;
+  labelId: string | null;
+  cells: SpanMatrixCell[];
+  runs: SpanMatrixRun[];
+}
+
+export interface SpanMatrixOptions {
+  bucket?: TimeBucketMode;
+  groupBy?: HeatmapGroupBy;
+}
+
+export interface SpanMatrixModel {
+  t0: number;
+  t1: number;
+  buckets: TimeBucket[];
+  groups: AggregateGroup[];
+  rows: SpanMatrixRow[];
+  maxOverlap: number;
+  presentCells: number;
+  bucket: TimeBucketMode;
+  groupBy: HeatmapGroupBy;
+}
+
+function asDate(t: number | string | Date): Date {
+  return t instanceof Date ? t : new Date(t);
+}
+
+function startOfDayUTC(t: number | string | Date): number {
+  const d = asDate(t);
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+
+/** Half-open [start,end) bucket windows across the dataset domain. */
+export function tvBuckets(t0: number | string | Date, t1: number | string | Date, mode: TimeBucketMode = "day"): TimeBucket[] {
+  const start = asDate(t0).getTime();
+  const end = asDate(t1).getTime();
+
+  if (mode === "week") {
+    return tvWeeks(start, end).map((w, i) => ({
+      key: "w" + i,
+      index: i,
+      start: w.start.getTime(),
+      end: w.end.getTime(),
+      label: String(fmt.day(w.start)),
+      sub: fmt.mon(w.start),
+      range: [w.start.getTime(), w.end.getTime() - DAY_MS],
+      mode: "week",
+    }));
+  }
+
+  const out: TimeBucket[] = [];
+  let d = startOfDayUTC(start);
+  let i = 0;
+  while (d < end) {
+    const dt = new Date(d);
+    out.push({
+      key: "d" + d,
+      index: i++,
+      start: d,
+      end: d + DAY_MS,
+      label: String(fmt.day(dt)),
+      sub: fmt.dow(dt),
+      range: [d, d],
+      mode: "day",
+      isMonday: (dt.getUTCDay() + 6) % 7 === 0,
+      isWeekend: dt.getUTCDay() === 0 || dt.getUTCDay() === 6,
+    });
+    d += DAY_MS;
+  }
+  return out;
+}
+
+export function tvAggregate(dataset: TimeDataset, opts: AggregateOptions = {}): AggregateMatrix {
+  const bucket = opts.bucket || "day";
+  const measure = opts.measure || "count";
+  const groupBy = opts.groupBy || "category";
+
+  const [t0, t1] = domainOf(dataset);
+  const buckets = tvBuckets(t0, t1, bucket);
+  const groups: AggregateGroup[] =
+    groupBy === "category"
+      ? (dataset.labels || []).map((l) => ({ id: l.id, name: l.name, labelId: l.id }))
+      : [{ id: "__all", name: "All activity", labelId: null }];
+  const groupOf = (labelId: string | undefined) => (groupBy === "category" ? labelId : "__all");
+
+  const cells: AggregateMatrix["cells"] = {};
+  groups.forEach((g) => {
+    cells[g.id] = {};
+    buckets.forEach((b) => {
+      cells[g.id][b.key] = { count: 0, durationMs: 0, items: [] };
+    });
+  });
+
+  (dataset.intervals || []).forEach((iv) => {
+    const s = new Date(iv.range.start).getTime();
+    const e = new Date(iv.range.end).getTime();
+    const labelId = iv.labelIds?.[0];
+    const gid = groupOf(labelId);
+    if (!gid || !cells[gid]) return;
+
+    buckets.forEach((b) => {
+      const overlapMs = Math.min(e, b.end) - Math.max(s, b.start);
+      if (overlapMs <= 0) return;
+      const cell = cells[gid][b.key];
+      cell.durationMs += overlapMs;
+      cell.count += 1;
+      cell.items.push({ id: iv.id, kind: "interval", title: iv.title, overlapMs, labelId });
+    });
+  });
+
+  (dataset.events || []).forEach((ev) => {
+    const t = new Date(ev.at).getTime();
+    const labelId = ev.labelIds?.[0];
+    const gid = groupOf(labelId);
+    if (!gid || !cells[gid]) return;
+    const b = buckets.find((candidate) => t >= candidate.start && t < candidate.end);
+    if (!b) return;
+    const cell = cells[gid][b.key];
+    cell.count += 1;
+    cell.items.push({ id: ev.id, kind: "event", title: ev.title, labelId });
+  });
+
+  const value = (cell: AggregateCell | undefined) => (cell ? (measure === "duration" ? cell.durationMs : cell.count) : 0);
+  let max = 0;
+  const totals: AggregateMatrix["totals"] = {};
+
+  buckets.forEach((b) => {
+    let sum = 0;
+    let count = 0;
+    let durationMs = 0;
+    groups.forEach((g) => {
+      const cell = cells[g.id][b.key];
+      max = Math.max(max, value(cell));
+      sum += value(cell);
+      count += cell.count;
+      durationMs += cell.durationMs;
+    });
+    totals[b.key] = { value: sum, count, durationMs };
+  });
+
+  let totalMax = 0;
+  buckets.forEach((b) => {
+    totalMax = Math.max(totalMax, totals[b.key].value);
+  });
+
+  return { t0, t1, buckets, groups, cells, max, totals, totalMax, measure, bucket, groupBy, value };
+}
+
+export function tvSpanMatrix(dataset: TimeDataset, opts: SpanMatrixOptions = {}): SpanMatrixModel {
+  const bucket = opts.bucket || "day";
+  const groupBy = opts.groupBy || "category";
+  const agg = tvAggregate(dataset, { bucket, measure: "count", groupBy });
+
+  let maxOverlap = 0;
+  let presentCells = 0;
+  const rows = agg.groups.map((g) => {
+    const cells = agg.buckets.map((b, i) => {
+      const items = agg.cells[g.id][b.key].items;
+      const intervals = items.filter((it): it is SpanMatrixIntervalItem => it.kind === "interval");
+      const events = items.filter((it): it is SpanMatrixEventItem => it.kind === "event");
+      maxOverlap = Math.max(maxOverlap, intervals.length);
+      if (intervals.length > 0) presentCells += 1;
+      return {
+        bucketKey: b.key,
+        index: i,
+        spanCount: intervals.length,
+        present: intervals.length > 0,
+        overlap: intervals.length >= 2,
+        runStart: false,
+        runEnd: false,
+        eventCount: events.length,
+        intervals,
+        events,
+      };
+    });
+
+    cells.forEach((cell, i) => {
+      const prev = cells[i - 1];
+      const next = cells[i + 1];
+      cell.runStart = cell.present && !(prev && prev.present);
+      cell.runEnd = cell.present && !(next && next.present);
+    });
+
+    const runs: SpanMatrixRun[] = [];
+    let cur: SpanMatrixRun | null = null;
+    cells.forEach((cell, i) => {
+      if (cell.present) {
+        if (!cur) {
+          cur = { c0: i, c1: i, cells: [cell], peak: cell.spanCount, title: "", labelId: g.labelId, span: 1 };
+          runs.push(cur);
+        } else {
+          cur.c1 = i;
+          cur.cells.push(cell);
+          cur.peak = Math.max(cur.peak, cell.spanCount);
+        }
+      } else {
+        cur = null;
+      }
+    });
+
+    runs.forEach((run) => {
+      const start = cells[run.c0];
+      const primary = [...start.intervals].sort((a, b) => (b.overlapMs || 0) - (a.overlapMs || 0))[0];
+      run.title = primary ? primary.title : "";
+      run.labelId = g.labelId;
+      run.span = run.c1 - run.c0 + 1;
+    });
+
+    return { id: g.id, name: g.name, labelId: g.labelId, cells, runs };
+  });
+
+  return {
+    t0: agg.t0,
+    t1: agg.t1,
+    buckets: agg.buckets,
+    groups: agg.groups,
+    rows,
+    maxOverlap,
+    presentCells,
+    bucket,
+    groupBy,
+  };
+}
+
+export function tvFmtDuration(ms: number): string {
+  if (!ms || ms <= 0) return "0h";
+  const hours = ms / 3600000;
+  if (hours < 24) return Math.round(hours) + "h";
+  const days = hours / 24;
+  return (days >= 9.95 ? Math.round(days) : days.toFixed(1)) + "d";
+}

package/src/timeview/core/calendar.ts

@@ -0,0 +1,81 @@
+// calendar.ts — shared week/day projection helpers.
+
+import { DAY_MS, tvWeeks } from "./time";
+import type { TimeInput } from "../types";
+
+export interface CalendarWeek {
+  index: number;
+  start: Date;
+  end: Date;
+  days: Date[];
+}
+
+export interface CalendarCell {
+  wi: number;
+  col: number;
+}
+
+export interface CalendarIntervalSegment {
+  wi: number;
+  c0: number;
+  c1: number;
+  startsHere: boolean;
+  endsHere: boolean;
+}
+
+function asDate(d: TimeInput): Date {
+  return d instanceof Date ? d : new Date(d);
+}
+
+export function startOfDayUTC(d: TimeInput): number {
+  const x = asDate(d);
+  return Date.UTC(x.getUTCFullYear(), x.getUTCMonth(), x.getUTCDate());
+}
+
+/** Mon-start weeks covering [t0,t1], each with 7 concrete UTC day dates. */
+export function tvGridWeeks(t0: TimeInput, t1: TimeInput): CalendarWeek[] {
+  return tvWeeks(t0, t1).map((w, index) => {
+    const days: Date[] = [];
+    for (let k = 0; k < 7; k++) days.push(new Date(w.start.getTime() + k * DAY_MS));
+    return { index, start: w.start, end: w.end, days };
+  });
+}
+
+/** Which {week,row col 0..6} a single instant lands in. */
+export function tvDayCell(t: TimeInput, weeks: CalendarWeek[]): CalendarCell | null {
+  const day = startOfDayUTC(t);
+  for (const w of weeks) {
+    const ws = startOfDayUTC(w.start);
+    const col = Math.round((day - ws) / DAY_MS);
+    if (col >= 0 && col < 7) return { wi: w.index, col };
+  }
+  return null;
+}
+
+/** Split an interval into inclusive day-column segments for each week row it touches. */
+export function tvSplitInterval(s: TimeInput, e: TimeInput, weeks: CalendarWeek[]): CalendarIntervalSegment[] {
+  const sDay = startOfDayUTC(s);
+  const eDay = startOfDayUTC(e);
+  const segments: CalendarIntervalSegment[] = [];
+
+  weeks.forEach((w) => {
+    const ws = startOfDayUTC(w.start);
+    const weLast = ws + 6 * DAY_MS;
+    const segStart = Math.max(sDay, ws);
+    const segEnd = Math.min(eDay, weLast);
+    if (segStart > segEnd) return;
+    segments.push({
+      wi: w.index,
+      c0: Math.round((segStart - ws) / DAY_MS),
+      c1: Math.round((segEnd - ws) / DAY_MS),
+      startsHere: sDay >= ws && sDay <= weLast,
+      endsHere: eDay >= ws && eDay <= weLast,
+    });
+  });
+
+  return segments;
+}
+
+export function tvSameUTCDay(a: TimeInput, b: TimeInput): boolean {
+  return startOfDayUTC(a) === startOfDayUTC(b);
+}

package/src/timeview/core/intervals.ts

@@ -0,0 +1,52 @@
+// intervals.ts — shared interval geometry helpers.
+
+export interface PackedInterval {
+  _s: number;
+  _e: number;
+  _lane: number;
+}
+
+// Greedy lane packing — intervals that don't overlap share a lane.
+export function packLanes<T extends PackedInterval>(intervals: T[]): number {
+  const sorted = [...intervals].sort((a, b) => a._s - b._s);
+  const laneEnds: number[] = [];
+  sorted.forEach((iv) => {
+    let placed = -1;
+    for (let i = 0; i < laneEnds.length; i++) {
+      if (iv._s >= laneEnds[i]) {
+        placed = i;
+        break;
+      }
+    }
+    if (placed === -1) {
+      placed = laneEnds.length;
+      laneEnds.push(0);
+    }
+    laneEnds[placed] = iv._e;
+    iv._lane = placed;
+  });
+  return laneEnds.length;
+}
+
+// Compute spans where >= 2 intervals are simultaneously active.
+export function overlapSpans<T extends Pick<PackedInterval, "_s" | "_e">>(intervals: T[]): [number, number][] {
+  const pts: [number, number][] = [];
+  intervals.forEach((iv) => {
+    pts.push([iv._s, 1]);
+    pts.push([iv._e, -1]);
+  });
+  pts.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+  const spans: [number, number][] = [];
+  let depth = 0;
+  let openAt: number | null = null;
+  pts.forEach(([t, d]) => {
+    const prev = depth;
+    depth += d;
+    if (prev < 2 && depth >= 2) openAt = t;
+    if (prev >= 2 && depth < 2 && openAt != null) {
+      spans.push([openAt, t]);
+      openAt = null;
+    }
+  });
+  return spans;
+}

package/src/timeview/core/labels.ts

@@ -0,0 +1,19 @@
+// labels.ts — shared label and palette helpers.
+
+import type { TimeDataset } from "../types";
+
+export function colorMap(dataset: TimeDataset, palette: string[]): Record<string, string> {
+  const m: Record<string, string> = {};
+  (dataset.labels || []).forEach((l, i) => {
+    m[l.id] = palette[i % palette.length];
+  });
+  return m;
+}
+
+export function mix(hex: string, pct: number, base = "#ffffff"): string {
+  return `color-mix(in srgb, ${hex} ${pct}%, ${base})`;
+}
+
+export function labelName(dataset: TimeDataset, id: string | undefined): string {
+  return (dataset.labels || []).find((l) => l.id === id)?.name || id || "";
+}