@nightkatana/kronosys-app 1.0.0-beta.0

package/components/dashboard/useDescriptionPopoverAfterMs.ts

@@ -0,0 +1,220 @@
+"use client";
+
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+  type RefCallback,
+} from "react";
+import { createPortal } from "react-dom";
+import { DescriptionTooltipPortaled } from "./DescriptionTooltipPortaled";
+
+const DEFAULT_OPEN_DELAY_MS = 3000;
+const LEAVE_GRACE_MS = 200;
+
+const TIP_PLACEHOLDER: CSSProperties = {
+  position: "fixed",
+  top: 0,
+  left: 0,
+  width: 288,
+  zIndex: 90,
+  visibility: "hidden",
+  pointerEvents: "none",
+};
+
+/**
+ * Infobulle « définition » au survol ou au focus : ouverture après quelques secondes (voir constante).
+ * Rendu en portail `fixed` pour éviter le clip des ancêtres `overflow-*` ; délai court au survol
+ * entre la pastille et la bulle pour ne pas fermer trop tôt.
+ */
+export function useDescriptionPopoverAfterMs(
+  description: string | undefined | null,
+  delayMs: number = DEFAULT_OPEN_DELAY_MS
+): {
+  hasDescription: boolean;
+  triggerProps: {
+    onPointerEnter: () => void;
+    onPointerLeave: () => void;
+    onPointerCancel: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+  };
+  popoverLayer: ReactNode;
+  /** À fusionner sur le conteneur qui englobe la pastille (ref + survol pour la grâce de fermeture). */
+  anchorWrapperProps: {
+    ref: RefCallback<HTMLSpanElement>;
+    onPointerEnter: () => void;
+    onPointerLeave: () => void;
+  };
+} {
+  const [open, setOpen] = useState(false);
+  const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const anchorRef = useRef<HTMLSpanElement | null>(null);
+  const reactId = useId().replace(/:/g, "");
+  const tipElementId = `kronosys-desc-tip-${reactId}`;
+  const desc = description?.trim() ?? "";
+
+  const clearOpenTimer = useCallback(() => {
+    if (openTimerRef.current !== null) {
+      clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+  }, []);
+
+  const clearLeaveTimer = useCallback(() => {
+    if (leaveTimerRef.current !== null) {
+      clearTimeout(leaveTimerRef.current);
+      leaveTimerRef.current = null;
+    }
+  }, []);
+
+  const scheduleOpen = useCallback(() => {
+    if (!desc) {
+      return;
+    }
+    clearOpenTimer();
+    openTimerRef.current = setTimeout(() => setOpen(true), delayMs);
+  }, [desc, delayMs, clearOpenTimer]);
+
+  const close = useCallback(() => {
+    clearOpenTimer();
+    clearLeaveTimer();
+    setOpen(false);
+  }, [clearOpenTimer, clearLeaveTimer]);
+
+  const scheduleCloseGrace = useCallback(() => {
+    clearLeaveTimer();
+    leaveTimerRef.current = setTimeout(() => {
+      leaveTimerRef.current = null;
+      setOpen(false);
+    }, LEAVE_GRACE_MS);
+  }, [clearLeaveTimer]);
+
+  useEffect(
+    () => () => {
+      clearOpenTimer();
+      clearLeaveTimer();
+    },
+    [clearOpenTimer, clearLeaveTimer]
+  );
+
+  useEffect(() => {
+    if (!desc) {
+      close();
+    }
+  }, [desc, close]);
+
+  const [tipStyle, setTipStyle] = useState<CSSProperties | undefined>(undefined);
+
+  useLayoutEffect(() => {
+    if (!open || !desc) {
+      setTipStyle(undefined);
+      return;
+    }
+    const place = () => {
+      const a = anchorRef.current;
+      if (!a) {
+        return;
+      }
+      const r = a.getBoundingClientRect();
+      const vw = globalThis.innerWidth;
+      const vh = globalThis.innerHeight;
+      const margin = 10;
+      const maxW = Math.min(18 * 16, vw - 2 * margin);
+      let left = r.left;
+      left = Math.max(margin, Math.min(left, vw - maxW - margin));
+      let top = r.bottom - 4;
+      const tip = document.getElementById(tipElementId);
+      if (tip instanceof HTMLElement) {
+        const th = tip.getBoundingClientRect().height;
+        if (top + th > vh - margin) {
+          top = Math.max(margin, r.top - 4 - th);
+        }
+      }
+      if (top < margin) {
+        top = margin;
+      }
+      setTipStyle({
+        position: "fixed",
+        top,
+        left,
+        width: maxW,
+        zIndex: 90,
+      });
+    };
+    place();
+    const raf = requestAnimationFrame(place);
+    globalThis.addEventListener("scroll", place, true);
+    globalThis.addEventListener("resize", place);
+    return () => {
+      cancelAnimationFrame(raf);
+      globalThis.removeEventListener("scroll", place, true);
+      globalThis.removeEventListener("resize", place);
+    };
+  }, [open, desc, tipElementId]);
+
+  const setAnchorRef = useCallback<RefCallback<HTMLSpanElement>>((node) => {
+    anchorRef.current = node;
+  }, []);
+
+  if (!desc) {
+    return {
+      hasDescription: false,
+      triggerProps: {
+        onPointerEnter: () => {},
+        onPointerLeave: () => {},
+        onPointerCancel: () => {},
+        onFocus: () => {},
+        onBlur: () => {},
+      },
+      popoverLayer: null,
+      anchorWrapperProps: {
+        ref: setAnchorRef,
+        onPointerEnter: () => {},
+        onPointerLeave: () => {},
+      },
+    };
+  }
+
+  const mergedTipStyle = tipStyle ?? (open ? TIP_PLACEHOLDER : undefined);
+
+  /* eslint-disable react-hooks/refs -- faux positif ESLint sur createElement + createPortal */
+  const popoverLayer =
+    open && typeof document !== "undefined" && mergedTipStyle
+      ? createPortal(
+          createElement(DescriptionTooltipPortaled, {
+            domId: tipElementId,
+            style: mergedTipStyle,
+            text: desc,
+            onPointerEnter: clearLeaveTimer,
+            onPointerLeave: scheduleCloseGrace,
+          }),
+          document.body
+        )
+      : null;
+  /* eslint-enable react-hooks/refs */
+
+  return {
+    hasDescription: true,
+    triggerProps: {
+      onPointerEnter: scheduleOpen,
+      onPointerLeave: clearOpenTimer,
+      onPointerCancel: clearOpenTimer,
+      onFocus: scheduleOpen,
+      onBlur: close,
+    },
+    popoverLayer,
+    anchorWrapperProps: {
+      ref: setAnchorRef,
+      onPointerEnter: clearLeaveTimer,
+      onPointerLeave: scheduleCloseGrace,
+    },
+  };
+}

package/components/dashboard/useKronoFocusLiveSeconds.ts

@@ -0,0 +1,36 @@
+"use client";
+
+import { useLayoutEffect, useState } from "react";
+
+/**
+ * Affiche les secondes restantes du KronoFocus en phase « running » à partir de
+ * `kronoFocusDeadlineAtMs` (horloge murale), comme le chronomètre de tâche qui lisse
+ * entre deux réponses API. Sans échéance (données héritées), on retombe sur `serverSecs`.
+ *
+ * `Date.now()` vit dans un effet pour respecter react-hooks/purity (pas d’horloge en rendu).
+ */
+export function useKronoFocusLiveSeconds(
+  serverSecs: number,
+  status: "idle" | "running" | "paused",
+  deadlineMs: number | undefined
+): number {
+  const [fromDeadlineSecs, setFromDeadlineSecs] = useState<number | null>(null);
+
+  useLayoutEffect(() => {
+    if (status !== "running" || typeof deadlineMs !== "number" || !Number.isFinite(deadlineMs)) {
+      setFromDeadlineSecs(null);
+      return;
+    }
+    const tick = () => {
+      setFromDeadlineSecs(Math.max(0, Math.ceil((deadlineMs - Date.now()) / 1000)));
+    };
+    tick();
+    const id = globalThis.setInterval(tick, 100);
+    return () => globalThis.clearInterval(id);
+  }, [status, deadlineMs]);
+
+  if (status === "running" && typeof deadlineMs === "number" && Number.isFinite(deadlineMs)) {
+    return fromDeadlineSecs ?? Math.max(0, Math.floor(serverSecs));
+  }
+  return Math.max(0, Math.floor(serverSecs));
+}

package/components/dashboard/useSmoothStopwatchMs.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Durée affichée à partir de `serverMs` ; si `smooth` est vrai, ajoute le temps écoulé
+ * localement entre deux mises à jour serveur (y compris quand la base est encore 0).
+ */
+export function useSmoothStopwatchDisplayMs(serverMs: number, smooth: boolean): number {
+  const base = Math.max(0, Math.floor(serverMs));
+  const [display, setDisplay] = useState(base);
+  useEffect(() => {
+    if (!smooth) {
+      setDisplay(base);
+      return;
+    }
+    setDisplay(base);
+    const t0 = Date.now();
+    const id = globalThis.setInterval(() => {
+      setDisplay(base + (Date.now() - t0));
+    }, 50);
+    return () => globalThis.clearInterval(id);
+  }, [smooth, base]);
+  return smooth ? display : base;
+}

package/lib/appShellHeaderClasses.ts

@@ -0,0 +1,12 @@
+/**
+ * Mise en page de l’en-tête commun (repères de repli, bordure, fond) : identique sur toutes
+ * les routes pour limiter les sauts visuels lors des changements de page.
+ */
+export const appShellHeaderClassName =
+  "sticky top-0 z-50 border-b border-zinc-200 bg-zinc-100/95 backdrop-blur-sm dark:border-zinc-800 dark:bg-zinc-900/95 px-5 py-5 sm:px-8 sm:py-5 lg:px-10 lg:py-6 xl:px-12";
+
+/**
+ * Ligne titre / fil d’Ariane (gauche) et barre d’outils navigation + thème + langue (droite).
+ */
+export const appShellHeaderToolRowClassName =
+  "flex w-full flex-col gap-3 sm:flex-row sm:items-start sm:justify-between";

package/lib/backupCsvExport.test.ts

@@ -0,0 +1,149 @@
+import { unzipSync } from "fflate";
+import { describe, expect, it } from "vitest";
+import type { KronosysUpdatePayload } from "@/lib/kronosysApi";
+import {
+  buildCsvBackupZipSync,
+  buildGitIdentityCsv,
+  buildSessionsBackupCsv,
+  buildStoreJsonBlobsCsv,
+  buildSubtasksBackupCsv,
+  buildTagDescriptionsCsv,
+  buildTagProjectRegistryCsv,
+  buildTasksBackupCsv,
+  isCsvBackupTable,
+} from "./backupCsvExport";
+
+function samplePayload(): KronosysUpdatePayload {
+  return {
+    viewType: "dashboard",
+    cfg: { autoStart: false, plannedSessions: [{ id: "p1" }] },
+    history: [
+      {
+        sessionId: "s-hist",
+        sessionName: "Hist",
+        startAt: "2026-04-01T10:00:00.000Z",
+        endAt: "2026-04-01T11:00:00.000Z",
+        savedAt: "2026-04-01T11:05:00.000Z",
+        sessionDurationMinutes: 60,
+        tasks: [
+          {
+            id: "t1",
+            name: "Do, thing",
+            tags: ["a", "b"],
+            project: "acme",
+            isDone: true,
+            durationMs: 3_600_000,
+            subtasks: [{ id: "st1", title: "Step, one", done: true, durationMs: 1000 }],
+          },
+        ],
+      },
+    ],
+    historyArchived: [
+      {
+        sessionId: "s-arch",
+        sessionName: "Arch",
+        savedAt: "2026-04-02T12:00:00.000Z",
+        tasks: [],
+      },
+    ],
+    current: {
+      sessionId: "s-live",
+      sessionName: "Live",
+      savedAt: "2026-04-03T08:00:00.000Z",
+      activeTasks: [{ id: "t2", name: "Running", isDone: false, durationMs: 0 }],
+      tasks: [],
+    },
+    knownTags: ["a"],
+    knownProjects: ["acme"],
+    userKnownTags: ["pinned"],
+    excludedSuggestionTags: ["hide-me"],
+    tagDescriptions: { alpha: "Desc, with comma" },
+    projectDescriptions: { acme: "Client" },
+    gitIdentity: { gitUserName: "n", gitUserEmail: "e@x.ca", gitAccountLogin: "gh" },
+    inspectingSessionId: "s-hist",
+    dismissArchiveSessionConfirm: true,
+  } as KronosysUpdatePayload;
+}
+
+describe("backupCsvExport", () => {
+  it("isCsvBackupTable reconnaît les noms de tables", () => {
+    expect(isCsvBackupTable("sessions")).toBe(true);
+    expect(isCsvBackupTable("nope")).toBe(false);
+  });
+
+  it("buildSessionsBackupCsv inclut la source et le JSON de session", () => {
+    const csv = buildSessionsBackupCsv(samplePayload());
+    expect(csv).toContain("scheduledStartAt");
+    expect(csv).toContain("sessionStartOffsetMinutes");
+    expect(csv).toContain("sessionSource");
+    expect(csv).toContain("s-hist");
+    expect(csv).toContain("history");
+    expect(csv).toContain("historyArchived");
+    expect(csv).toContain("current");
+    expect(csv).toContain("sessionJson");
+    expect(csv).toContain("Hist");
+  });
+
+  it("buildTasksBackupCsv échappe les virgules dans le nom et inclut taskJson", () => {
+    const csv = buildTasksBackupCsv(samplePayload());
+    expect(csv).toContain("Do, thing");
+    expect(csv).toContain("t1");
+    expect(csv).toContain("taskJson");
+    expect(csv).toContain('""id"":""t1""');
+  });
+
+  it("buildSubtasksBackupCsv liste les sous-tâches", () => {
+    const csv = buildSubtasksBackupCsv(samplePayload());
+    expect(csv).toContain("st1");
+    expect(csv).toContain("Step, one");
+  });
+
+  it("buildTagProjectRegistryCsv couvre les quatre listes", () => {
+    const csv = buildTagProjectRegistryCsv(samplePayload());
+    expect(csv).toContain("known_tag,a");
+    expect(csv).toContain("known_project,acme");
+    expect(csv).toContain("user_known_tag,pinned");
+    expect(csv).toContain("excluded_suggestion_tag,hide-me");
+  });
+
+  it("buildTagDescriptionsCsv échappe les descriptions", () => {
+    const csv = buildTagDescriptionsCsv(samplePayload());
+    expect(csv).toContain("alpha");
+    expect(csv).toContain("Desc, with comma");
+  });
+
+  it("buildGitIdentityCsv exporte les trois champs", () => {
+    const csv = buildGitIdentityCsv(samplePayload());
+    expect(csv.split("\n")[1]).toContain("n");
+    expect(csv.split("\n")[1]).toContain("e@x.ca");
+    expect(csv.split("\n")[1]).toContain("gh");
+  });
+
+  it("buildCsvBackupZipSync regroupe les huit CSV", () => {
+    const stamp = "TEST-STAMP";
+    const zip = buildCsvBackupZipSync(samplePayload(), stamp);
+    const entries = unzipSync(zip);
+    const names = Object.keys(entries).sort();
+    expect(names).toEqual([
+      `kronosys-git_identity-${stamp}.csv`,
+      `kronosys-project_descriptions-${stamp}.csv`,
+      `kronosys-sessions-${stamp}.csv`,
+      `kronosys-store_json_blobs-${stamp}.csv`,
+      `kronosys-subtasks-${stamp}.csv`,
+      `kronosys-tag_descriptions-${stamp}.csv`,
+      `kronosys-tag_project_registry-${stamp}.csv`,
+      `kronosys-tasks-${stamp}.csv`,
+    ]);
+    const sessionsUtf8 = new TextDecoder().decode(entries[`kronosys-sessions-${stamp}.csv`]);
+    expect(sessionsUtf8).toContain("sessionId");
+    expect(sessionsUtf8).toContain("s-hist");
+  });
+
+  it("buildStoreJsonBlobsCsv inclut cfg et métadonnées de tableau de bord", () => {
+    const csv = buildStoreJsonBlobsCsv(samplePayload());
+    expect(csv.startsWith("blobKind,json\n")).toBe(true);
+    expect(csv).toContain("autoStart");
+    expect(csv).toContain("inspectingSessionId");
+    expect(csv).toContain("s-hist");
+  });
+});