@mostajs/schema-form 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog — @mostajs/schema-form
+
+## 0.2.0 — 17/08/2026
+
+**Version incrémentée pour trois capacités qui existaient déjà en local sans avoir été publiées.**
+
+`repeaterScript`, `affichageMontant` et `centimesDepuis` avaient été ajoutés à la 0.1.0 **sans
+incrémenter la version**. Conséquence, constatée par une vérification en dossier vierge : la 0.1.0
+du registre ne les exportait pas, et `@mostajs/carte-restaurant-ui` — qui importe `repeaterScript` —
+**s'installait sans erreur puis cassait à l'import**.
+
+C'est le défaut le plus insidieux du versionnement : deux paquets portant le même numéro et un
+contenu différent. Rien ne le signale tant qu'on développe dans le dépôt, où le module local masque
+le publié.
+
+**Ajouté — un essai qui fige la surface publique** : toute modification de la liste des exports fait
+échouer la suite avec « INCRÉMENTER la version, mettre à jour llms.txt et README AVANT de publier ».
+
+**Rappel des trois capacités concernées**
+- `repeaterScript()` — le bouton « + Ajouter » d'un repeater ne faisait **rien** sans script ; un
+  `<template class="sf-tpl">` est désormais rendu même sur liste vide.
+- `affichageMontant` / `centimesDepuis` — saisie d'un montant en unité courante, stockage en
+  **entiers** de la plus petite unité. Jamais de flottant sur de l'argent.
+
+`CHANGELOG.md` ajouté à `files`.

package/llms.txt

@@ -42,6 +42,18 @@ Repeater côté navigateur : câbler add (clone d'un `.sf-item`, réindexer `nam
 ## STATUTS (exemple QatraxFlow)
 `resultat.statut` = Validé / Non validé / En cours / Interrompu (voir `examples/qatraxflow-recette.schema.js`).
 
+## LE CHAMP FICHIER (0.3.0)
+`{ path, type: 'fichier', accept?, capture?, multiple? }`
+
+- ⚠️ **L'`enctype="multipart/form-data"` est posé AUTOMATIQUEMENT** dès qu'un champ `fichier`
+  figure au schéma — répéteurs compris. Sans lui, le navigateur envoie le seul NOM du fichier,
+  jamais ses octets : il ne se plaint pas, le serveur reçoit un champ texte, et la photo n'arrive
+  jamais. C'est l'oubli le plus fréquent des formulaires de téléversement, et il est SILENCIEUX.
+- ⚠️ **La valeur n'est jamais pré-remplie** : un navigateur refuse qu'une page choisisse un fichier
+  (ce serait une exfiltration). Un écran de modification montre la pièce déjà envoyée À CÔTÉ.
+- ⚠️ `capture="environment"` ouvre l'**appareil photo** sur mobile, pas la galerie.
+- ⚠️ Les OCTETS ne passent pas par `readValues` : ils se lisent avec `@mostajs/form-data-extract`.
+
 ## 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()`.
@@ -52,3 +64,15 @@ Repeater côté navigateur : câbler add (clone d'un `.sf-item`, réindexer `nam
 ## 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`.
+
+## SURFACE PUBLIQUE (13 membres, figée par un essai — v0.2.0)
+SF_THEME · escapeHtml · getPath · setPath · label · moduleInfo · moduleName ·
+renderForm · renderField · readValues · **repeaterScript** · **affichageMontant** · **centimesDepuis**
+
+- repeaterScript() — SANS lui, le bouton « + Ajouter » d'un repeater ne fait RIEN. Le gabarit
+  `<template class="sf-tpl">` est rendu même sur liste vide.
+- affichageMontant / centimesDepuis — l'utilisateur saisit en unité courante, le stockage est en
+  ENTIERS de la plus petite unité. Jamais de flottant sur de l'argent.
+
+⚠️ Ces trois exports existaient en 0.1.0 LOCALE mais PAS dans la 0.1.0 publiée : la version n'avait
+pas été incrémentée. Un consommateur installait un paquet qui s'importait et cassait à l'usage.

package/package.json

@@ -1,14 +1,41 @@
 {
   "name": "@mostajs/schema-form",
-  "version": "0.1.0",
+  "version": "0.3.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"]
-}
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "llms.txt",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.1"
+  },
+  "keywords": [
+    "form",
+    "schema-form",
+    "saisie",
+    "data-entry",
+    "zero-dependency",
+    "localized",
+    "repeater",
+    "mostajs"
+  ],
+  "mostajs": {
+    "niveau": "N2",
+    "nature": "compose",
+    "reutilisabilite": "multi-domaine",
+    "depend_de": []
+  },
+  "scripts": {
+    "test": "bash test-scripts/run-tests.sh"
+  }
+}

package/src/index.js

@@ -49,8 +49,32 @@ function renderControl(f, value, name) {
       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>`;
+    // ── LE CHAMP FICHIER (0.3.0) ──────────────────────────────────────────
+    //
+    // ⚠️ `capture` ouvre l'APPAREIL PHOTO sur mobile, au lieu de la galerie. C'est ce qu'on veut
+    // pour photographier une facture au comptoir : demander à un exploitant de prendre la photo,
+    // de la retrouver dans sa galerie, puis de la choisir, c'est trois occasions d'abandonner.
+    //
+    // ⚠️ La valeur d'un champ fichier n'est JAMAIS pré-remplie : un navigateur refuse qu'une page
+    // décide quel fichier est sélectionné (ce serait une exfiltration). Un formulaire de
+    // modification doit donc afficher la pièce DÉJÀ envoyée à côté du champ, pas dedans.
+    case 'fichier':
+      return `<input type="file" name="${name}"${req}`
+        + `${f.accept ? ` accept="${escapeHtml(f.accept)}"` : ''}`
+        + `${f.capture ? ` capture="${escapeHtml(f.capture)}"` : ''}`
+        + `${f.multiple ? ' multiple' : ''} style="${inputStyle}">`;
     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 'montant': {
+      // Un texte, PAS un `number` : le contrôle numérique du navigateur rend un flottant, et un
+      // flottant n'est pas un montant. La conversion en unités mineures se fait à la relecture,
+      // par lecture de la CHAÎNE (voir centimesDepuis).
+      const dec = f.decimales ?? 2;
+      const aff = value === undefined || value === null || value === '' ? '' : affichageMontant(value, dec);
+      return `<div style="display:flex;gap:.4rem;align-items:center">
+        <input type="text" inputmode="decimal" name="${name}"${req} value="${escapeHtml(aff)}" placeholder="${escapeHtml(label(f.placeholder) || (dec ? '0,00' : '0'))}" style="${inputStyle}">
+        ${f.devise ? `<span style="opacity:.6;font-weight:600">${escapeHtml(f.devise)}</span>` : ''}</div>`;
+    }
     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':
@@ -63,7 +87,11 @@ function renderControl(f, value, name) {
     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>`;
+      // Un GABARIT accompagne toujours la liste, même vide : sans lui, « + Ajouter » n'aurait
+      // rien à cloner, et une liste qu'on ne peut pas allonger n'est pas une liste — c'est un
+      // formulaire figé qui en a l'air.
+      const gabarit = `<template class="sf-tpl">${renderRepeaterItem(f, {}, `${name}[__i__]`, 0)}</template>`;
+      return `<div class="sf-repeater" data-name="${name}">${items}${gabarit}<button type="button" class="sf-add" 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}">`;
@@ -78,6 +106,44 @@ function renderRepeaterItem(f, item, prefix, i) {
 }
 
 /** Rend un champ complet (label + contrôle). `name` = attribut name/chemin. */
+/**
+ * Une saisie textuelle → un ENTIER d'unités mineures, **sans jamais passer par un flottant**.
+ *
+ * `Math.round(4.475 * 100)` rend **447**, pas 448 : la multiplication flottante a déjà perdu la
+ * valeur avant l'arrondi. Un centime de moins sur une charge mensuelle, c'est invisible — et c'est
+ * exactement pour cela que c'est grave. On lit donc la CHAÎNE, chiffre par chiffre.
+ *
+ * `''` → `undefined` : une saisie vide est ABSENTE, jamais zéro.
+ * Une saisie illisible → `null` : elle ne vaut pas zéro non plus.
+ * Au-delà de `decimales`, l'arrondi est commercial (demi au-dessus), calculé sur la chaîne.
+ */
+export function centimesDepuis(saisie, decimales = 2) {
+  const t = String(saisie ?? '').trim().replace(/[\s\u00a0\u202f]/g, '').replace(',', '.');
+  if (t === '') return undefined;
+  const m = /^(-?)(\d*)(?:\.(\d*))?$/.exec(t);
+  if (!m || (!m[2] && !m[3])) return null;
+  const signe = m[1] === '-' ? -1 : 1;
+  const entier = m[2] || '0';
+  const frac = m[3] || '';
+  const gardees = frac.slice(0, decimales).padEnd(decimales, '0');
+  const suivant = frac.charCodeAt(decimales) - 48;
+  let n = Number(`${entier}${gardees}`);
+  if (suivant >= 5 && suivant <= 9) n += 1; //   demi au-dessus, en entier
+  return signe * n;
+}
+
+/** L'inverse, pour réafficher : `4565` → `« 45,65 »`. Affichage seulement ; rien n'en repart. */
+export function affichageMontant(centimes, decimales = 2) {
+  if (centimes === undefined || centimes === null) return '';
+  const n = Number(centimes);
+  if (!Number.isFinite(n)) return '';
+  const signe = n < 0 ? '-' : '';
+  const brut = String(Math.abs(Math.trunc(n))).padStart(decimales + 1, '0');
+  return decimales === 0
+    ? `${signe}${brut}`
+    : `${signe}${brut.slice(0, -decimales)},${brut.slice(-decimales)}`;
+}
+
 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">
@@ -98,7 +164,17 @@ export function renderForm(schema, values = {}, opts = {}) {
       <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}"` : ''}>
+  // ── L'ENCTYPE EST POSÉ TOUT SEUL, ET C'EST LE POINT ───────────────────────
+  //
+  // ⚠️ Un formulaire qui porte un `<input type=file>` SANS `enctype="multipart/form-data"` envoie
+  // le seul NOM du fichier, jamais ses octets. Le navigateur ne se plaint pas, le serveur reçoit
+  // un champ texte qui ressemble à un fichier, et la photo n'arrive jamais. C'est l'oubli le plus
+  // fréquent des formulaires de téléversement, et il est parfaitement silencieux.
+  //
+  // On ne le laisse donc pas à la charge de l'appelant : dès qu'un champ `fichier` figure au
+  // schéma — y compris DANS un répéteur — l'attribut est posé.
+  const aUnFichier = JSON.stringify(schema).includes('"fichier"');
+  return `<form class="sf-form"${opts.id ? ` id="${opts.id}"` : ''}${opts.action ? ` method="post" action="${opts.action}"` : ''}${aUnFichier ? ' enctype="multipart/form-data"' : ''}>
     ${schema.title ? `<h2 style="color:${SF_THEME.ink}">${escapeHtml(label(schema.title, locale))}</h2>` : ''}${body}${submit}</form>`;
 }
 
@@ -116,9 +192,60 @@ 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 === 'montant') setPath(obj, f.path, centimesDepuis(v, f.decimales ?? 2));
     else if (f.type === 'number' && v !== undefined && v !== '') setPath(obj, f.path, Number(v));
+    else if (f.type === 'repeater' && Array.isArray(v)) {
+      // La coercition DESCEND dans les items. Sans cela, une quantité saisie dans une liste
+      // revenait en CHAÎNE (« 40 ») là où la même quantité, hors liste, revenait en nombre :
+      // deux comportements pour un même type, et un `Number.isInteger()` qui échoue au hasard.
+      for (const item of v) coerce(item, (f.itemFields || []).map((sf) => ({ ...sf, path: sf.path || sf.name })));
+    }
   }
   return obj;
 }
 
+/**
+ * Le comportement des listes extensibles : ajouter, retirer, renuméroter.
+ *
+ * **Sans lui, le bouton « + Ajouter » ne fait rien** — la liste a l'air extensible et ne l'est pas.
+ * Le rendre ici plutôt que dans chaque application évite que chacune le réécrive, mal.
+ *
+ * Autonome, sans dépendance, à poser une fois dans la page. Le formulaire reste utilisable sans
+ * lui : les lignes déjà saisies s'affichent et se soumettent.
+ */
+export function repeaterScript() {
+  return `<script>
+document.addEventListener('click', (e) => {
+  const add = e.target.closest('.sf-add');
+  if (add) {
+    const zone = add.closest('.sf-repeater');
+    const tpl = zone.querySelector('.sf-tpl');
+    if (!tpl) return;
+    const i = zone.querySelectorAll('.sf-item').length;
+    const html = tpl.innerHTML.replace(/__i__/g, String(i));
+    const bloc = document.createElement('div');
+    bloc.innerHTML = html;
+    const item = bloc.firstElementChild;
+    item.querySelector('legend') && (item.querySelector('legend').textContent = '#' + (i + 1));
+    zone.insertBefore(item, tpl);
+    const premier = item.querySelector('input, select, textarea');
+    premier && premier.focus();
+    return;
+  }
+  const rm = e.target.closest('.sf-remove');
+  if (rm) {
+    const zone = rm.closest('.sf-repeater');
+    rm.closest('.sf-item').remove();
+    // Renuméroter : les index doivent rester contigus, sinon la relecture rend un tableau troué.
+    zone.querySelectorAll('.sf-item').forEach((it, k) => {
+      it.querySelector('legend') && (it.querySelector('legend').textContent = '#' + (k + 1));
+      it.querySelectorAll('[name]').forEach((ch) => {
+        ch.name = ch.name.replace(/\\[\\d+\\]/, '[' + k + ']');
+      });
+    });
+  }
+});
+</script>`;
+}
+
 export const moduleName = moduleInfo.name;