@inwink-mcp/backoffice-extension-helpers 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inwink-mcp/backoffice-extension-helpers",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "author": "inwink",
   "license": "ISC",
   "description": "CLI pour bootstrapper, packager et vérifier les extensions backoffice inwink.",

package/templates/test-app/src/components/Header.tsx

@@ -0,0 +1,36 @@
+import './Header.css';
+import { FiLogIn, FiLogOut } from 'react-icons/fi';
+import { useAuth } from '../hooks/useAuth';
+import EventPicker from './EventPicker';
+
+interface HeaderProps {
+  title: string;
+}
+
+// Version surchargée du Header par l'overlay "test-app".
+// Démontre qu'on peut personnaliser le Header (ici : montage d'un EventPicker)
+// sans toucher au Layout ni à App — et force la compilation des pickers + du
+// contexte inwink dans le build de test.
+export default function Header({ title }: HeaderProps) {
+  const { isAuthenticated, isLoading, login, logout } = useAuth();
+
+  return (
+    <header className="app-header">
+      <div className="app-header__brand">{title}</div>
+      <div className="app-header__actions">
+        {isAuthenticated && <EventPicker />}
+        {isAuthenticated ? (
+          <button onClick={() => void logout()}>
+            <FiLogOut aria-hidden />
+            Se déconnecter
+          </button>
+        ) : (
+          <button className="btn-primary" disabled={isLoading} onClick={() => void login()}>
+            <FiLogIn aria-hidden />
+            {isLoading ? 'Initialisation…' : 'Se connecter'}
+          </button>
+        )}
+      </div>
+    </header>
+  );
+}

package/templates/test-app/src/pages/HomePage.tsx.tpl

@@ -1,13 +1,16 @@
 import { useState } from 'react';
-import { FiLogIn, FiLogOut, FiRefreshCw } from 'react-icons/fi';
+import { FiRefreshCw } from 'react-icons/fi';
 import { useAuth } from '../hooks/useAuth';
+import { useInwinkContext } from '../hooks/useInwinkContext';
 import { useInwinkEventApi } from '../hooks/useInwinkEventApi';
 
 // Version de HomePage générée par le template overlay "test-app".
-// Sert à vérifier que le squelette bootstrappé compile et que les hooks API
-// (ici useInwinkEventApi) sont utilisables.
+// Sert à vérifier que le squelette bootstrappé compile et que les hooks
+// (useInwinkEventApi, useInwinkContext) sont utilisables. Le login/logout vit
+// désormais dans le Header (lui-même surchargé par cet overlay).
 export default function HomePage() {
-  const { isAuthenticated, isLoading, login, logout, user } = useAuth();
+  const { isAuthenticated, user } = useAuth();
+  const { scope, eventId, communityId, tenantId } = useInwinkContext();
   const eventApi = useInwinkEventApi();
   const [result, setResult] = useState<string>('');
   const [error, setError] = useState<string>('');
@@ -28,28 +31,27 @@ export default function HomePage() {
   }
 
   return (
-    <main>
+    <section>
       <h1>__DISPLAY_NAME__ — test API Event</h1>
       {!isAuthenticated ? (
-        <button disabled={isLoading} onClick={() => void login()}>
-          <FiLogIn aria-hidden />
-          {isLoading ? 'Initialisation...' : 'Se connecter'}
-        </button>
+        <p>Connectez-vous via le bouton « Se connecter » en haut à droite.</p>
       ) : (
         <>
           <p>Connecté en tant que : {user?.profile.email ?? 'Inconnu'}</p>
+          <p>
+            Contexte courant : {scope ?? 'aucun'}
+            {eventId ? ` — événement ${eventId}` : ''}
+            {communityId ? ` — communauté ${communityId}` : ''}
+            {tenantId ? ` — audience ${tenantId}` : ''}
+          </p>
           <button onClick={() => void callEventApi()}>
             <FiRefreshCw aria-hidden />
             Appeler l'API Event
           </button>
-          <button onClick={() => void logout()}>
-            <FiLogOut aria-hidden />
-            Se déconnecter
-          </button>
           {result && <pre>{result}</pre>}
           {error && <p role="alert">Erreur : {error}</p>}
         </>
       )}
-    </main>
+    </section>
   );
 }

package/templates/vite-extension/AGENTS.md.tpl

@@ -25,9 +25,20 @@ __NAME__/
 ├── vite.config.ts            # Config Vite (base: './' + copie du manifest)
 ├── scripts/zip-build.mjs     # Packaging zip {name}-{version}.zip
 └── src/
-    ├── main.tsx              # Bootstrap React (HashRouter + AuthProvider)
-    ├── App.tsx               # Routes
-    ├── styles.css            # Styles
+    ├── main.tsx              # Bootstrap React (HashRouter + AuthProvider + InwinkContextProvider)
+    ├── App.tsx               # Routes (via Layout + Outlet)
+    ├── styles.css            # Styles globaux : polices, tokens (couleurs/accent), base
+    ├── components/
+    │   ├── Layout.tsx + .css         # Gabarit : Header + zone de contenu (Outlet)
+    │   ├── Header.tsx + .css         # En-tête (marque + login/logout) — surchargeable
+    │   ├── ContextCombobox.tsx + .css # Combobox ergonomique réutilisable (recherche + clavier)
+    │   ├── EventPicker.tsx           # Sélecteur d'événement (autonome, non monté par défaut)
+    │   ├── CommunityPicker.tsx       # Sélecteur de communauté (idem)
+    │   └── AudiencePicker.tsx        # Sélecteur de tenant/audience (idem)
+    ├── context/
+    │   └── InwinkContextProvider.tsx  # Contexte event/community/tenant + loaders de listes
+    ├── lib/
+    │   └── inwinkContextParams.ts     # Lecture/persistance des params URL (eventid/communityid/tenantid)
     ├── pages/
     │   └── HomePage.tsx      # Page d'accueil (logique métier / UI)
     ├── api/
@@ -38,6 +49,8 @@ __NAME__/
     │   └── ProtectedRoute.tsx
     └── hooks/
         ├── useAuth.ts                # Hook d'accès au contexte auth
+        ├── useInwinkContext.ts       # Hook d'accès au contexte inwink (event/community/tenant)
+        ├── useContextOptions.ts      # Chargement (1×) des listes pour les pickers
         ├── useInwinkApi.ts           # Hook générique d'appel API (Bearer + renouvellement 401)
         ├── useInwinkEventApi.ts      # Hook API Event
         ├── useInwinkCommunityApi.ts  # Hook API Community
@@ -85,6 +98,50 @@ Bonnes pratiques :
 - Ne déclarer dans `permissions.platform` que les scopes réellement utilisés.
 - Déclarer les hôtes externes dans `permissions.externalHosts` (HTTPS uniquement).
 
+## Structure de pages & Header
+
+L'app est rendue dans un `Layout` (`components/Layout.tsx`) = `Header` + zone de contenu (`<Outlet />`). Le `Header` (`components/Header.tsx`) est **minimal par défaut** (marque + bouton login/logout) et **conçu pour être surchargé** : c'est l'endroit naturel où monter un picker de contexte si l'extension en a besoin.
+
+Pour **ajouter une page** : créer le composant dans `src/pages/`, puis ajouter une `<Route>` enfant du `<Route element={<Layout .../>}>` dans `App.tsx` (elle s'affichera dans l'`Outlet`).
+
+## Contexte inwink (event / community / tenant)
+
+Quand l'extension est ouverte depuis le back-office sur un objet précis, le BO passe `eventid`, `communityid` ou `tenantid` dans l'URL. Le template gère ça nativement :
+
+- `lib/inwinkContextParams.ts` lit ces paramètres (query classique **et** query du hash), insensible à la casse, et les **persiste en sessionStorage** — indispensable car le callback OIDC nettoie l'URL et le `redirect_uri` ne réémet pas la query.
+- `context/InwinkContextProvider.tsx` expose le contexte courant et les setters via le hook **`useInwinkContext`** :
+
+```typescript
+const { scope, eventId, communityId, tenantId, setEvent, setCommunity, setTenant } = useInwinkContext();
+// scope = 'event' | 'community' | 'tenant' | null  (tenant = audience)
+```
+
+Le contexte issu de l'URL est **pré-rempli mais modifiable** (l'utilisateur peut changer d'objet via un picker).
+
+## Pickers de contexte (event / community / audience)
+
+Trois composants autonomes existent dans `components/` : **`EventPicker`**, **`CommunityPicker`**, **`AudiencePicker`**. Ils consomment `useInwinkContext`, listent les objets de l'utilisateur via l'API Customer (`me/events/query`, `me/communities/query`, `me/tenants/query`) et appliquent la sélection. L'UI est mutualisée dans **`ContextCombobox`** (bouton + popover avec recherche et navigation clavier) — réutilise-le pour tout sélecteur similaire.
+
+Ces listes sont **paginées côté serveur** (1ʳᵉ page seulement). La recherche du combobox est donc déléguée au serveur via `useContextOptions` (loaders `loadEvents/loadCommunities/loadTenants`, paramètre `IInwinkContextQuery = { search?, id? }`) : la saisie est debouncée et filtre par nom **ou** id (`{ filters: { $or: [{ id }, { <label>: { $contains } }] } }`). Les événements sont triés par date décroissante (`orders`). Comme l'objet pré-sélectionné via l'URL peut ne pas figurer dans la page courante, `useContextOptions` **fetch son détail par id** et le fusionne dans les options pour afficher son libellé.
+
+**Ils ne sont PAS montés par défaut.** À toi de décider, selon l'usage de l'extension, d'en monter un — typiquement dans le `Header` (cf. ci-dessus) ou dans une page :
+
+```tsx
+import EventPicker from '../components/EventPicker';
+// ...
+{isAuthenticated && <EventPicker />}
+```
+
+## Branding inwink
+
+- Polices : **Lato** (texte) + **Poppins** (titres), chargées via Google Fonts dans `styles.css`. Les hôtes `fonts.googleapis.com` / `fonts.gstatic.com` sont déjà déclarés dans `permissions.externalHosts`.
+- Couleur d'accentuation : **`#e94c1e`** (variable CSS `--color-accent`).
+- Variables/tokens globaux dans `styles.css` ; classe `.btn-primary` pour l'action principale.
+
+## Convention CSS (obligatoire)
+
+**Tout nouveau composant doit avoir un fichier `.css` co-localisé**, importé en tête de son `.tsx` (`import './MonComposant.css';`). Les styles globaux et les tokens (`--font-*`, `--color-*`) restent dans `styles.css` ; les styles spécifiques d'un composant vivent dans son `.css`. Vite bundle automatiquement ces CSS dans `dist/assets/` (packagé dans le zip) — ne pas les oublier.
+
 ## Règles et contraintes
 
 | Règle | Détail |
@@ -96,6 +153,7 @@ Bonnes pratiques :
 | Pas d'imports Node.js | `fs`, `path`, `http`, `child_process`, etc. interdits dans le code source |
 | Pas de `fetch` direct | Toujours passer par `useInwinkEventApi` / `useInwinkCommunityApi` / `useInwinkCustomerApi` (ou `useInwinkApi` pour un hôte externe déclaré) |
 | Icônes via `react-icons` | Ne pas embarquer de SVG inline ni d'images d'icônes |
+| CSS co-localisé par composant | Chaque composant a un `.css` importé en tête de son `.tsx` ; tokens/global dans `styles.css` |
 | `HashRouter` obligatoire | Pour compatibilité avec l'hébergement versionné |
 | `base: './'` obligatoire | Dans `vite.config.ts`, pour les chemins d'assets relatifs |
 | `response_type: 'code'` | PKCE obligatoire, pas de flux implicit |

package/templates/vite-extension/extension.manifest.json.tpl

@@ -6,7 +6,7 @@
   "author": "__AUTHOR__",
   "permissions": {
     "platform": [],
-    "externalHosts": []
+    "externalHosts": ["https://fonts.googleapis.com", "https://fonts.gstatic.com"]
   },
   "auth": {
     "scopes": ["openid", "profile", "email"]

package/templates/vite-extension/index.html.tpl

@@ -3,6 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <title>__DISPLAY_NAME__</title>
   </head>
   <body>

package/templates/vite-extension/src/App.tsx.tpl

@@ -1,22 +1,28 @@
 import { Navigate, Route, Routes } from 'react-router-dom';
+import Layout from './components/Layout';
 import ProtectedRoute from './auth/ProtectedRoute';
 import HomePage from './pages/HomePage';
 // Pour appeler une API inwink, utilisez un hook dédié (jamais fetch directement) :
 //   import { useInwinkEventApi } from './hooks/useInwinkEventApi';
 //   const eventApi = useInwinkEventApi();
 //   const data = await eventApi.get('/v1/...');
+//
+// Pour ajouter une page : créez-la dans src/pages/ puis ajoutez une <Route> enfant
+// du <Route element={<Layout .../>}> ci-dessous (elle s'affichera dans l'<Outlet> du Layout).
 
 export default function App() {
   return (
     <Routes>
-      <Route
-        path="/"
-        element={
-          <ProtectedRoute>
-            <HomePage />
-          </ProtectedRoute>
-        }
-      />
+      <Route element={<Layout title="__DISPLAY_NAME__" />}>
+        <Route
+          path="/"
+          element={
+            <ProtectedRoute>
+              <HomePage />
+            </ProtectedRoute>
+          }
+        />
+      </Route>
       <Route path="*" element={<Navigate to="/" replace />} />
     </Routes>
   );

package/templates/vite-extension/src/components/AudiencePicker.tsx

@@ -0,0 +1,25 @@
+import ContextCombobox from './ContextCombobox';
+import { useContextOptions } from '../hooks/useContextOptions';
+import { useInwinkContext } from '../hooks/useInwinkContext';
+
+/**
+ * Sélecteur de tenant / audience courant. Pré-rempli depuis le contexte (URL) et modifiable.
+ * Composant autonome, montable où l'on veut (header, page…). Non monté par défaut.
+ */
+export default function AudiencePicker() {
+  const { tenantId, setTenant, loadTenants } = useInwinkContext();
+  const { options, isLoading, error, search } = useContextOptions(loadTenants, tenantId);
+
+  return (
+    <ContextCombobox
+      label="Audience"
+      placeholder="Choisir une audience"
+      value={tenantId}
+      options={options}
+      isLoading={isLoading}
+      error={error}
+      onChange={setTenant}
+      onSearch={search}
+    />
+  );
+}

package/templates/vite-extension/src/components/CommunityPicker.tsx

@@ -0,0 +1,25 @@
+import ContextCombobox from './ContextCombobox';
+import { useContextOptions } from '../hooks/useContextOptions';
+import { useInwinkContext } from '../hooks/useInwinkContext';
+
+/**
+ * Sélecteur de communauté courante. Pré-rempli depuis le contexte (URL) et modifiable.
+ * Composant autonome, montable où l'on veut (header, page…). Non monté par défaut.
+ */
+export default function CommunityPicker() {
+  const { communityId, setCommunity, loadCommunities } = useInwinkContext();
+  const { options, isLoading, error, search } = useContextOptions(loadCommunities, communityId);
+
+  return (
+    <ContextCombobox
+      label="Communauté"
+      placeholder="Choisir une communauté"
+      value={communityId}
+      options={options}
+      isLoading={isLoading}
+      error={error}
+      onChange={setCommunity}
+      onSearch={search}
+    />
+  );
+}

package/templates/vite-extension/src/components/ContextCombobox.css

@@ -0,0 +1,110 @@
+.context-combobox {
+  position: relative;
+  display: inline-flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  font-size: 0.85rem;
+}
+
+.context-combobox__label {
+  color: var(--color-text-muted);
+  font-weight: 600;
+}
+
+.context-combobox__trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  min-width: 14rem;
+  max-width: 20rem;
+  padding: 0.4rem 0.6rem;
+  border-radius: var(--radius);
+  border: 1px solid var(--color-border);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font: inherit;
+}
+
+.context-combobox__trigger:hover:not(:disabled) {
+  border-color: var(--color-accent);
+}
+
+.context-combobox__value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.context-combobox__chevron {
+  flex-shrink: 0;
+  color: var(--color-text-muted);
+}
+
+.context-combobox__panel {
+  position: absolute;
+  top: calc(100% + 0.25rem);
+  left: 0;
+  z-index: 20;
+  width: max(100%, 16rem);
+  background: var(--color-bg);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.12);
+  overflow: hidden;
+}
+
+.context-combobox__search {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.5rem 0.6rem;
+  border-bottom: 1px solid var(--color-border);
+  color: var(--color-text-muted);
+}
+
+.context-combobox__search input {
+  flex: 1;
+  border: none;
+  outline: none;
+  font: inherit;
+  background: transparent;
+  color: var(--color-text);
+}
+
+.context-combobox__list {
+  list-style: none;
+  margin: 0;
+  padding: 0.25rem;
+  max-height: 16rem;
+  overflow-y: auto;
+}
+
+.context-combobox__empty {
+  padding: 0.5rem 0.6rem;
+  color: var(--color-text-muted);
+}
+
+.context-combobox__option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 0.45rem 0.6rem;
+  border: none;
+  border-radius: calc(var(--radius) - 2px);
+  background: transparent;
+  color: var(--color-text);
+  font: inherit;
+  text-align: left;
+}
+
+.context-combobox__option.is-highlighted {
+  background: var(--color-surface);
+}
+
+.context-combobox__option.is-selected {
+  color: var(--color-accent);
+  font-weight: 600;
+}

package/templates/vite-extension/src/components/ContextCombobox.tsx

@@ -0,0 +1,167 @@
+import './ContextCombobox.css';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { FiCheck, FiChevronDown, FiSearch } from 'react-icons/fi';
+import type { InwinkContextOption } from '../context/InwinkContextProvider';
+
+interface ContextComboboxProps {
+  label: string;
+  placeholder: string;
+  value?: string;
+  options: InwinkContextOption[];
+  isLoading: boolean;
+  error: string | null;
+  onChange: (id: string) => void;
+  /**
+   * Si fourni, la recherche est déléguée au serveur (le terme saisi est transmis)
+   * et la liste n'est PAS refiltrée côté client. Sans ce prop, le filtrage se fait
+   * côté client sur le libellé.
+   */
+  onSearch?: (query: string) => void;
+}
+
+/**
+ * Sélecteur ergonomique réutilisable : bouton déclencheur + popover avec champ de
+ * recherche, liste filtrable et navigation clavier. Mutualise l'UI des pickers de
+ * contexte (Event / Community / Audience).
+ */
+export default function ContextCombobox({
+  label,
+  placeholder,
+  value,
+  options,
+  isLoading,
+  error,
+  onChange,
+  onSearch,
+}: ContextComboboxProps) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [highlight, setHighlight] = useState(0);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listId = useId();
+
+  const selected = options.find((option) => option.id === value);
+  const triggerLabel = selected?.label ?? (value && isLoading ? 'Chargement…' : placeholder);
+
+  // En mode serveur (`onSearch`), la liste est déjà filtrée par l'API : on ne refiltre
+  // pas côté client (une recherche par id n'apparaît pas dans le libellé).
+  const filtered = useMemo(() => {
+    if (onSearch) return options;
+    const q = query.trim().toLowerCase();
+    return q ? options.filter((option) => option.label.toLowerCase().includes(q)) : options;
+  }, [options, query, onSearch]);
+
+  // Fermeture au clic extérieur.
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: MouseEvent) => {
+      if (!containerRef.current?.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', onPointerDown);
+    return () => document.removeEventListener('mousedown', onPointerDown);
+  }, [open]);
+
+  // Focus du champ de recherche à l'ouverture, et réinitialisation de la liste
+  // (en mode serveur, on recharge la liste complète non filtrée).
+  useEffect(() => {
+    if (open) {
+      setQuery('');
+      setHighlight(0);
+      inputRef.current?.focus();
+      onSearch?.('');
+    }
+  }, [open, onSearch]);
+
+  const select = (id: string) => {
+    onChange(id);
+    setOpen(false);
+  };
+
+  const onInputKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      setHighlight((h) => Math.min(h + 1, filtered.length - 1));
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      setHighlight((h) => Math.max(h - 1, 0));
+    } else if (event.key === 'Enter') {
+      event.preventDefault();
+      const option = filtered[highlight];
+      if (option) select(option.id);
+    } else if (event.key === 'Escape') {
+      setOpen(false);
+    }
+  };
+
+  return (
+    <div className="context-combobox" ref={containerRef}>
+      <span className="context-combobox__label">{label}</span>
+      <button
+        type="button"
+        className="context-combobox__trigger"
+        disabled={Boolean(error)}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        title={error ?? undefined}
+        onClick={() => setOpen((o) => !o)}
+      >
+        <span className="context-combobox__value">
+          {error ? 'Erreur de chargement' : triggerLabel}
+        </span>
+        <FiChevronDown aria-hidden className="context-combobox__chevron" />
+      </button>
+
+      {open && (
+        <div className="context-combobox__panel">
+          <div className="context-combobox__search">
+            <FiSearch aria-hidden />
+            <input
+              ref={inputRef}
+              type="text"
+              value={query}
+              placeholder="Rechercher…"
+              aria-label={`Rechercher ${label.toLowerCase()}`}
+              onChange={(e) => {
+                setQuery(e.target.value);
+                setHighlight(0);
+                onSearch?.(e.target.value);
+              }}
+              onKeyDown={onInputKeyDown}
+            />
+          </div>
+          <ul className="context-combobox__list" role="listbox" id={listId}>
+            {isLoading && <li className="context-combobox__empty">Chargement…</li>}
+            {!isLoading && filtered.length === 0 && (
+              <li className="context-combobox__empty">Aucun résultat</li>
+            )}
+            {!isLoading &&
+              filtered.map((option, index) => {
+                const isSelected = option.id === value;
+                const isHighlighted = index === highlight;
+                return (
+                  <li key={option.id} role="option" aria-selected={isSelected}>
+                    <button
+                      type="button"
+                      className={
+                        'context-combobox__option' +
+                        (isHighlighted ? ' is-highlighted' : '') +
+                        (isSelected ? ' is-selected' : '')
+                      }
+                      onMouseEnter={() => setHighlight(index)}
+                      onClick={() => select(option.id)}
+                    >
+                      <span>{option.label}</span>
+                      {isSelected && <FiCheck aria-hidden />}
+                    </button>
+                  </li>
+                );
+              })}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/vite-extension/src/components/EventPicker.tsx

@@ -0,0 +1,25 @@
+import ContextCombobox from './ContextCombobox';
+import { useContextOptions } from '../hooks/useContextOptions';
+import { useInwinkContext } from '../hooks/useInwinkContext';
+
+/**
+ * Sélecteur d'événement courant. Pré-rempli depuis le contexte (URL) et modifiable.
+ * Composant autonome, montable où l'on veut (header, page…). Non monté par défaut.
+ */
+export default function EventPicker() {
+  const { eventId, setEvent, loadEvents } = useInwinkContext();
+  const { options, isLoading, error, search } = useContextOptions(loadEvents, eventId);
+
+  return (
+    <ContextCombobox
+      label="Événement"
+      placeholder="Choisir un événement"
+      value={eventId}
+      options={options}
+      isLoading={isLoading}
+      error={error}
+      onChange={setEvent}
+      onSearch={search}
+    />
+  );
+}

package/templates/vite-extension/src/components/Header.css

@@ -0,0 +1,25 @@
+.app-header {
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 1.5rem;
+  background: var(--color-bg);
+  border-bottom: 1px solid var(--color-border);
+  box-shadow: var(--shadow-sm);
+}
+
+.app-header__brand {
+  font-family: var(--font-title);
+  font-weight: 600;
+  font-size: 1.1rem;
+}
+
+.app-header__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}

package/templates/vite-extension/src/components/Header.tsx

@@ -0,0 +1,37 @@
+import './Header.css';
+import { FiLogIn, FiLogOut } from 'react-icons/fi';
+import { useAuth } from '../hooks/useAuth';
+
+interface HeaderProps {
+  title: string;
+}
+
+/**
+ * En-tête de l'application : marque à gauche, bouton de connexion/déconnexion à droite.
+ *
+ * Composant volontairement isolé dans son propre fichier pour être facilement
+ * surchargé/personnalisé (ex. y monter un EventPicker / CommunityPicker selon
+ * l'usage de l'extension). Les pickers ne sont PAS montés ici par défaut.
+ */
+export default function Header({ title }: HeaderProps) {
+  const { isAuthenticated, isLoading, login, logout } = useAuth();
+
+  return (
+    <header className="app-header">
+      <div className="app-header__brand">{title}</div>
+      <div className="app-header__actions">
+        {isAuthenticated ? (
+          <button onClick={() => void logout()}>
+            <FiLogOut aria-hidden />
+            Se déconnecter
+          </button>
+        ) : (
+          <button className="btn-primary" disabled={isLoading} onClick={() => void login()}>
+            <FiLogIn aria-hidden />
+            {isLoading ? 'Initialisation…' : 'Se connecter'}
+          </button>
+        )}
+      </div>
+    </header>
+  );
+}

package/templates/vite-extension/src/components/Layout.css

@@ -0,0 +1,13 @@
+.app-layout {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.app-content {
+  flex: 1;
+  width: 100%;
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 2rem 1.5rem;
+}

package/templates/vite-extension/src/components/Layout.tsx

@@ -0,0 +1,19 @@
+import './Layout.css';
+import { Outlet } from 'react-router-dom';
+import Header from './Header';
+
+interface LayoutProps {
+  title: string;
+}
+
+/** Gabarit applicatif : Header + zone de contenu (routes enfants via Outlet). */
+export default function Layout({ title }: LayoutProps) {
+  return (
+    <div className="app-layout">
+      <Header title={title} />
+      <main className="app-content">
+        <Outlet />
+      </main>
+    </div>
+  );
+}

package/templates/vite-extension/src/context/InwinkContextProvider.tsx

@@ -0,0 +1,170 @@
+// Contexte inwink : expose l'objet courant (event / community / tenant) déduit
+// de l'URL ou choisi par l'utilisateur, et les loaders de listes pour les pickers.
+import { createContext, useMemo, useState, type PropsWithChildren } from 'react';
+import { useInwinkCustomerApi } from '../hooks/useInwinkCustomerApi';
+import {
+  deriveScope,
+  loadPersistedContext,
+  persistContext,
+  readInwinkContextFromUrl,
+  type InwinkContextParams,
+  type InwinkScope,
+} from '../lib/inwinkContextParams';
+
+/** Option affichable dans un picker (événement, communauté ou tenant). */
+export interface InwinkContextOption {
+  id: string;
+  label: string;
+}
+
+export interface IInwinkContextQuery {
+  search?: string;
+  id?: string;
+}
+
+interface InwinkContextValue {
+  scope: InwinkScope;
+  eventId?: string;
+  communityId?: string;
+  tenantId?: string;
+  /** Sélectionne un événement (réinitialise la communauté). */
+  setEvent: (id: string) => void;
+  /** Sélectionne une communauté (réinitialise l'événement). */
+  setCommunity: (id: string) => void;
+  /** Sélectionne un tenant / audience (réinitialise event + community). */
+  setTenant: (id: string) => void;
+  /**
+   * Liste les événements de l'utilisateur (API Customer `me/events/query`),
+   * triés par date décroissante. `query` filtre côté serveur par nom ou id.
+   */
+  loadEvents: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>;
+  /**
+   * Liste les communautés de l'utilisateur (API Customer `me/communities/query`).
+   * `query` filtre côté serveur par nom ou id.
+   */
+  loadCommunities: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>;
+  /**
+   * Liste les tenants / audiences de l'utilisateur (API Customer `me/tenants/query`).
+   * `query` filtre côté serveur par nom ou id.
+   */
+  loadTenants: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>;
+}
+
+export const InwinkContext = createContext<InwinkContextValue | null>(null);
+
+// Pagination des requêtes `*/query`. Les listes sont paginées côté serveur :
+// la recherche (`query`) sert à retrouver un objet au-delà de la 1re page.
+const PAGE = { index: 0, size: 200 };
+
+// Construit le corps d'une requête de liste (`me/<entité>/query`) :
+// - `query` → filtre serveur par id (égalité) OU libellé (`$contains`) ;
+// - `labelField` → champ texte de l'entité (`title` pour les events, `name` sinon) ;
+// - `orders` → tri serveur (ex. date décroissante pour les events).
+// Ajuste `selects` / `filters` selon les entités après discovery MCP (cf. AGENTS.md).
+function buildQueryBody(opts: {
+  query?: IInwinkContextQuery;
+  labelField: string;
+  orders?: unknown[];
+}): Record<string, unknown> {
+  const body: Record<string, any> = { page: PAGE };
+  if (opts.orders) body.orders = opts.orders;
+  if (opts.query?.id) {
+    body.filters ??= {};
+    body.filters.id = opts.query.id;    
+  } else if (opts.query?.search) {
+    body.filters ??= {};
+    const q = opts.query?.search?.trim();
+    if (q) {
+      body.filters.$and ??= [];
+      //detect if q is a guid
+      const guidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (guidRegex.test(q)) {
+        body.filters.$and.push({ id: q });
+      } else {
+        body.filters.$and.push({ [opts.labelField]: { $contains: q } });
+      }
+      
+    }
+  }
+  return body;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+}
+
+// Normalise une réponse `*/query` en options { id, label }, quel que soit le wrapping.
+function normalizeOptions(raw: unknown): InwinkContextOption[] {
+  const root = asRecord(raw);
+  const list: unknown[] = Array.isArray(raw)
+    ? raw
+    : Array.isArray(root.data)
+      ? (root.data as unknown[])
+      : Array.isArray(root.items)
+        ? (root.items as unknown[])
+        : [];
+
+  const options: InwinkContextOption[] = [];
+  for (const entry of list) {
+    const item = asRecord(entry);
+    const id = item.id ?? item.eventId ?? item.communityId ?? item.tenantId;
+    if (id == null) continue;
+    const label = item.title ?? item.name ?? item.displayName ?? id;
+    options.push({ id: String(id), label: String(label) });
+  }
+  return options;
+}
+
+/** Init : l'URL fait foi ; sinon on retombe sur le contexte persisté en session. */
+function initialParams(): InwinkContextParams {
+  const fromUrl = readInwinkContextFromUrl();
+  if (fromUrl.eventId || fromUrl.communityId || fromUrl.tenantId) {
+    persistContext(fromUrl);
+    return fromUrl;
+  }
+  return loadPersistedContext();
+}
+
+export function InwinkContextProvider({ children }: PropsWithChildren) {
+  const customerApi = useInwinkCustomerApi();
+  const [params, setParams] = useState<InwinkContextParams>(initialParams);
+
+  const value = useMemo<InwinkContextValue>(() => {
+    const apply = (next: InwinkContextParams) => {
+      setParams(next);
+      persistContext(next);
+    };
+    return {
+      scope: deriveScope(params),
+      eventId: params.eventId,
+      communityId: params.communityId,
+      tenantId: params.tenantId,
+      setEvent: (id) => apply({ ...params, eventId: id, communityId: undefined }),
+      setCommunity: (id) => apply({ ...params, communityId: id, eventId: undefined }),
+      setTenant: (id) => apply({ tenantId: id }),
+      loadEvents: async (query?: IInwinkContextQuery) =>
+        normalizeOptions(
+          await customerApi.post(
+            '/00000000-0000-0000-0000-000000000000/my/events/query',
+            buildQueryBody({ query, labelField: 'title', orders: [{ desc: true, value: { startDate: {} } }] }),
+          ),
+        ),
+      loadCommunities: async (query?: IInwinkContextQuery) =>
+        normalizeOptions(
+          await customerApi.post(
+            '/00000000-0000-0000-0000-000000000000/my/communities/query',
+            buildQueryBody({ query, labelField: 'name' }),
+          ),
+        ),
+      loadTenants: async (query?: IInwinkContextQuery) =>
+        normalizeOptions(
+          await customerApi.post(
+            '/00000000-0000-0000-0000-000000000000/my/tenants/query',
+            buildQueryBody({ query, labelField: 'name' }),
+          ),
+        ),
+    };
+  }, [params, customerApi]);
+
+  return <InwinkContext.Provider value={value}>{children}</InwinkContext.Provider>;
+}

package/templates/vite-extension/src/hooks/useContextOptions.ts

@@ -0,0 +1,106 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { IInwinkContextQuery, InwinkContextOption } from '../context/InwinkContextProvider';
+
+interface ContextOptionsState {
+  options: InwinkContextOption[];
+  isLoading: boolean;
+  error: string | null;
+  /** Relance le loader avec un terme de recherche texte (debouncé). */
+  search: (query: string) => void;
+}
+
+const DEBOUNCE_MS = 250;
+
+/**
+ * Charge une liste d'options de contexte via le loader fourni
+ * (`loadEvents` / `loadCommunities` / `loadTenants` de useInwinkContext).
+ * Mutualise la gestion chargement / erreur des pickers et expose `search()`
+ * pour relancer le loader côté serveur (par nom ou id) en debounçant la saisie.
+ *
+ * `selectedId` (id courant, typiquement issu de l'URL) est fetché par id et
+ * fusionné dans les options : la liste `me/<entité>/query` étant paginée (1ʳᵉ page
+ * seulement), l'objet sélectionné peut ne pas y figurer alors qu'il existe — sans ce
+ * fetch le picker afficherait l'id brut au lieu de son libellé.
+ *
+ * Les réponses obsolètes (saisie rapide, démontage) sont ignorées.
+ */
+export function useContextOptions(
+  load: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>,
+  selectedId?: string,
+): ContextOptionsState {
+  const [options, setOptions] = useState<InwinkContextOption[]>([]);
+  const [selectedOption, setSelectedOption] = useState<InwinkContextOption | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // `load` provient du contexte et change d'identité à chaque rendu : on le garde
+  // dans une ref pour ne pas relancer le chargement initial à chaque rendu.
+  const loadRef = useRef(load);
+  loadRef.current = load;
+
+  // Identifiant monotone de requête : seule la dernière en vol met à jour l'état.
+  const reqId = useRef(0);
+  const debounce = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const run = useCallback((query?: IInwinkContextQuery) => {
+    const id = ++reqId.current;
+    setIsLoading(true);
+    setError(null);
+    loadRef.current(query)
+      .then((opts) => {
+        if (id === reqId.current) setOptions(opts);
+      })
+      .catch((err: unknown) => {
+        if (id === reqId.current) setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        if (id === reqId.current) setIsLoading(false);
+      });
+  }, []);
+
+  // Chargement initial (sans filtre) au montage ; invalide les requêtes en vol au démontage.
+  useEffect(() => {
+    run();
+    return () => {
+      reqId.current++;
+      clearTimeout(debounce.current);
+    };
+  }, [run]);
+
+  // Fetch du détail de l'objet sélectionné par id (cf. doc ci-dessus).
+  useEffect(() => {
+    if (!selectedId) {
+      setSelectedOption(null);
+      return;
+    }
+    let active = true;
+    loadRef.current({ id: selectedId })
+      .then((opts) => {
+        if (active) setSelectedOption(opts.find((o) => o.id === selectedId) ?? opts[0] ?? null);
+      })
+      .catch(() => {
+        // En cas d'échec, on laisse le picker afficher l'id brut : non bloquant.
+      });
+    return () => {
+      active = false;
+    };
+  }, [selectedId]);
+
+  const search = useCallback(
+    (query: string) => {
+      clearTimeout(debounce.current);
+      const q = query.trim();
+      debounce.current = setTimeout(() => run(q ? { search: q } : undefined), DEBOUNCE_MS);
+    },
+    [run],
+  );
+
+  // Garantit que l'option sélectionnée est toujours présente (et en tête) même si
+  // elle est absente de la page courante ou d'un résultat de recherche filtré.
+  const mergedOptions = useMemo(() => {
+    if (!selectedOption || options.some((o) => o.id === selectedOption.id)) return options;
+    return [selectedOption, ...options];
+  }, [options, selectedOption]);
+
+  return { options: mergedOptions, isLoading, error, search };
+}

package/templates/vite-extension/src/hooks/useInwinkContext.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+import { InwinkContext } from '../context/InwinkContextProvider';
+
+/** Accès au contexte inwink courant (event / community / tenant + loaders de listes). */
+export function useInwinkContext() {
+  const context = useContext(InwinkContext);
+
+  if (!context) {
+    throw new Error('useInwinkContext must be used within InwinkContextProvider.');
+  }
+
+  return context;
+}

package/templates/vite-extension/src/lib/inwinkContextParams.ts

@@ -0,0 +1,80 @@
+// Lecture / persistance du contexte inwink (event / community / tenant) passé
+// par le back-office dans l'URL à l'ouverture de l'extension.
+//
+// Pourquoi persister ? Le callback OIDC nettoie la query string
+// (`window.history.replaceState({}, '', pathname)`) et le `redirect_uri` ne
+// réémet pas la query : sans persistance, le contexte serait perdu après login.
+// On capture donc les paramètres dès le chargement dans sessionStorage.
+
+export type InwinkScope = 'event' | 'community' | 'tenant' | null;
+
+export interface InwinkContextParams {
+  eventId?: string;
+  communityId?: string;
+  tenantId?: string;
+}
+
+const STORAGE_KEY = 'inwink.context';
+
+/** Recherche une clé insensible à la casse dans un jeu de paramètres. */
+function pick(params: URLSearchParams, key: string): string | undefined {
+  for (const [k, v] of params.entries()) {
+    if (k.toLowerCase() === key && v) {
+      return v;
+    }
+  }
+  return undefined;
+}
+
+function paramsFromHashQuery(): URLSearchParams {
+  const hash = window.location.hash;
+  const queryIndex = hash.indexOf('?');
+  return queryIndex >= 0
+    ? new URLSearchParams(hash.slice(queryIndex + 1))
+    : new URLSearchParams();
+}
+
+/**
+ * Lit `eventid` / `communityid` / `tenantid` depuis l'URL.
+ * Couvre la query classique (`?eventid=`) ET la query dans le hash (`#/...?eventid=`),
+ * car le routage utilise HashRouter.
+ */
+export function readInwinkContextFromUrl(): InwinkContextParams {
+  const search = new URLSearchParams(window.location.search);
+  const hash = paramsFromHashQuery();
+  const get = (key: string) => pick(search, key) ?? pick(hash, key);
+
+  const params: InwinkContextParams = {};
+  const eventId = get('eventid');
+  const communityId = get('communityid');
+  const tenantId = get('tenantid');
+  if (eventId) params.eventId = eventId;
+  if (communityId) params.communityId = communityId;
+  if (tenantId) params.tenantId = tenantId;
+  return params;
+}
+
+export function persistContext(params: InwinkContextParams): void {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(params));
+  } catch {
+    // sessionStorage indisponible (mode privé strict) : on ignore silencieusement.
+  }
+}
+
+export function loadPersistedContext(): InwinkContextParams {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as InwinkContextParams) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Détermine le scope courant. Priorité : event > community > tenant. */
+export function deriveScope(params: InwinkContextParams): InwinkScope {
+  if (params.eventId) return 'event';
+  if (params.communityId) return 'community';
+  if (params.tenantId) return 'tenant';
+  return null;
+}

package/templates/vite-extension/src/main.tsx

@@ -3,13 +3,16 @@ import ReactDOM from 'react-dom/client';
 import { HashRouter } from 'react-router-dom';
 import App from './App';
 import { AuthProvider } from './auth/AuthProvider';
+import { InwinkContextProvider } from './context/InwinkContextProvider';
 import './styles.css';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <HashRouter>
       <AuthProvider>
-        <App />
+        <InwinkContextProvider>
+          <App />
+        </InwinkContextProvider>
       </AuthProvider>
     </HashRouter>
   </React.StrictMode>,

package/templates/vite-extension/src/pages/HomePage.tsx.tpl

@@ -1,26 +1,30 @@
-import { FiLogIn, FiLogOut } from 'react-icons/fi';
 import { useAuth } from '../hooks/useAuth';
+import { useInwinkContext } from '../hooks/useInwinkContext';
 
 export default function HomePage() {
-  const { isAuthenticated, isLoading, login, logout, user } = useAuth();
+  const { isAuthenticated, user } = useAuth();
+  const { scope, eventId, communityId, tenantId } = useInwinkContext();
+
+  if (!isAuthenticated) {
+    return (
+      <section>
+        <h1>__DISPLAY_NAME__</h1>
+        <p>Connectez-vous via le bouton « Se connecter » en haut à droite.</p>
+      </section>
+    );
+  }
 
   return (
-    <main>
+    <section>
       <h1>__DISPLAY_NAME__</h1>
-      {!isAuthenticated ? (
-        <button disabled={isLoading} onClick={() => void login()}>
-          <FiLogIn aria-hidden />
-          {isLoading ? 'Initialisation...' : 'Se connecter'}
-        </button>
-      ) : (
-        <>
-          <p>Connecté en tant que : {user?.profile.email ?? 'Inconnu'}</p>
-          <button onClick={() => void logout()}>
-            <FiLogOut aria-hidden />
-            Se déconnecter
-          </button>
-        </>
-      )}
-    </main>
+      <p>Connecté en tant que : {user?.profile.email ?? 'Inconnu'}</p>
+      <p>
+        Contexte courant : {scope ?? 'aucun'}
+        {eventId ? ` — événement ${eventId}` : ''}
+        {communityId ? ` — communauté ${communityId}` : ''}
+        {tenantId ? ` — audience ${tenantId}` : ''}
+      </p>
+      {/* Ajoutez ici la logique métier de l'extension. */}
+    </section>
   );
 }

package/templates/vite-extension/src/styles.css

@@ -1,32 +1,91 @@
+/* Polices inwink : Lato (texte) + Poppins (titres) via Google Fonts.
+   Nécessite que fonts.googleapis.com / fonts.gstatic.com soient déclarés
+   dans extension.manifest.json > permissions.externalHosts. */
+@import url('https://fonts.googleapis.com/css2?family=Lato:wght@400;700&family=Poppins:wght@500;600;700&display=swap');
+
+/* Design tokens — inspirés de l'identité inwink. */
 :root {
-  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  /* Polices */
+  --font-base: 'Lato', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  --font-title: 'Poppins', var(--font-base);
+
+  /* Couleur d'accentuation */
+  --color-accent: #e94c1e;
+  --color-accent-hover: #cf3f15;
+  --color-accent-contrast: #ffffff;
+
+  /* Neutres */
+  --color-bg: #ffffff;
+  --color-surface: #f7f7f8;
+  --color-border: #e2e2e6;
+  --color-text: #1d1d1f;
+  --color-text-muted: #6b6b73;
+
+  /* Rayons & ombres */
+  --radius: 8px;
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06);
+
+  font-family: var(--font-base);
   line-height: 1.5;
-  color-scheme: light dark;
+  color: var(--color-text);
+  background: var(--color-bg);
+}
+
+* {
+  box-sizing: border-box;
 }
 
 body {
   margin: 0;
-  padding: 2rem;
+  font-family: var(--font-base);
+  background: var(--color-bg);
+  color: var(--color-text);
 }
 
-main {
-  max-width: 720px;
-  margin: 0 auto;
+h1,
+h2,
+h3 {
+  font-family: var(--font-title);
+  font-weight: 600;
+  line-height: 1.2;
 }
 
+a {
+  color: var(--color-accent);
+}
+
+/* Boutons — base générique réutilisable.
+   .btn-primary = action principale (accent), sinon variante neutre. */
 button {
   cursor: pointer;
   display: inline-flex;
   align-items: center;
   gap: 0.5rem;
   padding: 0.5rem 1rem;
-  border-radius: 6px;
-  border: 1px solid currentColor;
-  background: transparent;
+  border-radius: var(--radius);
+  border: 1px solid var(--color-border);
+  background: var(--color-bg);
+  color: var(--color-text);
   font: inherit;
+  transition: background-color 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+}
+
+button:hover:not(:disabled) {
+  border-color: var(--color-accent);
 }
 
 button:disabled {
   cursor: default;
   opacity: 0.6;
 }
+
+button.btn-primary {
+  background: var(--color-accent);
+  border-color: var(--color-accent);
+  color: var(--color-accent-contrast);
+}
+
+button.btn-primary:hover:not(:disabled) {
+  background: var(--color-accent-hover);
+  border-color: var(--color-accent-hover);
+}