@mostajs/wagon-ui 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 **Auteur** : Dr Hamid MADANI <drmdh@msn.com>
 
+
+## 0.2.0 — 2026-10-02
+
+- **Affichage PC, tablette, mobile** : en-tête repliable derrière un **menu hamburger** (sans script : case à
+  cocher + CSS, compatible avec une CSP stricte), tableaux défilants, champs pleine largeur, grille des tarifs
+  sur une colonne sous 760 px.
+- **Documentation publique** (`pageDocumentation`, `rechercheDocumentation`) : la mise en page des sites de
+  référence d'API — en-tête, onglets (Guides, Recettes, Référence API…), recherche, barre latérale par sections
+  (repliée derrière un hamburger sur mobile), sommaire « Sur cette page », lien vers la version Markdown ; fr, en, ar.
+- Essais T-WUI-10 à 12, écrits avant le code, chacun confronté à un sabotage.
 ## 0.1.0 — 2026-10-01
 Première version : les pages du wagon de mdseal (mise en page, accueil, tarifs, inscription, connexion par mot
 de passe ou par code, espace client, administration des paliers et de l'usage, pages légales, introuvable), en

package/README.md

@@ -38,3 +38,19 @@ La logique vient des modules : comptes (`@mostajs/comptes`), abonnements et quot
 (`@mostajs/subscriptions-plan`), connexion (`@mostajs/auth-lite`, `@mostajs/auth-plug`).
 
 Voir `llms.txt` pour l'API complète.
+
+
+## Documentation publique (0.2)
+
+```js
+const html = ui.pageDocumentation({
+  lang: 'fr', version: 'v1', base: 'https://acme.test',
+  onglets: [{ href: '/docs', libelle: 'Guides' }, { href: '/docs/api', libelle: 'Référence API' }], onglet: '/docs',
+  sections: [{ titre: 'Bien démarrer', pages: [{ href: '/docs', titre: 'Vue d’ensemble' }] }], actif: '/docs',
+  titre: 'Vue d’ensemble', sousTitre: '…', contenu: '<h2 id="a">…</h2>', sommaire: [{ id: 'a', titre: '…' }],
+  markdown: '/docs/index.md',
+});
+```
+
+La recherche est un formulaire GET vers `recherche` (par défaut `/docs/recherche?q=`) : l'application cherche
+dans ses pages et rend `ui.rechercheDocumentation({ lang, q, resultats })` dans `pageDocumentation`.

package/llms.txt

@@ -29,3 +29,5 @@ Rendre les écrans communs à tout SaaS, identiques d'un produit à l'autre, san
 - `legal({ html })` n'échappe pas `html` : il doit venir des textes de l'éditeur (mostajs/templates), jamais d'un formulaire.
 - Les prix sont en CENTIMES. `-1` = sans limite ; `0` = non compris.
 - Une ressource sans `parPeriode` s'affiche « libellé : n ».
+
+- 0.2 : `pageDocumentation({ lang, onglets, onglet, sections, actif, titre, sousTitre, contenu, sommaire, markdown, version, base, recherche, q })`, `rechercheDocumentation({ lang, q, resultats })` ; menu hamburger sans script dans `page()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/wagon-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Les pages du wagon d'un SaaS — mise en page (langues, pied légal, en-têtes pour les moteurs), accueil, tarifs, inscription, connexion (mot de passe ou code), espace client (palier, jauges, clés, factures, gestion de l'abonnement), administration (paliers, usage), pages légales — en fr, en, ar. Extraites de mdseal, sans ce qu'il vend : l'identité et les ressources mesurées viennent de la configuration. Vues pures, zéro dépendance.",
   "license": "AGPL-3.0-or-later",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",

package/src/i18n/ar.js

@@ -7,7 +7,17 @@ export const ar = {
     "apropos": "حول",
     "legal": "قانوني"
   },
+  "doc": {
+    "documentation": "التوثيق",
+    "rechercher": "بحث",
+    "surCettePage": "في هذه الصفحة",
+    "markdown": "عرض بصيغة Markdown",
+    "resultats": "نتائج البحث عن «{q}»",
+    "aucun": "لا توجد نتائج.",
+    "accueil": "الرئيسية"
+  },
   "layout": {
+    "menu": "القائمة",
     "auteur": "المؤلّف",
     "propulse": "مبنيّ على منظومة",
     "langue": "اللغة"

package/src/i18n/en.js

@@ -7,7 +7,17 @@ export const en = {
     "apropos": "About",
     "legal": "Legal"
   },
+  "doc": {
+    "documentation": "Documentation",
+    "rechercher": "Search",
+    "surCettePage": "On this page",
+    "markdown": "View as Markdown",
+    "resultats": "Results for “{q}”",
+    "aucun": "No result.",
+    "accueil": "Home"
+  },
   "layout": {
+    "menu": "Menu",
     "auteur": "Author",
     "propulse": "built on the",
     "langue": "Language"

package/src/i18n/fr.js

@@ -7,7 +7,17 @@ export const fr = {
     "apropos": "À propos",
     "legal": "Légal"
   },
+  "doc": {
+    "documentation": "Documentation",
+    "rechercher": "Rechercher",
+    "surCettePage": "Sur cette page",
+    "markdown": "Voir en Markdown",
+    "resultats": "Résultats pour « {q} »",
+    "aucun": "Aucun résultat.",
+    "accueil": "Accueil"
+  },
   "layout": {
+    "menu": "Menu",
     "auteur": "Auteur",
     "propulse": "propulsé par l’écosystème",
     "langue": "Langue"

package/src/index.js

@@ -85,9 +85,49 @@ pre,code,kbd,samp{direction:ltr;text-align:left;unicode-bidi:isolate} [dir="rtl"
 .moi{margin-inline-start:auto;font-size:.9em} .moi a{color:var(--accent);text-decoration:none}
 .langues{margin-inline-start:.8em;font-size:.9em;color:var(--doux)} .langues a{color:var(--accent);text-decoration:none} .langues b{color:var(--brand)}
 .hint{color:var(--doux);font-size:.9em} footer{max-width:920px;margin:2rem auto 0;padding:1rem;border-top:1px solid var(--line);color:var(--doux);font-size:.9em}
-footer a{color:var(--accent)}`;
+footer a{color:var(--accent)}
+.menu{display:flex;align-items:center;gap:1.2rem;flex:1 1 auto;flex-wrap:wrap}
+.bascule{position:absolute;opacity:0;width:1px;height:1px;pointer-events:none}
+.burger{display:none;margin-inline-start:auto;font-size:1.5rem;line-height:1;cursor:pointer;padding:.2em .45em;border:1px solid var(--line);border-radius:6px;color:var(--brand);user-select:none}
+.bascule:focus-visible+.burger{outline:2px solid var(--accent);outline-offset:2px}
+table{display:block;max-width:100%;overflow-x:auto}
+img,pre{max-width:100%} pre{overflow-x:auto}
+@media (max-width: 760px){
+  .burger{display:block}
+  .menu{display:none;flex-basis:100%;flex-direction:column;align-items:stretch;gap:.4rem;padding-top:.4rem}
+  .bascule:checked ~ .menu{display:flex}
+  nav{flex-direction:column} nav a{padding:.55em .7em}
+  .moi,.langues{margin-inline-start:0}
+  header{padding:.7rem .8rem} main{padding:0 .8rem 1.5rem} h1{font-size:1.45rem}
+  input[type=text],input[type=email],input[type=password]{min-width:0;width:100%}
+  .champs label{flex:1 1 100%}
+  .grille-tarifs{grid-template-columns:1fr}
+}`;
 }
 
+/** La documentation (0.2) : la mise en page des sites de référence d'API — onglets, barre latérale, sommaire. */
+const STYLE_DOC = `body{background:var(--surface)} .doc-tete{display:flex;align-items:center;gap:1rem;flex-wrap:wrap;padding:.8rem 1.2rem;background:var(--brand);color:var(--surface)}
+.doc-tete .brand{color:var(--surface)} .doc-tete .doc-mot{opacity:.85} .doc-tete .version{font-size:.8em;border:1px solid currentColor;border-radius:4px;padding:0 .4em;opacity:.85}
+.doc-tete .moi a,.doc-tete .langues a,.doc-tete .langues b{color:var(--surface)} .doc-tete .langues{color:var(--surface)}
+.doc-barre{display:flex;align-items:center;gap:.6rem;flex-wrap:wrap;padding:.4rem 1.2rem;background:var(--brand);border-top:1px solid rgba(255,255,255,.15)}
+.onglets{display:flex;gap:.3rem;flex-wrap:wrap} .onglets a{color:var(--surface);text-decoration:none;padding:.35em .8em;border-radius:6px;opacity:.9} .onglets a.on,.onglets a:hover{background:rgba(255,255,255,.16);opacity:1}
+.recherche{margin-inline-start:auto} .recherche input{padding:.4em .7em;border-radius:6px;border:0;min-width:14em}
+.doc{display:grid;grid-template-columns:16rem minmax(0,1fr) 14rem;max-width:1280px;margin:0 auto}
+.laterale{border-inline-end:1px solid var(--line);padding:1.4rem 1rem;position:sticky;top:0;align-self:start;max-height:100vh;overflow:auto}
+.laterale h3{font-size:.78rem;letter-spacing:.06em;text-transform:uppercase;color:var(--doux);margin:1.4em 0 .4em} .laterale h3:first-child{margin-top:0}
+.laterale ul{list-style:none;margin:0;padding:0} .laterale a{display:block;padding:.35em .6em;border-radius:6px;color:var(--ink);text-decoration:none} .laterale a.on{background:var(--fond-doux);font-weight:600} .laterale a:hover{background:var(--survol)}
+.doc-corps{padding:1.6rem 2.2rem 3rem;min-width:0} .doc-corps h1{margin:.1em 0 .2em;font-size:2.1rem} .doc-corps .lede{font-size:1.12rem;color:var(--doux);margin:.2em 0 1em}
+.doc-corps hr{border:0;border-top:1px solid var(--line);margin:1.2em 0 1.6em} .doc-corps a.md{float:inline-end;font-size:.88em;border:1px solid var(--line);border-radius:6px;padding:.3em .7em;text-decoration:none;color:var(--accent)}
+.sommaire{padding:1.6rem 1rem;position:sticky;top:0;align-self:start;font-size:.9em} .sommaire p{color:var(--doux);margin:0 0 .4em}
+.sommaire ul{list-style:none;margin:0;padding:0;border-inline-start:2px solid var(--line)} .sommaire a{display:block;padding:.25em .8em;color:var(--doux);text-decoration:none} .sommaire a:hover{color:var(--accent)}
+.doc-barre .burger{color:var(--surface);border-color:rgba(255,255,255,.4)}
+@media (max-width: 1100px){ .doc{grid-template-columns:15rem minmax(0,1fr)} .sommaire{display:none} }
+@media (max-width: 760px){
+  .doc{grid-template-columns:1fr} .laterale{display:none;position:static;max-height:none;border-inline-end:0;border-bottom:1px solid var(--line)}
+  .bascule:checked ~ .doc .laterale{display:block} .doc-barre .burger{display:block;margin-inline-start:0}
+  .recherche{flex-basis:100%} .recherche input{width:100%;min-width:0} .doc-corps{padding:1.2rem .9rem 2rem} .doc-corps h1{font-size:1.6rem}
+}`;
+
 /** Un texte multilingue de la configuration : chaîne simple, ou { fr, en, ar }. */
 const dansLangue = (v, lang) => (v && typeof v === 'object' ? (v[lang] ?? v.fr ?? Object.values(v)[0] ?? '') : (v ?? ''));
 const remplir = (s, vars = {}) => String(s).replace(/\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
@@ -152,7 +192,7 @@ export function creerWagonUi({ marque, couleurs = {}, langues = ['fr', 'en', 'ar
       return `<!doctype html><html lang="${L}" dir="${dirDe(L)}"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(titre)} — ${nom}</title>
 ${tete}<style>${STYLE}</style></head><body>
-<header><a class="brand" href="/">${marque.symbole ? `${esc(marque.symbole)} ` : ''}${nom}</a><nav>${nav.map(([h, l]) => `<a href="${lien(h)}"${actif === h ? ' class="on"' : ''}>${esc(l)}</a>`).join('')}</nav><span class="moi"><a href="${connecte ? '/compte' : '/connexion'}">${esc(tr(connecte ? 'espace.compte' : 'espace.seConnecter'))}</a>${connecte ? ` · <a href="/deconnexion">${esc(tr('espace.seDeconnecter'))}</a>` : ''}</span>${choixLangue}</header>
+<header><a class="brand" href="/">${marque.symbole ? `${esc(marque.symbole)} ` : ''}${nom}</a><input type="checkbox" id="wagon-menu" class="bascule"><label for="wagon-menu" class="burger" aria-label="${esc(tr('layout.menu'))}">☰</label><div class="menu"><nav>${nav.map(([h, l]) => `<a href="${lien(h)}"${actif === h ? ' class="on"' : ''}>${esc(l)}</a>`).join('')}</nav><span class="moi"><a href="${connecte ? '/compte' : '/connexion'}">${esc(tr(connecte ? 'espace.compte' : 'espace.seConnecter'))}</a>${connecte ? ` · <a href="/deconnexion">${esc(tr('espace.seDeconnecter'))}</a>` : ''}</span>${choixLangue}</div></header>
 <main>${contenu}</main>
 <footer><b>${nom}</b>${slogan ? ` — ${esc(slogan)}` : ''} · ${esc(tr('layout.auteur'))} : <b>${esc(marque.auteur)}</b>${marque.courriel ? ` &lt;${esc(marque.courriel)}&gt;` : ''} · ${esc(marque.licence ?? 'AGPL-3.0')} · ${esc(tr('layout.propulse'))} <code>@mostajs/*</code><br><span class="legal">${DOCUMENTS_LEGAUX.map(([h, k]) => `<a href="/${h}">${esc(tr(`legal.${k}`))}</a>`).join(' · ')}</span></footer>
 </body></html>`;
@@ -393,6 +433,45 @@ ${anonyme ? `<h2>${esc(tr('usage.anonyme'))}</h2>
         : `<h1>${esc(tr(`legal.${cle}`))}</h1><p class="hint">${esc(tr('legal.indisponible'))}</p>`;
     },
 
+    /**
+     * 0.2 — LA DOCUMENTATION publique, page entière : en-tête, onglets (Guides, Recettes, Référence API…),
+     * recherche, barre latérale par sections, contenu, sommaire « Sur cette page », lien vers la version
+     * Markdown. `contenu` est du HTML rendu par l'application depuis SES textes (jamais d'un formulaire).
+     * Sans script : la barre latérale se replie derrière un hamburger sur mobile.
+     */
+    pageDocumentation({ lang, onglets = [], onglet = '', sections = [], actif = '', titre = '', sousTitre = '', contenu = '', sommaire = [], markdown = '', version = '', base = '', recherche = '/docs/recherche', q = '' }) {
+      const L = langueDe(lang); const tr = t(L);
+      const nom = esc(marque.nom);
+      const canonique = base && actif ? `${String(base).replace(/\/$/, '')}${actif}` : '';
+      const chemin = lien(actif || '/');
+      const choixLangue = LANGUES.length < 2 ? '' : `<span class="langues">${LANGUES.map((l) => (l === L ? `<b lang="${l}">${esc(LIBELLES_LANGUES[l])}</b>` : `<a href="${chemin}?lang=${l}" hreflang="${l}" lang="${l}" rel="alternate">${esc(LIBELLES_LANGUES[l])}</a>`)).join(' · ')}</span>`;
+      const lienPage = (p) => (p.externe
+        ? `<a href="${lien(p.href)}" rel="noopener" target="_blank">${esc(p.titre)} ↗</a>`
+        : `<a href="${lien(p.href)}"${p.href === actif ? ' class="on" aria-current="page"' : ''}>${esc(p.titre)}</a>`);
+      return `<!doctype html><html lang="${L}" dir="${dirDe(L)}"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1"><title>${esc(titre)} — ${esc(tr('doc.documentation'))} ${nom}</title>
+${canonique ? `<link rel="canonical" href="${esc(canonique)}">${sousTitre ? `<meta name="description" content="${esc(sousTitre)}">` : ''}` : ''}<style>${STYLE}${STYLE_DOC}</style></head><body>
+<header class="doc-tete"><a class="brand" href="/">${marque.symbole ? `${esc(marque.symbole)} ` : ''}${nom}</a><span class="doc-mot">${esc(tr('doc.documentation'))}</span>${version ? `<span class="version">${esc(version)}</span>` : ''}<span class="moi"><a href="/">${esc(tr('doc.accueil'))}</a></span>${choixLangue}</header>
+<input type="checkbox" id="doc-menu" class="bascule">
+<div class="doc-barre"><label for="doc-menu" class="burger" aria-label="${esc(tr('layout.menu'))}">☰</label><nav class="onglets">${onglets.map((o) => `<a href="${lien(o.href)}"${o.href === onglet ? ' class="on"' : ''}>${esc(dansLangue(o.libelle, L))}</a>`).join('')}</nav><form class="recherche" method="get" action="${lien(recherche)}"><input type="search" name="q" value="${esc(q)}" placeholder="${esc(tr('doc.rechercher'))}" aria-label="${esc(tr('doc.rechercher'))}"></form></div>
+<div class="doc">
+<aside class="laterale">${sections.map((x) => `<h3>${esc(dansLangue(x.titre, L))}</h3><ul>${(x.pages ?? []).map((p) => `<li>${lienPage({ ...p, titre: dansLangue(p.titre, L) })}</li>`).join('')}</ul>`).join('')}</aside>
+<main class="doc-corps">${markdown ? `<a class="md" href="${lien(markdown)}">${esc(tr('doc.markdown'))}</a>` : ''}<h1>${esc(titre)}</h1>${sousTitre ? `<p class="lede">${esc(sousTitre)}</p>` : ''}<hr>
+${contenu}</main>
+<aside class="sommaire">${sommaire.length ? `<p>${esc(tr('doc.surCettePage'))}</p><ul>${sommaire.map((x) => `<li><a href="#${esc(String(x.id).replace(/[^A-Za-z0-9_-]/g, ''))}">${esc(x.titre)}</a></li>`).join('')}</ul>` : ''}</aside>
+</div>
+<footer><b>${nom}</b> · ${esc(tr('layout.auteur'))} : <b>${esc(marque.auteur)}</b> · ${esc(marque.licence ?? 'AGPL-3.0')}<br><span class="legal">${DOCUMENTS_LEGAUX.map(([h, k]) => `<a href="/${h}">${esc(tr(`legal.${k}`))}</a>`).join(' · ')}</span></footer>
+</body></html>`;
+    },
+
+    /** Les résultats d'une recherche dans la documentation (le contenu de `pageDocumentation`). */
+    rechercheDocumentation({ lang, q = '', resultats = [] }) {
+      const tr = t(langueDe(lang));
+      return `<p class="lede">${esc(tr('doc.resultats', { q }))}</p>${resultats.length
+        ? `<ul class="resultats">${resultats.map((r) => `<li><a href="${lien(r.href)}">${esc(r.titre)}</a>${r.extrait ? `<br><span class="hint">${esc(r.extrait)}</span>` : ''}</li>`).join('')}</ul>`
+        : `<p>${esc(tr('doc.aucun'))}</p>`}`;
+    },
+
     introuvable({ lang }) {
       const tr = t(langueDe(lang));
       return `<h1>${esc(tr('erreur.introuvable'))}</h1><p>${esc(tr('erreur.introuvableTexte'))}</p><p><a href="/">${esc(tr('erreur.retour'))}</a></p>`;