From 45d7d31ae6c06c6f4ed126c79655eedc4a399e0d Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 26 Aug 2026 19:52:14 +0900 Subject: [PATCH] docs(forms): explain default validation messages --- projects/kit/docs/forms.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/projects/kit/docs/forms.md b/projects/kit/docs/forms.md index aecdb90..3a29d20 100644 --- a/projects/kit/docs/forms.md +++ b/projects/kit/docs/forms.md @@ -14,7 +14,33 @@ import { KitIonicFormField } from '@rdlabo/ionic-angular-kit/forms'; export class ProfilePage {} ``` -The adapter copies the first non-empty string validation message to Ionic's `errorText` property for `ion-input`, `ion-textarea`, `ion-select`, `ion-checkbox`, `ion-radio-group`, and `ion-toggle`. Validation wording and localization remain the application's responsibility. An explicit `errorText` or `[errorText]` binding takes precedence and prevents the adapter from being instantiated. +The adapter copies the first non-empty explicit validation message to Ionic's `errorText` property for `ion-input`, `ion-textarea`, `ion-select`, `ion-checkbox`, `ion-radio-group`, and `ion-toggle`. When Angular's validator does not provide a message, the adapter derives a generic English message from the validation error `kind` and its constraint metadata. Built-in validators therefore need no message configuration: + +```ts +readonly profileForm = form(this.profile, (path) => { + required(path.name); + email(path.email); + maxLength(path.name, 200); +}); +``` + +Unknown custom error kinds fall back to `Enter a valid value.`. Keep business-rule failures outside field validation. An explicit validation message still takes precedence for compatibility, and an explicit `errorText` or `[errorText]` binding prevents the adapter from being instantiated. + +Applications may replace the fallback resolver for localization without changing validator definitions: + +```ts +import type { ValidationError } from '@angular/forms/signals'; +import { KIT_SIGNAL_FORM_ERROR_MESSAGE_RESOLVER } from '@rdlabo/ionic-angular-kit/forms'; + +export const appConfig: ApplicationConfig = { + providers: [ + { + provide: KIT_SIGNAL_FORM_ERROR_MESSAGE_RESOLVER, + useValue: (error: ValidationError) => localizedMessageFor(error), + }, + ], +}; +``` Install the state-class configuration once at application bootstrap: