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

package/dist/cli.js

@@ -252,7 +252,8 @@ function bootstrap(opts) {
       error(`La cible existe et n'est pas un dossier : ${destDir}`);
       return 1;
     }
-    const entries = fs3.readdirSync(destDir);
+    const IGNORED_DIRS = /* @__PURE__ */ new Set([".claude", ".github", ".git", ".vscode", ".idea", ".cursor"]);
+    const entries = fs3.readdirSync(destDir).filter((e) => !IGNORED_DIRS.has(e));
     if (entries.length > 0 && !opts.force) {
       error(`Le dossier cible n'est pas vide : ${destDir}`);
       info("Utilisez --force pour \xE9crire malgr\xE9 tout, ou --dir vers un dossier vide.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inwink-mcp/backoffice-extension-helpers",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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/auth/AuthProvider.tsx

@@ -1,5 +1,5 @@
 // src/auth/AuthProvider.tsx
-import { createContext, useEffect, useState, type PropsWithChildren } from 'react';
+import { createContext, useCallback, useEffect, useMemo, useRef, useState, type PropsWithChildren } from 'react';
 import type { User } from 'oidc-client-ts';
 import { userManager } from './config';
 
@@ -24,6 +24,8 @@ function isOidcCallback(): boolean {
 export function AuthProvider({ children }: PropsWithChildren) {
   const [user, setUser] = useState<User | null>(null);
   const [isLoading, setIsLoading] = useState(true);
+  const userRef = useRef(user);
+  useEffect(() => { userRef.current = user; }, [user]);
 
   useEffect(() => {
     let isMounted = true;
@@ -56,24 +58,40 @@ export function AuthProvider({ children }: PropsWithChildren) {
     };
   }, []);
 
+  const login = useCallback(async () => {
+    setIsLoading(true);
+    await userManager.signinRedirect();
+  }, []);
+
+  const logout = useCallback(async () => {
+    await userManager.removeUser();
+    setUser(null);
+  }, []);
+
+  const getAccessToken = useCallback(() => userRef.current?.access_token ?? null, []);
+
+  const renewToken = useCallback(async () => {
+    try {
+      const renewed = await userManager.signinSilent();
+      setUser(renewed);
+      return renewed?.access_token ?? null;
+    } catch {
+      return null;
+    }
+  }, []);
+
+  const value = useMemo(() => ({
+    isAuthenticated: Boolean(user && !user.expired),
+    isLoading,
+    login,
+    logout,
+    user,
+    getAccessToken,
+    renewToken,
+  }), [user, isLoading]);
+
   return (
-    <AuthContext.Provider value={{
-      isAuthenticated: Boolean(user && !user.expired),
-      isLoading,
-      login: async () => { setIsLoading(true); await userManager.signinRedirect(); },
-      logout: async () => { await userManager.removeUser(); setUser(null); },
-      user,
-      getAccessToken: () => user?.access_token ?? null,
-      renewToken: async () => {
-        try {
-          const renewed = await userManager.signinSilent();
-          setUser(renewed);
-          return renewed?.access_token ?? null;
-        } catch {
-          return null;
-        }
-      },
-    }}>
+    <AuthContext.Provider value={value}>
       {children}
     </AuthContext.Provider>
   );

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>
+  );
+}