@zantopia/zephyr-widget 0.4.0

package/README.md

@@ -0,0 +1,277 @@
+# 🦊 @zephyr/widget — Embeddable AI Navigation Assistant
+
+Composant réutilisable d'assistant IA pour guider les utilisateurs dans n'importe quelle application web.
+
+## Installation
+
+### Option 1 : Script tag (le plus simple)
+
+```html
+<script src="https://your-zephyr-server/api/sdk/zephyr-widget.js"></script>
+<script>
+  ZephyrWidget.init({
+    server: 'https://your-zephyr-server',
+    persona: 'minimal',
+    theme: 'dark',
+    position: 'bottom-right',
+    accentColor: '#ff6b35',
+    language: 'fr',
+  });
+</script>
+```
+
+### Option 2 : npm
+
+```bash
+npm install @zephyr/widget
+```
+
+## Utilisation React
+
+```jsx
+import { ZephyrChat } from '@zephyr/widget/react';
+
+function App() {
+  return (
+    <ZephyrChat
+      server="https://your-zephyr-server"
+      persona="spirit"
+      theme="auto"
+      position="bottom-right"
+      accentColor="#6c63ff"
+      language="fr"
+      onMessage={(msg) => console.log(msg)}
+    />
+  );
+}
+```
+
+### Inline (dans un conteneur)
+
+```jsx
+<ZephyrChat
+  server="https://your-zephyr-server"
+  inline
+  style={{ height: '500px', width: '100%' }}
+/>
+```
+
+### Hook impératif
+
+```jsx
+import { useZephyr } from '@zephyr/widget/react';
+
+function HelpButton() {
+  const { open, send } = useZephyr();
+  return <button onClick={() => { open(); send("Comment faire X ?"); }}>Aide</button>;
+}
+```
+
+## Utilisation Vue 3
+
+```vue
+<script setup>
+import ZephyrWidget from '@zephyr/widget/vue';
+</script>
+
+<template>
+  <ZephyrWidget
+    server="https://your-zephyr-server"
+    persona="futuristic"
+    theme="dark"
+    position="bottom-left"
+    accent-color="#ff9f43"
+    @message="onMessage"
+    @toggle="onToggle"
+  />
+</template>
+```
+
+### Inline + ref
+
+```vue
+<template>
+  <ZephyrWidget
+    ref="zephyr"
+    server="..."
+    :inline="true"
+    style="height: 500px"
+  />
+  <button @click="$refs.zephyr.send('Bonjour')">Envoyer</button>
+</template>
+```
+
+## Utilisation Vanilla JS (Web Component / n'importe quel framework)
+
+```js
+import { ZephyrWidget } from '@zephyr/widget';
+
+const widget = ZephyrWidget.init({
+  server: 'https://your-zephyr-server',
+  persona: 'mascot',
+  theme: 'light',
+  position: 'bottom-right',
+});
+
+// API impérative
+widget.open();
+widget.send("Où trouver les paramètres ?");
+widget.setTheme('dark');
+widget.setPersona('spirit');
+widget.close();
+widget.destroy();
+```
+
+## Props / Options
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `server` | string | **required** | URL du serveur Zephyr |
+| `apiKey` | string | `""` | Clé API pour l'authentification |
+| `persona` | string | `"minimal"` | `"mascot"` \| `"spirit"` \| `"minimal"` \| `"futuristic"` \| URL image custom |
+| `theme` | string | `"dark"` | `"dark"` \| `"light"` \| `"auto"` |
+| `position` | string | `"bottom-right"` | `"bottom-right"` \| `"bottom-left"` \| `"top-right"` \| `"top-left"` |
+| `size` | string | `"md"` | `"sm"` \| `"md"` \| `"lg"` |
+| `language` | string | `"fr"` | `"fr"` \| `"en"` |
+| `greeting` | string | `null` | Message d'accueil custom |
+| `placeholder` | string | `null` | Placeholder du champ de saisie |
+| `accentColor` | string | `"#ff6b35"` | Couleur d'accent (CSS) |
+| `zIndex` | number | `99999` | Z-index CSS |
+| `open` | boolean | `false` | Ouvrir au chargement |
+| `showBadge` | boolean | `true` | Afficher le badge de notification |
+| `features` | array | `["chat","guide","search"]` | Fonctionnalités activées |
+| `appContext` | object | `null` | Contexte applicatif métier (voir ci-dessous) |
+| `inline` | boolean | `false` | Mode inline (dans un conteneur) |
+| `customCSS` | string | `""` | CSS additionnel |
+
+## Personas
+
+| ID | Style | Description |
+|---|---|---|
+| `mascot` | Mascotte complète | Renard Zephyr avec moustaches, détails complets |
+| `spirit` | Esprit flottant | Version éthérée avec glow radial |
+| `minimal` | Ultra minimal SaaS | Fond arrondi, traits simples |
+| `futuristic` | Futuriste | Dégradé, yeux rectangulaires, point lumineux |
+
+Vous pouvez aussi passer une **URL d'image** pour un persona custom :
+```js
+ZephyrWidget.init({
+  server: '...',
+  persona: 'https://example.com/my-custom-avatar.svg',
+});
+```
+
+## Events / Callbacks
+
+| Event | Payload | Description |
+|---|---|---|
+| `onReady` / `@ready` | `widget` | Widget initialisé |
+| `onMessage` / `@message` | `{ role, text, expression }` | Nouveau message |
+| `onError` / `@error` | `{ message }` | Erreur WebSocket/serveur |
+| `onToggle` / `@toggle` | `boolean` | Panel ouvert/fermé |
+
+## API Impérative
+
+| Méthode | Description |
+|---|---|
+| `widget.open()` | Ouvre le panel |
+| `widget.close()` | Ferme le panel |
+| `widget.toggle()` | Bascule |
+| `widget.send(text)` | Envoie un message |
+| `widget.setTheme(theme)` | Change le thème |
+| `widget.setPersona(persona)` | Change le persona |
+| `widget.setAccentColor(color)` | Change la couleur d'accent |
+| `widget.setAppContext(ctx)` | Met à jour le contexte applicatif (utile pour les SPAs) |
+| `widget.destroy()` | Détruit le widget |
+
+## Application Context (`appContext`)
+
+Le contexte applicatif permet au chatbot de répondre **instantanément** aux questions métier sans analyser le DOM à chaque fois.
+
+Le développeur qui intègre Zephyr décrit son application : ses features, sa FAQ, sa terminologie et ses workflows.
+
+### Structure
+
+```js
+ZephyrWidget.init({
+  server: 'https://...',
+  appContext: {
+    // Nom et description de l'application
+    name: 'MonApp',
+    description: 'Plateforme de gestion de projets collaboratifs',
+
+    // Fonctionnalités principales (utilisé pour guider la navigation)
+    features: [
+      { name: 'Dashboard', path: '/dashboard', description: 'Vue d\'ensemble des projets actifs' },
+      { name: 'Kanban', path: '/board', description: 'Tableau de suivi des tâches drag & drop' },
+      { name: 'Paramètres', path: '/settings', description: 'Configuration du compte et des projets' },
+    ],
+
+    // FAQ — réponses pré-écrites (le chatbot les renvoie directement)
+    faq: [
+      { question: 'Comment créer un projet ?', answer: 'Menu + > Nouveau projet > Remplir le formulaire' },
+      { question: 'Comment inviter un membre ?', answer: 'Paramètres du projet > Membres > Inviter' },
+    ],
+
+    // Terminologie métier (le chatbot utilisera ces définitions)
+    terminology: {
+      sprint: 'période de travail de 2 semaines',
+      story: 'tâche utilisateur à compléter',
+      backlog: 'liste des tâches à planifier',
+    },
+
+    // Workflows typiques (parcours utilisateur)
+    workflows: [
+      'Créer un projet → Ajouter des membres → Créer des tâches → Suivre l\'avancement',
+      'Se connecter → Dashboard → Sélectionner un projet → Vue Kanban',
+    ],
+
+    // Texte libre complémentaire
+    custom: 'L\'app supporte 3 rôles : Admin, Manager et Contributeur.',
+  },
+});
+```
+
+### Mise à jour dynamique (SPA)
+
+Pour les Single Page Applications, mettez à jour le contexte lors des changements de route :
+
+```js
+const widget = ZephyrWidget.init({ server: '...', appContext: globalContext });
+
+// Quand l'utilisateur change de page
+router.afterEach((to) => {
+  widget.setAppContext({
+    ...globalContext,
+    custom: `L'utilisateur est sur la page ${to.name}.`,
+  });
+});
+```
+
+### API REST
+
+Le contexte applicatif peut aussi être défini via l'API REST :
+
+```bash
+# Définir le contexte
+curl -X PUT https://your-server/api/guide/app-context \
+  -H 'Content-Type: application/json' \
+  -d '{ "session_id": "...", "app_context": { "name": "MonApp", ... } }'
+
+# Récupérer le contexte
+curl https://your-server/api/guide/app-context/{session_id}
+```
+
+### Comment ça marche
+
+1. Le widget envoie le `appContext` au serveur via WebSocket à la connexion
+2. Le serveur le stocke dans la session utilisateur
+3. À chaque question, le contexte applicatif est injecté **en priorité** dans le prompt LLM
+4. Si la FAQ contient la réponse, le chatbot la renvoie directement
+5. Sinon, il combine le contexte applicatif + l'analyse DOM pour une réponse complète
+
+**Avantages :**
+- ⚡ Réponses instantanées aux questions métier (pas d'analyse DOM nécessaire)
+- 🎯 Réponses plus précises (le dev connaît mieux son app que le DOM)
+- 💰 Moins de tokens LLM consommés
+- 🗣️ Le chatbot parle le "langage" de l'app

package/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @zephyr/widget — TypeScript type definitions
+ */
+
+/** Application context provided by the integrator to enrich chatbot responses. */
+export interface AppContext {
+  /** Application name */
+  name?: string;
+  /** Short description of what the application does */
+  description?: string;
+  /** Key features / pages of the application */
+  features?: Array<{
+    name: string;
+    path?: string;
+    description?: string;
+  }>;
+  /** Frequently asked questions with pre-written answers */
+  faq?: Array<{
+    question: string;
+    answer: string;
+  }>;
+  /** Domain-specific terminology definitions */
+  terminology?: Record<string, string>;
+  /** Typical user workflows described as steps */
+  workflows?: string[];
+  /** Any extra free-form context the integrator wants the chatbot to know */
+  custom?: string;
+}
+
+export interface ZephyrWidgetOptions {
+  /** URL of the Zephyr backend server */
+  server: string;
+  /** API key for authentication (optional) */
+  apiKey?: string;
+  /** Persona style: "mascot" | "spirit" | "minimal" | "futuristic" | custom image URL */
+  persona?: "mascot" | "spirit" | "minimal" | "futuristic" | string;
+  /** Color theme */
+  theme?: "dark" | "light" | "auto";
+  /** Widget position on screen */
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  /** Avatar size */
+  size?: "sm" | "md" | "lg";
+  /** Language */
+  language?: "fr" | "en";
+  /** Custom greeting message */
+  greeting?: string | null;
+  /** Input placeholder */
+  placeholder?: string | null;
+  /** Primary accent color (CSS) */
+  accentColor?: string;
+  /** CSS z-index */
+  zIndex?: number;
+  /** Allow dragging the trigger button */
+  draggable?: boolean;
+  /** Start with panel open */
+  open?: boolean;
+  /** Show notification badge */
+  showBadge?: boolean;
+  /** Badge count */
+  badgeCount?: number;
+  /** Enabled features */
+  features?: Array<"chat" | "guide" | "search">;
+  /**
+   * Application context — describe your app so the chatbot can answer
+   * user questions faster without needing to analyse the DOM every time.
+   */
+  appContext?: AppContext;
+  /** Mount inside a specific selector (inline mode — no floating trigger) */
+  containerSelector?: string | null;
+  /** Additional CSS to inject */
+  customCSS?: string;
+
+  // Callbacks
+  onReady?: (widget: ZephyrWidgetInstance) => void;
+  onMessage?: (msg: { role: string; text: string; expression: string }) => void;
+  onError?: (err: { message: string }) => void;
+  onToggle?: (isOpen: boolean) => void;
+}
+
+export interface ZephyrWidgetInstance {
+  mount(container?: string | HTMLElement | null): void;
+  destroy(): void;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  send(text: string): void;
+  setTheme(theme: "dark" | "light" | "auto"): void;
+  setPersona(persona: string): void;
+  setAccentColor(color: string): void;
+  /** Update the application context at runtime (useful for SPAs). */
+  setAppContext(ctx: AppContext): void;
+  on(event: "ready" | "message" | "error" | "toggle", handler: Function): void;
+  readonly messages: Array<{ role: string; text: string; expression: string }>;
+  readonly isOpen: boolean;
+  readonly sessionId: string | null;
+  readonly expression: string;
+}
+
+export interface ZephyrWidgetStatic {
+  init(options: ZephyrWidgetOptions): ZephyrWidgetInstance;
+  getInstance(): ZephyrWidgetInstance | null;
+  Widget: new (options: ZephyrWidgetOptions) => ZephyrWidgetInstance;
+  PERSONAS: Record<string, { svg: (accent: string) => string }>;
+  THEMES: Record<string, Record<string, string>>;
+}
+
+declare const ZephyrWidget: ZephyrWidgetStatic;
+export default ZephyrWidget;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@zantopia/zephyr-widget",
+  "version": "0.4.0",
+  "description": "Zephyr AI Navigation Assistant — Embeddable widget for any web project",
+  "type": "module",
+  "main": "zephyr-widget.js",
+  "module": "zephyr-widget.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./zephyr-widget.js",
+      "types": "./index.d.ts"
+    },
+    "./react": {
+      "import": "./react/index.jsx",
+      "types": "./react/index.d.ts"
+    },
+    "./vue": {
+      "import": "./vue/ZephyrWidget.vue"
+    }
+  },
+  "files": [
+    "zephyr-widget.js",
+    "index.d.ts",
+    "react/",
+    "vue/",
+    "README.md"
+  ],
+  "scripts": {},
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0",
+    "vue": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true },
+    "vue": { "optional": true }
+  },
+  "keywords": ["zephyr", "ai", "widget", "assistant", "navigation", "ux"],
+  "license": "MIT"
+}

package/react/index.d.ts

@@ -0,0 +1,55 @@
+import React from "react";
+
+export interface ZephyrChatProps {
+  /** Zephyr backend server URL */
+  server: string;
+  /** API key */
+  apiKey?: string;
+  /** Persona: "mascot" | "spirit" | "minimal" | "futuristic" | custom URL */
+  persona?: "mascot" | "spirit" | "minimal" | "futuristic" | string;
+  /** Theme */
+  theme?: "dark" | "light" | "auto";
+  /** Position */
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  /** Size */
+  size?: "sm" | "md" | "lg";
+  /** Language */
+  language?: "fr" | "en";
+  /** Custom greeting */
+  greeting?: string;
+  /** Input placeholder */
+  placeholder?: string;
+  /** Accent color */
+  accentColor?: string;
+  /** z-index */
+  zIndex?: number;
+  /** Start open */
+  open?: boolean;
+  /** Show badge */
+  showBadge?: boolean;
+  /** Features */
+  features?: Array<"chat" | "guide" | "search">;
+  /** Inline mode (render inside container) */
+  inline?: boolean;
+  /** Custom CSS */
+  customCSS?: string;
+  /** CSS class */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+
+  // Callbacks
+  onReady?: (widget: any) => void;
+  onMessage?: (msg: { role: string; text: string; expression: string }) => void;
+  onError?: (err: { message: string }) => void;
+  onToggle?: (isOpen: boolean) => void;
+}
+
+export declare function ZephyrChat(props: ZephyrChatProps): React.ReactElement | null;
+export declare function useZephyr(): {
+  send: (text: string) => void;
+  open: () => void;
+  close: () => void;
+};
+
+export default ZephyrChat;

package/react/index.jsx

@@ -0,0 +1,186 @@
+/**
+ * 🦊 @kitsune/widget/react — React component wrapper
+ *
+ * Usage:
+ *   import { KitsuneChat } from '@kitsune/widget/react';
+ *
+ *   function App() {
+ *     return (
+ *       <KitsuneChat
+ *         server="https://your-kitsune-server"
+ *         persona="minimal"
+ *         theme="dark"
+ *         position="bottom-right"
+ *         accentColor="#ff6b35"
+ *         onMessage={(msg) => console.log(msg)}
+ *       />
+ *     );
+ *   }
+ */
+
+import React, { useEffect, useRef, useCallback } from "react";
+
+// Widget is loaded as an IIFE — import the core
+let WidgetModule = null;
+try {
+  WidgetModule = require("../kitsune-widget.js");
+} catch {
+  // Dynamic import fallback handled in useEffect
+}
+
+/**
+ * Configuration props — matches KitsuneWidgetOptions
+ */
+const defaultProps = {
+  server: "",
+  persona: "minimal",
+  theme: "dark",
+  position: "bottom-right",
+  size: "md",
+  language: "fr",
+  accentColor: "#ff6b35",
+  zIndex: 99999,
+  open: false,
+};
+
+export function KitsuneChat(props) {
+  const containerRef = useRef(null);
+  const instanceRef = useRef(null);
+
+  const {
+    server,
+    apiKey,
+    persona,
+    theme,
+    position,
+    size,
+    language,
+    greeting,
+    placeholder,
+    accentColor,
+    zIndex,
+    draggable,
+    open,
+    showBadge,
+    features,
+    customCSS,
+    inline,
+    onReady,
+    onMessage,
+    onError,
+    onToggle,
+    className,
+    style,
+    ...rest
+  } = { ...defaultProps, ...props };
+
+  useEffect(() => {
+    let widget = null;
+
+    const init = async () => {
+      let Mod = WidgetModule;
+      if (!Mod) {
+        // Fallback: load from CDN or relative path
+        try {
+          Mod = await import("../kitsune-widget.js");
+        } catch {
+          console.error("[KitsuneChat] Could not load kitsune-widget.js");
+          return;
+        }
+      }
+
+      const Cls = Mod.Widget || Mod.default?.Widget;
+      if (!Cls) return;
+
+      widget = new Cls({
+        server,
+        apiKey,
+        persona,
+        theme,
+        position,
+        size,
+        language,
+        greeting,
+        placeholder,
+        accentColor,
+        zIndex,
+        draggable,
+        open,
+        showBadge,
+        features,
+        customCSS,
+        containerSelector: inline ? null : null,
+        onReady,
+        onMessage,
+        onError,
+        onToggle,
+      });
+
+      if (inline && containerRef.current) {
+        widget.mount(containerRef.current);
+      } else {
+        widget.mount();
+      }
+
+      instanceRef.current = widget;
+    };
+
+    init();
+
+    return () => {
+      if (widget) widget.destroy();
+    };
+  }, [server]); // Re-init only on server change
+
+  // React to prop changes
+  useEffect(() => {
+    if (!instanceRef.current) return;
+    instanceRef.current.setTheme(theme);
+  }, [theme]);
+
+  useEffect(() => {
+    if (!instanceRef.current) return;
+    instanceRef.current.setPersona(persona);
+  }, [persona]);
+
+  useEffect(() => {
+    if (!instanceRef.current) return;
+    instanceRef.current.setAccentColor(accentColor);
+  }, [accentColor]);
+
+  // Inline renders a container div; floating renders nothing
+  if (inline) {
+    return React.createElement("div", {
+      ref: containerRef,
+      className: `kitsune-react-container ${className || ""}`,
+      style: { width: "100%", height: "100%", ...style },
+      ...rest,
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Hook for imperative widget control
+ */
+export function useKitsune() {
+  const send = useCallback((text) => {
+    const w = typeof KitsuneWidget !== "undefined" ? KitsuneWidget.getInstance() : null;
+    if (w) w.send(text);
+  }, []);
+
+  const open = useCallback(() => {
+    const w = typeof KitsuneWidget !== "undefined" ? KitsuneWidget.getInstance() : null;
+    if (w) w.open();
+  }, []);
+
+  const close = useCallback(() => {
+    const w = typeof KitsuneWidget !== "undefined" ? KitsuneWidget.getInstance() : null;
+    if (w) w.close();
+  }, []);
+
+  return { send, open, close };
+}
+
+export default KitsuneChat;