@nightkatana/kronosys-app 1.0.0-beta.0

package/lib/reportingWeekLayout.ts

@@ -0,0 +1,313 @@
+/** Aligné sur {@link UNDATED_KEY} dans `reportingAggregate` (évite import circulaire). */
+const UNDATED = "undated";
+
+export type ReportingWeekStartsOn = "monday" | "sunday" | "saturday";
+
+const JS_DAY: Record<ReportingWeekStartsOn, number> = {
+  monday: 1,
+  sunday: 0,
+  saturday: 6,
+};
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** `YYYY-MM-DD` + `delta` jours (calendrier local). */
+export function addDaysYmd(dayKey: string, delta: number): string {
+  const [y, m, d] = dayKey.split("-").map(Number);
+  const x = new Date(y, m - 1, d);
+  x.setDate(x.getDate() + delta);
+  return `${x.getFullYear()}-${pad2(x.getMonth() + 1)}-${pad2(x.getDate())}`;
+}
+
+/** Nombre de jours calendaires locaux entre deux clés `YYYY-MM-DD` (fin − début). */
+export function localCalendarDaysBetween(startKey: string, endKey: string): number {
+  const [y1, m1, d1] = startKey.split("-").map(Number);
+  const [y2, m2, d2] = endKey.split("-").map(Number);
+  const a = new Date(y1, m1 - 1, d1);
+  const b = new Date(y2, m2 - 1, d2);
+  return Math.round((b.getTime() - a.getTime()) / 86400000);
+}
+
+/**
+ * Date du premier jour de la semaine (selon `weekStartsOn`) contenant `dayKey`.
+ */
+export function localWeekStartKeyFromDayKey(
+  dayKey: string,
+  weekStartsOn: ReportingWeekStartsOn
+): string | null {
+  if (!dayKey || dayKey === UNDATED) {
+    return null;
+  }
+  const parts = dayKey.split("-");
+  if (parts.length !== 3) {
+    return null;
+  }
+  const y = Number(parts[0]);
+  const mo = Number(parts[1]);
+  const d = Number(parts[2]);
+  if (!y || !mo || !d) {
+    return null;
+  }
+  const x = new Date(y, mo - 1, d);
+  if (Number.isNaN(x.getTime())) {
+    return null;
+  }
+  const W = JS_DAY[weekStartsOn];
+  const dow = x.getDay();
+  const offset = (dow - W + 7) % 7;
+  x.setDate(x.getDate() - offset);
+  return `${x.getFullYear()}-${pad2(x.getMonth() + 1)}-${pad2(x.getDate())}`;
+}
+
+/** Libellés courts des 7 jours dans l’ordre des colonnes (selon le premier jour de semaine). */
+export function weekdayColumnLabels(
+  weekStartsOn: ReportingWeekStartsOn,
+  locale: string
+): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { weekday: "short" });
+  const baseSunday = new Date(2026, 0, 4);
+  const W = JS_DAY[weekStartsOn];
+  const deltaToFirst = (W - baseSunday.getDay() + 7) % 7;
+  const start = new Date(baseSunday);
+  start.setDate(start.getDate() + deltaToFirst);
+  const out: string[] = [];
+  for (let i = 0; i < 7; i++) {
+    const cell = new Date(start);
+    cell.setDate(cell.getDate() + i);
+    out.push(fmt.format(cell));
+  }
+  return out;
+}
+
+export type WeekdayDateColumnHeader = {
+  /** Clé `YYYY-MM-DD` de la colonne (alignée sur les cellules du tableau). */
+  dateKey: string;
+  /** Jour de la semaine court (ex. lun., Mon). */
+  weekdayShort: string;
+  /** Date calendaire courte (ex. 3 févr., Feb 3). */
+  calendarDateShort: string;
+};
+
+/**
+ * En-têtes des 7 colonnes d’une semaine : jour de la semaine + date réelle pour chaque `YYYY-MM-DD`
+ * à partir de `weekStartKey` (premier jour de la bande, selon le réglage « semaine commence »).
+ */
+export function weekdayDateColumnHeaders(
+  weekStartKey: string,
+  locale: string
+): WeekdayDateColumnHeader[] {
+  const wdFmt = new Intl.DateTimeFormat(locale, { weekday: "short" });
+  const dateFmt = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short" });
+  const out: WeekdayDateColumnHeader[] = [];
+  for (let i = 0; i < 7; i++) {
+    const dateKey = addDaysYmd(weekStartKey, i);
+    const [y, m, d] = dateKey.split("-").map(Number);
+    const cell = new Date(y, m - 1, d);
+    if (Number.isNaN(cell.getTime())) {
+      continue;
+    }
+    out.push({
+      dateKey,
+      weekdayShort: wdFmt.format(cell),
+      calendarDateShort: dateFmt.format(cell),
+    });
+  }
+  return out;
+}
+
+/** Plage affichée pour une ligne de semaine (dates locales). */
+export function formatWeekRangeLabel(weekStartKey: string, locale: string): string {
+  const endKey = addDaysYmd(weekStartKey, 6);
+  const [y1, m1, d1] = weekStartKey.split("-").map(Number);
+  const [y2, m2, d2] = endKey.split("-").map(Number);
+  const di = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short" });
+  if (m1 === m2 && y1 === y2) {
+    return `${d1}–${di.format(new Date(y2, m2 - 1, d2))} ${y2}`;
+  }
+  return `${di.format(new Date(y1, m1 - 1, d1))} – ${di.format(new Date(y2, m2 - 1, d2))} ${y2}`;
+}
+
+export type TagWeekCalendarRow = {
+  tagKey: string;
+  displayTag: string;
+  weekStart: string;
+  slots: number[];
+  total: number;
+};
+
+export type TagWeekCalendarDayInput = {
+  day: string;
+  tagKey: string;
+  displayTag: string;
+  minutes: number;
+};
+
+export type KeyedWeekCalendarDayInput = {
+  day: string;
+  rowKey: string;
+  displayLabel: string;
+  minutes: number;
+};
+
+export type KeyedWeekCalendarRow = {
+  rowKey: string;
+  displayLabel: string;
+  weekStart: string;
+  slots: number[];
+  total: number;
+};
+
+function compareRowKeyEmptyLast(a: string, b: string): number {
+  if (a === "" && b !== "") {
+    return 1;
+  }
+  if (b === "" && a !== "") {
+    return -1;
+  }
+  return a.localeCompare(b);
+}
+
+/**
+ * Agrège des lignes « jour » (clé + libellé) en grilles 7 jours + total par semaine.
+ */
+export function buildKeyedWeekCalendarRows(
+  byDay: readonly KeyedWeekCalendarDayInput[],
+  weekStartsOn: ReportingWeekStartsOn
+): KeyedWeekCalendarRow[] {
+  type Acc = { displayLabel: string; weeks: Map<string, number[]> };
+  const byEntity = new Map<string, Acc>();
+
+  for (const row of byDay) {
+    if (row.day === UNDATED) {
+      continue;
+    }
+    const ws = localWeekStartKeyFromDayKey(row.day, weekStartsOn);
+    if (!ws) {
+      continue;
+    }
+    const idx = localCalendarDaysBetween(ws, row.day);
+    if (idx < 0 || idx > 6 || row.minutes <= 0) {
+      continue;
+    }
+
+    let acc = byEntity.get(row.rowKey);
+    if (!acc) {
+      acc = { displayLabel: row.displayLabel, weeks: new Map() };
+      byEntity.set(row.rowKey, acc);
+    }
+    if (row.displayLabel && row.rowKey !== "") {
+      acc.displayLabel = row.displayLabel;
+    }
+
+    let slots = acc.weeks.get(ws);
+    if (!slots) {
+      slots = [0, 0, 0, 0, 0, 0, 0];
+      acc.weeks.set(ws, slots);
+    }
+    slots[idx] += row.minutes;
+  }
+
+  const flat: KeyedWeekCalendarRow[] = [];
+  for (const [rowKey, acc] of byEntity) {
+    for (const [weekStart, slots] of acc.weeks) {
+      const total = slots.reduce((s, v) => s + v, 0);
+      flat.push({
+        rowKey,
+        displayLabel: acc.displayLabel,
+        weekStart,
+        slots: [...slots],
+        total,
+      });
+    }
+  }
+
+  flat.sort(
+    (a, b) =>
+      compareRowKeyEmptyLast(a.rowKey, b.rowKey) ||
+      a.weekStart.localeCompare(b.weekStart)
+  );
+  return flat;
+}
+
+/**
+ * Agrège les lignes « jour » en grilles 7 jours + total par semaine et par étiquette.
+ */
+export function buildTagWeekCalendarRows(
+  byDay: readonly TagWeekCalendarDayInput[],
+  weekStartsOn: ReportingWeekStartsOn
+): TagWeekCalendarRow[] {
+  return buildKeyedWeekCalendarRows(
+    byDay.map((r) => ({
+      day: r.day,
+      rowKey: r.tagKey,
+      displayLabel: r.displayTag,
+      minutes: r.minutes,
+    })),
+    weekStartsOn
+  ).map((r) => ({
+    tagKey: r.rowKey,
+    displayTag: r.displayLabel,
+    weekStart: r.weekStart,
+    slots: r.slots,
+    total: r.total,
+  }));
+}
+
+export type ProjectWeekCalendarDayInput = {
+  day: string;
+  projectKey: string;
+  displayProject: string;
+  minutes: number;
+};
+
+export type ProjectWeekCalendarRow = {
+  projectKey: string;
+  displayProject: string;
+  weekStart: string;
+  slots: number[];
+  total: number;
+};
+
+/** Même logique que {@link buildTagWeekCalendarRows} pour les `@projet`. */
+export function buildProjectWeekCalendarRows(
+  byDay: readonly ProjectWeekCalendarDayInput[],
+  weekStartsOn: ReportingWeekStartsOn
+): ProjectWeekCalendarRow[] {
+  return buildKeyedWeekCalendarRows(
+    byDay.map((r) => ({
+      day: r.day,
+      rowKey: r.projectKey,
+      displayLabel: r.displayProject,
+      minutes: r.minutes,
+    })),
+    weekStartsOn
+  ).map((r) => ({
+    projectKey: r.rowKey,
+    displayProject: r.displayLabel,
+    weekStart: r.weekStart,
+    slots: r.slots,
+    total: r.total,
+  }));
+}
+
+export const REPORTING_WEEK_START_STORAGE_KEY = "kronosys-reporting-weekStartsOn";
+
+export function readWeekStartsOnFromStorage(): ReportingWeekStartsOn {
+  if (typeof window === "undefined") {
+    return "monday";
+  }
+  const v = window.localStorage.getItem(REPORTING_WEEK_START_STORAGE_KEY);
+  if (v === "sunday" || v === "saturday" || v === "monday") {
+    return v;
+  }
+  return "monday";
+}
+
+export function writeWeekStartsOnToStorage(value: ReportingWeekStartsOn): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  window.localStorage.setItem(REPORTING_WEEK_START_STORAGE_KEY, value);
+}

package/lib/sessionAssiduity.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { assiduityFromScheduledStart } from "./sessionAssiduity";
+
+describe("sessionAssiduity", () => {
+  it("retourne un écart positif si l’ouverture est après l’heure prévue", () => {
+    const a = assiduityFromScheduledStart(
+      Date.parse("2026-04-24T09:15:00.000Z"),
+      "2026-04-24T09:00:00.000Z"
+    );
+    expect(a?.sessionStartOffsetMinutes).toBe(15);
+    expect(a?.scheduledStartAt).toBe("2026-04-24T09:00:00.000Z");
+  });
+
+  it("retourne un écart négatif si l’ouverture est en avance", () => {
+    const a = assiduityFromScheduledStart(
+      Date.parse("2026-04-24T08:50:00.000Z"),
+      "2026-04-24T09:00:00.000Z"
+    );
+    expect(a?.sessionStartOffsetMinutes).toBe(-10);
+  });
+
+  it("refuse une chaîne d’horodatage invalide", () => {
+    expect(assiduityFromScheduledStart(Date.now(), "pas-une-date")).toBeNull();
+  });
+});

package/lib/sessionAssiduity.ts

@@ -0,0 +1,33 @@
+/**
+ * Assiduité : comparaison entre l’heure d’ouverture réelle d’une session et une heure de
+ * début de référence fournie par l’hôte (p. ex. processus lié à l’horaire ou aux sessions
+ * planifiées). Sert au reporting (retards cumulés, moyennes) et à l’export.
+ */
+export type SessionStartAssiduity = {
+  /** `scheduledStartAt` normalisé (ISO). */
+  scheduledStartAt: string;
+  /**
+   * `startAt` effectif moins l’heure de référence, en minutes (arrondi) :
+   * positif = ouverture après l’heure prévue, négatif = avant.
+   */
+  sessionStartOffsetMinutes: number;
+};
+
+/**
+ * @param actualStartAtMs     Horodatage de création de la session (même repère que `startAt`)
+ * @param scheduledStartAtIso Heure de début de référence (toute chaîne `Date` valide)
+ */
+export function assiduityFromScheduledStart(
+  actualStartAtMs: number,
+  scheduledStartAtIso: string
+): SessionStartAssiduity | null {
+  const t = Date.parse(String(scheduledStartAtIso).trim());
+  if (!Number.isFinite(t)) {
+    return null;
+  }
+  const offset = Math.round((actualStartAtMs - t) / 60_000);
+  return {
+    scheduledStartAt: new Date(t).toISOString(),
+    sessionStartOffsetMinutes: offset,
+  };
+}

package/lib/sessionEndReason.ts

@@ -0,0 +1,55 @@
+import type { DashboardStrings } from "@/lib/dashboardCopy";
+
+const ALLOWED_KINDS = new Set(["planned", "early", "overrun", "other"]);
+
+export type SessionEndReasonKind = "planned" | "early" | "overrun" | "other";
+
+export function normalizeSessionEndReasonKind(raw: unknown): SessionEndReasonKind | "" {
+  const s = typeof raw === "string" ? raw.trim() : "";
+  return ALLOWED_KINDS.has(s) ? (s as SessionEndReasonKind) : "";
+}
+
+export function normalizeSessionEndReasonNote(raw: unknown): string {
+  if (typeof raw !== "string") {
+    return "";
+  }
+  return raw.trim().slice(0, 500);
+}
+
+type SessionEndReasonLabels = Pick<
+  DashboardStrings,
+  | "sessionEndReasonPlanned"
+  | "sessionEndReasonEarly"
+  | "sessionEndReasonOverrun"
+  | "sessionEndReasonOther"
+>;
+
+/** Ligne lisible pour la carte session (session terminée avec raison enregistrée). */
+export function formatSessionEndReasonLine(
+  t: SessionEndReasonLabels,
+  kind: string | undefined,
+  note: string | undefined
+): string | null {
+  const k = normalizeSessionEndReasonKind(kind);
+  const n = normalizeSessionEndReasonNote(note);
+  const label =
+    k === "planned"
+      ? t.sessionEndReasonPlanned
+      : k === "early"
+        ? t.sessionEndReasonEarly
+        : k === "overrun"
+          ? t.sessionEndReasonOverrun
+          : k === "other"
+            ? t.sessionEndReasonOther
+            : "";
+  if (!label && !n) {
+    return null;
+  }
+  if (!label) {
+    return n;
+  }
+  if (!n) {
+    return label;
+  }
+  return `${label} — ${n}`;
+}

package/lib/sessionEndWarnings.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  formatEndLiveSessionConfirmMessage,
+  formatEndLiveSessionModalIntro,
+  getEndLiveSessionWarningFlags,
+  shouldConfirmEndLiveSession,
+} from "./sessionEndWarnings";
+
+const STRINGS = {
+  sessionEndLiveConfirmIntro: "Attention :",
+  sessionEndLiveConfirmIntroCalm: "Tout est tranquille.",
+  sessionEndLiveWarnActiveTask: "Une tâche est en cours.",
+  sessionEndLiveWarnPausedTasks: "Des tâches sont en attente.",
+  sessionEndLiveWarnIncompleteSubtasks: "Des sous-tâches sont ouvertes.",
+};
+
+describe("getEndLiveSessionWarningFlags", () => {
+  it("retourne tout false si live est null", () => {
+    const flags = getEndLiveSessionWarningFlags(null);
+    expect(flags).toEqual({
+      hasActiveTracking: false,
+      hasPausedOrPendingTasks: false,
+      hasIncompleteSubtasks: false,
+    });
+  });
+
+  it("retourne tout false si live est undefined", () => {
+    expect(getEndLiveSessionWarningFlags(undefined)).toEqual({
+      hasActiveTracking: false,
+      hasPausedOrPendingTasks: false,
+      hasIncompleteSubtasks: false,
+    });
+  });
+
+  it("hasActiveTracking=true si activeTasks contient une tâche non terminée non en pause", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      activeTasks: [{ id: "t1", isDone: false, manualTaskTimerPaused: false }],
+    });
+    expect(flags.hasActiveTracking).toBe(true);
+  });
+
+  it("hasActiveTracking=false si la tâche active est en pause manuelle", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      activeTasks: [{ id: "t1", isDone: false, manualTaskTimerPaused: true }],
+    });
+    expect(flags.hasActiveTracking).toBe(false);
+  });
+
+  it("hasActiveTracking=false si la tâche active est terminée", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      activeTasks: [{ id: "t1", isDone: true }],
+    });
+    expect(flags.hasActiveTracking).toBe(false);
+  });
+
+  it("utilise activeTask (forme simple) si activeTasks est absent", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      activeTask: { id: "t1", isDone: false, manualTaskTimerPaused: false },
+    });
+    expect(flags.hasActiveTracking).toBe(true);
+  });
+
+  it("hasPausedOrPendingTasks=true si tasks contient une tâche non terminée", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      tasks: [{ id: "t1", isDone: false }],
+    });
+    expect(flags.hasPausedOrPendingTasks).toBe(true);
+  });
+
+  it("hasPausedOrPendingTasks=false si toutes les tâches sont terminées", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      tasks: [{ id: "t1", isDone: true }, { id: "t2", isDone: true }],
+    });
+    expect(flags.hasPausedOrPendingTasks).toBe(false);
+  });
+
+  it("hasIncompleteSubtasks=true si une tâche a une sous-tâche non terminée", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      tasks: [{ id: "t1", isDone: false, subtasks: [{ done: false }] }],
+    });
+    expect(flags.hasIncompleteSubtasks).toBe(true);
+  });
+
+  it("hasIncompleteSubtasks=false si toutes les sous-tâches sont done", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      tasks: [{ id: "t1", isDone: false, subtasks: [{ done: true }] }],
+    });
+    expect(flags.hasIncompleteSubtasks).toBe(false);
+  });
+
+  it("tâche active avec sous-tâche incomplète est détectée même si absente de tasks", () => {
+    const flags = getEndLiveSessionWarningFlags({
+      activeTasks: [{ id: "t-unique", isDone: false, subtasks: [{ done: false }] }],
+      tasks: [],
+    });
+    expect(flags.hasIncompleteSubtasks).toBe(true);
+  });
+
+  it("avertit pour une tâche active non terminée absente de la liste tasks", () => {
+    expect(
+      getEndLiveSessionWarningFlags({
+        tasks: [],
+        activeTasks: [{ id: "a", isDone: false }],
+      })
+    ).toEqual({
+      hasActiveTracking: true,
+      hasPausedOrPendingTasks: true,
+      hasIncompleteSubtasks: false,
+    });
+  });
+
+  it("avertit pour une tâche active en pause absente de la liste tasks", () => {
+    expect(
+      getEndLiveSessionWarningFlags({
+        tasks: [],
+        activeTasks: [{ id: "a", isDone: false, manualTaskTimerPaused: true }],
+      }).hasPausedOrPendingTasks
+    ).toBe(true);
+  });
+
+  it("avertit pour une sous-tâche ouverte sur activeTask quand activeTasks existe aussi", () => {
+    expect(
+      getEndLiveSessionWarningFlags({
+        tasks: [],
+        activeTasks: [{ id: "a", isDone: true }],
+        activeTask: {
+          id: "b",
+          isDone: true,
+          subtasks: [{ done: true }, { done: false }],
+        },
+      }).hasIncompleteSubtasks
+    ).toBe(true);
+  });
+});
+
+describe("shouldConfirmEndLiveSession", () => {
+  it("retourne false si aucun flag", () => {
+    expect(shouldConfirmEndLiveSession({
+      hasActiveTracking: false,
+      hasPausedOrPendingTasks: false,
+      hasIncompleteSubtasks: false,
+    })).toBe(false);
+  });
+
+  it("retourne true si hasActiveTracking", () => {
+    expect(shouldConfirmEndLiveSession({
+      hasActiveTracking: true,
+      hasPausedOrPendingTasks: false,
+      hasIncompleteSubtasks: false,
+    })).toBe(true);
+  });
+
+  it("retourne true si hasPausedOrPendingTasks seulement", () => {
+    expect(shouldConfirmEndLiveSession({
+      hasActiveTracking: false,
+      hasPausedOrPendingTasks: true,
+      hasIncompleteSubtasks: false,
+    })).toBe(true);
+  });
+});
+
+describe("formatEndLiveSessionConfirmMessage", () => {
+  it("inclut uniquement les bullets correspondant aux flags actifs", () => {
+    const msg = formatEndLiveSessionConfirmMessage(
+      { hasActiveTracking: true, hasPausedOrPendingTasks: false, hasIncompleteSubtasks: true },
+      STRINGS,
+    );
+    expect(msg).toContain("Attention :");
+    expect(msg).toContain("• Une tâche est en cours.");
+    expect(msg).toContain("• Des sous-tâches sont ouvertes.");
+    expect(msg).not.toContain("attente");
+  });
+
+  it("message vide de bullets si aucun flag (cas théorique)", () => {
+    const msg = formatEndLiveSessionConfirmMessage(
+      { hasActiveTracking: false, hasPausedOrPendingTasks: false, hasIncompleteSubtasks: false },
+      STRINGS,
+    );
+    expect(msg).toBe("Attention :\n");
+  });
+});
+
+describe("formatEndLiveSessionModalIntro", () => {
+  it("retourne le message calme si aucun flag", () => {
+    const intro = formatEndLiveSessionModalIntro(
+      { hasActiveTracking: false, hasPausedOrPendingTasks: false, hasIncompleteSubtasks: false },
+      STRINGS,
+    );
+    expect(intro).toBe("Tout est tranquille.");
+  });
+
+  it("retourne le message d'avertissement si au moins un flag", () => {
+    const intro = formatEndLiveSessionModalIntro(
+      { hasActiveTracking: false, hasPausedOrPendingTasks: true, hasIncompleteSubtasks: false },
+      STRINGS,
+    );
+    expect(intro).toContain("Des tâches sont en attente.");
+  });
+});