@creezio/interactive-demo 0.22.0

package/ui/demo-root.tsx

@@ -0,0 +1,312 @@
+"use client";
+
+/**
+ * Racine de la démo interactive — à monter une fois dans le chrome de la
+ * marque (layout / BrandChrome). Charge les scénarios depuis le mount
+ * `/api/v1/modules/interactive-demo`, lance automatiquement le scénario
+ * `autoStart` à la première visite (après setup/onboarding), affiche le
+ * lanceur flottant « Visite guidée » et écoute l'événement
+ * `creezio-interactive-demo` pour un déclenchement programmatique.
+ *
+ * « Déjà vu » : localStorage (immédiat) + preferences serveur (par
+ * utilisateur, si `userKey` fourni) — best effort, jamais bloquant.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { DemoScenario } from "@creezio/interactive-demo";
+import { scenarioMatchesRole } from "@creezio/interactive-demo";
+import { registerSidebarActionsProvider } from "@creezio/shell-ui/ui";
+import { DemoPlayer } from "./demo-player";
+
+/** Icône du lanceur (play) — inline : lucide-react est un peer optionnel. */
+function LauncherIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className={className}
+    >
+      <path d="M5 3l14 9-14 9V3z" />
+    </svg>
+  );
+}
+
+export const INTERACTIVE_DEMO_EVENT = "creezio-interactive-demo";
+
+/** Déclenche la démo depuis n'importe où (bouton marque, page d'aide…). */
+export function startInteractiveDemo(scenarioId?: string) {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(
+    new CustomEvent(INTERACTIVE_DEMO_EVENT, { detail: { scenarioId } }),
+  );
+}
+
+export type InteractiveDemoRootProps = {
+  /** Base du mount api-kernel (défaut `/api/v1/modules/interactive-demo`). */
+  apiBase?: string;
+  /** Navigation SPA (ex. `router.push` Next) — fortement recommandé. */
+  navigate?: (href: string) => void;
+  /** Clé utilisateur pour la persistance serveur du « déjà vu ». */
+  userKey?: string | null;
+  /**
+   * Rôle de l'utilisateur courant : le lanceur et l'autoStart ne proposent
+   * que les scénarios sans `roles` ou dont `roles` inclut ce rôle.
+   * `null`/`undefined` = pas de filtrage (comportement historique). Un
+   * lancement explicite (`startInteractiveDemo(id)`) ignore ce filtre.
+   */
+  role?: string | null;
+  /** Lancement auto du scénario `autoStart` à la première visite (défaut true). */
+  autoStart?: boolean;
+  /** Affiche le bouton flottant « Visite guidée » (défaut true). */
+  showLauncher?: boolean;
+  /**
+   * Placement du lanceur : "floating" = bouton flottant historique (défaut,
+   * rétrocompatible) ; "sidebar" = entrée d'action dans la sidebar kit
+   * (registre @creezio/shell-ui — visible uniquement dans le workspace
+   * authentifié, jamais sur /login) ; "none" = aucun lanceur (déclenchement
+   * uniquement via `startInteractiveDemo()`).
+   */
+  launcher?: "floating" | "sidebar" | "none";
+  /** Libellé du lanceur. */
+  launcherLabel?: string;
+  /** Scénarios injectés (tests / offline) — court-circuite le fetch. */
+  scenarios?: DemoScenario[];
+  /** Badge du faux curseur (défaut « Démo »). */
+  cursorLabel?: string;
+};
+
+function seenStorageKey(id: string) {
+  return `creezio-demo-seen:${id}`;
+}
+
+function hasSeenLocally(id: string): boolean {
+  try {
+    return window.localStorage.getItem(seenStorageKey(id)) != null;
+  } catch {
+    return false;
+  }
+}
+
+function markSeenLocally(id: string) {
+  try {
+    window.localStorage.setItem(seenStorageKey(id), new Date().toISOString());
+  } catch {
+    /* stockage indisponible — le serveur garde la trace */
+  }
+}
+
+export function InteractiveDemoRoot({
+  apiBase = "/api/v1/modules/interactive-demo",
+  navigate,
+  userKey,
+  role,
+  autoStart = true,
+  showLauncher = true,
+  launcher = "floating",
+  launcherLabel = "Visite guidée",
+  scenarios: injected,
+  cursorLabel,
+}: InteractiveDemoRootProps) {
+  const [scenarios, setScenarios] = useState<DemoScenario[]>(injected ?? []);
+  const [active, setActive] = useState<DemoScenario | null>(null);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const autoStartedRef = useRef(false);
+  const serverSeenRef = useRef<Set<string>>(new Set());
+
+  const enabled = scenarios.filter((s) => s.enabled !== false && s.steps.length > 0);
+  /* Lanceur + autoStart : scénarios visibles pour le rôle courant. */
+  const visible = enabled.filter((s) => scenarioMatchesRole(s, role));
+
+  /* Chargement des scénarios + « déjà vu » serveur. */
+  useEffect(() => {
+    if (injected) {
+      setScenarios(injected);
+      return;
+    }
+    let disposed = false;
+    (async () => {
+      try {
+        const res = await fetch(`${apiBase}/scenarios`);
+        if (!res.ok) return;
+        const data = (await res.json()) as { scenarios?: DemoScenario[] };
+        if (!disposed && Array.isArray(data.scenarios)) {
+          setScenarios(data.scenarios);
+        }
+      } catch {
+        /* mount absent — pas de démo */
+      }
+      if (disposed || !userKey) return;
+      try {
+        const res = await fetch(
+          `${apiBase}/preferences?user=${encodeURIComponent(userKey)}`,
+        );
+        if (!res.ok) return;
+        const data = (await res.json()) as { answers?: Record<string, unknown> };
+        if (!disposed && data.answers) {
+          for (const key of Object.keys(data.answers)) {
+            if (key.startsWith("seen:")) {
+              serverSeenRef.current.add(key.slice("seen:".length));
+            }
+          }
+        }
+      } catch {
+        /* préférences indisponibles — localStorage suffit */
+      }
+    })();
+    return () => {
+      disposed = true;
+    };
+  }, [apiBase, injected, userKey]);
+
+  const markSeen = useCallback(
+    (id: string) => {
+      markSeenLocally(id);
+      serverSeenRef.current.add(id);
+      if (!userKey) return;
+      fetch(`${apiBase}/preferences`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          user: userKey,
+          answers: { [`seen:${id}`]: new Date().toISOString() },
+        }),
+        keepalive: true,
+      }).catch(() => {
+        /* best effort */
+      });
+    },
+    [apiBase, userKey],
+  );
+
+  const start = useCallback(
+    (scenarioId?: string) => {
+      setMenuOpen(false);
+      const list = scenarios.filter((s) => s.enabled !== false && s.steps.length > 0);
+      // Id explicite (startInteractiveDemo) : lancement forcé, sans filtre rôle.
+      if (scenarioId) {
+        const scenario = list.find((s) => s.id === scenarioId);
+        if (scenario) setActive(scenario);
+        return;
+      }
+      const candidates = list.filter((s) => scenarioMatchesRole(s, role));
+      const scenario = candidates.find((s) => s.autoStart) ?? candidates[0];
+      if (scenario) setActive(scenario);
+    },
+    [scenarios, role],
+  );
+
+  /* Déclenchement programmatique. */
+  useEffect(() => {
+    const onEvent = (e: Event) => {
+      const detail = (e as CustomEvent<{ scenarioId?: string }>).detail;
+      start(detail?.scenarioId);
+    };
+    window.addEventListener(INTERACTIVE_DEMO_EVENT, onEvent);
+    return () => window.removeEventListener(INTERACTIVE_DEMO_EVENT, onEvent);
+  }, [start]);
+
+  /* Lancement auto à la première visite. */
+  useEffect(() => {
+    if (!autoStart || autoStartedRef.current || active) return;
+    const candidate = visible.find((s) => s.autoStart);
+    if (!candidate) return;
+    if (hasSeenLocally(candidate.id) || serverSeenRef.current.has(candidate.id)) {
+      return;
+    }
+    autoStartedRef.current = true;
+    const timer = setTimeout(() => setActive(candidate), 1400);
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoStart, active, scenarios, role]);
+
+  /* Lanceur « sidebar » : entrée d'action dans la sidebar kit dès qu'un
+     scénario est proposable pour le rôle courant. L'entrée reste visible
+     même pendant une lecture (cliquer relance proprement via start()). Le
+     provider est relu à chaque (ré)enregistrement — garder la closure pure. */
+  useEffect(() => {
+    if (launcher !== "sidebar" || visible.length === 0) return;
+    return registerSidebarActionsProvider(() => [
+      {
+        id: "interactive-demo",
+        label: launcherLabel,
+        icon: LauncherIcon,
+        onSelect: () => start(),
+      },
+    ]);
+  }, [launcher, launcherLabel, visible.length, start]);
+
+  const stop = useCallback(
+    (finished: boolean) => {
+      if (active) markSeen(active.id);
+      void finished;
+      setActive(null);
+    },
+    [active, markSeen],
+  );
+
+  if (active) {
+    return (
+      <DemoPlayer
+        scenario={active}
+        navigate={navigate}
+        cursorLabel={cursorLabel}
+        onFinish={() => stop(true)}
+        onExit={() => stop(false)}
+      />
+    );
+  }
+
+  if (launcher !== "floating" || !showLauncher || visible.length === 0) {
+    return null;
+  }
+
+  return (
+    <div data-creezio-demo-ui="1">
+      {menuOpen && visible.length > 1 ? (
+        <div className="creezio-demo-launcher-menu">
+          {visible.map((s) => (
+            <button
+              key={s.id}
+              type="button"
+              className="creezio-demo-launcher-item"
+              onClick={() => start(s.id)}
+            >
+              <p className="creezio-demo-launcher-item-title">{s.title}</p>
+              {s.description ? (
+                <p className="creezio-demo-launcher-item-desc">{s.description}</p>
+              ) : null}
+            </button>
+          ))}
+        </div>
+      ) : null}
+      <button
+        type="button"
+        className="creezio-demo-launcher"
+        onClick={() =>
+          visible.length > 1 ? setMenuOpen((v) => !v) : start(visible[0]!.id)
+        }
+        aria-label={launcherLabel}
+      >
+        <svg
+          width="15"
+          height="15"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M5 3l14 9-14 9V3z" />
+        </svg>
+        {launcherLabel}
+      </button>
+    </div>
+  );
+}

package/ui/dom.ts

@@ -0,0 +1,280 @@
+/**
+ * Utilitaires DOM du lecteur de démo : résolution des cibles (`DemoTarget` :
+ * sélecteur CSS, `data-aid` shell-ui, libellé d'élément interactif),
+ * événements synthétiques (clic pointeur complet, frappe caractère par
+ * caractère compatible React) et déplacement du faux curseur.
+ */
+
+import type { DemoTarget } from "@creezio/interactive-demo";
+import { resolveAidAttr } from "@creezio/shell-ui/ui";
+import { getDemoCursor } from "./fake-cursor";
+
+export const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+function interactiveSelector(): string {
+  return [
+    "a[href]",
+    "button",
+    '[role="button"]',
+    '[role="option"]',
+    '[role="menuitem"]',
+    '[role="tab"]',
+    '[role="combobox"]',
+    'input:not([type="hidden"])',
+    "select",
+    "textarea",
+    `[${resolveAidAttr()}]`,
+  ].join(", ");
+}
+
+export function isVisible(el: Element): boolean {
+  if (el.closest("[data-creezio-demo-ui]")) return false;
+  if (el.closest('[aria-hidden="true"]')) return false;
+  const he = el as HTMLElement;
+  if (he.hidden) return false;
+  if ((he as HTMLButtonElement).disabled) return false;
+  const rect = el.getBoundingClientRect();
+  if (rect.width < 4 || rect.height < 4) return false;
+  const margin = 400;
+  if (
+    rect.bottom < -margin ||
+    rect.top > window.innerHeight + margin ||
+    rect.right < -margin ||
+    rect.left > window.innerWidth + margin
+  ) {
+    return false;
+  }
+  const style = window.getComputedStyle(el);
+  if (style.visibility === "hidden" || style.display === "none") return false;
+  return true;
+}
+
+function normalize(s: string): string {
+  return s
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function labelFor(el: Element): string {
+  const he = el as HTMLElement;
+  const aria = he.getAttribute("aria-label");
+  if (aria?.trim()) return aria.trim();
+  const title = he.getAttribute("title");
+  if (title?.trim()) return title.trim();
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    const ph = el.placeholder?.trim();
+    if (ph) return ph;
+    if (el.name) return el.name;
+  }
+  const text = (he.innerText || he.textContent || "").replace(/\s+/g, " ").trim();
+  return text.slice(0, 90);
+}
+
+function scope(within?: string): ParentNode {
+  if (within) {
+    const root = document.querySelector(within);
+    if (root) return root;
+  }
+  return document;
+}
+
+function findByText(text: string, within?: string): Element | null {
+  const needle = normalize(text);
+  if (!needle) return null;
+  let partial: Element | null = null;
+  for (const el of Array.from(scope(within).querySelectorAll(interactiveSelector()))) {
+    if (!isVisible(el)) continue;
+    const label = normalize(labelFor(el));
+    if (!label) continue;
+    if (label === needle) return el;
+    if (!partial && (label.includes(needle) || needle.includes(label))) partial = el;
+  }
+  return partial;
+}
+
+function findByAid(aid: string, within?: string): Element | null {
+  const attr = resolveAidAttr();
+  const needle = normalize(aid);
+  for (const el of Array.from(scope(within).querySelectorAll(`[${attr}]`))) {
+    if (normalize(el.getAttribute(attr) || "") === needle && isVisible(el)) return el;
+  }
+  return null;
+}
+
+function findBySelector(selector: string, within?: string): Element | null {
+  try {
+    for (const el of Array.from(scope(within).querySelectorAll(selector))) {
+      if (isVisible(el)) return el;
+    }
+  } catch {
+    /* sélecteur invalide → autres stratégies */
+  }
+  return null;
+}
+
+/** Résolution ponctuelle d'une cible (null si introuvable/invisible). */
+export function resolveDemoTarget(target: DemoTarget): Element | null {
+  if (typeof target === "string") {
+    return (
+      findBySelector(target) || findByAid(target) || findByText(target)
+    );
+  }
+  const { selector, aid, text, within } = target;
+  if (selector) {
+    const el = findBySelector(selector, within);
+    if (el) return el;
+  }
+  if (aid) {
+    const el = findByAid(aid, within);
+    if (el) return el;
+  }
+  if (text) {
+    const el = findByText(text, within);
+    if (el) return el;
+  }
+  return null;
+}
+
+/**
+ * Attend la cible (polling 150 ms) — les pages App Router chargent en
+ * asynchrone. Renvoie null au timeout, jamais de throw.
+ */
+export async function waitForDemoTarget(
+  target: DemoTarget,
+  timeoutMs = 6000,
+  isCancelled?: () => boolean,
+): Promise<Element | null> {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  for (;;) {
+    if (isCancelled?.()) return null;
+    const el = resolveDemoTarget(target);
+    if (el) return el;
+    if (Date.now() >= deadline) return null;
+    await sleep(150);
+  }
+}
+
+/* ── Événements synthétiques (mêmes séquences que la souris réelle) ── */
+
+function pointerOpts(x: number, y: number): PointerEventInit & MouseEventInit {
+  return {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    view: window,
+    clientX: x,
+    clientY: y,
+    button: 0,
+    buttons: 1,
+    pointerId: 9002,
+    pointerType: "mouse",
+    isPrimary: true,
+  };
+}
+
+export function synthClick(el: Element, x: number, y: number) {
+  const opts = pointerOpts(x, y);
+  el.dispatchEvent(new PointerEvent("pointerover", opts));
+  el.dispatchEvent(new PointerEvent("pointerenter", { ...opts, bubbles: false }));
+  el.dispatchEvent(new PointerEvent("pointermove", opts));
+  el.dispatchEvent(new PointerEvent("pointerdown", opts));
+  el.dispatchEvent(new MouseEvent("mousedown", opts));
+  (el as HTMLElement).focus?.({ preventScroll: true });
+  el.dispatchEvent(new PointerEvent("pointerup", { ...opts, buttons: 0 }));
+  el.dispatchEvent(new MouseEvent("mouseup", { ...opts, buttons: 0 }));
+  el.dispatchEvent(new MouseEvent("click", { ...opts, buttons: 0, detail: 1 }));
+}
+
+/** Pose la valeur via le setter natif (déclenche l'onChange React). */
+export function setNativeValue(
+  el: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+) {
+  const proto =
+    el instanceof HTMLTextAreaElement
+      ? window.HTMLTextAreaElement.prototype
+      : window.HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+  if (setter) setter.call(el, value);
+  else el.value = value;
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+/** Frappe progressive avec touches simulées (vitesse plafonnée). */
+export async function typeInto(
+  el: HTMLInputElement | HTMLTextAreaElement,
+  text: string,
+  isCancelled?: () => boolean,
+) {
+  setNativeValue(el, "");
+  const perChar = Math.max(28, Math.min(75, Math.floor(2200 / Math.max(text.length, 1))));
+  let acc = "";
+  for (const ch of text) {
+    if (isCancelled?.()) return;
+    const keyOpts = { bubbles: true, cancelable: true, key: ch };
+    el.dispatchEvent(new KeyboardEvent("keydown", keyOpts));
+    acc += ch;
+    setNativeValue(el, acc);
+    el.dispatchEvent(new KeyboardEvent("keyup", keyOpts));
+    await sleep(perChar);
+  }
+}
+
+export function submitField(el: HTMLInputElement | HTMLTextAreaElement) {
+  const keyOpts = { bubbles: true, cancelable: true, key: "Enter", code: "Enter" };
+  el.dispatchEvent(new KeyboardEvent("keydown", keyOpts));
+  el.dispatchEvent(new KeyboardEvent("keyup", keyOpts));
+  el.form?.requestSubmit();
+}
+
+/** Conteneur défilant principal (layouts à scroll interne inclus). */
+export function findScrollableRoot(): Element {
+  const doc = document.scrollingElement;
+  if (doc && doc.scrollHeight > doc.clientHeight + 50) return doc;
+  let best: Element | null = null;
+  let bestArea = 0;
+  for (const el of Array.from(
+    document.querySelectorAll("main, [data-scroll-root], div"),
+  )) {
+    if (el.closest("[data-creezio-demo-ui]")) continue;
+    const he = el as HTMLElement;
+    if (he.scrollHeight <= he.clientHeight + 50) continue;
+    const style = window.getComputedStyle(he);
+    if (!/(auto|scroll)/.test(style.overflowY)) continue;
+    const rect = he.getBoundingClientRect();
+    const area = rect.width * rect.height;
+    if (area > bestArea) {
+      bestArea = area;
+      best = el;
+    }
+  }
+  return best || doc || document.documentElement;
+}
+
+/** Scroll la cible au centre si besoin puis amène le curseur dessus. */
+export async function moveCursorToElement(
+  el: Element,
+): Promise<{ x: number; y: number }> {
+  const cursor = getDemoCursor();
+  cursor.show();
+
+  let rect = el.getBoundingClientRect();
+  const outOfView =
+    rect.top < 60 ||
+    rect.bottom > window.innerHeight - 20 ||
+    rect.left < 0 ||
+    rect.right > window.innerWidth;
+  if (outOfView) {
+    el.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+    await sleep(450);
+    rect = el.getBoundingClientRect();
+  }
+
+  const x = rect.left + Math.min(rect.width / 2, 180);
+  const y = rect.top + rect.height / 2;
+  await cursor.moveTo(x, y);
+  return { x, y };
+}