@mostajs/schema-form 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+@mostajs/mjs-unit
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The complete text of the GNU Affero General Public License version 3 is
+available at the URL above and must accompany any distribution of this
+software.

package/README.md

@@ -0,0 +1,49 @@
+# @mostajs/schema-form
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · Licence : AGPL-3.0-or-later · **Niveau** : N2
+Proposition : `docs/00-CARTOGRAPHIE-ET-PROPOSITION.md` (cas C, règle d'or §0)
+
+Interface de **saisie générique pilotée par schéma**, **zéro-dépendance** (HTML-string) —
+réutilisable par **toute app** `@mostajs`. Généralise le `SchemaForm` de TicketFlow :
+sections, champs typés, **chemins imbriqués**, **multilingue AR/FR/EN**, **repeater**.
+
+## Installation
+```bash
+npm i @mostajs/schema-form
+```
+
+## Exemple
+```js
+import { renderForm, readValues } from '@mostajs/schema-form';
+
+const schema = {
+  title: 'Fiche de recette',
+  sections: [
+    { id: 'condition', label: 'Condition', fields: [
+      { path: 'condition.env', type: 'text', label: 'Environnement', required: true },
+    ] },
+    { id: 'resultat', label: 'Logs & Résultats', fields: [
+      { path: 'resultat.statut', type: 'select', label: 'Statut', options: [
+        { value: 'valide', label: 'Validé' }, { value: 'non_valide', label: 'Non validé' },
+        { value: 'en_cours', label: 'En cours' }, { value: 'interrompu', label: 'Interrompu' } ] },
+      { path: 'resultat.logs', type: 'textarea', label: 'Logs JSON-lines' },
+    ] },
+  ],
+};
+
+el.innerHTML = renderForm(schema, { condition: { env: 'windows-11' } }, { id: 'f' });
+form.onsubmit = (e) => { e.preventDefault(); const values = readValues(new FormData(form), schema); save(values); };
+```
+
+## Types de champs
+`text` · `textarea` · `number` · `boolean` · `select` · `color` · `date` ·
+`localized` (un input par locale, RTL pour `ar`) · `repeater` (liste d'objets, `itemFields`).
+
+## Positionnement
+- `@mostajs/settings` → réglages **clé-valeur plat** (reste le bon choix pour ça).
+- `@mostajs/crud-ui` → formulaire+table **d'entité CRUD**.
+- **`@mostajs/schema-form`** → saisie **riche générique** (nested, repeater, localized, sections).
+
+## Démo & schéma d'exemple
+`examples/demo.html` (schéma QatraxFlow : Condition→Exécution→Comportement→Logs/Résultats) ;
+`examples/qatraxflow-recette.schema.js`. Tests : `npm test` → `test-scripts/.out/report.html`.

package/llms.txt

@@ -0,0 +1,54 @@
+# @mostajs/schema-form — fiche LLM
+> Interface de SAISIE générique pilotée par schéma (zéro-dép HTML), réutilisable par toute app.
+
+- Version : 0.1.0 · Licence : AGPL-3.0-or-later · Auteur : Dr Hamid MADANI <drmdh@msn.com>
+- Chemin : mostajs/mosta-ui-html-stack/mosta-schema-form · **Niveau** : N2 (composé/UI)
+- Zéro dépendance runtime. Généralise le SchemaForm de TicketFlow (cas C, règle d'or §0).
+
+## RÔLE
+Rend un formulaire de saisie à partir d'un SCHÉMA de champs (sections + champs typés,
+chemins imbriqués, multilingue AR/FR/EN, repeater/listes) et relit les valeurs en objet
+imbriqué. Aucun couplage métier : tout schéma. 1er consommateur : MostaQatraxFlow (fiche
+de recette Condition→Exécution→Comportement→Logs/Résultats). Complète `@mostajs/settings`
+(clé-valeur plat) et `@mostajs/crud-ui` (CRUD) sans les remplacer.
+
+## EXPORTS
+- `renderForm(schema, values?, opts?) : string` — HTML `<form>` (opts: id, action, locale, submitLabel|null)
+- `renderField(field, value, name?, locale?) : string` — un champ
+- `readValues(formData|entries|obj, schema?) : object` — reconstruit l'objet (coerce boolean/number)
+- `getPath(obj,path)` / `setPath(obj,path,val)` — chemins `a.b[0].c`
+- `label(l, locale)` — libellé string ou {ar,fr,en} · `escapeHtml` · `SF_THEME` · `moduleInfo`
+
+## SCHÉMA
+```
+{ title?, sections?: [{ id, label, fields:[Field] }], fields?:[Field] }
+Field = { path, type, label, required?, placeholder?, help?, options?, min?, max?, step?, rows?,
+          locales?, itemFields?, itemDefaults?, addLabel? }
+label = string | { ar, fr, en }
+```
+Types : `text` (défaut) · `textarea` · `number` · `boolean` (checkbox) · `select` (options
+`{value,label}`) · `color` · `date` · `localized` (un input/locale, RTL pour ar) · `repeater`
+(liste d'objets, `itemFields`, add/remove).
+
+## PATTERN
+```js
+import { renderForm, readValues } from '@mostajs/schema-form'
+el.innerHTML = renderForm(schema, values, { id: 'f' })
+form.onsubmit = (e) => { e.preventDefault(); const v = readValues(new FormData(form), schema); save(v) }
+```
+Repeater côté navigateur : câbler add (clone d'un `.sf-item`, réindexer `name`) / remove
+(retirer le `.sf-item`) — cf. `examples/demo.html`.
+
+## STATUTS (exemple QatraxFlow)
+`resultat.statut` = Validé / Non validé / En cours / Interrompu (voir `examples/qatraxflow-recette.schema.js`).
+
+## PIÈGES
+- **Zéro-dép, HTML-string** : `renderForm` rend une chaîne ; côté React, injecter ou porter en composants.
+- `readValues` : Array traité comme liste [name,value] (pas via `.entries()`), FormData via `.entries()`.
+- `boolean` : checkbox non cochée = absente du FormData → `coerce` la met à `false`.
+- Repeater : le rendu statique liste les items ; l'ajout/retrait dynamique = client (démo).
+- `localized` : valeur = objet `{ar,fr,en}` ; names `path.ar`/`path.fr`/`path.en`.
+
+## RÉFÉRENCES
+docs/00-CARTOGRAPHIE-ET-PROPOSITION.md · examples/demo.html · examples/qatraxflow-recette.schema.js.
+Compose (à terme) `@mostajs/ui` pour une variante React. Voisin : `@mostajs/settings`, `@mostajs/crud-ui`.

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@mostajs/schema-form",
+  "version": "0.1.0",
+  "description": "Interface de SAISIE générique pilotée par schéma (zéro-dép) : sections + champs typés (text/textarea/number/boolean/select/color/date/localized/repeater), chemins imbriqués, multilingue AR/FR/EN. Rendu HTML (renderForm) + relecture (readValues). Réutilisable par toute app @mostajs.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": { ".": "./src/index.js" },
+  "files": ["src", "README.md", "llms.txt", "LICENSE"],
+  "scripts": { "test": "bash test-scripts/run-tests.sh" },
+  "devDependencies": { "@mostajs/mjs-unit": "^0.3.1" },
+  "keywords": ["form", "schema-form", "saisie", "data-entry", "zero-dependency", "localized", "repeater", "mostajs"]
+}

package/src/index.js

@@ -0,0 +1,124 @@
+/**
+ * @mostajs/schema-form — interface de SAISIE générique pilotée par schéma (ZÉRO-DÉP).
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ *
+ * Généralise le pattern SchemaForm de TicketFlow en module réutilisable par TOUTE app :
+ * un schéma de champs (sections + champs typés, chemins imbriqués, multilingue, repeater)
+ * → HTML de formulaire (`renderForm`) + relecture des valeurs (`readValues`). Aucune
+ * dépendance, aucun framework (embarquable partout : statique, Express, Next, React).
+ * 1er consommateur : MostaQatraxFlow (saisie de recette Condition→Exécution→Comportement→Logs).
+ */
+
+export const moduleInfo = { name: '@mostajs/schema-form', version: '0.1.0' };
+export const SF_THEME = { blue: '#1E88E5', ink: '#1a2b45', line: '#e3e9f2', bg: '#f7f9fc' };
+const LOCALES = ['ar', 'fr', 'en'];
+
+export function escapeHtml(s) {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+/** Libellé : string ou objet multilingue {ar,fr,en}. */
+export function label(l, locale = 'fr') { return typeof l === 'object' && l ? (l[locale] ?? l.fr ?? Object.values(l)[0] ?? '') : (l ?? ''); }
+
+/* ── chemins imbriqués (a.b, a.b[0].c) ─────────────────────────────────────── */
+export function getPath(obj, path) {
+  if (!path) return undefined;
+  return path.replace(/\[(\d+)\]/g, '.$1').split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+export function setPath(obj, path, value) {
+  const keys = path.replace(/\[(\d+)\]/g, '.$1').split('.');
+  let o = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const k = keys[i], nextIsIndex = /^\d+$/.test(keys[i + 1]);
+    if (o[k] == null || typeof o[k] !== 'object') o[k] = nextIsIndex ? [] : {};
+    o = o[k];
+  }
+  o[keys[keys.length - 1]] = value;
+  return obj;
+}
+
+/* ── rendu d'un champ ──────────────────────────────────────────────────────── */
+const inputStyle = `width:100%;padding:.5rem;border:1px solid ${SF_THEME.line};border-radius:.4rem;font:inherit`;
+
+function renderControl(f, value, name) {
+  const req = f.required ? ' required' : '';
+  const ph = f.placeholder ? ` placeholder="${escapeHtml(label(f.placeholder))}"` : '';
+  switch (f.type) {
+    case 'textarea':
+      return `<textarea name="${name}"${req}${ph} rows="${f.rows || 4}" style="${inputStyle};font-family:ui-monospace,monospace">${escapeHtml(value ?? '')}</textarea>`;
+    case 'number':
+      return `<input type="number" name="${name}"${req}${ph} value="${escapeHtml(value ?? '')}"${f.min != null ? ` min="${f.min}"` : ''}${f.max != null ? ` max="${f.max}"` : ''}${f.step != null ? ` step="${f.step}"` : ''} style="${inputStyle}">`;
+    case 'boolean':
+      return `<label style="display:inline-flex;gap:.4rem;align-items:center"><input type="checkbox" name="${name}" value="true"${value ? ' checked' : ''}> ${escapeHtml(label(f.help) || 'Oui')}</label>`;
+    case 'select':
+      return `<select name="${name}"${req} style="${inputStyle}">${(f.options || []).map((o) => `<option value="${escapeHtml(o.value)}"${String(value) === String(o.value) ? ' selected' : ''}>${escapeHtml(label(o.label ?? o.value))}</option>`).join('')}</select>`;
+    case 'color':
+      return `<input type="color" name="${name}" value="${escapeHtml(value || '#000000')}" style="height:2.2rem;width:3rem;border:1px solid ${SF_THEME.line};border-radius:.4rem">`;
+    case 'date':
+      return `<input type="date" name="${name}"${req} value="${escapeHtml(value ?? '')}" style="${inputStyle}">`;
+    case 'localized': {
+      const locs = f.locales || LOCALES;
+      return `<div style="display:flex;flex-direction:column;gap:.3rem">${locs.map((lc) =>
+        `<div style="display:flex;gap:.4rem;align-items:center"><span style="width:2rem;font-size:.72rem;opacity:.6;text-transform:uppercase">${lc}</span><input name="${name}.${lc}"${lc === 'ar' ? ' dir="rtl"' : ''} value="${escapeHtml((value && value[lc]) ?? '')}" style="${inputStyle}"></div>`).join('')}</div>`;
+    }
+    case 'repeater': {
+      const arr = Array.isArray(value) ? value : [];
+      const items = arr.map((item, i) => renderRepeaterItem(f, item, `${name}[${i}]`, i)).join('');
+      return `<div class="sf-repeater" data-name="${name}">${items}<button type="button" class="sf-add" data-name="${name}" style="margin-top:.4rem;background:${SF_THEME.blue};color:#fff;border:0;border-radius:.4rem;padding:.35rem .8rem;cursor:pointer">${escapeHtml(label(f.addLabel) || '+ Ajouter')}</button></div>`;
+    }
+    default: // text
+      return `<input type="text" name="${name}"${req}${ph} value="${escapeHtml(value ?? '')}" style="${inputStyle}">`;
+  }
+}
+function renderRepeaterItem(f, item, prefix, i) {
+  return `<fieldset class="sf-item" style="border:1px solid ${SF_THEME.line};border-radius:.5rem;padding:.6rem;margin-bottom:.5rem">
+    <legend style="font-size:.75rem;opacity:.6">#${i + 1}</legend>
+    ${(f.itemFields || []).map((sub) => renderField({ ...sub, path: sub.path || sub.name }, getPath(item, sub.path || sub.name), `${prefix}.${sub.path || sub.name}`)).join('')}
+    <button type="button" class="sf-remove" style="background:#C62828;color:#fff;border:0;border-radius:.4rem;padding:.2rem .6rem;cursor:pointer;font-size:.75rem">Retirer</button>
+  </fieldset>`;
+}
+
+/** Rend un champ complet (label + contrôle). `name` = attribut name/chemin. */
+export function renderField(f, value, name = f.path, locale = 'fr') {
+  if (f.type === 'boolean') return `<div class="sf-field" style="margin-bottom:.8rem">${renderControl(f, value, name)}${f.help ? '' : ''}<div style="font-size:.85rem;color:${SF_THEME.ink};margin-top:.2rem;font-weight:600">${escapeHtml(label(f.label, locale))}</div></div>`;
+  return `<div class="sf-field" style="margin-bottom:.9rem">
+    <label style="display:block;font-size:.85rem;font-weight:600;color:${SF_THEME.ink};margin-bottom:.25rem">${escapeHtml(label(f.label, locale))}${f.required ? ' <span style="color:#C62828">*</span>' : ''}</label>
+    ${renderControl(f, value, name)}
+    ${f.help && f.type !== 'boolean' ? `<div style="font-size:.75rem;opacity:.6;margin-top:.2rem">${escapeHtml(label(f.help, locale))}</div>` : ''}
+  </div>`;
+}
+
+/** Rend un formulaire complet depuis un schéma { title?, sections?[], fields?[] }. */
+export function renderForm(schema, values = {}, opts = {}) {
+  const locale = opts.locale || 'fr';
+  const sections = schema.sections || [{ fields: schema.fields || [] }];
+  const body = sections.map((sec) => {
+    const inner = (sec.fields || []).map((f) => renderField(f, getPath(values, f.path), f.path, locale)).join('');
+    if (!sec.label && !sec.id) return inner;
+    return `<fieldset style="border:1px solid ${SF_THEME.line};border-radius:.6rem;padding:1rem;margin-bottom:1rem">
+      <legend style="padding:0 .5rem;font-weight:700;color:${SF_THEME.blue}">${escapeHtml(label(sec.label, locale) || sec.id)}</legend>${inner}</fieldset>`;
+  }).join('');
+  const submit = opts.submitLabel === null ? '' : `<button type="submit" style="background:${SF_THEME.blue};color:#fff;border:0;border-radius:.45rem;padding:.6rem 1.2rem;font-weight:600;cursor:pointer">${escapeHtml(opts.submitLabel || 'Enregistrer')}</button>`;
+  return `<form class="sf-form"${opts.id ? ` id="${opts.id}"` : ''}${opts.action ? ` method="post" action="${opts.action}"` : ''}>
+    ${schema.title ? `<h2 style="color:${SF_THEME.ink}">${escapeHtml(label(schema.title, locale))}</h2>` : ''}${body}${submit}</form>`;
+}
+
+/* ── relecture des valeurs (FormData → objet imbriqué) ─────────────────────── */
+/** Reconstruit l'objet de valeurs depuis un FormData (ou un iterable [name,value]). */
+export function readValues(formData, schema) {
+  const out = {};
+  const entries = Array.isArray(formData) ? formData
+    : (typeof formData?.entries === 'function' ? [...formData.entries()] : Object.entries(formData || {}));
+  for (const [name, raw] of entries) setPath(out, name, raw);
+  if (schema) coerce(out, schema.sections ? schema.sections.flatMap((s) => s.fields || []) : (schema.fields || []));
+  return out;
+}
+function coerce(obj, fields) {
+  for (const f of fields) {
+    const v = getPath(obj, f.path);
+    if (f.type === 'boolean') setPath(obj, f.path, v === true || v === 'true' || v === 'on');
+    else if (f.type === 'number' && v !== undefined && v !== '') setPath(obj, f.path, Number(v));
+  }
+  return obj;
+}
+
+export const moduleName = moduleInfo.name;