ngx-recipe-forms 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# ngx-recipe-forms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Moteur de formulaire générique **par recette**, construit sur Angular Signal Forms (`@angular/forms/signals`, Angular 22.2) et Tailwind 4.
+Une recette est **un objet typé par le modèle**, déclaré dans le code ; le moteur en déduit le schéma Signal Forms, le rendu, les messages et la mise en page.
+
+Pour écrire une recette, suivre `../../AGENTS.md` (démarche, catalogue, interdits, liste de contrôle).
+
+## Ce que fait la bibliothèque
+
+- **Types de la recette** : `FormRecipe<TModel>`, nœuds `section`, `row`, `sectionGroup`, `field`, `linked`, `array` ; contrôles et règles contraints par le type de la valeur ; constructeur typé `recipeBuilder<TModel>()`. Les nœuds d'un élément d'`array` se construisent avec `recipeBuilder<ItemModel, RootModel>()` : leurs règles lisent la racine par `ctx.root(key)`.
+- **Schéma** : `RecipeSchema.build(recipe)` traduit chaque règle en une fonction native (`required`, `pattern`, `min`…, `validate`, `validateTree`, `validateAsync`, `metadata`), applique `disabled`, `hidden`, `readonly` (par champ, par section ou pour toute la recette), les règles des éléments d'`array` (`applyEach`), les règles de la liste entière (`minItems`, `maxItems`, `unique`, `validate`), les avertissements non bloquants (`warn`), les contrôles liés et `extraRules`. Une panne d'un validateur serveur pose l'avertissement « validation indisponible » sans bloquer : le serveur reste juge à l'enregistrement.
+- **Messages** : priorités champ → recette → défaut → message brut ; erreurs serveur affichées par leur `message`, que l’appelant a traduit, sinon par la clé `errors.<code>` ; une erreur de champ posée par l'application hôte sous la forme `{ kind: 'server', error: { code, constraint?, message } }` est lue telle quelle.
+- **Erreurs serveur par chemin** : `RecipeServerPaths` mémorise la correspondance position → clé des `array` à l'envoi ; `rooms[2].code` est posé sur l'élément qui occupait la position 2, l'erreur s'efface dès que la valeur change, ce qui ne se place pas sort par `unplacedServerErrors`.
+- **Sections** : `RecipeSections` (index des champs, compteur d'erreurs, premier champ en erreur).
+- **Mise en page Tailwind**, **mesure des temps de réponse** des validateurs serveur.
+- **Rendu** : `<app-recipe-form>`, `<app-recipe-node>`, `<app-recipe-section-group>` (formats `plain`, `panel` et `tabs`, compteurs d'erreurs par volet ou par onglet, ouverture du volet ou activation de l'onglet du premier champ en erreur ; aucun format ne détruit une section), `<app-recipe-field>`, `array` en liste ou en table avec slot et API (`addItem`, `removeItem`, `has`, `items`, tri déclaré). Wrappers par défaut `app-input-text`, `app-input-number` (décimales bornées par `minFractionDigits` et `maxFractionDigits`), `app-select`, `app-date-picker`, `app-date-picker-multiple`, `app-checkbox`, `app-button`, `app-panel`, `app-tabs` (avec `TabPanelDirective`), et `app-message` pour les messages de champ, de groupe et de liste. Sous un champ : l'aide (`hintKey`, conditionnable par `{ key, when?, showWhenReadonly? }`, masquée en lecture seule comme l'astérisque d'obligation), puis la raison traduite d'une règle `disabled` active (`reasonKey`), au même style, retirée à la réactivation. Les options `labelKey` d'un `select` sont traduites par le moteur avant d'atteindre le wrapper. Un `array` en table défile dans son propre conteneur (`overflow-x-auto`) ; un message de cellule passe à la ligne au lieu d'élargir sa colonne.
+
+## Utilisation
+
+```ts
+// 1. Le modèle du formulaire, en texte brut (la conversion vers le DTO reste dans le mapper).
+interface CourseFormData { deliveryMode: string | null; sessions: readonly CourseSession[]; totalHours: number | null; }
+interface CourseSession extends ArrayItem { date: Date | null; hours: number | null; }
+
+// 2. La recette, construite avec son contexte (signaux de droits, d'options, validateurs).
+const b = recipeBuilder<CourseFormData>();
+const item = recipeBuilder<Omit<CourseSession, 'key'>, CourseFormData>();
+export const courseRecipe = (ctx: Ctx) => b.recipe('course', {
+  readonly: () => ctx.readOnly(),
+  nodes: [
+    b.sectionGroup('main', { display: SectionDisplayEnum.PANEL, sections: [
+      b.section('sessions', { legendKey: 'course.sections.sessions', nodes: [
+        b.array('sessions', {
+          display: ArrayDisplayEnum.TABLE,
+          emptyItem: (key) => ({ key, date: null, hours: 7 }),
+          sort: (a, c) => (a.date?.getTime() ?? 0) - (c.date?.getTime() ?? 0),
+          slot: { name: 'calendar', position: 'before' },
+          rules: [{ rule: RuleTypeEnum.MIN_ITEMS, value: 1 }, { rule: RuleTypeEnum.UNIQUE, by: (s) => String(s.date) }],
+          item: [
+            item.field('date', { labelKey: 'course.fields.date', control: { type: ControlTypeEnum.DISPLAY } }),
+            item.field('hours', { labelKey: 'course.fields.hours', control: { type: ControlTypeEnum.NUMBER },
+              rules: [{ rule: RuleTypeEnum.VALIDATE, fn: (hours, c) => (c.root('deliveryMode') === 'REMOTE' && hours !== null && hours > 4 ? { kind: 'remoteHours' } : undefined) }] }),
+          ],
+        }),
+        b.field('totalHours', { labelKey: 'course.fields.totalHours', control: { type: ControlTypeEnum.DISPLAY, compute: (m) => String(m.sessions.reduce((sum, s) => sum + (s.hours ?? 0), 0)) } }),
+      ] }),
+    ] }),
+  ],
+});
+
+// 3. L'appelant crée le FieldTree et reçoit la valeur soumise.
+readonly model = signal<CourseFormData>(initial);
+readonly form = form(this.model, RecipeSchema.build(this.recipe, { timing: inject(FORM_VALIDATION_TIMING) }));
+```
+
+```html
+<app-recipe-form
+  [recipe]="recipe"
+  [form]="form"
+  [serverErrors]="rejection()"
+  (submitted)="save($event)"
+  (invalidSubmit)="…"
+  (unplacedServerErrors)="generalErrors.set($event)"
+>
+  <ng-template appRecipeSlot="calendar" let-list let-api="api">
+    <app-date-picker-multiple
+      [value]="selectedDates()"
+      (dateAdded)="api.addItem({ date: $event })"
+      (dateRemoved)="api.removeItem(keyOf($event))"
+    />
+  </ng-template>
+  <button appRecipeActions type="submit">Enregistrer</button>
+</app-recipe-form>
+```
+
+Fournisseurs : `provideRecipeForms({ production, translator, translationChanges, keyGenerator })`. `translator` et `translationChanges` sont des fabriques exécutées dans le contexte d'injection (`useFactory`). Par exemple avec Transloco :
+
+```ts
+provideRecipeForms({
+  production,
+  translator: () => {
+    const transloco = inject(TranslocoService);
+    return (key, params) => transloco.translate(key, params);
+  },
+  // Un objet nouveau à chaque événement : scope chargé en différé, langue changée.
+  translationChanges: () => toSignal(inject(TranslocoService).events$),
+});
+```
+
+`translationChanges` (jeton `RECIPE_FORM_TRANSLATION_CHANGES`, par défaut un signal constant) renvoie un signal dont la valeur change à chaque chargement ou changement de traductions. Le moteur le lit avant d'appeler le traducteur dans les titres d'onglets, les textes des compteurs d'erreurs, les options `labelKey` d'un `select` et le pipe `recipeTranslate` : un scope chargé après le premier rendu remplace les clés brutes affichées. Une valeur égale à la précédente (`Object.is`) ne déclenche rien : avec Transloco, `langChanges$` seul ne suffit pas, il ne change pas au chargement d'un scope.
+
+## Brancher son design system
+
+- Les sélecteurs sont `app-*` et les classes suffixées `Component`.
+- **Contrôles** : le moteur rend chaque contrôle (`text`, `number`, `select`, `date`, `dateMultiple`, `checkbox`) par un gabarit du registre `RecipeUi`. L'hôte passe à `provideRecipeForms({ ui })` un composant qui déclare un `<ng-template appRecipeTextControl let-field let-inputId="inputId" …>` (`appRecipeNumberControl`, `appRecipeSelectControl`, `appRecipeDateControl`, `appRecipeDateMultipleControl`, `appRecipeCheckboxControl`) par contrôle à rendre avec son design system, et y lie son wrapper par `[formField]="field"`. Un contrôle qu'il ne déclare pas garde le gabarit par défaut. `RecipeDefaultUiComponent` (`ui/recipe-default-ui.ts`) déclare les six gabarits avec les wrappers de `ui/` et sert de modèle ; le contexte de chaque gabarit est typé (`RecipeTextControlContext`…). Le registre crée ces composants une fois, hors de l'arbre de l'application ; la vue d'un gabarit est rafraîchie avec le champ qui l'insère, et mise à jour en place quand son contexte change (le contrôle garde son focus). Tests d'apprentissage : `specs/ui-seam.learning.spec.ts`.
+- **Messages, boutons, volets et onglets** : le moteur les rend par `app-recipe-message`, `app-recipe-button`, `app-recipe-panel` et `app-recipe-tabs`, qui gardent l'identifiant visé par `aria-describedby`, les classes de placement et l'état (volet replié, onglet actif), et rendent à l'intérieur le gabarit du registre : `appRecipeMessage` (texte traduit, `severity`, `inline`), `appRecipeButton` (libellé, `variant`, `severity`, `click`), `appRecipePanel` (`let-content` à rendre par `ngTemplateOutlet`, textes, `collapsed` et `toggle`), `appRecipeTabs` (`let-panels`, un `{ value, template }` par section à rendre sans jamais le détruire, `options`, `value`, `select`, `fill`). Le gabarit des onglets suit les panneaux par `value` : la liste est recréée à chaque calcul du contexte.
+- Pour un champ isolé, un contrôle `SLOT` rend le gabarit fourni par l'appelant. Les wrappers de `ui/` restent ceux des gabarits par défaut. Contrats attendus des wrappers :
+  - chaque contrôle : contrat Signal Forms (`value` ou `checked`, `disabled`, `invalid`, `touched`, sortie `touch`), entrées `inputId` et `describedBy` (`aria-describedby` posé sur l'élément qui reçoit le focus), méthode `focus(options?: FocusOptions)` qui transmet `options` au focus natif (focus du premier champ en erreur, appelé avec `preventScroll: true` : le moteur fait ensuite défiler `app-recipe-field` au centre par `scrollIntoView({ block: 'center' })`) ;
+  - `app-input-text` : `placeholder` (`''` par défaut), `inputmode` (`'text'` par défaut), `maxLength` (entrée de `FormValueControl`, liée par `[formField]` à la règle `MAX_LENGTH`), `icon` (icône de fin de champ, absente par défaut ; le moteur passe `TextControlDef.icon` tel quel, un nom d'icône du wrapper de l'hôte, `string` par défaut et restreint aux noms de l'hôte s'il étend `RecipeIconTypes` (`declare module 'ngx-recipe-forms' { interface RecipeIconTypes { icon: IconEnum } }`) ; le wrapper par défaut l'accepte sans la dessiner) ;
+  - `app-input-number` : `step`, `minFractionDigits` (décimales toujours affichées), `maxFractionDigits` (décimales admises à la saisie, 3 par défaut) ;
+  - `app-select` : `options: SelectOption<T>[]` (`[]` par défaut ; le champ en passe une copie, `label` déjà traduit pour une option de recette en `labelKey`), `showClear`, `filter` (recherche dans la liste, `false` par défaut ; le moteur passe `filter ?? false` ; le `<select>` natif du wrapper par défaut l'ignore et garde la recherche du navigateur par premières lettres), `ariaLabelledBy` (identifiant du libellé : la liste d'un design system n'est souvent pas un champ natif), `placeholder` (texte affiché quand la valeur est `null`, traduction de `SelectControlDef.placeholderKey`, `''` sans clé). En `readonly`, la liste reste focalisable (jamais `disabled` pour la lecture seule), ne s'ouvre pas, ne change pas de valeur au clavier, n'a ni chevron ni curseur main et porte `aria-readonly="true"` ; le contexte `RecipeSelectControlContext` transmet `placeholder` et `readonly` au gabarit. Spec de contrat du gabarit par défaut : `specs/recipe-select-readonly.spec.ts` ;
+  - `app-date-picker-multiple` : `FormValueControl<readonly Date[]>`, `maxDate`, `numberOfMonths` (mois affichés côte à côte, 3 par défaut ; le moteur passe `months ?? 3` ; le champ natif du wrapper par défaut l'ignore), `ariaLabel` (nom du groupe, le libellé traduit), sorties `dateAdded` et `dateRemoved` à chaque jour coché ou décoché ;
+  - `app-panel` : `header`, `collapsible`, `collapsed` (modèle), `badge` (nombre, absent à zéro), `badgeLabel`, `collapseLabel` et `expandLabel` (nom du bouton de repli, avec `aria-expanded`) ;
+  - `app-tabs` : `value` (modèle, `string`), `options: TabOption[]` (`label`, `value`, `disabled`, `badge` absent à zéro, `badgeLabel` ; même forme que `SelectOption<string>`), `fill` (`false` par défaut ; vrai : sous 768 px, les onglets se partagent toute la largeur, `flex-1` sur une base nulle, et leur titre passe à la ligne entre les mots seulement, sans couper un mot, aucun onglet hors de vue ; marges et texte réduits (`px-2`, `text-xs`) ; pastille au coin haut droit de l'onglet (`absolute`, onglet `relative`), dans un espace haut réservé même sans compteur (`pt-6`) : le titre a toute la largeur et l'onglet la même hauteur avec ou sans compteur ; rien ne change au-dessus ; le groupe de sections le passe à vrai) ; un panneau par `<ng-template [appTabPanel]="valeur">` projeté (`TabPanelDirective`, dans l'ordre des gabarits), masqué (`hidden`) quand son onglet est inactif et jamais détruit ; la barre seule sans gabarit ; motif ARIA des onglets (`aria-controls`, `aria-labelledby`, focus mobile, flèches, Début, Fin) ; barre collante en haut du conteneur qui défile (`sticky z-10`, fond blanc opaque), panneaux dans le même bloc, à `top: var(--app-sticky-top, 0px)` (classe `top-[var(--app-sticky-top,0px)]`) : un conteneur qui défile avec une marge haute pose `--app-sticky-top` au négatif de cette marge (`-20px` pour 20 px), sinon le contenu reste visible dans la bande au-dessus de la barre collée ; changement d'onglet par l'utilisateur (clic ou clavier) quand la barre est collée (haut de l'hôte au-dessus du haut de la barre) : l'hôte défile au début de la zone (`scrollIntoView({ block: 'start' })`, après le rendu), rien sans défilement préalable, rien quand `value` change par le parent (onglet du premier champ en erreur : le focus du champ pilote) ; nom de l'onglet (et du panneau) = titre seul, `badgeLabel` dans un élément `hidden` visé par `aria-describedby` de l'onglet, pastille en `aria-hidden` ; même hauteur d'onglet avec ou sans pastille (`leading-none` dans un conteneur `h-5`, la ligne du titre) ;
+  - `app-checkbox` (et tout gabarit `appRecipeCheckboxControl`) : `FormCheckboxControl` ; en `readonly`, la case ne change jamais d'état, ni à l'écran ni pour les technologies d'assistance (clic, clic sur le libellé et Espace annulés, la case native ne se coche pas), reste focalisable (jamais `disabled` pour la lecture seule), porte `aria-readonly="true"` sur l'élément focalisable, et garde le curseur par défaut sur la case et son libellé. Le contexte `RecipeCheckboxControlContext` transmet `readonly` au gabarit. Spec de contrat du gabarit par défaut : `specs/recipe-readonly-field.spec.ts` ;
+  - `app-message` : `severity` (`SeverityEnum`, dont la clé `WARNING`), `inline`, contenu projeté ; `[id]` posé sur l'élément hôte.
+- Traducteur : `RECIPE_FORM_TRANSLATOR` et `RECIPE_FORM_TRANSLATION_CHANGES` sont fournis par `useFactory` : la fabrique peut injecter le service i18n de l'application (voir « Fournisseurs » ci-dessus). Sans traducteur, la clé est affichée telle quelle. Le pipe `recipeTranslate` est impur (scopes chargés en différé).
+- `translationChanges` : les options `labelKey` d'un `select`, les titres d'onglets et les textes des compteurs sont traduits par le traducteur dans un `computed`, pas par le pipe impur : ils se recalculent à chaque changement de leurs données et, avec `translationChanges`, à chaque chargement de traductions ; sans cette option, le scope qui porte leurs clés doit être chargé avant le rendu du formulaire.
+- Clés par défaut : elles sont listées par la constante `RECIPE_FORM_DEFAULT_KEYS` (`constants/recipe-form-default-keys.constants.ts`) ; une spec de l'hôte vérifie que son dictionnaire, mis à plat (`forms.array.add`), contient chacune (modèle : `projects/playground/src/app/i18n/fr.spec.ts`) : `forms.errors.*` (dont `minItems`, `maxItems`, `unique`), `forms.warnings.validationUnavailable`, `forms.pending`, `forms.array.*`, `forms.display.errorCountOne` et `forms.display.errorCount` (« {{ count }} erreur », « {{ count }} erreurs » : le moteur prend la première pour `count` égal à 1, la seconde sinon, le traducteur n'ayant pas de pluriel), `forms.display.collapsePanel` et `forms.display.expandPanel` (« Replier le volet {{ title }} », « Déplier le volet {{ title }} »), et, hors de la constante, `errors.<code>` (ou `<scope>.errors.<code>`) pour les codes serveur.
+
+## Dans l'application hôte
+
+- Tailwind 4 : les classes de la bibliothèque sont littérales. Si le paquet est consommé depuis `node_modules`, ajouter `@source "../node_modules/ngx-recipe-forms";` dans la feuille de style de l'hôte.
+- Les validateurs serveur (`ServerValidator<T>`) renvoient un `Observable<ServerValidationResult>` ; l'adaptateur vers les services HTTP de l'application s'écrit chez l'appelant. Un validateur qui a besoin d'autres clés du modèle (par exemple la date de début et le format d'une formation) se déclare `ServerValidator<T, RootModel>`, reçoit `(value, ctx)` et lit par `ctx.root(key)` les clés que sa règle déclare dans `dependsOn`. Les erreurs d'une écriture (`RecipeServerError[]` : `fields`, `code`, `message?`) se passent telles quelles à `serverErrors`.
+- Les règles `server` appellent leur validateur par la ressource de `RECIPE_FORM_RX_RESOURCE` (`rxResource` par défaut) : une application qui impose son propre wrapper de ressources le passe à `provideRecipeForms({ rxResource })`, avec la signature de `rxResource`. Le collecteur de temps est un `@Service({ autoProvided: false })`.
+- `npm run check:loose` compile la bibliothèque et ses specs sous des options moins strictes, comme une application qui ne fixe ni `strict` ni `strictTemplates` : les `@ts-expect-error` de `recipe-types.spec.ts` doivent tenir. Les specs n'utilisent aucune API propre à Vitest 5. Celles qui soumettent un formulaire invalide remplacent `Element.prototype.scrollIntoView`, que jsdom n'implémente pas, par un espion `vi.fn` le temps de chaque test ; une spec de l'hôte qui soumet un formulaire de recette invalide fait de même.
+
+## Commandes
+
+```bash
+npm run build:lib      # ng build recipe-forms
+npm run pack:lib       # construit puis emballe le paquet (dist/ngx-recipe-forms-<version>.tgz)
+npm run publish:lib    # construit puis publie dist/recipe-forms sur npm
+npm run test:lib       # ng test recipe-forms --watch=false
+npm run check:loose    # tsc avec des options moins strictes
+npm start              # ng serve playground
+npm run install:host -- <dossier de l'hôte>   # installe le paquet construit dans un hôte (file:…tgz)
+npm run export:host -- <dossier>              # copie les sources dans un hôte, avec le manifeste d'empreintes
+```
+
+Les deux scripts sont décrits dans le `README.md` à la racine du dépôt (« Trying it in an application before publication », « Copying it into an application »).