ngx-recipe-forms 0.1.1 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@ To write a recipe, follow [`AGENTS.md`](https://github.com/SrenoG/ngx-recipe-for
 
 - **Recipe types**: `FormRecipe<TModel>`, nodes `section`, `row`, `sectionGroup`, `field`, `linked`, `array`; controls and rules constrained by the type of the value; typed builder `recipeBuilder<TModel>()`. The nodes of an `array` item are built with `recipeBuilder<ItemModel, RootModel>()`: their rules read the root through `ctx.root(key)`.
 - **Schema**: `RecipeSchema.build(recipe)` turns each rule into a native function (`required`, `pattern`, `min`…, `validate`, `validateTree`, `validateAsync`, `metadata`), and applies `disabled`, `hidden`, `readonly` (per field, per section or for the whole recipe), the rules of `array` items (`applyEach`), the rules of the whole list (`minItems`, `maxItems`, `unique`, `validate`), non-blocking warnings (`warn`), linked controls and `extraRules`. When a server validator fails, the engine sets the "validation unavailable" warning without blocking: the server still decides on save.
-- **Messages**: priority field → recipe → default → raw message; server errors are shown by their `message`, translated by the caller, otherwise by the key `errors.<code>`; a field error set by the host application as `{ kind: 'server', error: { code, constraint?, message } }` is read as is.
+- **Messages**: priority field → recipe → default → raw message; a field's message appears once the user changes its value (`dirty`), leaves it (`touched`) or submits the form, and a field never changed shows nothing before that; after `reset()` and `resetSubmitAttempt()`, messages stay hidden again until the next change, exit or submit; server errors are shown by their `message`, translated by the caller, otherwise by the key `errors.<code>`; a field error set by the host application as `{ kind: 'server', error: { code, constraint?, message } }` is read as is.
 - **Server errors by path**: `RecipeServerPaths` records the position → key mapping of each `array` when the request is sent; `rooms[2].code` is set on the item that was at position 2, the error clears as soon as the value changes, and whatever cannot be placed comes out through `unplacedServerErrors`.
 - **Sections**: `RecipeSections` (field index, error count, first field in error).
 - **Tailwind layout**, **response time measurement** of server validators.
@@ -95,7 +95,7 @@ provideRecipeForms({
 - **Controls**: the engine renders each control (`text`, `number`, `select`, `date`, `dateMultiple`, `checkbox`) with a template from the `RecipeUi` registry. The host passes to `provideRecipeForms({ ui })` a component that declares one `<ng-template appRecipeTextControl let-field let-inputId="inputId" …>` (`appRecipeNumberControl`, `appRecipeSelectControl`, `appRecipeDateControl`, `appRecipeDateMultipleControl`, `appRecipeCheckboxControl`) per control to render with its design system, and binds its wrapper to it with `[formField]="field"`. A control it does not declare keeps the default template. `RecipeDefaultUiComponent` (`ui/recipe-default-ui.ts`) declares the six templates with the wrappers from `ui/` and serves as a model; the context of each template is typed (`RecipeTextControlContext`…). The registry creates these components once, outside the application tree; a template's view is refreshed with the field that inserts it, and updated in place when its context changes (the control keeps its focus). Learning tests: `specs/ui-seam.learning.spec.ts`.
 - **Messages, buttons, panels and tabs**: the engine renders them through `app-recipe-message`, `app-recipe-button`, `app-recipe-panel` and `app-recipe-tabs`, which keep the id targeted by `aria-describedby`, the placement classes and the state (collapsed panel, active tab), and render the registry template inside: `appRecipeMessage` (translated text, `severity`, `inline`), `appRecipeButton` (label, `variant`, `severity`, `click`), `appRecipePanel` (`let-content` to render with `ngTemplateOutlet`, texts, `collapsed` and `toggle`), `appRecipeTabs` (`let-panels`, one `{ value, template }` per section, to render without ever destroying it, `options`, `value`, `select`, `fill`). The tabs template tracks panels by `value`: the list is recreated on each computation of the context.
 - For a single field, a `SLOT` control renders the template provided by the caller. The wrappers in `ui/` remain those of the default templates. Contracts expected from the wrappers:
-  - every control: Signal Forms contract (`value` or `checked`, `disabled`, `invalid`, `touched`, `touch` output), `inputId` and `describedBy` inputs (`aria-describedby` set on the element that receives focus), a `focus(options?: FocusOptions)` method that passes `options` to the native focus (focus of the first field in error, called with `preventScroll: true`: the engine then scrolls `app-recipe-field` to the center with `scrollIntoView({ block: 'center' })`);
+  - every control: Signal Forms contract (`value` or `checked`, `disabled`, `invalid`, `touched`, `dirty`, `touch` output; `aria-invalid="true"` when invalid and touched or dirty, like the message under the field), `inputId` and `describedBy` inputs (`aria-describedby` set on the element that receives focus), a `focus(options?: FocusOptions)` method that passes `options` to the native focus (focus of the first field in error, called with `preventScroll: true`: the engine then scrolls `app-recipe-field` to the center with `scrollIntoView({ block: 'center' })`);
   - `app-input-text`: `placeholder` (`''` by default), `inputmode` (`'text'` by default), `maxLength` (a `FormValueControl` input, bound by `[formField]` to the `MAX_LENGTH` rule), `icon` (trailing icon, none by default; the engine passes `TextControlDef.icon` as is, an icon name of the host's wrapper, `string` by default and restricted to the host's names if it extends `RecipeIconTypes` (`declare module 'ngx-recipe-forms' { interface RecipeIconTypes { icon: IconEnum } }`); the default wrapper accepts it without drawing it);
   - `app-input-number`: `step`, `minFractionDigits` (decimals always shown), `maxFractionDigits` (decimals allowed when typing, 3 by default);
   - `app-select`: `options: SelectOption<T>[]` (`[]` by default; the field passes a copy, with `label` already translated for a recipe option using `labelKey`), `showClear`, `filter` (search in the list, `false` by default; the engine passes `filter ?? false`; the native `<select>` of the default wrapper ignores it and keeps the browser's first-letter search), `ariaLabelledBy` (id of the label: a design system's dropdown is often not a native field), `placeholder` (text shown when the value is `null`, translation of `SelectControlDef.placeholderKey`, `''` without a key). In `readonly` mode, the list stays focusable (never `disabled` for read-only), does not open, does not change value from the keyboard, has neither chevron nor pointer cursor and carries `aria-readonly="true"`; the `RecipeSelectControlContext` context passes `placeholder` and `readonly` to the template. Contract spec of the default template: `specs/recipe-select-readonly.spec.ts`;
@@ -106,7 +106,7 @@ provideRecipeForms({
   - `app-message`: `severity` (`SeverityEnum`, including the `WARNING` key), `inline`, projected content; `[id]` set on the host element.
 - Translator: `RECIPE_FORM_TRANSLATOR` and `RECIPE_FORM_TRANSLATION_CHANGES` are provided with `useFactory`: the factory can inject the application's i18n service (see "Providers" above). Without a translator, the key is shown as is. The `recipeTranslate` pipe is impure (lazily loaded scopes).
 - `translationChanges`: the `labelKey` options of a `select`, tab titles and count texts are translated by the translator in a `computed`, not by the impure pipe: they are recomputed whenever their data changes and, with `translationChanges`, whenever translations load; without this option, the scope that holds their keys must be loaded before the form renders.
-- Default keys: they are listed by the `RECIPE_FORM_DEFAULT_KEYS` constant (`constants/recipe-form-default-keys.constants.ts`); a host spec checks that its flattened dictionary (`forms.array.add`) contains each of them (model: `projects/playground/src/app/i18n/fr.spec.ts`): `forms.errors.*` (including `minItems`, `maxItems`, `unique`), `forms.warnings.validationUnavailable`, `forms.pending`, `forms.array.*`, `forms.display.errorCountOne` and `forms.display.errorCount` ("{{ count }} error", "{{ count }} errors": the engine uses the first one when `count` is 1 and the second otherwise, since the translator has no plural), `forms.display.collapsePanel` and `forms.display.expandPanel` ("Collapse panel {{ title }}", "Expand panel {{ title }}"), and, outside the constant, `errors.<code>` (or `<scope>.errors.<code>`) for server codes.
+- Default keys: they are listed by the `RECIPE_FORM_DEFAULT_KEYS` constant (`constants/recipe-form-default-keys.constants.ts`); a host spec checks that its flattened dictionary (`forms.array.add`) contains each of them (model: `projects/playground/src/app/i18n/fr.spec.ts`): `forms.errors.*` (including `minItems`, `maxItems`, `unique`, and `invalidDate` for a typed date that does not exist, set by the host date wrapper), `forms.warnings.validationUnavailable`, `forms.pending`, `forms.array.*`, `forms.display.errorCountOne` and `forms.display.errorCount` ("{{ count }} error", "{{ count }} errors": the engine uses the first one when `count` is 1 and the second otherwise, since the translator has no plural), `forms.display.collapsePanel` and `forms.display.expandPanel` ("Collapse panel {{ title }}", "Expand panel {{ title }}"), and, outside the constant, `errors.<code>` (or `<scope>.errors.<code>`) for server codes.
 
 ## In the host application