form-errors

Biblioteca Angular moderna para exibição de erros de validação em formulários do Ionic 7 e 8+.

100% Standalone · Zero dependências em runtime · Suporte a Signals · Compatível com NgModule

🏛️ Precisa de suporte para Ionic 2, 3, 4, 5 ou 6?
Utilize a versão universal legada [email protected] mantida na branch v1-legacy.

✨ Recursos

• 🚀 100% Standalone: Não requer NgModule. Importe e use diretamente em componentes modernos.
• 🧩 Compatível com NgModule: Funciona perfeitamente dentro de módulos clássicos do Angular 17+.
• 🎨 Integração Visual com Ionic: Respeita as CSS Custom Properties (--ion-color-danger) e a API nativa errorText.
• 📦 Duas Formas de Uso:
  1. <ion-form-errors>: Componente visual com ícone SVG nativo e animação fluida.
  2. [ionFormErrors]: Diretiva inline para preencher o slot errorText nativo do <ion-input> sem markup extra.
• 🌍 Pronto para i18n: Mensagens podem ser strings estáticas ou funções dinâmicas com parâmetros.
• 🎯 Estratégias de Exibição: Controle quando os erros aparecem (dirty, touched, dirtyOrTouched, ou immediate).
• ⚙️ Configuração Global: Defina mensagens e comportamento padrão uma única vez com provideIonFormErrors().

📋 Matriz de Versões

| Versão da Lib | Ecossistema Alvo | Versão do Ionic | Versão do Angular | |---|---|---|---| | [email protected] (Esta) | Moderno | Ionic 7 e 8+ | Angular 17, 18, 19+ | | [email protected] (branch v1-legacy) | Legado Universal | Ionic 2, 3, 4, 5 e 6 | Angular 2 a 15 |

📦 Instalação

npm install form-errors

⚙️ Configuração Global (Opcional)

No seu app.config.ts (ou no providers do seu AppModule):

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideIonFormErrors } from 'form-errors';

export const appConfig: ApplicationConfig = {
  providers: [
    provideIonFormErrors({
      defaultMessages: {
        required: 'Este campo é obrigatório',
        email: 'Informe um endereço de e-mail válido',
        minlength: ({ requiredLength, actualLength }) =>
          `Mínimo de ${requiredLength} caracteres (digitados: ${actualLength})`,
        maxlength: ({ requiredLength }) =>
          `Máximo de ${requiredLength} caracteres permitidos`,
        min: ({ min }) => `Valor mínimo permitido é ${min}`,
        max: ({ max }) => `Valor máximo permitido é ${max}`,
        pattern: 'Formato inválido',
      },
      displayStrategy: 'dirty', // 'dirty' | 'touched' | 'dirtyOrTouched' | 'immediate'
      maxErrors: 1,
    }),
  ],
};

📚 Casos de Uso (Cases)

Caso 1: Componente Standalone em Página Ionic 8 (Recomendado)

import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { IonContent, IonHeader, IonInput, IonItem, IonList, IonTitle, IonToolbar, IonButton } from '@ionic/angular/standalone';
import { IonFormErrorsComponent } from 'form-errors';

@Component({
  selector: 'app-login',
  standalone: true,
  imports: [
    ReactiveFormsModule,
    IonHeader,
    IonToolbar,
    IonTitle,
    IonContent,
    IonList,
    IonItem,
    IonInput,
    IonButton,
    IonFormErrorsComponent, // Importe o componente diretamente!
  ],
  template: `
    <ion-content class="ion-padding">
      <form [formGroup]="form" (ngSubmit)="onSubmit()">
        <ion-list>
          <ion-item>
            <ion-input formControlName="email" label="E-mail" labelPlacement="floating" type="email" />
          </ion-item>
          <!-- Exibe erros do campo com mensagens customizadas -->
          <ion-form-errors
            [control]="form.controls.email"
            [messages]="{ required: 'O e-mail é obrigatório para continuar' }" />

          <ion-item>
            <ion-input formControlName="password" label="Senha" labelPlacement="floating" type="password" />
          </ion-item>
          <ion-form-errors [control]="form.controls.password" />

          <ion-button expand="block" type="submit" [disabled]="form.invalid">
            Entrar
          </ion-button>
        </ion-list>
      </form>
    </ion-content>
  `,
})
export class LoginPage {
  private fb = inject(FormBuilder);

  form = this.fb.group({
    email: ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required, Validators.minLength(8)]],
  });

  onSubmit() {
    if (this.form.valid) {
      console.log('Login:', this.form.value);
    }
  }
}

Caso 2: Diretiva Inline [ionFormErrors] (Sem Markup Extra)

A diretiva conecta automaticamente o status de validação à propriedade nativa errorText do componente Ionic:

<ion-item>
  <ion-input
    formControlName="email"
    label="E-mail"
    labelPlacement="floating"
    type="email"
    ionFormErrors
    [errorMessages]="{
      required: 'E-mail obrigatório',
      email: 'Formato de e-mail inválido'
    }">
  </ion-input>
</ion-item>

Caso 3: Uso em Projetos com NgModule Clássico (Ionic 7 ou 8)

Mesmo que sua aplicação ainda utilize a estrutura tradicional baseada em NgModule, você pode consumir a biblioteca sem problemas:

// login.module.ts
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ReactiveFormsModule } from '@angular/forms';
import { IonicModule } from '@ionic/angular';
import { IonFormErrorsComponent, IonFormErrorsDirective } from 'form-errors';
import { LoginPage } from './login.page';

@NgModule({
  imports: [
    CommonModule,
    ReactiveFormsModule,
    IonicModule,
    IonFormErrorsComponent, // Componentes standalone são aceitos no imports do NgModule!
    IonFormErrorsDirective,
  ],
  declarations: [LoginPage],
})
export class LoginPageModule {}

Caso 4: Exibição de Múltiplos Erros Simultâneos

Por padrão, a biblioteca exibe 1 erro por vez (o primeiro ativo). Você pode configurar para exibir múltiplos erros no mesmo campo:

<ion-form-errors
  [control]="form.controls.password"
  [maxErrors]="3"
  [messages]="{
    required: 'Senha é obrigatória',
    minlength: 'Mínimo de 8 dígitos',
    pattern: 'Deve conter letras e números'
  }">
</ion-form-errors>

Caso 5: Mensagens Dinâmicas com Parâmetros do Validador

Você pode fornecer funções que recebem os parâmetros exatos calculados pelo Angular:

const customMessages: ErrorMessages = {
  minlength: ({ requiredLength, actualLength }) =>
    `Faltam ${Number(requiredLength) - Number(actualLength)} caracteres`,
  min: ({ min, actual }) =>
    `Valor digitado (${actual}) é menor que o mínimo (${min})`,
};

<ion-form-errors [control]="form.controls.age" [messages]="customMessages" />

📖 Referência da API

<ion-form-errors> Component

| Input | Tipo | Padrão | Descrição | |---|---|---|---| | control | AbstractControl | obrigatório | Controle do formulário a ser observado | | messages | ErrorMessages | {} | Mensagens no nível do componente (sobrescrevem globais) | | maxErrors | number | config global (1) | Quantidade máxima de erros simultâneos |

[ionFormErrors] Directive

| Input | Tipo | Padrão | Descrição | |---|---|---|---| | errorMessages | ErrorMessages | {} | Mensagens específicas para o input | | [ionFormErrors] | ErrorMessages | {} | Alias permitindo binding direto: [ionFormErrors]="msgs" |

provideIonFormErrors(config)

| Opção | Tipo | Padrão | Descrição | |---|---|---|---| | defaultMessages | ErrorMessages | Padrão inglês | Mensagens globais de fallback | | displayStrategy | DisplayStrategy | 'dirty' | Quando exibir erros ('dirty', 'touched', 'dirtyOrTouched', 'immediate') | | maxErrors | number | 1 | Limite padrão de erros por campo |

🔄 Tabela de Migração da v1 (Legada)

| Recurso | Versão Legada (v1.x) | Versão Moderna (v2.x) | |---|---|---| | Pacote npm | form-errors | form-errors | | Arquitetura | NgModule (FormErrorsModule) | 100% Standalone | | Reatividade | Invocação estática / getter | Change Detection integrada | | Diretiva Inline | ❌ Não suportada | ✅ [ionFormErrors] com errorText nativo | | Configuração Global | ❌ Não suportada | ✅ provideIonFormErrors() | | Suporte i18n / Funções | ❌ Apenas strings estáticas | ✅ Strings ou funções dinâmicas | | Cobertura de Testes | 0% | 98.29% (Vitest) |

📄 Licença

MIT © Anderson Pereira