@ephia/dova-sdk 1.0.0

package/src/ui/recorder/EphiaFloatingButton.tsx

@@ -0,0 +1,489 @@
+"use client";
+
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { EphiaProvider } from "../../react/provider/EphiaProvider";
+import { useOptionalEphiaContext } from "../../react/provider/EphiaContext";
+import { useEphia, useEphiaAudioLevel } from "../../react/hooks/useEphia";
+import type { EphiaStatus } from "../../react/store/types";
+import type { EphiaSessionOptions } from "../../shared/types/session";
+import type { Transport } from "../../core/transport/Transport";
+import {
+  EphiaLogo,
+  EPHIA_BRAND_PURPLE,
+  logoWidthFromHeight,
+} from "../components/EphiaLogo";
+import {
+  EPHIA_FLOATING_BUTTON_RADIUS_CSS,
+  type EphiaFloatingButtonBorderRadius,
+} from "./appearance";
+import { MinimalProcessingBars } from "./MinimalProcessingBars";
+import { StandardIntensityVisualizer } from "./StandardIntensityVisualizer";
+
+export type { EphiaFloatingButtonBorderRadius } from "./appearance";
+
+const EPHIA_APP_URL = "https://ephia.app";
+
+function EphiaExternalLinkIcon() {
+  return (
+    <svg
+      className="ephia-transcribe-poweredby-icon"
+      viewBox="0 0 24 24"
+      aria-hidden
+      focusable="false"
+    >
+      <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+      <path d="M15 3h6v6" />
+      <path d="M10 14 21 3" />
+    </svg>
+  );
+}
+
+/* ── Types ───────────────────────────────────────────────────────── */
+
+export type EphiaFloatingButtonPosition =
+  | "bottom-right"
+  | "bottom-left"
+  | "bottom-center"
+  | "top-right"
+  | "top-left"
+  | "top-center";
+export type EphiaFloatingButtonTheme = "light" | "dark";
+export type EphiaFloatingButtonSize = "S" | "M" | "L";
+export type EphiaFloatingButtonVariant = "minimal" | "standard";
+export type EphiaFloatingButtonInteractionMode = "toggle" | "push-to-talk";
+export type EphiaFloatingButtonCustomColors = {
+  /** Ink color: logo, visualiseur Standard, texte. Any valid CSS color. */
+  primary: string;
+  /** Background color. Any valid CSS color. */
+  secondary: string;
+};
+
+export interface EphiaFloatingButtonProps {
+  /**
+   * API URL. Optional override (ex. http://localhost:8000 en dev).
+   * Sans override : EPHIA_SDK_ENDPOINT, sinon https://api.ephia.app.
+   */
+  apiUrl?: string;
+  apiKey?: string;
+  bearerToken?: string;
+  clientType?: string;
+  transport?: Transport;
+  position?: EphiaFloatingButtonPosition;
+  theme?: EphiaFloatingButtonTheme;
+  size?: EphiaFloatingButtonSize;
+  variant?: EphiaFloatingButtonVariant;
+  colors?: EphiaFloatingButtonCustomColors;
+  /** Corner radius of the dictation control. Default `md`. */
+  borderRadius?: EphiaFloatingButtonBorderRadius;
+  /** Interaction model. `"toggle"` (default): click to start, click to stop. `"push-to-talk"`: hold to record, release to stop. */
+  interactionMode?: EphiaFloatingButtonInteractionMode;
+  className?: string;
+  style?: React.CSSProperties;
+  sessionOptions?: EphiaSessionOptions;
+  onError?: (error: { code: string; message: string }) => void;
+  onStatusChange?: (status: EphiaStatus) => void;
+}
+
+const SIZE_CONFIG: Record<EphiaFloatingButtonSize, { logoHeightPx: number }> = {
+  S: { logoHeightPx: 24 },
+  M: { logoHeightPx: 32 },
+  L: { logoHeightPx: 44 },
+};
+
+/** Logo légèrement réduit en pilule (full) pour l’équilibre visuel. */
+const LOGO_SCALE_WHEN_RADIUS_FULL = 0.92;
+
+const POSITION_STYLE: Record<EphiaFloatingButtonPosition, React.CSSProperties> = {
+  "bottom-right": { bottom: 24, right: 24 },
+  "bottom-left": { bottom: 24, left: 24 },
+  "bottom-center": { bottom: 24, left: "50%", transform: "translateX(-50%)" },
+  "top-right": { top: 24, right: 24 },
+  "top-left": { top: 24, left: 24 },
+  "top-center": { top: 24, left: "50%", transform: "translateX(-50%)" },
+};
+
+/* ── Inner button — requires Provider in scope ───────────────────── */
+
+interface InnerProps {
+  position: EphiaFloatingButtonPosition;
+  theme: EphiaFloatingButtonTheme;
+  size: EphiaFloatingButtonSize;
+  variant: EphiaFloatingButtonVariant;
+  borderRadius: EphiaFloatingButtonBorderRadius;
+  interactionMode: EphiaFloatingButtonInteractionMode;
+  colors?: EphiaFloatingButtonCustomColors;
+  className?: string;
+  style?: React.CSSProperties;
+  onError?: (error: { code: string; message: string }) => void;
+  onStatusChange?: (status: EphiaStatus) => void;
+}
+
+function EphiaFloatingButtonInner({
+  position,
+  theme,
+  size,
+  variant,
+  borderRadius,
+  interactionMode,
+  colors,
+  className,
+  style,
+  onError,
+  onStatusChange,
+}: InnerProps) {
+  const { status, isRecording, isProcessing, start, stop, error, activeTargetId } = useEphia();
+  const audio = useEphiaAudioLevel();
+
+  // Traitement sans micro ouvert : bouton en attente.
+  const isArming = isProcessing;
+  const voiceLevel = Math.min(1, Math.max(0, audio?.level ?? audio?.rms ?? 0));
+  const isLiveSession =
+    isRecording || (!!audio?.localAudioPublished && !!audio?.micReady);
+
+  // Callbacks — compare by value, not reference, to catch same-code re-errors
+  const lastErrorRef = useRef<{ code: string; message: string } | null>(null);
+  useEffect(() => {
+    if (error && (lastErrorRef.current?.code !== error.code || lastErrorRef.current?.message !== error.message)) {
+      lastErrorRef.current = error;
+      onError?.(error);
+    }
+  }, [error, onError]);
+
+  const lastStatusRef = useRef(status);
+  useEffect(() => {
+    if (status !== lastStatusRef.current) {
+      lastStatusRef.current = status;
+      onStatusChange?.(status);
+    }
+  }, [status, onStatusChange]);
+
+  // Screen reader status
+  const statusAnnouncement =
+    isLiveSession ? "Dictée en cours" :
+    status === "processing" ? "Traitement" :
+    status === "error" ? "Erreur de dictée" : "";
+
+  // Colors — validate non-empty strings to avoid silent CSS failures
+  const isLight = theme === "light";
+  const isValidColor = (c: string | undefined): boolean => Boolean(c?.trim());
+  const hasCustomColors = isValidColor(colors?.primary) && isValidColor(colors?.secondary);
+  const swapForLight = hasCustomColors && isLight;
+  const effectivePrimary = hasCustomColors
+    ? (swapForLight ? colors!.secondary.trim() : colors!.primary.trim())
+    : (isLight ? "#ffffff" : "#262626");
+  const effectiveSecondary = hasCustomColors
+    ? (swapForLight ? colors!.primary.trim() : colors!.secondary.trim())
+    : null;
+
+  const safeSize = (size && size in SIZE_CONFIG) ? size : "M";
+  const { logoHeightPx: baseLogoHeightPx } = SIZE_CONFIG[safeSize];
+  const logoHeightPx =
+    borderRadius === "full"
+      ? Math.round(baseLogoHeightPx * LOGO_SCALE_WHEN_RADIUS_FULL)
+      : baseLogoHeightPx;
+  const logoWidthPx = logoWidthFromHeight(logoHeightPx);
+
+  const isStandardVariant = variant === "standard";
+  const showTimer = isStandardVariant && isRecording;
+  const showProcessing = isStandardVariant && isArming && !isRecording;
+  const showStandardPrompt = isStandardVariant && !isRecording && !isArming;
+  const [sessionElapsedMs, setSessionElapsedMs] = useState(0);
+  const sessionStartRef = useRef<number | null>(null);
+  const timerMeasureRef = useRef<HTMLSpanElement | null>(null);
+  const [logoSlotWidthPx, setLogoSlotWidthPx] = useState(logoHeightPx);
+
+  useEffect(() => {
+    if (showTimer) {
+      sessionStartRef.current = Date.now();
+      setSessionElapsedMs(0);
+      const id = setInterval(() => {
+        if (sessionStartRef.current != null) setSessionElapsedMs(Date.now() - sessionStartRef.current);
+      }, 200);
+      return () => clearInterval(id);
+    }
+    sessionStartRef.current = null;
+  }, [showTimer]);
+
+  const timerLabel = useMemo(() => {
+    const s = Math.max(0, Math.floor(sessionElapsedMs / 1000));
+    return `${Math.floor(s / 60).toString().padStart(2, "0")}:${(s % 60).toString().padStart(2, "0")}`;
+  }, [sessionElapsedMs]);
+
+  // useLayoutEffect is intentional: measures DOM before paint to avoid width flicker.
+  // Only runs when recording (showTimer=true), so SSR hydration mismatch is not a concern.
+  useLayoutEffect(() => {
+    if (!showTimer) { setLogoSlotWidthPx(logoHeightPx); return; }
+    const el = timerMeasureRef.current;
+    const measured = el ? Math.ceil(el.getBoundingClientRect().width) : 0;
+    setLogoSlotWidthPx(Math.max(logoHeightPx, measured + 12));
+  }, [showTimer, timerLabel, logoHeightPx]);
+
+  const logoVariant = hasCustomColors ? "mono" : "color";
+  const waveformColor = hasCustomColors ? effectivePrimary : EPHIA_BRAND_PURPLE;
+  const radiusCss =
+    EPHIA_FLOATING_BUTTON_RADIUS_CSS[borderRadius] ?? EPHIA_FLOATING_BUTTON_RADIUS_CSS.md;
+
+  // useState initializer so SSR gives false without crashing, client gets real value on mount
+  const [reducedMotion] = useState(
+    () => typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+
+  return (
+    <div
+      className="ephia-transcribe-floating-root"
+      data-ephia-control="true"
+      style={{ ...POSITION_STYLE[position], ...style }}
+    >
+      {/* Screen-reader live region */}
+      <div
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        style={{ position: "absolute", width: 1, height: 1, overflow: "hidden", clip: "rect(0,0,0,0)", whiteSpace: "nowrap" }}
+      >
+        {statusAnnouncement}
+      </div>
+
+      {/* Inner Ephia button — same markup as the original TranscriptionButton */}
+      <div
+        className={`ephia-transcribe-root ephia-transcribe-root--${theme} ephia-transcribe-size--${size} ephia-transcribe-radius--${borderRadius}${className ? ` ${className}` : ""}`}
+        style={
+          {
+            ["--ephia-transcribe-radius" as string]: radiusCss,
+            ...(hasCustomColors
+              ? {
+                  backgroundColor: effectiveSecondary ?? undefined,
+                  ["--ephia-transcribe-ink" as string]: effectivePrimary,
+                }
+              : {}),
+          } as React.CSSProperties
+        }
+      >
+        {/* Lien externe ephia.app */}
+        <div className={`ephia-transcribe-poweredby ephia-transcribe-poweredby--${theme}`}>
+          <a
+            href={EPHIA_APP_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="ephia-transcribe-poweredby-btn"
+            aria-label="En savoir plus sur Ephia — ouvre ephia.app dans un nouvel onglet"
+            onClick={(e) => e.stopPropagation()}
+            onPointerDown={(e) => e.stopPropagation()}
+          >
+            <EphiaExternalLinkIcon />
+          </a>
+          <div className="ephia-transcribe-poweredby-tooltip">ephia.app</div>
+        </div>
+
+        {/* Recording glow ring */}
+        {isLiveSession && !reducedMotion && (
+          <div
+            className="ephia-transcribe-ring"
+            style={
+              hasCustomColors
+                ? {
+                    boxShadow: `0 0 20px color-mix(in srgb, ${effectivePrimary} 55%, transparent)`,
+                  }
+                : {
+                    boxShadow:
+                      "0 0 24px rgba(114, 58, 222, 0.55), 0 0 14px rgba(0, 235, 208, 0.45)",
+                  }
+            }
+          />
+        )}
+
+        <button
+          type="button"
+          {...(interactionMode === "push-to-talk"
+            ? {
+                onPointerDown: (e: React.PointerEvent) => {
+                  e.preventDefault();
+                  if (typeof window !== "undefined") {
+                    (window as any).__ephia_record_click_ts = Date.now();
+                    window.dispatchEvent(
+                      new CustomEvent("ephia:sdk-debug", {
+                        detail: {
+                          type: "sdk.record.click",
+                          sessionId: null,
+                          payload: { message: "Push-to-talk press", ts: Date.now() },
+                        },
+                      })
+                    );
+                  }
+                  if (!isLiveSession && !isArming) void start(activeTargetId ?? undefined, { startupBufferMs: 5000 });
+                },
+                onPointerUp: () => { if (isLiveSession) void stop(); },
+                onPointerLeave: () => { if (isLiveSession) void stop(); },
+              }
+            : {
+                onClick: () => {
+                  if (isArming) return;
+                  if (typeof window !== "undefined") {
+                    (window as any).__ephia_record_click_ts = Date.now();
+                    window.dispatchEvent(
+                      new CustomEvent("ephia:sdk-debug", {
+                        detail: {
+                          type: "sdk.record.click",
+                          sessionId: null,
+                          payload: { message: "Clic sur Record", ts: Date.now() },
+                        },
+                      })
+                    );
+                  }
+                  if (isLiveSession) { void stop(); } else { void start(activeTargetId ?? undefined, { startupBufferMs: 5000 }); }
+                },
+              })}
+          disabled={isArming}
+          className="ephia-transcribe-btn"
+          aria-pressed={isLiveSession}
+          aria-busy={isArming}
+          aria-label={
+            isLiveSession ? "Arrêter la dictée" :
+            isArming ? "Traitement en cours…" :
+            "Démarrer la dictée"
+          }
+        >
+          <span
+            className={`ephia-transcribe-btn-inner${isStandardVariant ? " ephia-transcribe-btn-inner--standard" : ""}${showProcessing ? " ephia-transcribe-btn-inner--processing" : ""}`}
+          >
+            {variant === "minimal" ? (
+              <span
+                className={`ephia-transcribe-minimal-swap${isRecording || isArming ? " ephia-transcribe-minimal-swap--recording" : ""}`}
+                style={{ width: logoWidthPx, height: logoHeightPx }}
+              >
+                <span className="ephia-transcribe-minimal-swap-layer ephia-transcribe-minimal-swap-layer--logo" aria-hidden>
+                  <span className="ephia-transcribe-logo-clip ephia-transcribe-logo-slot" style={{ width: logoWidthPx, height: logoHeightPx }}>
+                    <span className="ephia-transcribe-logo-slot-layer ephia-transcribe-logo-slot-layer--logo" aria-hidden>
+                      <EphiaLogo
+                        height={logoHeightPx}
+                        width={logoWidthPx}
+                        variant={logoVariant}
+                        fill={effectivePrimary}
+                        isRecording={isLiveSession}
+                      />
+                    </span>
+                  </span>
+                </span>
+                <span className="ephia-transcribe-minimal-swap-layer ephia-transcribe-minimal-swap-layer--activity" aria-hidden>
+                  <MinimalProcessingBars
+                    active={isRecording || isArming}
+                    size={safeSize}
+                    color={waveformColor}
+                  />
+                </span>
+              </span>
+            ) : (
+              // standard variant
+              <span
+                className={`ephia-transcribe-logo-clip ephia-transcribe-logo-slot${showTimer ? " ephia-transcribe-logo-slot--recording" : ""}`}
+                style={{ width: logoSlotWidthPx, height: logoHeightPx }}
+              >
+                <span className="ephia-transcribe-logo-slot-layer ephia-transcribe-logo-slot-layer--logo" aria-hidden>
+                  <EphiaLogo
+                    height={logoHeightPx}
+                    width={logoWidthPx}
+                    variant={logoVariant}
+                    fill={effectivePrimary}
+                    isRecording={isLiveSession}
+                  />
+                </span>
+                {showTimer && (
+                  <>
+                    <span className="ephia-transcribe-logo-slot-layer ephia-transcribe-logo-slot-layer--timer" aria-hidden>
+                      <span className="ephia-transcribe-session-timer">{timerLabel}</span>
+                    </span>
+                    <span className="ephia-transcribe-session-timer ephia-transcribe-session-timer--measure" ref={timerMeasureRef}>
+                      {timerLabel}
+                    </span>
+                  </>
+                )}
+              </span>
+            )}
+
+            {isStandardVariant && (
+              <span
+                className={`ephia-transcribe-standard-right-swap${showStandardPrompt ? " ephia-transcribe-standard-right-swap--prompt" : showProcessing ? " ephia-transcribe-standard-right-swap--processing" : " ephia-transcribe-standard-right-swap--waveform"}`}
+                aria-hidden
+              >
+                <span className="ephia-transcribe-standard-right-layer ephia-transcribe-standard-right-layer--prompt">
+                  Commencer à dicter
+                </span>
+                <span className="ephia-transcribe-standard-right-layer ephia-transcribe-standard-right-layer--processing">
+                  Traitement…
+                </span>
+                {!showProcessing ? (
+                  <span className="ephia-transcribe-standard-right-layer ephia-transcribe-standard-right-layer--waveform">
+                    <StandardIntensityVisualizer
+                      enabled={isRecording}
+                      level={voiceLevel}
+                    />
+                  </span>
+                ) : null}
+              </span>
+            )}
+          </span>
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/* ── Public component ────────────────────────────────────────────── */
+
+export function EphiaFloatingButton({
+  apiUrl,
+  apiKey,
+  bearerToken,
+  clientType,
+  transport,
+  position = "bottom-center",
+  theme = "light",
+  size = "M",
+  variant = "standard",
+  borderRadius = "lg",
+  interactionMode = "toggle",
+  colors,
+  className,
+  style,
+  sessionOptions,
+  onError,
+  onStatusChange,
+}: EphiaFloatingButtonProps) {
+  const ctx = useOptionalEphiaContext();
+  const safeRadius: EphiaFloatingButtonBorderRadius =
+    borderRadius && borderRadius in EPHIA_FLOATING_BUTTON_RADIUS_CSS ? borderRadius : "lg";
+
+  const innerProps = useMemo<InnerProps>(() => ({
+    position,
+    theme,
+    size,
+    variant,
+    borderRadius: safeRadius,
+    interactionMode,
+    colors,
+    className,
+    style,
+    onError,
+    onStatusChange,
+  }), [position, theme, size, variant, safeRadius, interactionMode, colors, className, style, onError, onStatusChange]);
+
+  if (ctx) {
+    return <EphiaFloatingButtonInner {...innerProps} />;
+  }
+
+  return (
+    <EphiaProvider
+      apiUrl={apiUrl}
+      apiKey={apiKey}
+      bearerToken={bearerToken}
+      clientType={clientType}
+      transport={transport}
+      options={{
+        language: sessionOptions?.language as string | undefined,
+        sessionOptions: sessionOptions,
+      }}
+    >
+      <EphiaFloatingButtonInner {...innerProps} />
+    </EphiaProvider>
+  );
+}

package/src/ui/recorder/MinimalProcessingBars.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+type MinimalBarsSize = "S" | "M" | "L";
+
+const BAR_LAYOUT: Record<MinimalBarsSize, { barWidthPx: number; gapPx: number }> = {
+  S: { barWidthPx: 3, gapPx: 2.5 },
+  M: { barWidthPx: 3.5, gapPx: 3 },
+  L: { barWidthPx: 4, gapPx: 3.5 },
+};
+
+const TAU = Math.PI * 2;
+
+/** Chaque barre : fréquences différentes + petite amplitude → pas de cycle min/max synchronisé. */
+const BAR_MOTION = [
+  { base: 0.62, a1: 0.14, a2: 0.09, f1: 1.25, f2: 2.05, p1: 0, p2: 0.7 },
+  { base: 0.64, a1: 0.15, a2: 0.07, f1: 1.65, f2: 2.35, p1: 1.4, p2: 2.2 },
+  { base: 0.6, a1: 0.12, a2: 0.1, f1: 1.05, f2: 1.85, p1: 2.5, p2: 0.4 },
+] as const;
+
+const LERP = 0.14;
+
+function clamp01(x: number): number {
+  return Math.max(0.36, Math.min(0.9, x));
+}
+
+function targetHeight(phaseSec: number, spec: (typeof BAR_MOTION)[number]): number {
+  const t = phaseSec;
+  const v =
+    spec.base +
+    spec.a1 * Math.sin(t * spec.f1 * TAU + spec.p1) +
+    spec.a2 * Math.sin(t * spec.f2 * TAU + spec.p2);
+  return clamp01(v);
+}
+
+/**
+ * Indicateur minimal : 3 barres, même couleur, respiration douce (pas de balayage min→max).
+ */
+export function MinimalProcessingBars({
+  active,
+  size = "M",
+  color,
+}: {
+  active: boolean;
+  size?: MinimalBarsSize;
+  color: string;
+}) {
+  const rootRef = useRef<HTMLSpanElement>(null);
+  const heightsRef = useRef([0.55, 0.58, 0.54]);
+  const layout = BAR_LAYOUT[size] ?? BAR_LAYOUT.M;
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+
+    const applyHeights = (h: number[]) => {
+      root.style.setProperty("--ephia-bar-0", String(h[0]));
+      root.style.setProperty("--ephia-bar-1", String(h[1]));
+      root.style.setProperty("--ephia-bar-2", String(h[2]));
+    };
+
+    if (!active) {
+      heightsRef.current = [0.52, 0.56, 0.54];
+      applyHeights(heightsRef.current);
+      return;
+    }
+
+    const reducedMotion =
+      typeof window !== "undefined" &&
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+    if (reducedMotion) {
+      applyHeights([0.55, 0.58, 0.54]);
+      return;
+    }
+
+    let raf = 0;
+    const start = performance.now();
+
+    const tick = (now: number) => {
+      const phase = (now - start) / 1000;
+      const current = heightsRef.current;
+
+      for (let i = 0; i < 3; i++) {
+        const target = targetHeight(phase, BAR_MOTION[i]);
+        current[i] += (target - current[i]) * LERP;
+      }
+
+      applyHeights(current);
+      raf = requestAnimationFrame(tick);
+    };
+
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [active]);
+
+  return (
+    <span
+      ref={rootRef}
+      className="ephia-transcribe-minimal-bars"
+      style={
+        {
+          ["--ephia-minimal-bar-gap" as string]: `${layout.gapPx}px`,
+        } as React.CSSProperties
+      }
+      aria-hidden
+    >
+      {BAR_MOTION.map((_, i) => (
+        <span
+          key={i}
+          className="ephia-transcribe-minimal-bar"
+          style={{
+            width: layout.barWidthPx,
+            backgroundColor: color,
+            ["--ephia-bar-scale" as string]: `var(--ephia-bar-${i}, 0.5)`,
+          }}
+        />
+      ))}
+    </span>
+  );
+}