@nightkatana/kronosys-app 1.0.0-beta.0

package/components/dashboard/PageRefreshButton.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import { Loader2, RotateCw } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+
+export type PageRefreshInlineMessages = {
+  loading: string;
+  success: string;
+  error: string;
+};
+
+type BannerPhase = "idle" | "loading" | "success" | "error";
+
+const BANNER_DISMISS_MS = 2800;
+
+export function PageRefreshButton({
+  title,
+  ariaLabel,
+  onRefresh,
+  className = "",
+  inlineMessages,
+}: {
+  title: string;
+  ariaLabel: string;
+  /** Recharge les données (ex. `fetchKronosysState`) ; renvoyer `false` signale un échec. */
+  onRefresh: () => boolean | void | Promise<boolean | void>;
+  className?: string;
+  /** Si défini, affiche un court libellé sous le bouton (vert / ambre) au lieu d’un toast global. */
+  inlineMessages?: PageRefreshInlineMessages;
+}) {
+  const [loading, setLoading] = useState(false);
+  const [bannerPhase, setBannerPhase] = useState<BannerPhase>("idle");
+  const clearBannerTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (clearBannerTimerRef.current) {
+        clearTimeout(clearBannerTimerRef.current);
+      }
+    },
+    []
+  );
+
+  const scheduleBannerClear = () => {
+    if (clearBannerTimerRef.current) {
+      clearTimeout(clearBannerTimerRef.current);
+    }
+    clearBannerTimerRef.current = setTimeout(() => {
+      setBannerPhase("idle");
+      clearBannerTimerRef.current = null;
+    }, BANNER_DISMISS_MS);
+  };
+
+  const handleRefresh = async () => {
+    if (inlineMessages) {
+      if (clearBannerTimerRef.current) {
+        clearTimeout(clearBannerTimerRef.current);
+        clearBannerTimerRef.current = null;
+      }
+      setBannerPhase("loading");
+    }
+    setLoading(true);
+    const t0 = Date.now();
+    let ok = true;
+    try {
+      const r = await onRefresh();
+      ok = r !== false;
+    } catch {
+      ok = false;
+    } finally {
+      const minMs = 400;
+      const wait = minMs - (Date.now() - t0);
+      if (wait > 0) {
+        await new Promise((r) => setTimeout(r, wait));
+      }
+      if (inlineMessages) {
+        setBannerPhase(ok ? "success" : "error");
+        scheduleBannerClear();
+      }
+      setLoading(false);
+    }
+  };
+
+  let bannerLabel = "";
+  if (inlineMessages) {
+    if (bannerPhase === "loading") {
+      bannerLabel = inlineMessages.loading;
+    } else if (bannerPhase === "success") {
+      bannerLabel = inlineMessages.success;
+    } else if (bannerPhase === "error") {
+      bannerLabel = inlineMessages.error;
+    }
+  }
+
+  const showBanner = Boolean(inlineMessages) && bannerPhase !== "idle" && bannerLabel;
+
+  const bannerCls =
+    bannerPhase === "loading" || bannerPhase === "success"
+      ? "border border-emerald-400/60 bg-emerald-50 text-emerald-950 shadow-sm dark:border-emerald-500/45 dark:bg-emerald-950/75 dark:text-emerald-50"
+      : "border border-amber-400/60 bg-amber-50 text-amber-950 shadow-sm dark:border-amber-600/40 dark:bg-amber-950/70 dark:text-amber-100";
+
+  return (
+    <div className="relative inline-flex flex-col items-end">
+      <button
+        type="button"
+        className={`inline-flex size-10 shrink-0 items-center justify-center rounded-lg border border-zinc-300 bg-white text-zinc-700 shadow-sm transition hover:border-zinc-400 hover:bg-zinc-50 disabled:opacity-50 dark:border-zinc-600 dark:bg-zinc-800/90 dark:text-zinc-200 dark:hover:border-zinc-500 dark:hover:bg-zinc-800 ${className}`}
+        onClick={() => void handleRefresh()}
+        disabled={loading}
+        title={title}
+        aria-label={ariaLabel}
+        aria-busy={loading ? "true" : "false"}
+      >
+        {loading ? (
+          <Loader2 size={18} className="animate-spin text-violet-600 dark:text-violet-400" aria-hidden />
+        ) : (
+          <RotateCw size={18} aria-hidden />
+        )}
+      </button>
+      {showBanner && (
+        <div
+          role="status"
+          aria-live="polite"
+          className={`pointer-events-none absolute right-0 top-full z-[70] mt-1.5 w-max max-w-[min(calc(100vw-2rem),32rem)] whitespace-normal rounded-md px-2.5 py-1.5 text-right text-[0.8125rem] font-medium leading-snug ${bannerCls}`}
+        >
+          {bannerLabel}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/dashboard/PlainHelpPopover.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import { useEffect, useId, useRef, useState, type CSSProperties } from "react";
+import { createPortal } from "react-dom";
+import { CircleHelp } from "lucide-react";
+import { useAnchoredFloatingPortalStyle } from "./useAnchoredFloatingPortalStyle";
+
+const PANEL_PLACEHOLDER_STYLE: CSSProperties = {
+  position: "fixed",
+  top: 0,
+  left: 0,
+  width: 320,
+  zIndex: 80,
+  visibility: "hidden",
+  pointerEvents: "none",
+};
+
+/**
+ * Bouton (?) qui ouvre un panneau : rendu en portail fixe pour éviter le clip des rangées
+ * `overflow-x-auto` (plus de zone scroll « popover »).
+ */
+export function PlainHelpPopover({
+  ariaLabel,
+  body,
+  compact = true,
+}: {
+  ariaLabel: string;
+  /** Texte du panneau (paragraphes séparés par \\n\\n si besoin). */
+  body: string;
+  compact?: boolean;
+}) {
+  const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const id = useId();
+
+  const panelStyle = useAnchoredFloatingPortalStyle(open, triggerRef, panelRef, {
+    align: "start",
+    maxWidthRem: 20,
+  });
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const onDoc = (e: MouseEvent) => {
+      const t = e.target as Node;
+      if (!triggerRef.current?.contains(t) && !panelRef.current?.contains(t)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", onDoc);
+    return () => document.removeEventListener("mousedown", onDoc);
+  }, [open]);
+
+  const icon = compact ? 11 : 18;
+
+  const mergedStyle = panelStyle ?? (open ? PANEL_PLACEHOLDER_STYLE : undefined);
+
+  const panel =
+    open && typeof document !== "undefined" && mergedStyle
+      ? createPortal(
+          <div
+            ref={panelRef}
+            id={`${id}-plain-help`}
+            style={mergedStyle}
+            className="rounded-lg border border-zinc-200 bg-white p-2.5 text-left shadow-xl dark:border-zinc-600 dark:bg-zinc-900"
+            role="region"
+            aria-label={ariaLabel}
+          >
+            <p className="whitespace-pre-line text-[0.7rem] leading-snug text-zinc-700 dark:text-zinc-300">
+              {body.trim()}
+            </p>
+          </div>,
+          document.body
+        )
+      : null;
+
+  return (
+    <div
+      className={`relative flex shrink-0 items-center justify-center self-center ${compact ? "h-5 min-w-5" : "h-10"}`}
+      ref={triggerRef}
+    >
+      <button
+        type="button"
+        className={`text-zinc-500 hover:bg-zinc-200/90 hover:text-zinc-800 dark:hover:bg-zinc-800 dark:hover:text-zinc-300 ${compact ? "flex size-full items-center justify-center rounded-sm p-0" : "rounded-md p-1.5"}`}
+        aria-label={ariaLabel}
+        aria-expanded={open ? "true" : "false"}
+        aria-controls={`${id}-plain-help`}
+        onClick={() => setOpen((o) => !o)}
+      >
+        <CircleHelp size={icon} strokeWidth={1.75} aria-hidden />
+      </button>
+      {panel}
+    </div>
+  );
+}

package/components/dashboard/ReportingPageToc.tsx

@@ -0,0 +1,68 @@
+type ReportingTocEntry = Readonly<{ id: string; label: string }>;
+
+export function ReportingPageTocMobile({
+  title,
+  ariaLabel,
+  entries,
+}: Readonly<{
+  title: string;
+  ariaLabel: string;
+  entries: readonly ReportingTocEntry[];
+}>) {
+  if (entries.length === 0) {
+    return null;
+  }
+  return (
+    <nav aria-label={ariaLabel} className="mb-6 lg:hidden">
+      <h2 className="mb-2 text-xs font-semibold uppercase tracking-wide text-zinc-500">{title}</h2>
+      <ul className="flex flex-wrap gap-2">
+        {entries.map((e) => (
+          <li key={e.id}>
+            <a
+              href={`#${e.id}`}
+              className="inline-block max-w-full rounded-md border border-zinc-300 bg-white px-2.5 py-1.5 text-xs leading-snug text-zinc-700 underline-offset-2 hover:border-violet-500/55 hover:text-violet-800 dark:border-zinc-700/90 dark:bg-zinc-900/80 dark:text-zinc-300 dark:hover:text-violet-200"
+            >
+              {e.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}
+
+export function ReportingPageTocDesktop({
+  title,
+  ariaLabel,
+  entries,
+}: Readonly<{
+  title: string;
+  ariaLabel: string;
+  entries: readonly ReportingTocEntry[];
+}>) {
+  if (entries.length === 0) {
+    return null;
+  }
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className="hidden lg:block lg:shrink-0 lg:self-start lg:border-l lg:border-zinc-200 lg:pl-5 xl:pl-6 dark:lg:border-zinc-800"
+    >
+      <div className="sticky top-28">
+        <h2 className="mb-3 text-xs font-semibold uppercase tracking-wide text-zinc-500">{title}</h2>
+        <ul className="space-y-0.5">
+          {entries.map((e) => (
+            <li key={e.id}>
+              <a
+                href={`#${e.id}`}
+                className="block rounded-r-md py-1.5 pl-2 text-sm leading-snug text-zinc-600 underline-offset-2 hover:bg-zinc-200/70 hover:text-violet-800 dark:text-zinc-400 dark:hover:bg-zinc-800/50 dark:hover:text-violet-200"
+              >
+                {e.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </nav>
+  );
+}

package/components/dashboard/ReportingTour.tsx

@@ -0,0 +1,342 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+} from "react";
+import { createPortal } from "react-dom";
+import { markReportingTourCompleted } from "@/lib/dashboardTourStorage";
+import type { DashboardStrings } from "@/lib/dashboardCopy";
+
+const INTRO_SELECTOR = "#reporting-tour-anchor-intro";
+const FILTERS_SELECTOR = "#report-filters";
+const KPI_SELECTOR = "#report-summary-kpis";
+const CHART_SELECTOR = "#report-chart-sessions";
+const TAG_TIME_SELECTOR = "#report-tag-time";
+/** Conteneur principal (contenu + sommaire) : repère stable sur tous les écrans. */
+const TOC_LAYOUT_SELECTOR = "#reporting-tour-anchor-toc-layout";
+
+const HOLE_PADDING_PX = 10;
+const TOOLTIP_MAX_W = 360;
+const VIEW_MARGIN = 12;
+const TOOLTIP_GAP = 12;
+
+function useEscapeDismiss(open: boolean, onDismiss: () => void) {
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onDismiss();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, onDismiss]);
+}
+
+type HoleRect = { top: number; left: number; width: number; height: number };
+
+function expandRect(r: DOMRect, pad: number): HoleRect {
+  return {
+    top: r.top - pad,
+    left: r.left - pad,
+    width: r.width + 2 * pad,
+    height: r.height + 2 * pad,
+  };
+}
+
+export function ReportingTour({
+  open,
+  onOpenChange,
+  dt,
+  hasReportingChartData,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  dt: DashboardStrings;
+  /** Inclut les étapes graphiques et temps par étiquette (sinon elles sont omises). */
+  hasReportingChartData: boolean;
+}) {
+  const [step, setStep] = useState(0);
+  const [hole, setHole] = useState<HoleRect | null>(null);
+  const [tipStyle, setTipStyle] = useState<CSSProperties>({});
+  const panelRef = useRef<HTMLDivElement>(null);
+  const primaryBtnRef = useRef<HTMLButtonElement>(null);
+
+  const { selectors, steps } = useMemo(() => {
+    const s = [
+      { title: dt.reportingTourStep1Title, body: dt.reportingTourStep1Body },
+      { title: dt.reportingTourStep2Title, body: dt.reportingTourStep2Body },
+      { title: dt.reportingTourStep3Title, body: dt.reportingTourStep3Body },
+    ];
+    const sel = [INTRO_SELECTOR, FILTERS_SELECTOR, KPI_SELECTOR];
+    if (hasReportingChartData) {
+      s.push(
+        { title: dt.reportingTourStep4Title, body: dt.reportingTourStep4Body },
+        { title: dt.reportingTourStep5Title, body: dt.reportingTourStep5Body }
+      );
+      sel.push(CHART_SELECTOR, TAG_TIME_SELECTOR);
+    }
+    s.push({ title: dt.reportingTourStep6Title, body: dt.reportingTourStep6Body });
+    sel.push(TOC_LAYOUT_SELECTOR);
+    return { selectors: sel, steps: s };
+  }, [dt, hasReportingChartData]);
+
+  const total = steps.length;
+  const last = step >= total - 1;
+  const current = steps[step] ?? steps[0];
+  const selector = selectors[Math.min(step, selectors.length - 1)];
+
+  useEffect(() => {
+    if (open) {
+      setStep(0);
+    }
+  }, [open]);
+
+  const finish = useCallback(() => {
+    markReportingTourCompleted();
+    onOpenChange(false);
+  }, [onOpenChange]);
+
+  useEscapeDismiss(open, finish);
+
+  const updateHoleFromDom = useCallback(() => {
+    if (!open) {
+      setHole(null);
+      return;
+    }
+    const el = document.querySelector(selector);
+    if (!el || !(el instanceof HTMLElement)) {
+      setHole(null);
+      return;
+    }
+    setHole(expandRect(el.getBoundingClientRect(), HOLE_PADDING_PX));
+  }, [open, selector]);
+
+  useLayoutEffect(() => {
+    if (!open) {
+      setHole(null);
+      return;
+    }
+    const el = document.querySelector(selector);
+    if (el instanceof HTMLElement) {
+      el.scrollIntoView({ block: "center", inline: "nearest", behavior: "auto" });
+    }
+    updateHoleFromDom();
+    const raf = requestAnimationFrame(updateHoleFromDom);
+    window.addEventListener("scroll", updateHoleFromDom, true);
+    window.addEventListener("resize", updateHoleFromDom);
+    const observed = el instanceof HTMLElement ? el : null;
+    const ro =
+      observed && typeof ResizeObserver !== "undefined"
+        ? new ResizeObserver(() => updateHoleFromDom())
+        : null;
+    if (observed && ro) {
+      ro.observe(observed);
+    }
+    return () => {
+      cancelAnimationFrame(raf);
+      window.removeEventListener("scroll", updateHoleFromDom, true);
+      window.removeEventListener("resize", updateHoleFromDom);
+      ro?.disconnect();
+    };
+  }, [open, selector, step, updateHoleFromDom]);
+
+  useLayoutEffect(() => {
+    if (!open) {
+      return;
+    }
+    const vw = typeof window !== "undefined" ? window.innerWidth : 1024;
+    const vh = typeof window !== "undefined" ? window.innerHeight : 768;
+    const w = Math.min(TOOLTIP_MAX_W, vw - 2 * VIEW_MARGIN);
+
+    if (!hole) {
+      setTipStyle({
+        position: "fixed",
+        top: "50%",
+        left: "50%",
+        transform: "translate(-50%, -50%)",
+        width: w,
+        maxWidth: "calc(100vw - 2rem)",
+        zIndex: 212,
+      });
+      return;
+    }
+
+    const panel = panelRef.current;
+    const ph = panel?.getBoundingClientRect().height ?? 220;
+
+    let top = hole.top + hole.height + TOOLTIP_GAP;
+    if (top + ph > vh - VIEW_MARGIN && hole.top - TOOLTIP_GAP - ph >= VIEW_MARGIN) {
+      top = hole.top - TOOLTIP_GAP - ph;
+    }
+    top = Math.max(VIEW_MARGIN, Math.min(top, vh - ph - VIEW_MARGIN));
+
+    let left = hole.left + hole.width / 2 - w / 2;
+    left = Math.max(VIEW_MARGIN, Math.min(left, vw - w - VIEW_MARGIN));
+
+    setTipStyle({
+      position: "fixed",
+      top,
+      left,
+      transform: undefined,
+      width: w,
+      maxWidth: undefined,
+      zIndex: 212,
+    });
+  }, [open, hole, step, current.title, current.body]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const t = window.setTimeout(() => primaryBtnRef.current?.focus(), 80);
+    return () => window.clearTimeout(t);
+  }, [open, step]);
+
+  if (!open) {
+    return null;
+  }
+
+  const progressLabel = dt.reportingTourProgressLabel
+    .replace("{n}", String(step + 1))
+    .replace("{total}", String(total));
+
+  const secondaryBtn =
+    "rounded-lg border border-zinc-300 bg-white px-4 py-2 text-sm font-medium text-zinc-800 transition hover:bg-zinc-50 dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-200 dark:hover:bg-zinc-700";
+  const primaryBtn =
+    "rounded-lg bg-violet-600 px-4 py-2 text-sm font-medium text-white transition hover:bg-violet-700 focus:outline-none focus:ring-2 focus:ring-violet-500 focus:ring-offset-2 dark:bg-violet-500 dark:hover:bg-violet-600 dark:focus:ring-offset-zinc-900";
+
+  const vw = typeof window !== "undefined" ? window.innerWidth : 0;
+  const vh = typeof window !== "undefined" ? window.innerHeight : 0;
+
+  const fullBackdrop = !hole ? (
+    <div className="fixed inset-0 z-[210] bg-black/55" aria-hidden />
+  ) : null;
+
+  const dimPanels =
+    hole && vw > 0 && vh > 0
+      ? (() => {
+          const { top: t, left: l, width: w, height: h } = hole;
+          const topH = Math.max(0, t);
+          const bottomTop = t + h;
+          const bottomH = Math.max(0, vh - bottomTop);
+          const leftW = Math.max(0, l);
+          const rightLeft = l + w;
+          const rightW = Math.max(0, vw - rightLeft);
+          return (
+            <>
+              <div
+                className="fixed bg-black/55"
+                style={{ top: 0, left: 0, width: vw, height: topH, zIndex: 210 }}
+                aria-hidden
+              />
+              <div
+                className="fixed bg-black/55"
+                style={{ top: bottomTop, left: 0, width: vw, height: bottomH, zIndex: 210 }}
+                aria-hidden
+              />
+              <div
+                className="fixed bg-black/55"
+                style={{ top: t, left: 0, width: leftW, height: h, zIndex: 210 }}
+                aria-hidden
+              />
+              <div
+                className="fixed bg-black/55"
+                style={{ top: t, left: rightLeft, width: rightW, height: h, zIndex: 210 }}
+                aria-hidden
+              />
+              <div
+                className="pointer-events-none fixed rounded-xl border-2 border-violet-500 shadow-[0_0_0_1px_rgba(139,92,246,0.35)] dark:border-violet-400 dark:shadow-[0_0_0_1px_rgba(167,139,250,0.35)]"
+                style={{
+                  top: t,
+                  left: l,
+                  width: w,
+                  height: h,
+                  zIndex: 211,
+                }}
+                aria-hidden
+              />
+            </>
+          );
+        })()
+      : null;
+
+  const node = createPortal(
+    <>
+      {fullBackdrop}
+      {dimPanels}
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="reporting-tour-title"
+        aria-describedby="reporting-tour-body"
+        className="rounded-xl border border-zinc-300 bg-white shadow-2xl dark:border-zinc-600 dark:bg-zinc-900"
+        style={tipStyle}
+        onMouseDown={(e) => e.stopPropagation()}
+      >
+        <div className="border-b border-zinc-200 px-4 py-3 dark:border-zinc-700">
+          <p className="text-xs font-medium uppercase tracking-wide text-violet-600 dark:text-violet-300">
+            {progressLabel}
+          </p>
+          <h2 id="reporting-tour-title" className="mt-1 text-base font-semibold text-zinc-900 dark:text-zinc-100">
+            {current.title}
+          </h2>
+        </div>
+        <div id="reporting-tour-body" className="max-h-[min(42vh,18rem)] overflow-y-auto px-4 py-3">
+          <p className="whitespace-pre-wrap text-sm leading-relaxed text-zinc-700 dark:text-zinc-300">{current.body}</p>
+        </div>
+        <div className="flex flex-wrap items-center justify-between gap-2 border-t border-zinc-200 px-4 py-3 dark:border-zinc-700">
+          <div className="flex gap-1.5" role="presentation" aria-hidden>
+            {steps.map((_, i) => (
+              <span
+                key={i}
+                className={`h-2 w-2 rounded-full ${i === step ? "bg-violet-500 dark:bg-violet-400" : "bg-zinc-300 dark:bg-zinc-600"}`}
+              />
+            ))}
+          </div>
+          <div className="flex flex-wrap items-center justify-end gap-2">
+            <button
+              type="button"
+              className="text-sm text-zinc-500 underline-offset-2 hover:text-zinc-800 hover:underline dark:text-zinc-400 dark:hover:text-zinc-200"
+              onClick={finish}
+            >
+              {dt.tourSkipBtn}
+            </button>
+            {step > 0 ? (
+              <button type="button" className={secondaryBtn} onClick={() => setStep((s) => Math.max(0, s - 1))}>
+                {dt.tourBackBtn}
+              </button>
+            ) : null}
+            {last ? (
+              <button ref={primaryBtnRef} type="button" className={primaryBtn} onClick={finish}>
+                {dt.tourDoneBtn}
+              </button>
+            ) : (
+              <button
+                ref={primaryBtnRef}
+                type="button"
+                className={primaryBtn}
+                onClick={() => setStep((s) => Math.min(total - 1, s + 1))}
+              >
+                {dt.tourNextBtn}
+              </button>
+            )}
+          </div>
+        </div>
+      </div>
+    </>,
+    document.body
+  );
+
+  return node;
+}