@mostajs/users-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — @mostajs/users-ui
+
+Format : Keep a Changelog · SemVer.
+
+## [0.1.0] — 2026-06-18
+### Added
+- Logique **headless** : `validateUserForm`, `buildUsersListViewModel`, `buildMemberCard`, `createUsersUiController` (filtres/pagination/submit/toggleStatus/remove).
+- Composants **React** (`@mostajs/users-ui/react`) : `<UsersList>`, `<UserForm>`, `<PhotoCapture>`/`<FaceEnroll>`, `<MemberCardGenerator>`.
+- Exemple §12 headless + tests `test-scripts/unit` (8 verts).
+- Démos web : `examples/web-demo` (vanilla, admin liste) et `examples/web-react` (composants React + **carte/QR rendu par `@mostajs/qrpanel`** via `useQrDataUrl`) avec scripts de démarrage.
+- `<MemberCardGenerator>` compose `@mostajs/qrpanel/qr-image` (QR), ne réembarque pas `qrcode`.
+
+### Notes
+- **Peer-dependency stricte `@mostajs/users`** (le contrôleur throw sans le service). `password` → `@mostajs/auth` ; rôles → `@mostajs/rbac`.
+- Extraction depuis `SolutionCh/MostaGare` (components/admin/User*) + `SolutionCh/SecuAccessPro` (FaceDetector/ClientCardGenerator). Composants Roles → contribués à `@mostajs/rbac`.

package/README.md

@@ -0,0 +1,31 @@
+# @mostajs/users-ui
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+**Stack** : membre de `@mostajs/users-stack` (`../`). **Statut** : 0.1.0 (headless exécutable — 8 tests verts).
+
+> **UI d'administration des utilisateurs** — couche de présentation de `@mostajs/users`.
+> **Logique headless** (testable sans navigateur) + **composants React** (`@mostajs/users-ui/react`).
+
+## ⚠ Dépendance stricte
+**`@mostajs/users-ui` → `@mostajs/users`** (peer). Le contrôleur **throw** sans le service `users`.
+`password` → `@mostajs/auth` · rôles → `@mostajs/rbac` · composants Roles → contribués à `rbac` (pas ici).
+
+## Headless (exécutable)
+```js
+import { createUsersUiController, validateUserForm } from '@mostajs/users-ui';
+const ui = createUsersUiController({ service: usersService });   // usersService = createUsers()
+const r = await ui.submit({ firstName:'Inès', email:'ines@ex.dz' });   // valide + crée via users
+const vm = await ui.refresh();   // {rows, stats, ...}
+```
+
+## React
+```jsx
+import { UsersList, UserForm, PhotoCapture, MemberCardGenerator } from '@mostajs/users-ui/react';
+<UsersList service={usersService} t={t} onEdit={...} />
+```
+
+## Lancer
+```bash
+node examples/users-ui-headless/run.mjs
+node test-scripts/unit/headless.test.mjs
+```

package/docs/03-PLAN-DEV-USERS-UI.md

@@ -0,0 +1,76 @@
+# 03 — Plan de développement (EXTRACTION) — `@mostajs/users-ui`
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**Date** : 2026-06-18
+**Statut** : proposition à discuter (livrable §9 #3). **Précède le scaffold code.**
+**Principe** : **EXTRAIRE, NE PAS REDÉVELOPPER.** Chaque composant = *lift-and-adapt* d'un composant existant, ou *composition* d'un module. Aucune primitive réécrite.
+**Amont** : `PROPOSITION-MODULE-USERS-UI.md` (§4, carte U1–U7) · `../mosta-users/docs/03-PLAN-DEV-USERS.md`
+**Sources** : `SolutionCh/MostaGare` (`components/admin/User*`, ~2041 l.) · `SolutionCh/SecuAccessPro` (`components/clients/{FaceDetector,ClientForm,ClientCardGenerator}`)
+**Dépendance** : **peer stricte `@mostajs/users`** + `react>=18`. Livré **après `@mostajs/users@0.1`**.
+
+---
+
+## 1. Périmètre & responsabilité unique
+Composants/pages React d'**administration des utilisateurs** — **couche de présentation** de `@mostajs/users`.
+**Hors périmètre (délégué)** : données/actions (`users`), rôles UI (`rbac`), primitives (`ui`), visage (`face`), photo bytes (`storage`), QR (`qrpanel`), abonnement (`subscriptions-plan`), i18n (`i18n`), lecture badge (`scan`/`pwa-scan`). **Composants Roles → contribués à `rbac` (cas B), pas ici.**
+
+## 2. Architecture d'extraction — paramétrage des endpoints (adaptation transverse)
+Les composants MostaGare appellent des **URLs en dur** (`/api/admin/users…`). À l'extraction, on les **paramètre** :
+- `UsersApiProvider` (contexte React) **ou** prop `endpoints` → branché sur `makeUsersHandlers()` de `@mostajs/users`.
+- défauts conventionnels (`/api/admin/users`, `/api/user-preferences`) surchargés par config.
+- Aucun composant ne code d'URL en dur ni de logique métier (déléguée à `users`).
+
+## 3. Carte d'extraction composant-par-composant (source → cible)
+
+| # | Source | Cible `mosta-users-ui/src/` | Action |
+|---|---|---|---|
+| U1 | MostaGare `UsersList.tsx` (472 l. : search/role/status, pagination, stats, toggle-status, delete) | `UsersList.tsx` | **LIFT** + endpoints paramétrés + `ui`/`i18n` |
+| U2 | MostaGare `UserForm.tsx` (344 l. : password/confirm, roles via `/api/admin/roles`) | `UserForm.tsx` | **LIFT** + **ADAPT** : password→`auth`, roles→`rbac`, endpoints |
+| U3 | MostaGare `UserEditForm.tsx` (76 l. : fetch `/api/admin/users/[id]`) | `UserEditForm.tsx` | **LIFT** + endpoint paramétré |
+| U4 | SecuAccessPro `FaceDetector.tsx` (`onCapture({photo,faceDescriptor})`, webcam, loadModels) | `PhotoCapture.tsx` + `FaceEnroll.tsx` | **LIFT** + **DROP→COMPOSE `@mostajs/face`** (retire `faceApi` local) |
+| U5 | SecuAccessPro `ClientCardGenerator.tsx` (`qrcode`+`html2canvas`, download/print) | `MemberCardGenerator.tsx` | **LIFT** + **COMPOSE `qrpanel`** (QR) + `subscriptions-plan` ; garder rasterisation (`html2canvas`) |
+| U6 | SecuAccessPro `ClientForm.tsx` (`handleFaceCapture`→form) | câblage `<PhotoCapture>` dans `<UserForm>` | **PATTERN** (intégration) |
+| U7 | MostaGare `user-preferences` UI + `messages/{fr,ar,en}.json` | `UserPreferencesPanel.tsx` + `i18n/` | **EXTRACT** + compose `i18n` |
+| U8 | (dérivé U1/U2/U3) | `pages/` (UsersAdminPage prête à brancher) | **ASSEMBLE** (façon rbac UI) |
+| — | MostaGare `Role*` (~1149 l.) | **→ `@mostajs/rbac` (cas B)** | **OUT** |
+
+> Actions ∈ {LIFT, ADAPT, EXTRACT, COMPOSE, DROP→COMPOSE, ASSEMBLE, PATTERN}. **Aucune ligne « réécrire de zéro ».**
+
+## 4. Composition (§10) — déclarée
+**`@mostajs/users` (peer, requis)** · `rbac` (rôles) · `ui` (primitives) · `i18n` (FR/AR/EN + RTL) · `face` (visage) · `storage` (photo) · `qrpanel` (QR) · `subscriptions-plan` (carte) · `scan`/`pwa-scan` (lecture badge).
+
+## 5. Versions (jalons — ordre d'extraction)
+| Version | Contenu | Extraction | Prérequis |
+|---|---|---|---|
+| **0.1.0** | `<UsersList>` + `<UserForm>` + `<UserEditForm>` + `UsersApiProvider` + `llms.txt`/`CHANGELOG` | U1, U2, U3, §2 | **`@mostajs/users@0.1`** |
+| **0.2.0** | `<PhotoCapture>` + `<FaceEnroll>` (compose `face`/`storage`) + câblage dans `<UserForm>` | U4, U6 | `users@0.3` (enrollFace) |
+| **0.3.0** | `<MemberCardGenerator>` (compose `qrpanel`+`subscriptions-plan`) | U5 | — |
+| **0.4.0** | `<UserPreferencesPanel>` + `<UserRoleAssign>` + i18n FR/AR/EN | U7 | `users@0.2` (preferences) |
+| **0.5.0** | `pages/` admin prêtes (`UsersAdminPage`) + a11y (WCAG) + RTL | U8 | — |
+| **1.0.0** | 14 livrables §9 + portes §11 + exemple §12 + article #17 + **migration MostaGare & SecuAccessPro** | — | — |
+
+## 6. Migrations consommateurs (preuve d'extraction)
+- **MostaGare** : remplacer `components/admin/User*` + pages admin par `@mostajs/users-ui` (endpoints → `makeUsersHandlers`). `Role*` → contribués à `rbac`.
+- **SecuAccessPro** : remplacer `dashboard/users` + `FaceDetector`/`ClientCardGenerator` par les composants `users-ui` (Client = entité **dérivée** de `users`).
+
+## 7. Risques & portes
+| Risque | Mitigation |
+|---|---|
+| URLs en dur non paramétrables | `UsersApiProvider`/prop `endpoints` dès 0.1 (§2) |
+| Re-tomber dans le doublon face/QR | U4/U5 = **DROP→COMPOSE** impératif (`face`/`qrpanel`) |
+| Couplage password dans l'UI | champ délégué à `@mostajs/auth` (U2) ; `users` n'a pas de password |
+| Désync avec `users` | peer-dependency versionnée ; versions alignées (tableau §5) |
+
+**Portes §11** : **§11.1 qualité (bloquante)** build/typecheck/lint + tests composants ; **§11.5 i18n/a11y (UI)** FR/AR/EN + RTL + WCAG 2.1 AA + responsive ; **§11.2/§11.3 informatives** (photo/biométrie affichée → DPIA #16 informatif : consentement, minimisation — *informe l'exploitant, ne bloque pas le dev*) ; §11.8 SemVer + alignement peer `users`.
+
+## 8. Plan de test (aperçu → #4)
+- **Rendu/interaction** (RTL/Testing-Library) : `<UsersList>` (recherche/filtre/pagination/toggle/delete), `<UserForm>` (validation, password→auth, role→rbac), `<PhotoCapture>` (onCapture mock `face`), `<MemberCardGenerator>` (QR via `qrpanel` mock).
+- **i18n/RTL/a11y** : clés FR/AR/EN, sens RTL, axe-core.
+- Tests dans `test-scripts/` (jamais `/tmp`, §5). **Exemple §12** : page admin headless composant `users`+`users-ui` (assertions) AVANT article #17.
+
+## 9. Jalons §9
+`#1` état de l'art (UI admin/IAM — mutualisable avec `users`) · `#2` audit (= doc audit stack) · **`#3` ce plan** · `#4` plan de test · `#6` `llms.txt` dès 0.1 · `#7` CHANGELOG · §12 exemple AVANT #17.
+
+---
+
+**Fin du plan de dev (extraction) `@mostajs/users-ui`.**

package/docs/04-PLAN-TESTS-USERS-UI.md

@@ -0,0 +1,111 @@
+# 04 — Plan de test — `@mostajs/users-ui`
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**Date** : 2026-06-18
+**Statut** : proposition à discuter (livrable §9 #4). Rend la porte **§11.1** vérifiable.
+**Amont** : `03-PLAN-DEV-USERS-UI.md` (carte U1–U8) · `PROPOSITION-MODULE-USERS-UI.md`
+**Emplacement des tests** : `test-scripts/` (JAMAIS `/tmp` — §5), rejouables & committés ; sorties dans `.out*` (gitignorées).
+**Dépendance** : teste l'UI **présentation de `@mostajs/users`** → `users` (et `face`/`rbac`/`qrpanel`/`storage`) sont **mockés** (DI/endpoints).
+
+---
+
+## 1. Stratégie
+- **Composants** (Testing-Library + jsdom) : rendu + interaction, **sans vrai back** — `UsersApiProvider` pointé sur un **mock d'endpoints** (ou `users` mémoire via `makeUsersHandlers` en MSW).
+- **Accessibilité** : `axe-core` (WCAG 2.1 AA) sur chaque écran.
+- **i18n / RTL** : rendu FR/AR/EN + sens **RTL** (AR).
+- **Exemple §12** (`examples/`) : page admin headless composant `users`+`users-ui` avec assertions (DoD, **avant** article #17).
+- **Couverture cible** : composants ≥ 80 % lignes/branches (§11.1).
+- **Isolation des dépendances** : `@mostajs/face` (caméra/modèles), `qrpanel`, `storage`, `rbac`, `auth` → **mockés** (pas d'accès matériel/réseau en CI).
+
+## 2. Matrice de couverture (T-cases)
+
+### 2.1 `<UsersList>` (← U1)
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-LIST-01 | rendu liste depuis endpoint mock | lignes = données ; colonnes nom/email/rôle/statut |
+| TC-LIST-02 | recherche (`search`) | requête endpoint avec param + debounce |
+| TC-LIST-03 | filtre rôle + statut | params `role`/`status` transmis |
+| TC-LIST-04 | pagination | param `page` ; nav page suivante/précédente |
+| TC-LIST-05 | stats (total/actifs/…) | affichage des compteurs renvoyés |
+| TC-LIST-06 | toggle-status (lock/unlock) | PATCH endpoint + maj optimiste/refetch |
+| TC-LIST-07 | delete (confirm) | dialog confirm → DELETE endpoint |
+| TC-LIST-08 | état vide / erreur réseau | message vide / message d'erreur (pas de crash) |
+
+### 2.2 `<UserForm>` / `<UserEditForm>` (← U2/U3)
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-FORM-01 | création : champs requis | validation (email format, nom requis) |
+| TC-FORM-02 | **password → `auth`** | le password n'est PAS écrit dans `users` ; routé via handler auth (mock) |
+| TC-FORM-03 | password ≠ confirm (création) | erreur, submit bloqué |
+| TC-FORM-04 | **rôles via `rbac`** | liste des rôles chargée depuis endpoint rbac (mock), admin filtré selon droits |
+| TC-FORM-05 | édition : préremplissage | `UserEditForm` fetch `[id]` → champs remplis |
+| TC-FORM-06 | submit OK / erreur serveur | toast succès / message erreur |
+| TC-FORM-07 | endpoints paramétrés (Provider) | aucune URL en dur ; utilise `UsersApiProvider` |
+
+### 2.3 `<PhotoCapture>` / `<FaceEnroll>` (← U4 ; compose `face`/`storage`)
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-FACE-01 | `onCapture({photo, faceDescriptor})` émis | callback reçoit photo (dataURL) + descripteur (mock `face`) |
+| TC-FACE-02 | **compose `@mostajs/face`** (pas de `faceApi` local) | `loadModels/detectFace` appelés sur le module mocké |
+| TC-FACE-03 | aucun visage détecté | état « pas de visage » ; `faceDescriptor=null` |
+| TC-FACE-04 | photo → `storage` | upload délégué au mock `storage` (URL signée) |
+| TC-FACE-05 | permission caméra refusée | message d'erreur gracieux (pas de crash) |
+
+### 2.4 `<MemberCardGenerator>` (← U5 ; compose `qrpanel`/`subscriptions-plan`)
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-CARD-01 | QR généré via **`qrpanel`** (mock) | data QR = `qrCode`/id ; pas de `qrcode` réembarqué |
+| TC-CARD-02 | carte = photo + QR + **abonnement** | infos plan via `subscriptions-plan` (mock) |
+| TC-CARD-03 | download / print | rasterisation (html2canvas) → image ; handlers appelés |
+
+### 2.5 `<UserPreferencesPanel>` (← U7)
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-PREF-01 | thème/langue/notifications | GET preferences (mock) → valeurs ; PUT au changement |
+| TC-PREF-02 | i18n des libellés | clés FR/AR/EN résolues (compose `i18n`) |
+
+### 2.6 `<UserRoleAssign>` (← délégué rbac)
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-ROLE-01 | affecter / révoquer rôle | appelle handlers rbac (mock) ; pas de logique rôle locale |
+
+### 2.7 Pages (← U8) & transverses
+| ID | Cas | Attendu |
+|---|---|---|
+| TC-PAGE-01 | `UsersAdminPage` assemble liste+form | navigation liste ↔ création/édition |
+| TC-A11Y-01 | axe-core sur chaque écran | 0 violation critique WCAG 2.1 AA |
+| TC-RTL-01 | rendu AR | direction RTL, libellés AR |
+| TC-DEP-01 | **peer `@mostajs/users` absent** | erreur explicite/typed (le module ne fonctionne pas sans `users`) |
+
+## 3. Doublures de test (mocks/DI)
+| Dépendance | Doublure |
+|---|---|
+| `@mostajs/users` (handlers) | MSW sur `makeUsersHandlers()` **ou** mock `endpoints` du `UsersApiProvider` |
+| `@mostajs/face` | mock `loadModels/detectFace/extractDescriptor` (descripteur factice) |
+| `@mostajs/qrpanel` | mock renvoyant un dataURL QR déterministe |
+| `@mostajs/storage` | mock upload → URL signée factice |
+| `@mostajs/rbac` | mock liste rôles |
+| `@mostajs/auth` | mock handler password |
+| caméra (`getUserMedia`) | stub jsdom |
+
+## 4. Emplacement & exécution
+```
+mosta-users-ui/
+├── test-scripts/
+│   ├── components/   # TC-LIST/FORM/FACE/CARD/PREF/ROLE (Testing-Library + jsdom)
+│   ├── a11y/         # axe-core (TC-A11Y), RTL (TC-RTL)
+│   └── .out*/        # sorties (gitignorées)
+└── examples/
+    └── users-admin/  # page admin headless composant users+users-ui + assertions (§12)
+```
+- Rejouables & **committés** ; CI : `build + typecheck + lint + tests` (porte §11.1) — bloquant avant tag/publish.
+
+## 5. Critère de Definition of Done (test)
+- Toutes les T-cases **vertes** ; couverture composants **≥ 80 %**.
+- **0 violation a11y critique** (axe-core) ; rendu **RTL** OK.
+- **Aucune dépendance réelle** appelée en CI (face/qr/storage mockés).
+- **Exemple §12 exécuté** (assertions vertes) → **prérequis de l'article #17**.
+
+---
+
+**Fin du plan de test `@mostajs/users-ui`.**

package/docs/PROPOSITION-MODULE-USERS-UI.md

@@ -0,0 +1,91 @@
+# Proposition de module (cas C — DEVRULES §4) — `@mostajs/users-ui`
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**Date** : 2026-06-18
+**Statut** : **proposition à discuter** (cas C — précède le scaffold code).
+**Stack** : `@mostajs/users-stack` (`../../`) · **livré APRÈS `@mostajs/users`** (dépendance stricte).
+**Principe** : **EXTRACTION de l'existant — NE PAS redévelopper.** *Lift-and-adapt* des composants React éprouvés de `MostaGare` (UI admin riche) + `SecuAccessPro` (photo/visage/carte).
+**Amont** : `../../docs/00-AUDIT-EXTRACTION-USERS-ET-USERS-UI-18062026.md` · `../mosta-users/docs/PROPOSITION-MODULE-USERS.md`
+
+---
+
+## 4.1 Le besoin
+
+L'**UI d'administration des utilisateurs** (liste, recherche, création/édition de profil avec **photo + visage**, préférences, affectation de rôle, **carte/badge** photo+QR+abonnement) est aujourd'hui **réimplémentée** dans `MostaGare` (~2041 lignes de composants admin) et `SecuAccessPro` (UI clients avec photo/face/carte). Besoin **transverse** (tout back-office) → à **extraire** en composants React réutilisables, **couche de présentation** de `@mostajs/users`.
+
+**Consommateurs** : MostaGare, SecuAccessPro + P1/P2/P3 + iquesta (≥ 2 immédiats — §4.4 satisfaite).
+
+---
+
+## 4.2 Application de la règle d'or (§0)
+
+| Proche | Couvre | Ne couvre PAS |
+|---|---|---|
+| `@mostajs/rbac` (UI) | composants **rôles/permissions** (matrice, managers) | l'UI de **gestion des utilisateurs** (liste/profil/photo/visage/carte/préférences) |
+| `@mostajs/ui` | primitives (button/table/dialog/input…) | les **écrans métier** utilisateurs (assemblage) |
+| `@mostajs/face`, `qrpanel` | primitives visage / QR | les **composants utilisateur** qui les **assemblent** (`<FaceEnroll>`, `<MemberCardGenerator>`) |
+
+→ **cas A/B écartés** ; **cas C** confirmé. (Les composants **Roles** de MostaGare relèvent de **l'UI de `rbac`** → contribués à `rbac` en **cas B**, pas ici.)
+
+---
+
+## 4.3 L'argumentation
+
+- **Module séparé du back (`users`)** : même logique que `rbac` (schémas) vs ses composants — un back réutilisable, une UI **optionnelle**. Permet d'utiliser `users` côté serveur sans imposer React.
+- **Dépendance stricte `users-ui` → `users`** : `users-ui` est la **présentation** de `users` ; il consomme ses types/actions/handlers. **Peer-dependency** `peerDependencies: { "@mostajs/users": "^x", "react": ">=18" }`. Sens unique. Build/publish : **`users` d'abord**.
+- **Nom** : `@mostajs/users-ui`, dans `mosta-users-stack/mosta-users-ui/`.
+- **Extraction-first** : composants en prod (MostaGare/SecuAccessPro) → on **modularise**, on ne réécrit pas.
+
+---
+
+## 4.4 La discussion du besoin
+
+- **Bon moment ?** Oui — UI dupliquée sur 2 projets, `users` en cours d'extraction.
+- **Réutilisable ?** Oui — tout back-office. 
+- **Duplication/chevauchement ?** Maîtrisé par **composition** : visage→`face`, QR→`qrpanel`, abonnement→`subscriptions-plan`, rôles→`rbac`, primitives→`ui`, i18n→`i18n`, lecture badge→`scan`/`pwa-scan`. `users-ui` **assemble**, n'implémente aucune primitive.
+- **Alternatives rejetées** : (1) laisser l'UI dans chaque app → divergence (cas actuel) ; (2) tout mettre dans `rbac` UI → mélange rôles/utilisateurs ; (3) réembarquer `face-api`/`qrcode` → réimplémentation interdite (§0) → composer les modules.
+
+---
+
+## 4.5 Documentation technique — **composants EXTRAITS**
+
+### Composants (cible) — façon `rbac` UI, endpoints **paramétrables**
+| Composant | Rôle | Compose |
+|---|---|---|
+| `<UsersList>` | tableau + recherche + filtre rôle/statut + pagination + stats + toggle-status/delete | `users` (handlers), `ui` |
+| `<UserForm>` / `<UserEditForm>` | création / édition profil + sélection rôle | `users`, `rbac` (roles), **`auth`** (password) |
+| `<PhotoCapture>` / `<FaceEnroll>` | webcam → photo + descripteur ; `onCapture({photo, faceDescriptor})` | **`face`** (détection/descripteur), `storage` (photo) |
+| `<MemberCardGenerator>` | carte/badge : photo + **QR** + **abonnement**, download/print | **`qrpanel`**, `subscriptions-plan` |
+| `<UserPreferencesPanel>` | thème / langue / notifications | `users` (preferences), `i18n` |
+| `<UserRoleAssign>` | affecter/révoquer rôles | délégué `rbac` |
+
+### Carte d'extraction (source → cible — *lift/adapt/compose*)
+| # | Source | Cible | Action |
+|---|---|---|---|
+| U1 | MostaGare `components/admin/UsersList.tsx` (472 l. ; fetch `/api/admin/users` search/role/status/pagination/stats, toggle-status, delete) | `src/UsersList.tsx` | **LIFT** + **paramétrer les endpoints** (props/context au lieu d'URL en dur) |
+| U2 | MostaGare `components/admin/UserForm.tsx` (344 l. ; roles via `/api/admin/roles`, password/confirm) | `src/UserForm.tsx` | **LIFT** + **ADAPT** : password → `@mostajs/auth` ; roles → `@mostajs/rbac` |
+| U3 | MostaGare `components/admin/UserEditForm.tsx` (76 l. ; fetch `/api/admin/users/[id]`) | `src/UserEditForm.tsx` | **LIFT** + paramétrer endpoint |
+| U4 | SecuAccessPro `components/clients/FaceDetector.tsx` (`onCapture({photo,faceDescriptor})`, webcam) | `src/PhotoCapture.tsx` + `src/FaceEnroll.tsx` | **LIFT** + **DROP→COMPOSE `@mostajs/face`** (remplace `faceApi`) |
+| U5 | SecuAccessPro `components/clients/ClientCardGenerator.tsx` (`qrcode` + `html2canvas`, download/print) | `src/MemberCardGenerator.tsx` | **LIFT** + **COMPOSE `@mostajs/qrpanel`** (QR) + `subscriptions-plan` (abonnement) ; garder rasterisation carte |
+| U6 | SecuAccessPro `ClientForm.tsx` (câblage `handleFaceCapture` → form) | `<UserForm>` intègre `<PhotoCapture>` | **PATTERN** (montre le câblage photo/visage) |
+| U7 | MostaGare `user-preferences` UI + `messages/{fr,ar,en}.json` | `src/UserPreferencesPanel.tsx` + i18n | **EXTRACT** + compose `i18n` |
+| — | MostaGare `RolesList`/`RoleForm`/`RolePermissionsManager` | **→ `@mostajs/rbac` (cas B)** | **OUT** (hors `users-ui`) |
+
+> **Adaptation transversale** : les composants MostaGare appellent des **URLs en dur** (`/api/admin/users…`). À l'extraction, **paramétrer** (prop `endpoints`/contexte `UsersApiProvider`) pour brancher les `makeUsersHandlers()` de `@mostajs/users`. Aucune logique métier réécrite.
+
+### Composition (§10)
+**`@mostajs/users` (peer — requis)** · `rbac` (rôles) · `ui` (primitives) · `i18n` (FR/AR/EN) · `face` (visage) · `storage` (photo) · `qrpanel` (QR) · `subscriptions-plan` (carte) · `scan`/`pwa-scan` (lecture badge).
+
+### Squelettes
+`README.md` happy-path (install `@mostajs/users-ui @mostajs/users` → `<UsersList endpoints=…/>`). `llms.txt` : RÔLE (UI admin utilisateurs, présentation de `users`), EXPORTS (composants), PIÈGES (peer `users` requis ; endpoints à paramétrer ; ne pas réembarquer face-api/qrcode → composer ; password→auth ; roles→rbac).
+
+---
+
+## Suite (après validation §4)
+Plan de dev #3 (versions : 0.1 `<UsersList>`/`<UserForm>`/`<UserEditForm>` ; 0.2 `<PhotoCapture>`/`<FaceEnroll>`/`<MemberCardGenerator>` ; 0.3 `<UserPreferencesPanel>`/`<UserRoleAssign>` + pages admin) → #4 tests → scaffold code **après `@mostajs/users@0.1`**. Portes §11.1 (bloquante), §11.5 i18n/a11y (UI), §11.2/§11.3 **informatives**.
+
+**Validation demandée** : périmètre (utilisateurs uniquement, Roles → rbac), dépendance stricte `users`, paramétrage des endpoints, noms des composants.
+
+---
+
+**Fin de la proposition `@mostajs/users-ui`.**

package/examples/users-ui-headless/run.mjs

@@ -0,0 +1,32 @@
+// Exemple §12 — @mostajs/users-ui (headless) composant @mostajs/users. node examples/users-ui-headless/run.mjs
+import assert from 'node:assert/strict';
+import { createUsers, createMemoryRepositories } from '../../../mosta-users/src/index.js';
+import { createUsersUiController, validateUserForm, buildMemberCard } from '../../src/index.js';
+
+const service = createUsers({ repositories: createMemoryRepositories(), qr: { generate: (id) => `QR:${id}` } });
+const ui = createUsersUiController({ service, t: (k) => k });
+
+// validation
+assert.equal(validateUserForm({ email: 'bad' }).valid, false);
+assert.equal(validateUserForm({ firstName: 'A', email: 'a@b.dz' }).valid, true);
+
+// submit via le contrôleur (password délégué à auth, jamais persisté dans users)
+const r = await ui.submit({ firstName: 'Leïla', lastName: 'Hadj', email: 'leila@ex.dz', password: 'x', confirmPassword: 'x' });
+assert.ok(r.ok && r.user.id);
+assert.equal(r._passwordDelegatedToAuth, true);
+assert.ok(!('password' in r.user), 'users ne stocke pas le password');
+
+// liste view-model + stats
+await ui.submit({ firstName: 'Omar' });
+const vm = await ui.refresh();
+assert.equal(vm.total, 2);
+assert.ok(vm.rows.find((x) => x.displayName === 'Leïla Hadj'));
+
+// carte membre
+const card = buildMemberCard(r.user);
+assert.ok(card.qr.startsWith('QR:'));
+
+// dépendance stricte : sans service → erreur
+assert.throws(() => createUsersUiController({}), /service @mostajs\/users requis/);
+
+console.log('✅ @mostajs/users-ui (headless) — OK (dépend de @mostajs/users)');

package/examples/web-demo/README.md

@@ -0,0 +1,23 @@
+# Démo web — interface `@mostajs/users-ui` (autonome)
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+Interface **dédiée** d'administration des utilisateurs (application autonome, **non fusionnée** avec allocations).
+Zéro-build (DEVRULES §12) : importmap → modules ESM réels, état **in-memory** navigateur.
+
+## Démarrer
+```bash
+./serve.sh            # (ou ./serve.sh 8080)
+```
+Le script sert depuis la **racine commune** (`mosta-users-stack/`, car l'importmap référence le module voisin
+`@mostajs/users`) et affiche l'URL exacte à ouvrir, p. ex. :
+`http://localhost:8000/mosta-users-ui/examples/web-demo/index.html`
+
+> Lancement manuel équivalent : depuis `mosta-users-stack/`, `python3 -m http.server` puis ouvrir l'URL ci-dessus.
+> Pour exécuter une commande dans cette session, tape-la préfixée de `!`.
+
+## Ce que ça montre
+- Création/validation d'utilisateur, liste + recherche + stats, verrouiller/déverrouiller/supprimer — pilotés par
+  la **logique headless** de `@mostajs/users-ui` (`createUsersUiController`, `validateUserForm`) au-dessus de `@mostajs/users`.
+- **QR / carte membre** : le rendu de l'image QR **compose `@mostajs/qrpanel`** dans le composant React
+  `<MemberCardGenerator>` (`useQrDataUrl`). Cette démo vanilla affiche l'admin liste ; pour la carte/QR live, utiliser le composant React `@mostajs/users-ui/react`.

package/examples/web-demo/app.mjs

@@ -0,0 +1,50 @@
+// Interface @mostajs/users-ui (application autonome). Author: Dr Hamid MADANI <drmdh@msn.com>
+import { createUsers, createMemoryRepositories } from '@mostajs/users';
+import { createUsersUiController, validateUserForm } from '@mostajs/users-ui';
+
+const $ = (id) => document.getElementById(id);
+const t = (k) => ({ 'status.active': 'actif', 'status.locked': 'verrouillé', 'status.disabled': 'désactivé' }[k] || k);
+
+// users-ui pilote @mostajs/users (dépendance)
+// Le payload de carte (qrCode) est généré par défaut ; le RENDU de l'image QR compose @mostajs/qrpanel
+// (composant <MemberCardGenerator> / useQrDataUrl). Ici, démo vanilla → on n'affiche que l'admin liste.
+const service = createUsers({ repositories: createMemoryRepositories() });
+const ui = createUsersUiController({ service, t });
+
+$('u-add').onclick = async () => {
+  const form = { firstName: $('u-first').value.trim(), lastName: $('u-last').value.trim(), email: $('u-email').value.trim() };
+  const v = validateUserForm(form);
+  $('u-err').textContent = v.valid ? '' : Object.values(v.errors).join(' · ');
+  if (!v.valid) return;
+  const r = await ui.submit(form);
+  if (!r.ok) { $('u-err').textContent = Object.values(r.errors).join(' · '); return; }
+  $('u-first').value = $('u-last').value = $('u-email').value = '';
+  render();
+};
+$('u-search').oninput = (e) => { ui.setFilters({ search: e.target.value }); render(); };
+
+async function render() {
+  const vm = await ui.refresh();
+  $('u-stats').textContent = `total ${vm.stats.total} · ${t('status.active')} ${vm.stats.active} · ${t('status.locked')} ${vm.stats.locked} · ${t('status.disabled')} ${vm.stats.disabled}`;
+  $('u-rows').innerHTML = vm.rows.map((r) => `
+    <tr>
+      <td>${r.displayName}</td><td>${r.email || ''}</td>
+      <td><span class="pill s-${r.status}">${r.statusLabel}</span></td>
+      <td>
+        <button class="sm ghost" data-do="toggle" data-id="${r.id}" data-st="${r.status}">${r.status === 'locked' ? 'déverrouiller' : 'verrouiller'}</button>
+        <button class="sm ghost" data-do="del" data-id="${r.id}">suppr.</button>
+      </td>
+    </tr>`).join('');
+  $('u-rows').querySelectorAll('[data-do]').forEach((b) => {
+    b.onclick = async () => {
+      if (b.dataset.do === 'toggle') await ui.toggleStatus(b.dataset.id, b.dataset.st);
+      else await ui.remove(b.dataset.id);
+      render();
+    };
+  });
+}
+
+// seed démo
+for (const n of [['Amina', 'Belkacem', 'amina@ex.dz'], ['Karim', 'Saidi', 'karim@ex.dz']])
+  await ui.submit({ firstName: n[0], lastName: n[1], email: n[2] });
+render();

package/examples/web-demo/index.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="fr">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Interface — @mostajs/users-ui</title>
+<!--
+  Auteur : Dr Hamid MADANI <drmdh@msn.com>
+  Démo navigateur ZÉRO-BUILD (DEVRULES §12) — interface DÉDIÉE @mostajs/users-ui (application autonome).
+  Lancer : ./serve.sh  (ou python3 -m http.server) → http://localhost:8000
+-->
+<script type="importmap">
+{
+  "imports": {
+    "@mostajs/users":    "../../../mosta-users/src/index.js",
+    "@mostajs/users-ui": "../../src/index.js"
+  }
+}
+</script>
+<style>
+  :root { --card:#1e293b; --mut:#94a3b8; --ok:#22c55e; --warn:#f59e0b; --bad:#ef4444; --acc:#a78bfa; }
+  *{box-sizing:border-box} body{margin:0;font:14px/1.5 system-ui,sans-serif;background:#0b1220;color:#e2e8f0}
+  header{padding:16px 24px;background:#0f172a;border-bottom:1px solid #334155}
+  header h1{margin:0;font-size:18px;color:var(--acc)} header small{color:var(--mut)}
+  .wrap{max-width:880px;margin:0 auto;padding:16px 24px}
+  .card{background:var(--card);border:1px solid #334155;border-radius:12px;padding:16px;margin-bottom:16px}
+  .card h2{margin:0 0 12px;font-size:15px}
+  label{display:block;font-size:12px;color:var(--mut);margin:8px 0 2px}
+  input,select{width:100%;padding:8px;border-radius:8px;border:1px solid #475569;background:#0f172a;color:#e2e8f0}
+  button{padding:7px 12px;border-radius:8px;border:0;background:var(--acc);color:#1a1033;font-weight:700;cursor:pointer}
+  button.ghost{background:#334155;color:#e2e8f0} button.sm{padding:4px 8px;font-size:12px}
+  .row{display:flex;gap:8px;align-items:end}.row>*{flex:1}
+  .stats{color:var(--mut);font-size:12px;margin:8px 0}
+  table{width:100%;border-collapse:collapse;margin-top:10px}th,td{text-align:left;padding:6px 8px;border-bottom:1px solid #334155;font-size:13px}
+  .pill{padding:2px 8px;border-radius:999px;font-size:11px;font-weight:700}
+  .s-active{background:rgba(34,197,94,.15);color:var(--ok)} .s-locked{background:rgba(245,158,11,.15);color:var(--warn)} .s-disabled{background:rgba(239,68,68,.15);color:var(--bad)}
+  .err{color:var(--bad);font-size:12px;min-height:16px}
+</style>
+</head>
+<body>
+<header>
+  <h1>👤 @mostajs/users-ui</h1>
+  <small>Application autonome — administration des utilisateurs (logique headless du module). État in-memory.</small>
+</header>
+<div class="wrap">
+  <section class="card">
+    <h2>Créer un utilisateur</h2>
+    <div class="row">
+      <div><label>Prénom</label><input id="u-first" /></div>
+      <div><label>Nom</label><input id="u-last" /></div>
+    </div>
+    <label>Email</label><input id="u-email" placeholder="nom@ex.dz" />
+    <div id="u-err" class="err"></div>
+    <button id="u-add">+ Créer</button>
+  </section>
+
+  <section class="card">
+    <h2>Utilisateurs</h2>
+    <label>Recherche</label><input id="u-search" placeholder="nom, email…" />
+    <div class="stats" id="u-stats"></div>
+    <table><thead><tr><th>Nom</th><th>Email</th><th>Statut</th><th></th></tr></thead><tbody id="u-rows"></tbody></table>
+  </section>
+</div>
+<script type="module" src="./app.mjs"></script>
+</body>
+</html>

package/examples/web-demo/serve.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Démarre la démo web @mostajs/users-ui (zéro-build). Author: Dr Hamid MADANI <drmdh@msn.com>
+# L'importmap référence des modules voisins (../../../) → on sert depuis la RACINE commune.
+# Usage : ./serve.sh [port]
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$DIR/../../.." && pwd)"          # mosta-users-stack (contient mosta-users + mosta-users-ui)
+REL="${DIR#"$ROOT"/}/index.html"
+PORT="${1:-8000}"
+echo "📂 racine servie : $ROOT"
+echo "🌐 ouvrir       : http://localhost:$PORT/$REL"
+cd "$ROOT"
+exec python3 -m http.server "$PORT"

package/examples/web-react/README.md

@@ -0,0 +1,28 @@
+# Démo React — `@mostajs/users-ui` (carte + QR qrpanel en direct)
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+Variante **React** zéro-build qui charge les **vrais composants** `@mostajs/users-ui/react`
+(`<UserForm>`, `<UsersList>`, `<MemberCardGenerator>`). La **carte membre** affiche un **QR rendu en direct
+par `@mostajs/qrpanel`** (`useQrDataUrl` de `@mostajs/qrpanel/qr-image`).
+
+## Démarrer
+```bash
+./serve.mjs            # (ou node serve.mjs 8080)
+```
+Le serveur Node sert les `.jsx`/`.mjs` en `text/javascript` (ce que `python http.server` ne fait pas) et
+sert depuis la racine `mostajs/` (pour atteindre `@mostajs/qrpanel`). Il affiche l'URL à ouvrir, p. ex. :
+`http://localhost:8000/mosta-users-stack/mosta-users-ui/examples/web-react/index.html`
+
+> **Internet requis au runtime** : `react`, `react-dom`, `qrcode`, `html2canvas` sont chargés via `esm.sh`
+> (importmap). Nos modules (`@mostajs/*`) sont servis en local. Pour exécuter ici, tape `!…/serve.mjs`.
+
+## Ce que ça montre
+- Création d'un utilisateur via le composant **`<UserForm>`** (validation headless, password délégué à `auth`).
+- Liste **`<UsersList>`** (recherche, statut, verrouiller/déverrouiller).
+- **`<MemberCardGenerator>`** : carte (photo avatar + abonnement) + **QR généré par qrpanel** ; bouton de
+  téléchargement PNG (html2canvas).
+
+## Composition (DEVRULES §10)
+`@mostajs/users` (service, peer) · `@mostajs/users-ui/react` (composants) · **`@mostajs/qrpanel`** (QR) ·
+`react`/`html2canvas` (CDN). Aucune primitive QR réembarquée.

package/examples/web-react/app.js

@@ -0,0 +1,53 @@
+// Démo React @mostajs/users-ui (carte + QR qrpanel live). Author: Dr Hamid MADANI <drmdh@msn.com>
+// React.createElement (pas de JSX → pas de transpilation). Charge les VRAIS composants du module.
+import React, { useState, useMemo, useCallback } from 'react';
+import { createRoot } from 'react-dom/client';
+import { createUsers, createMemoryRepositories } from '@mostajs/users';
+import { UsersList, UserForm, MemberCardGenerator } from '@mostajs/users-ui/react';
+
+const h = React.createElement;
+const t = (k) => ({
+  'status.active': 'actif', 'status.locked': 'verrouillé', 'status.disabled': 'désactivé',
+  firstName: 'Prénom', lastName: 'Nom', email: 'Email', role: 'Rôle', password: 'Mot de passe',
+  save: 'Enregistrer', edit: 'éditer', lock: 'verrouiller', unlock: 'déverrouiller',
+  search: 'Recherche…', loading: '…', download: 'Télécharger la carte', capture: 'Capturer',
+}[k] || k);
+
+// avatar SVG (data URL) pour que la carte ait une photo
+const avatar = (a, b) => {
+  const ini = `${(a || '?')[0]}${(b || '')[0] || ''}`.toUpperCase();
+  const svg = `<svg xmlns='http://www.w3.org/2000/svg' width='96' height='96'><rect width='100%' height='100%' rx='12' fill='#a78bfa'/><text x='50%' y='55%' font-size='38' text-anchor='middle' dominant-baseline='middle' font-family='sans-serif' fill='#1a1033'>${ini}</text></svg>`;
+  return 'data:image/svg+xml;utf8,' + encodeURIComponent(svg);
+};
+
+function App() {
+  const service = useMemo(() => createUsers({ repositories: createMemoryRepositories() }), []);
+  const [selected, setSelected] = useState(null);
+  const [tick, setTick] = useState(0);
+  const refresh = useCallback(() => setTick((n) => n + 1), []);
+
+  const onSaved = useCallback(async (u) => {
+    // attache un avatar de démo + sélectionne pour afficher la carte
+    const withPhoto = await service.update(u.id, { photo: avatar(u.firstName, u.lastName) });
+    setSelected(withPhoto); refresh();
+  }, [service, refresh]);
+
+  const onEdit = useCallback(async (id) => setSelected(await service.get(id)), [service]);
+
+  return [
+    h('section', { className: 'card', key: 'left' },
+      h('h2', null, 'Créer / éditer'),
+      h(UserForm, { service, t, onSaved }),
+      h('h2', { style: { marginTop: 18 } }, 'Utilisateurs'),
+      h(UsersList, { service, t, onEdit, key: tick }),    // key=tick → re-render après création
+    ),
+    h('section', { className: 'card', key: 'right' },
+      h('h2', null, '🪪 Carte membre (QR via @mostajs/qrpanel)'),
+      selected
+        ? h(MemberCardGenerator, { user: selected, t, subscription: { planName: 'Abonnement Gold' } })
+        : h('div', { style: { color: '#94a3b8' } }, 'Crée un utilisateur ou clique « éditer » pour voir sa carte + QR.'),
+    ),
+  ];
+}
+
+createRoot(document.getElementById('root')).render(h(App));

package/examples/web-react/index.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="fr">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Démo React — @mostajs/users-ui (carte + QR qrpanel live)</title>
+<!--
+  Auteur : Dr Hamid MADANI <drmdh@msn.com>
+  Variante REACT zéro-build : charge les VRAIS composants @mostajs/users-ui/react + <MemberCardGenerator>,
+  dont le QR est rendu EN DIRECT par @mostajs/qrpanel (useQrDataUrl). React/qrcode via esm.sh (CDN, internet requis).
+  Lancer : ./serve.mjs   (serveur Node qui sert les .jsx en text/javascript) → URL affichée.
+-->
+<script type="importmap">
+{
+  "imports": {
+    "react":                     "https://esm.sh/react@18.3.1",
+    "react/jsx-runtime":         "https://esm.sh/react@18.3.1/jsx-runtime",
+    "react-dom/client":          "https://esm.sh/react-dom@18.3.1/client",
+    "qrcode":                    "https://esm.sh/qrcode@1.5.4",
+    "html2canvas":               "https://esm.sh/html2canvas@1.4.1",
+    "@mostajs/users":            "../../../mosta-users/src/index.js",
+    "@mostajs/users-ui":         "../../src/index.js",
+    "@mostajs/users-ui/react":   "../../src/react/index.js",
+    "@mostajs/qrpanel/qr-image": "../../../../mosta-qrpanel/dist/qr-image.js"
+  }
+}
+</script>
+<style>
+  :root{--card:#1e293b;--mut:#94a3b8;--ok:#22c55e;--warn:#f59e0b;--acc:#a78bfa}
+  *{box-sizing:border-box} body{margin:0;font:14px/1.5 system-ui,sans-serif;background:#0b1220;color:#e2e8f0}
+  header{padding:16px 24px;background:#0f172a;border-bottom:1px solid #334155}
+  header h1{margin:0;font-size:18px;color:var(--acc)} header small{color:var(--mut)}
+  .wrap{display:grid;grid-template-columns:1.2fr .8fr;gap:16px;padding:16px 24px;align-items:start}
+  @media(max-width:880px){.wrap{grid-template-columns:1fr}}
+  .card{background:var(--card);border:1px solid #334155;border-radius:12px;padding:16px}
+  .card h2{margin:0 0 12px;font-size:15px;color:var(--acc)}
+  input,select{width:100%;padding:8px;border-radius:8px;border:1px solid #475569;background:#0f172a;color:#e2e8f0;margin:4px 0}
+  button{padding:7px 12px;border-radius:8px;border:0;background:var(--acc);color:#1a1033;font-weight:700;cursor:pointer}
+  button.ghost{background:#334155;color:#e2e8f0} .mosta-users-list table{width:100%;border-collapse:collapse}
+  .mosta-users-list td,.mosta-users-list th{padding:6px;border-bottom:1px solid #334155;font-size:13px;text-align:left}
+  .mosta-users-list input{margin-bottom:8px} .mosta-user-form{display:flex;flex-direction:column;gap:6px}
+  /* carte membre */
+  .mosta-member-card{width:260px;background:linear-gradient(135deg,#312e81,#1e293b);border:1px solid #475569;border-radius:14px;padding:16px;display:flex;flex-direction:column;align-items:center;gap:8px;margin-bottom:10px}
+  .mosta-member-card .photo{width:84px;height:84px;border-radius:12px;object-fit:cover}
+  .mosta-member-card .qr{width:120px;height:120px;background:#fff;border-radius:8px;padding:4px}
+  .mosta-member-card strong{font-size:16px}
+</style>
+</head>
+<body>
+<header>
+  <h1>👤 @mostajs/users-ui — variante React</h1>
+  <small>Vrais composants React du module · carte membre avec <b>QR rendu en direct par @mostajs/qrpanel</b></small>
+</header>
+<div id="root" class="wrap"></div>
+<script type="module" src="./app.js"></script>
+</body>
+</html>

package/examples/web-react/serve.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Serveur statique zéro-dépendance pour la démo React. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Sert les .jsx/.mjs en text/javascript (que python http.server ne fait pas) ; racine = mostajs/.
+// Usage : ./serve.mjs [port]   (ou: node serve.mjs 8080)
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, normalize, extname } from 'node:path';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const ROOT = normalize(join(DIR, '..', '..', '..', '..'));        // mostajs/ (contient mosta-users-stack + mosta-qrpanel)
+const REL = DIR.slice(ROOT.length + 1).split(/[\\/]/).join('/') + '/index.html';
+const PORT = Number(process.argv[2]) || 8000;
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8', '.jsx': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml', '.map': 'application/json',
+};
+
+createServer(async (req, res) => {
+  try {
+    const url = decodeURIComponent((req.url || '/').split('?')[0]);
+    const path = normalize(join(ROOT, url === '/' ? '/index.html' : url));
+    if (!path.startsWith(ROOT)) { res.writeHead(403).end('forbidden'); return; }
+    const body = await readFile(path);
+    res.writeHead(200, { 'content-type': MIME[extname(path)] || 'application/octet-stream' });
+    res.end(body);
+  } catch {
+    res.writeHead(404, { 'content-type': 'text/plain' }).end('404');
+  }
+}).listen(PORT, () => {
+  console.log(`📂 racine servie : ${ROOT}`);
+  console.log(`🌐 ouvrir       : http://localhost:${PORT}/${REL}`);
+  console.log('   (React + qrcode via esm.sh — connexion internet requise au runtime)');
+});

package/llms.txt

@@ -0,0 +1,25 @@
+# @mostajs/users-ui — fiche LLM
+
+RÔLE
+  UI d'administration des utilisateurs — couche de PRÉSENTATION de @mostajs/users.
+  Logique HEADLESS (framework-agnostique, testable sans navigateur) + composants React (src/react).
+  DÉPEND de @mostajs/users (peer stricte) ; compose rbac (rôles), ui, i18n, face, qrpanel, subscriptions-plan.
+
+EXPORTS (headless — "@mostajs/users-ui")
+  validateUserForm(data,{isEditing}) -> {valid,errors}
+  buildUsersListViewModel(listResult,{t}) -> {rows,total,page,pageSize,stats}
+  buildMemberCard(user,{subscription}) -> {name,photo,qr,subscription}
+  createUsersUiController({service,t}) -> { query, setFilters, refresh, submit, toggleStatus, remove }
+EXPORTS (react — "@mostajs/users-ui/react")
+  <UsersList> <UserForm> <PhotoCapture>/<FaceEnroll> <MemberCardGenerator>
+
+DÉPENDANCE
+  createUsersUiController EXIGE `service` = createUsers() de @mostajs/users (sinon throw). password → @mostajs/auth ; rôles → @mostajs/rbac.
+
+EXTRACTION
+  MostaGare components/admin/User* (UsersList/UserForm/UserEditForm) + SecuAccessPro FaceDetector/ClientCardGenerator.
+
+PIÈGES
+  - Ne fonctionne pas sans @mostajs/users. Les composants Roles → @mostajs/rbac (pas ici).
+  - PhotoCapture/MemberCardGenerator composent face/qrpanel (ne réembarquent pas face-api/qrcode).
+  - Endpoints/serveur : le contrôleur appelle le service users (in-process) ou des handlers — paramétrable.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mostajs/users-ui",
+  "version": "0.1.0",
+  "description": "UI d'administration des utilisateurs — couche de présentation de @mostajs/users (liste, profil, photo/visage, carte, préférences). Logique headless + composants React.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./react": "./src/react/index.js"
+  },
+  "peerDependencies": {
+    "@mostajs/users": "^0.1.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "mostajs",
+    "users",
+    "admin",
+    "ui",
+    "react"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/headless.test.mjs",
+    "example": "node examples/users-ui-headless/run.mjs"
+  }
+}

package/src/headless.js

@@ -0,0 +1,70 @@
+// @mostajs/users-ui — logique HEADLESS (framework-agnostique), vérifiable sans navigateur.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// Dépend de @mostajs/users (service injecté). Les composants React (src/react) enveloppent cette logique.
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Validation de formulaire utilisateur (password collecté ici mais délégué à @mostajs/auth). */
+export function validateUserForm(data = {}, { isEditing = false } = {}) {
+  const errors = {};
+  if (!data.firstName && !data.lastName && !data.username) errors.name = 'nom ou identifiant requis';
+  if (data.email && !EMAIL_RE.test(data.email)) errors.email = 'email invalide';
+  if (!isEditing) {
+    if (data.password != null && data.confirmPassword != null && data.password !== data.confirmPassword)
+      errors.confirmPassword = 'les mots de passe diffèrent';
+  }
+  return { valid: Object.keys(errors).length === 0, errors };
+}
+
+/** Construit le view-model d'une liste à partir du résultat de users.list(). */
+export function buildUsersListViewModel(listResult, { t = (k) => k } = {}) {
+  const STATUS = { active: t('status.active'), locked: t('status.locked'), disabled: t('status.disabled') };
+  return {
+    rows: (listResult.items || []).map((u) => ({
+      id: u.id,
+      displayName: `${u.firstName || ''} ${u.lastName || ''}`.trim() || u.username || u.email || u.id,
+      email: u.email,
+      status: u.status,
+      statusLabel: STATUS[u.status] || u.status,
+      hasPhoto: !!u.photo,
+      hasFace: Array.isArray(u.faceDescriptor) && u.faceDescriptor.length > 0,
+    })),
+    total: listResult.total,
+    page: listResult.page,
+    pageSize: listResult.pageSize,
+    stats: listResult.stats,
+  };
+}
+
+/** Modèle de carte/badge (photo + QR + abonnement) — compose qrpanel/subscriptions-plan côté composant. */
+export function buildMemberCard(user, { subscription } = {}) {
+  return {
+    name: `${user.firstName || ''} ${user.lastName || ''}`.trim() || user.username,
+    photo: user.photo || null,
+    qr: user.qrCode || null,
+    subscription: subscription || null,
+  };
+}
+
+/**
+ * Contrôleur d'admin utilisateurs (state filtres/pagination) au-dessus du service @mostajs/users.
+ * @param {object} opts.service  l'API renvoyée par createUsers() (PEER @mostajs/users — REQUIS)
+ */
+export function createUsersUiController({ service, t = (k) => k } = {}) {
+  if (!service?.list) throw new Error('users-ui: service @mostajs/users requis (peer dependency)');
+  let q = { search: '', role: '', status: '', page: 1, pageSize: 20 };
+  return {
+    get query() { return { ...q }; },
+    setFilters(patch) { q = { ...q, ...patch, page: patch.page ?? 1 }; return this; },
+    async refresh() { return buildUsersListViewModel(await service.list(q), { t }); },
+    async submit(form, { isEditing = false, id } = {}) {
+      const v = validateUserForm(form, { isEditing });
+      if (!v.valid) return { ok: false, errors: v.errors };
+      const { password, confirmPassword, ...profile } = form; // password → @mostajs/auth (hors users)
+      const user = isEditing ? await service.update(id, profile) : await service.create(profile);
+      return { ok: true, user, _passwordDelegatedToAuth: password != null };
+    },
+    toggleStatus(id, status) { return status === 'locked' ? service.unlock(id) : service.lock(id); },
+    remove(id) { return service.repositories.users.remove(id); },
+  };
+}

package/src/index.js

@@ -0,0 +1,8 @@
+// @mostajs/users-ui — point d'entrée (logique headless ; composants React via "@mostajs/users-ui/react")
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+export {
+  validateUserForm,
+  buildUsersListViewModel,
+  buildMemberCard,
+  createUsersUiController,
+} from './headless.js';

package/src/react/MemberCardGenerator.jsx

@@ -0,0 +1,32 @@
+// @mostajs/users-ui/react — <MemberCardGenerator> — EXTRAIT de SecuAccessPro ClientCardGenerator.tsx.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// COMPOSE @mostajs/qrpanel (QR — useQrDataUrl) + @mostajs/subscriptions-plan (abonnement).
+// Carte = photo + QR (qrpanel) + abonnement. Ne réembarque PAS `qrcode` (délégué à qrpanel).
+import React from 'react';
+import { useQrDataUrl } from '@mostajs/qrpanel/qr-image';
+import { buildMemberCard } from '../headless.js';
+
+/** @param {{ user:object, subscription?:object }} props */
+export function MemberCardGenerator({ user, subscription, t = (k) => k }) {
+  const cardRef = React.useRef(null);
+  const model = buildMemberCard(user, { subscription });
+  const { src: qrSrc } = useQrDataUrl(model.qr || user.id);   // ← QR via @mostajs/qrpanel
+
+  const download = async () => {
+    const { default: html2canvas } = await import('html2canvas');
+    const canvas = await html2canvas(cardRef.current);
+    const a = document.createElement('a');
+    a.href = canvas.toDataURL('image/png'); a.download = `card-${user.id}.png`; a.click();
+  };
+
+  return React.createElement('div', null,
+    React.createElement('div', { ref: cardRef, className: 'mosta-member-card' },
+      model.photo && React.createElement('img', { src: model.photo, alt: model.name, className: 'photo' }),
+      React.createElement('strong', null, model.name),
+      model.subscription && React.createElement('span', null, model.subscription.planName),
+      qrSrc && React.createElement('img', { src: qrSrc, alt: 'QR', className: 'qr' }),
+    ),
+    React.createElement('button', { type: 'button', onClick: download }, t('download')),
+  );
+}
+export default MemberCardGenerator;

package/src/react/PhotoCapture.jsx

@@ -0,0 +1,39 @@
+// @mostajs/users-ui/react — <PhotoCapture> / <FaceEnroll> (wrapper) — EXTRAIT de SecuAccessPro FaceDetector.tsx.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// COMPOSE @mostajs/face (détection/descripteur) — ne réembarque PAS face-api.
+import React from 'react';
+
+/** @param {{ face:object, onCapture:(d:{photo:string,faceDescriptor:number[]|null})=>void }} props  (face = @mostajs/face) */
+export function PhotoCapture({ face, onCapture, t = (k) => k }) {
+  const videoRef = React.useRef(null);
+  const [ready, setReady] = React.useState(false);
+
+  React.useEffect(() => {
+    let stream;
+    (async () => {
+      try {
+        await face.loadModels?.();
+        stream = await navigator.mediaDevices.getUserMedia({ video: true });
+        if (videoRef.current) { videoRef.current.srcObject = stream; setReady(true); }
+      } catch (e) { /* permission caméra refusée — dégradation gracieuse */ }
+    })();
+    return () => stream?.getTracks().forEach((tk) => tk.stop());
+  }, [face]);
+
+  const capture = async () => {
+    const video = videoRef.current;
+    const canvas = document.createElement('canvas');
+    canvas.width = video.videoWidth; canvas.height = video.videoHeight;
+    canvas.getContext('2d').drawImage(video, 0, 0);
+    const photo = canvas.toDataURL('image/jpeg');
+    const faceDescriptor = (await face.extractDescriptor?.(video)) || null;
+    onCapture({ photo, faceDescriptor: faceDescriptor ? Array.from(faceDescriptor) : null });
+  };
+
+  return React.createElement('div', { className: 'mosta-photo-capture' },
+    React.createElement('video', { ref: videoRef, autoPlay: true, muted: true }),
+    React.createElement('button', { type: 'button', disabled: !ready, onClick: capture }, t('capture')),
+  );
+}
+export const FaceEnroll = PhotoCapture;
+export default PhotoCapture;

package/src/react/UserForm.jsx

@@ -0,0 +1,36 @@
+// @mostajs/users-ui/react — <UserForm> / <UserEditForm> (wrapper headless)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// EXTRAIT de MostaGare UserForm.tsx. password → @mostajs/auth ; rôles → @mostajs/rbac.
+import React from 'react';
+import { createUsersUiController, validateUserForm } from '../headless.js';
+
+export function UserForm({ service, t = (k) => k, isEditing = false, userId, initialData = {}, roles = [], onSaved }) {
+  const controller = React.useMemo(() => createUsersUiController({ service, t }), [service]);
+  const [form, setForm] = React.useState({ firstName: '', lastName: '', email: '', role: '', ...initialData });
+  const [errors, setErrors] = React.useState({});
+
+  const set = (k) => (e) => setForm((f) => ({ ...f, [k]: e.target.value }));
+  const submit = async (e) => {
+    e.preventDefault();
+    const v = validateUserForm(form, { isEditing });
+    if (!v.valid) return setErrors(v.errors);
+    const res = await controller.submit(form, { isEditing, id: userId });
+    if (!res.ok) return setErrors(res.errors);
+    onSaved?.(res.user);
+  };
+
+  return React.createElement('form', { onSubmit: submit, className: 'mosta-user-form' },
+    React.createElement('input', { value: form.firstName, onChange: set('firstName'), placeholder: t('firstName') }),
+    React.createElement('input', { value: form.lastName, onChange: set('lastName'), placeholder: t('lastName') }),
+    React.createElement('input', { value: form.email, onChange: set('email'), placeholder: t('email') }),
+    errors.email && React.createElement('span', { className: 'err' }, errors.email),
+    // rôle (← @mostajs/rbac)
+    React.createElement('select', { value: form.role, onChange: set('role') },
+      React.createElement('option', { value: '' }, t('role')),
+      roles.map((r) => React.createElement('option', { key: r.id, value: r.id }, r.name))),
+    // password (← @mostajs/auth) seulement à la création
+    !isEditing && React.createElement('input', { type: 'password', onChange: set('password'), placeholder: t('password') }),
+    React.createElement('button', { type: 'submit' }, t('save')),
+  );
+}
+export default UserForm;

package/src/react/UsersList.jsx

@@ -0,0 +1,42 @@
+// @mostajs/users-ui/react — <UsersList> (thin wrapper sur la logique headless)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// Compose @mostajs/users (service), @mostajs/ui (primitives), @mostajs/i18n. EXTRAIT de MostaGare UsersList.tsx.
+import React from 'react';
+import { createUsersUiController } from '../headless.js';
+
+/** @param {{ service:object, t?:Function, onEdit?:Function }} props  (service = @mostajs/users, PEER requis) */
+export function UsersList({ service, t = (k) => k, onEdit }) {
+  const controller = React.useMemo(() => createUsersUiController({ service, t }), [service]);
+  const [vm, setVm] = React.useState(null);
+  const [search, setSearch] = React.useState('');
+
+  const refresh = React.useCallback(async () => {
+    controller.setFilters({ search });
+    setVm(await controller.refresh());
+  }, [controller, search]);
+
+  React.useEffect(() => { refresh(); }, [refresh]);
+  if (!vm) return React.createElement('div', null, t('loading'));
+
+  return React.createElement('div', { className: 'mosta-users-list' },
+    React.createElement('input', {
+      value: search, placeholder: t('search'),
+      onChange: (e) => setSearch(e.target.value),
+    }),
+    React.createElement('div', { className: 'stats' },
+      `${t('status.active')}: ${vm.stats.active} · ${t('status.locked')}: ${vm.stats.locked} · ${t('status.disabled')}: ${vm.stats.disabled}`),
+    React.createElement('table', null,
+      React.createElement('tbody', null, vm.rows.map((r) =>
+        React.createElement('tr', { key: r.id },
+          React.createElement('td', null, r.displayName),
+          React.createElement('td', null, r.email),
+          React.createElement('td', null, r.statusLabel),
+          React.createElement('td', null,
+            React.createElement('button', { onClick: () => onEdit?.(r.id) }, t('edit')),
+            React.createElement('button', { onClick: () => controller.toggleStatus(r.id, r.status).then(refresh) },
+              r.status === 'locked' ? t('unlock') : t('lock')),
+          ),
+        )))),
+  );
+}
+export default UsersList;

package/src/react/index.js

@@ -0,0 +1,6 @@
+// @mostajs/users-ui/react — composants React (peer: react, @mostajs/users)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+export { UsersList } from './UsersList.jsx';
+export { UserForm } from './UserForm.jsx';
+export { PhotoCapture, FaceEnroll } from './PhotoCapture.jsx';
+export { MemberCardGenerator } from './MemberCardGenerator.jsx';

package/test-scripts/unit/headless.test.mjs

@@ -0,0 +1,52 @@
+// @mostajs/users-ui — tests unitaires (headless) (DEVRULES §5 : test-scripts/, rejouables, committés).
+// node test-scripts/unit/headless.test.mjs
+import assert from 'node:assert/strict';
+import { createUsers, createMemoryRepositories } from '../../../mosta-users/src/index.js';
+import { validateUserForm, buildUsersListViewModel, buildMemberCard, createUsersUiController } from '../../src/index.js';
+
+let pass = 0; const test = async (n, fn) => { await fn(); pass++; console.log('  ✓', n); };
+const svc = () => createUsers({ repositories: createMemoryRepositories(), qr: { generate: (id) => `QR:${id}` } });
+
+await test('validateUserForm: email invalide / nom requis', async () => {
+  assert.equal(validateUserForm({ email: 'bad' }).valid, false);
+  assert.equal(validateUserForm({}).valid, false);
+  assert.equal(validateUserForm({ firstName: 'A', email: 'a@b.dz' }).valid, true);
+});
+await test('validateUserForm: confirmation mot de passe (création)', async () => {
+  assert.equal(validateUserForm({ firstName: 'A', password: 'x', confirmPassword: 'y' }).valid, false);
+  assert.equal(validateUserForm({ firstName: 'A', password: 'x', confirmPassword: 'x' }).valid, true);
+});
+await test('controller: dépendance stricte à @mostajs/users', async () => {
+  assert.throws(() => createUsersUiController({}), /service @mostajs\/users requis/);
+});
+await test('controller.submit: crée via users, password délégué à auth', async () => {
+  const ui = createUsersUiController({ service: svc() });
+  const r = await ui.submit({ firstName: 'A', email: 'a@b.dz', password: 'p', confirmPassword: 'p' });
+  assert.ok(r.ok && r.user.id);
+  assert.equal(r._passwordDelegatedToAuth, true);
+  assert.ok(!('password' in r.user));
+});
+await test('controller.refresh: view-model + stats', async () => {
+  const ui = createUsersUiController({ service: svc() });
+  await ui.submit({ firstName: 'Amina' }); await ui.submit({ firstName: 'Karim' });
+  const vm = await ui.refresh();
+  assert.equal(vm.total, 2); assert.equal(vm.stats.active, 2);
+  assert.ok(vm.rows[0].displayName);
+});
+await test('controller: filtre recherche', async () => {
+  const ui = createUsersUiController({ service: svc() });
+  await ui.submit({ firstName: 'Amina' }); await ui.submit({ firstName: 'Karim' });
+  ui.setFilters({ search: 'kar' });
+  const vm = await ui.refresh(); assert.equal(vm.rows.length, 1);
+});
+await test('buildUsersListViewModel: labels statut + flags photo/face', async () => {
+  const vm = buildUsersListViewModel({ items: [{ id: '1', firstName: 'A', status: 'locked', faceDescriptor: [1] }], total: 1, stats: {} },
+    { t: (k) => k });
+  assert.equal(vm.rows[0].status, 'locked'); assert.equal(vm.rows[0].hasFace, true);
+});
+await test('buildMemberCard: photo + QR', async () => {
+  const card = buildMemberCard({ firstName: 'A', lastName: 'B', qrCode: 'QR:1', photo: 'data:...' });
+  assert.equal(card.name, 'A B'); assert.equal(card.qr, 'QR:1'); assert.ok(card.photo);
+});
+
+console.log(`\n✅ @mostajs/users-ui — ${pass} tests OK`);