Forem: Bruno Donatelli

Angular Forms Signal: O que as documentações não te falam

Bruno Donatelli — Tue, 06 Jan 2026 11:00:00 +0000

Uma Jornada de Transformação: Do Tradicional ao Moderno

Introdução

Com o lançamento do Angular 21, uma das features experimentais mais empolgantes é o Signal Forms (@angular/forms/signal). Esta nova API representa uma evolução significativa na forma como construímos e gerenciamos formulários, oferecendo uma developer experience mais agradável, abordagem mais simples e alinhada com a direção que o framework vem adotando.

Este artigo documenta a migração de uma aplicação de reserva de voos, mostrando como transformamos formulários reativos tradicionais em uma implementação baseada em signals, explorando os benefícios, desafios e mudanças de paradigma.

repo: forms signal

Índice de Navegação

Seções Principais

Introdução
O Projeto: Sistema de Reserva de Voos
As Etapas do Formulário
- Etapa 1: Detalhes do Voo (Flight Details)
- Etapa 2: Detalhes dos Passageiros (Passenger Details)
- Etapa 3: Serviços (Services)
- Etapa 4: Pagamento (Payment)
Reactive Forms: A Abordagem Tradicional
- Como Reactive Forms Lidam com Formulários
- Tratamento de Erros no Template (Reactive Forms)
- Problemas e Limitações dos Reactive Forms
Forms/Signal: A Nova Era
- O Que É Signal Forms?
- O Que Signal Forms Resolve?
Migração: Da Teoria à Prática
- Passo 1: Converter FormGroups em Modelos de Domínio
- Passo 2: Substituir FormBuilder por Signal + Form
- Passo 3: Migrar Validação para Schema
- Passo 4: Migrar FormArray para Array no Modelo
- Passo 5: Atualizar Templates
Tratamento de Erros com Signal Forms
- Erros Nativos no Template
- Componente de Erro Reutilizável
- Erros Customizados com Validadores
Casos de Uso Avançados
- Integração com APIs Externas (ViaCEP)
- Formulários Condicionais (Nested Dynamic Forms)
- Computed Values e Derived State
Tabela Comparativa: Reactive Forms vs Signal Forms
Conclusão
- Principais Benefícios Observados
- Desafios e Considerações
- Quando Migrar?
- Reflexões Finais
Referências

O Projeto: Sistema de Reserva de Voos

O projeto desenvolvido é uma aplicação de reserva de voos que implementa um formulário multi-etapas com formulários dinâmicos, validações complexas e integração com APIs externas (ViaCEP para endereços brasileiros).

Arquitetura

O projeto mantém duas implementações paralelas:

flight-booking-legacy/: Implementação com Reactive Forms tradicional
flight-booking/: Nova implementação com Signal Forms

Esta abordagem permite comparação direta entre as duas tecnologias e facilita o aprendizado incremental.

As Etapas do Formulário

O formulário de reserva é dividido em 4 steps principais, cada uma com sua complexidade específica:

Step 1: Detalhes do Voo (Flight Details)

Etapa inicial onde são definidos os dados base da viagem:

Campos:

Tipo de voo (ida e volta / somente ida)
Origem e destino (códigos de aeroporto de 3 caracteres)
Datas de partida e retorno
Número de passageiros (adultos, crianças, bebês)
Classe do voo (econômica, premium, executiva, primeira classe)

Validações especiais:

Data de retorno obrigatória apenas para voos de ida e volta
Data de retorno deve ser posterior à data de partida
Códigos de aeroporto devem ter exatamente 3 caracteres

Step 2: Detalhes dos Passageiros (Passenger Details)

Esta etapa é dinâmica e se adapta ao número de passageiros do primeiro step. O formulário cresce e diminui conforme necessário.

Para cada passageiro:

Nome e sobrenome
Data de nascimento
Gênero
Número de passaporte
Nacionalidade
Tipo de passageiro (adulto/criança) - atribuído automaticamente

Características técnicas:

Implementado com FormArray (Reactive Forms) ou field (Signal Forms)
Formulários são adicionados/removidos dinamicamente conforme o total de passageiros muda

Step 3: Serviços (Services)

Aqui o passageiro escolhe os serviços adicionais para sua viagem:

Serviços disponíveis:

Bagagem despachada (checked bags)
Bagagem de mão (carry-on)
Seleção de assentos (array)
Preferências de refeição (array)
Seguro viagem (boolean)

Step 4: Pagamento (Payment)

O step mais complexo, com sub-formulários dinâmicos que mudam baseados no método de pagamento selecionado.

Lembrando que: Esse projeto não é um projeto do mundo real, portanto nenhum dado é salvo em nenhum banco de dados ou qualquer coisa.

Métodos de pagamento e seus formulários:

Cartão de Crédito/Débito:
- Número do cartão
- Nome no cartão
- Data de validade
- CVV
- Endereço de cobrança completo
PIX:
- CPF
- Email
- Nome completo
Boleto Bancário:
- Tipo de documento (CPF/CNPJ)
- Número do documento
- Nome completo
- Endereço completo brasileiro com integração ViaCEP

Integração ViaCEP:
Quando o usuário informa o CEP no formulário de Boleto, a aplicação automaticamente preenche:

Logradouro (rua)
Bairro
Cidade
Estado

Reactive Forms: A Abordagem Tradicional

Como Reactive Forms Lidam com Formulários

No Angular tradicional, os Reactive Forms são construídos usando o FormBuilder e uma hierarquia de FormGroup, FormControl e FormArray. Vamos analisar a implementação que chamaremos de "legacy" do nosso projeto.

Estrutura do Formulário Principal

// flight-booking-legacy/flight-search.ts
export class FlightSearchComponent implements OnInit, OnDestroy {
  private readonly fb = inject(NonNullableFormBuilder);
  private readonly destroy$ = new Subject<void>();

  // Formulário principal com hierarquia complexa
  bookingForm = this.fb.group<BookingForm>({
    flightDetails: this.createFlightDetailsGroup(),
    passengerDetails: this.fb.array<FormGroup<PassengerDetailForm>>([]),
    services: this.createServicesGroup(),
    payment: this.createPaymentGroup()
  });

  ngOnInit(): void {
    // Subscrição para mudanças no número de passageiros
    this.bookingForm.controls.flightDetails.valueChanges
      .pipe(takeUntil(this.destroy$))
      .subscribe((flightDetails) => {
        if (flightDetails.passengers) {
          this.updatePassengerForms(flightDetails.passengers);
        }
      });

    // Subscrição para mudanças no método de pagamento
    this.bookingForm.controls.payment
      .get('paymentMethod')
      ?.valueChanges.pipe(takeUntil(this.destroy$))
      .subscribe((method) => {
        this.updatePaymentForm(method);
      });
  }

  ngOnDestroy(): void {
    this.destroy$.next();
    this.destroy$.complete();
  }

  // Criação do grupo de detalhes do voo
  private createFlightDetailsGroup(): FormGroup<FlightDetailsForm> {
    const group = this.fb.group<FlightDetailsForm>(
      {
        flightType: this.fb.control(FLIGHT_TYPE.ROUNDTRIP),
        origin: this.fb.control('', {
          validators: [Validators.required, Validators.minLength(3)],
        }),
        destination: this.fb.control('', {
          validators: [Validators.required, Validators.minLength(3)],
        }),
        departureDate: this.fb.control('', {
          validators: [Validators.required],
        }),
        returnDate: this.fb.control(''),
        passengers: this.fb.group<PassengersForm>({
          adults: this.fb.control(1, {
            validators: [Validators.required, Validators.min(1)],
          }),
          children: this.fb.control(0, {
            validators: [Validators.min(0)],
          }),
        }),
        class: this.fb.control(FLIGHT_CLASS.ECONOMY),
      },
      {
        validators: [this.returnDateValidator],
      }
    );

    return group;
  }
}

Sim, funciona.

Sim, está correto.
Não, ninguém quer manter isso para sempre (ou quer, né... vai saber).

Validadores Customizados

// Validador cross-field para data de retorno
private returnDateValidator(control: AbstractControl): ValidationErrors | null {
  const flightType = control.get('flightType')?.value;
  const returnDate = control.get('returnDate')?.value;
  const departureDate = control.get('departureDate')?.value;

  if (flightType === FLIGHT_TYPE.ROUNDTRIP) {
    if (!returnDate) {
      return { returnDateRequired: true };
    }

    if (
      departureDate &&
      returnDate &&
      new Date(returnDate) <= new Date(departureDate)
    ) {
      return { returnDateInvalid: true };
    }
  }

  return null;
}

Gerenciamento de FormArray Dinâmico

// Atualização dinâmica de passageiros
private updatePassengerForms(passengers: Passengers): void {
  const totalPassengers = passengers.adults + passengers.children;
  const currentPassengers = this.passengerDetailsArray.length;

  if (totalPassengers > currentPassengers) {
    // Adicionar novos formulários
    for (let i = currentPassengers; i < totalPassengers; i++) {
      const passengerType = i < passengers.adults
        ? PASSENGER_TYPE.ADULT
        : PASSENGER_TYPE.CHILD;
      this.passengerDetailsArray.push(
        this.createPassengerDetailGroup(passengerType)
      );
    }
  } else if (totalPassengers < currentPassengers) {
    // Remover formulários excedentes
    for (let i = currentPassengers - 1; i >= totalPassengers; i--) {
      this.passengerDetailsArray.removeAt(i);
    }
  }
}

private createPassengerDetailGroup(
  type: PassengerType
): FormGroup<PassengerDetailForm> {
  return this.fb.group<PassengerDetailForm>({
    firstName: this.fb.control('', {
      validators: [Validators.required, Validators.minLength(2)],
    }),
    lastName: this.fb.control('', {
      validators: [Validators.required, Validators.minLength(2)],
    }),
    dateOfBirth: this.fb.control('', {
      validators: [Validators.required],
    }),
    gender: this.fb.control('', {
      validators: [Validators.required],
    }),
    passport: this.fb.control('', {
      validators: [
        Validators.required,
        Validators.pattern(/^[A-Z0-9]{6,9}$/),
      ],
    }),
    nationality: this.fb.control('', {
      validators: [Validators.required],
    }),
    type: this.fb.control(type),
  });
}

Sub-formulários Dinâmicos de Pagamento

Ao trocar o método de pagamento, precisamos adicionar e remover controles do formulário de forma dinâmica.

// Mudança dinâmica de formulário baseada no método de pagamento
private updatePaymentForm(method: string | null | undefined): void {
  if (!method) return;

  const paymentControl = this.bookingForm.controls.payment;

  switch (method) {
    case PAYMENT_METHOD.CREDIT_CARD:
    case PAYMENT_METHOD.DEBIT_CARD:
      paymentControl.setControl('cardDetails', this.createCardDetailsGroup());
      paymentControl.removeControl('pixDetails');
      paymentControl.removeControl('boletoDetails');
      break;

    case PAYMENT_METHOD.PIX:
      paymentControl.setControl('pixDetails', this.createPixDetailsGroup());
      paymentControl.removeControl('cardDetails');
      paymentControl.removeControl('boletoDetails');
      break;

    case PAYMENT_METHOD.BOLETO:
      paymentControl.setControl('boletoDetails', this.createBoletoDetailsGroup());
      paymentControl.removeControl('cardDetails');
      paymentControl.removeControl('pixDetails');
      break;
  }
}

private createCardDetailsGroup(): FormGroup<CardDetailsForm> {
  return this.fb.group<CardDetailsForm>({
    cardNumber: this.fb.control('', {
      validators: [Validators.required, Validators.pattern(/^\d{16}$/)],
    }),
    cardholderName: this.fb.control('', {
      validators: [Validators.required],
    }),
    expirationDate: this.fb.control('', {
      validators: [Validators.required, Validators.pattern(/^\d{2}\/\d{2}$/)],
    }),
    cvv: this.fb.control('', {
      validators: [Validators.required, Validators.pattern(/^\d{3,4}$/)],
    }),
    billingAddress: this.createAddressGroup(),
  });
}

Tratamento de Erros no Template (Reactive Forms)

Template de Detalhes de Passageiros

<!-- flight-booking-legacy/passenger-details-step/passenger-details-step.component.html -->
<div class="passenger-form" [formGroup]="passengerForm">
  <div class="form-group">
    <label [for]="'firstName-' + index">First Name *</label>
    <input
      [id]="'firstName-' + index"
      type="text"
      formControlName="firstName"
      class="form-control"
      [class.invalid]="isFieldInvalid(passengerForm.controls.firstName)"
    />
    @if (isFieldInvalid(passengerForm.controls.firstName)) {
      <span class="error-message">
        {{ getFieldError(passengerForm.controls.firstName) }}
      </span>
    }
  </div>

  <div class="form-group">
    <label [for]="'passport-' + index">Passport Number *</label>
    <input
      [id]="'passport-' + index"
      type="text"
      formControlName="passport"
      class="form-control"
      [class.invalid]="isFieldInvalid(passengerForm.controls.passport)"
    />
    @if (isFieldInvalid(passengerForm.controls.passport)) {
      <span class="error-message">
        {{ getFieldError(passengerForm.controls.passport) }}
      </span>
    }
  </div>
</div>

Lógica de Validação no Component

// Verificar se campo está inválido
isFieldInvalid(control: AbstractControl<PassengerDetailForm>): boolean {
  return !!(control && control.invalid && (control.dirty || control.touched));
}

// Obter mensagem de erro apropriada
getFieldError(control: AbstractControl<PassengerDetailForm>): string {
  if (!control || !control.errors) return '';

  if (control.errors['required']) return 'This field is required';
  if (control.errors['minlength']) {
    return `Minimum length is ${control.errors['minlength'].requiredLength}`;
  }
  if (control.errors['pattern']) return 'Invalid format';
  if (control.errors['min']) {
    return `Minimum value is ${control.errors['min'].min}`;
  }

  return 'Invalid field';
}

Problemas e Limitações dos Reactive Forms

Após trabalhar com Reactive Forms em projetos complexos, alguns problemas se tornam mais escancarados no nosso dia a dia:

Boilerplate Excessivo: Muito código para criar e gerenciar formulários
Gerenciamento de Subscrições: takeUntil, Subject, ngOnDestroy em todo lugar
Tipos Duplicados: FormControl<string> vs string - duplicação de tipo entre modelo e formulário
Validação Espalhada: Validadores em múltiplos lugares (criação do form, validadores customizados, template)
Mensagens de Erro Manuais: Lógica repetitiva de mapeamento de erros para mensagens
Reatividade Manual: Precisa subscrever manualmente a valueChanges para reagir
Complexidade de FormArray: Adicionar/remover itens requer muita cerimônia

Forms/Signal: A Nova Era

O Que É Signal Forms?

Lançado experimentalmente no Angular 21, o Signal Forms (@angular/forms/signal) é uma reimaginação completa da API de formulários, projetada para trabalhar nativamente com o sistema de signals em Angular.

Principais diferenças filosóficas:

Aspecto	Reactive Forms	Signal Forms
Fonte de verdade	FormGroup/FormControl	Signal com modelo de domínio
Validação	Validators em cada control	Schema centralizado
Reatividade	RxJS Observables	Signals nativos
Tipos	Tipos de form específicos	Tipos de domínio diretos
Template binding	`formControlName`	`[field]` directive

O Que Signal Forms Resolve?

Signal Forms ataca diretamente alguns dos pontos mais dolorosos dos Reactive Forms tradicionais:

1. Eliminação do Boilerplate

Não é mais necessário:

Importar e injetar FormBuilder ou NonNullableFormBuilder
Criar tipos específicos de formulário (FormControl<T>, FormGroup<T>)
Gerenciar subscrições manualmente
Menos código para manter e menos pontos de falha.

A primeira impressão costuma ser: “isso parece simples demais”.

Normalmente é o momento em que algo bom está acontecendo.

2. Modelo como Fonte de Verdade

// Modelo de domínio limpo - não tipos de formulário!
protected readonly bookingModel = signal<FlightBooking>({
  flightDetails: defaultFlightDetails(),
  passengerDetails: [],
  services: defaultServices(),
  payment: defaultPaymentBase()
});

// Form criado A PARTIR do modelo
protected readonly bookingForm = form(this.bookingModel, (schemaPath) => {
  // Validação aqui
});

Nessa etapa, o "form" recebe o signal como primeiro argumento, e então é passado um callback chamado schemaPath (SchemaPathTree), onde será possível acessar os objetos do formulário.

Se você está procurando onde ficou a sincronização manual, ela não ficou.

3. Validação Centralizada e Declarativa

Toda a lógica de validação em um único lugar, com mensagens inline:

protected readonly bookingForm = form(this.bookingModel, (schemaPath) => {
  const { flightDetails, passengerDetails, services, payment } = schemaPath;

  // Validações simples com mensagens inline
  required(flightDetails.origin, { message: 'Origin is required' });
  minLength(flightDetails.origin, 3, {
    message: 'Origin must be at least 3 characters'
  });

  required(flightDetails.destination, { message: 'Destination is required' });
  minLength(flightDetails.destination, 3, {
    message: 'Destination must be at least 3 characters'
  });

  required(flightDetails.departureDate, {
    message: 'Departure date is required'
  });

  // Validação cross-field
  validate(flightDetails.returnDate, ({ value, valueOf }) => {
    const flightType = valueOf(flightDetails.flightType);
    const returnDate = value();
    const departureDate = valueOf(flightDetails.departureDate);

    if (flightType === FLIGHT_TYPE.ROUNDTRIP) {
      if (!returnDate) {
        return {
          kind: 'returnDateRequired',
          message: 'Return date is required for round trip flights'
        };
      }

      if (departureDate && returnDate && new Date(returnDate) < new Date(departureDate)) {
        return {
          kind: 'returnDateInvalid',
          message: 'Return date must be after departure date'
        };
      }
    }

    return null;
  });

  // Validação de arrays
  const passengerSchema = schema<PassengerDetail>((passengerPath) => {
    required(passengerPath.firstName, { message: 'First name is required' });
    minLength(passengerPath.firstName, 2, {
      message: 'First name must be at least 2 characters'
    });

    required(passengerPath.lastName, { message: 'Last name is required' });
    minLength(passengerPath.lastName, 2, {
      message: 'Last name must be at least 2 characters'
    });

    required(passengerPath.dateOfBirth, {
      message: 'Date of birth is required'
    });

    required(passengerPath.gender, { message: 'Gender is required' });

    required(passengerPath.passport, { message: 'Passport is required' });
    pattern(passengerPath.passport, /^[A-Z0-9]{6,9}$/, {
      message: 'Passport must be 6-9 alphanumeric characters',
    });

    required(passengerPath.nationality, { message: 'Nationality is required' });
  });

  applyEach(schemaPath.passengerDetails, passengerSchema);
});

Você pode ter notado algo interessante: os validadores como required, min, max e minLength possuem o mesmo nome dos atributos HTML nativos.

Ao usar esses validadores, o forms/signal reflete automaticamente esses atributos no field correspondente.
Ao declarar manualmente um atributo como max no template HTML em um campo que utiliza a diretiva field, o Angular lança o seguinte erro:

4. Reatividade Automática com Signals

// Computed values automáticos - sem subscrições!
protected readonly totalPassengers = computed(() => {
  const passengers = this.bookingModel().flightDetails.passengers;
  return passengers.adults + passengers.children;
});

// Effect para reagir a mudanças - ainda sem subscrições manuais!
constructor() {
  effect(() => {
    const model = this.bookingModel();
    const totalPassengers =
      model.flightDetails.passengers.adults +
      model.flightDetails.passengers.children;

    this.updatePassengerDetails(totalPassengers);
  });

  effect(() => {
    const paymentMethod = this.bookingModel().payment.paymentMethod;
    // Atualiza modelo baseado no método de pagamento
  });
}

Migração: aplicando Signal Forms passo a passo

O primeiro passo da migração envolve o modelo.

Antes de pensar em validação ou template, precisamos separar o "domínio" da "infraestrutura" de formulário.

Passo 1: Converter FormGroups em Modelos de Domínio

Antes (Reactive Forms):

// Tipos específicos de formulário reativo
export interface FlightDetailsForm {
  flightType: FormControl<'roundtrip' | 'oneway'>;
  origin: FormControl<string>;
  destination: FormControl<string>;
  departureDate: FormControl<string>;
  returnDate: FormControl<string>;
  passengers: FormGroup<PassengersForm>;
  class: FormControl<FlightClass>;
}

export interface PassengersForm {
  adults: FormControl<number>;
  children: FormControl<number>;
}

Depois (Signal Forms):

// Tipos de domínio, sem acoplamento ao formulário
export interface FlightDetails {
  flightType: FlightType;
  origin: string;
  destination: string;
  departureDate: string;
  returnDate: string;
  passengers: Passengers;
  class: FlightClass;
}

export interface Passengers {
  adults: number;
  children: number;
}

Passo 2: Substituir FormBuilder por Signal + Form

Antes:

export class FlightSearchComponent implements OnInit, OnDestroy {
  private readonly fb = inject(NonNullableFormBuilder);
  private readonly destroy$ = new Subject<void>();

  bookingForm = this.fb.group<BookingForm>({
    flightDetails: this.createFlightDetailsGroup(),
    passengerDetails: this.fb.array<FormGroup<PassengerDetailForm>>([]),
    services: this.createServicesGroup(),
    payment: this.createPaymentGroup()
  });

  private createFlightDetailsGroup(): FormGroup<FlightDetailsForm> {
    return this.fb.group<FlightDetailsForm>({
      flightType: this.fb.control(FLIGHT_TYPE.ROUNDTRIP),
      origin: this.fb.control('', {
        validators: [Validators.required, Validators.minLength(3)],
      }),
      // ... mais 20 linhas de criação de form
    });
  }

  ngOnInit(): void {
    this.bookingForm.controls.flightDetails.valueChanges
      .pipe(takeUntil(this.destroy$))
      .subscribe(/* ... */);
  }

  ngOnDestroy(): void {
    this.destroy$.next();
    this.destroy$.complete();
  }
}

Depois:

export class SearchFlightComponent {
  // Signal com modelo de domínio
  protected readonly bookingModel = signal<FlightBooking>({
    flightDetails: defaultFlightDetails(),
    passengerDetails: [],
    services: defaultServices(),
    payment: defaultPaymentBase()
  });

  // Form criado a partir do modelo, com validação declarada em um único lugar
  protected readonly bookingForm = form(this.bookingModel, (schemaPath) => {
    // Todo schema de validação aqui
    const { flightDetails } = schemaPath;

    required(flightDetails.origin, { message: 'Origin is required' });
    minLength(flightDetails.origin, 3, {
      message: 'Origin must be at least 3 characters'
    });
    // ... validações declarativas
  });
}

Com o modelo isolado, o formulário deixa de ser o centro da aplicação.
Ele passa a ser apenas uma projeção reativa desse estado.

Passo 3: Migrar Validação para Schema

Padrão de Migração:

// ANTES: Validators espalhados
origin: this.fb.control('', {
  validators: [Validators.required, Validators.minLength(3)],
})

// DEPOIS: Validação no schema com mensagens
required(flightDetails.origin, { message: 'Origin is required' });
minLength(flightDetails.origin, 3, {
  message: 'Origin must be at least 3 characters'
});

Nesse ponto da migração, normalmente bate aquela sensação de alívio:

Validadores Customizados:

// ANTES: Método separado
private returnDateValidator(control: AbstractControl): ValidationErrors | null {
  const flightType = control.get('flightType')?.value;
  const returnDate = control.get('returnDate')?.value;
  // ... lógica complexa
  return { returnDateRequired: true };
}

// DEPOIS: Inline no schema com acesso a outros valores
validate(flightDetails.returnDate, ({ value, valueOf }) => {
  const flightType = valueOf(flightDetails.flightType);
  const returnDate = value();
  const departureDate = valueOf(flightDetails.departureDate);

  if (flightType === FLIGHT_TYPE.ROUNDTRIP) {
    if (!returnDate) {
      return {
        kind: 'returnDateRequired',
        message: 'Return date is required for round trip flights'
      };
    }

    if (departureDate && returnDate && new Date(returnDate) < new Date(departureDate)) {
      return {
        kind: 'returnDateInvalid',
        message: 'Return date must be after departure date'
      };
    }
  }

  return null;
});

Passo 4: Migrar FormArray para Array no Modelo

Antes:

// FormArray complexo
passengerDetails: this.fb.array<FormGroup<PassengerDetailForm>>([])

// Adicionar item
this.passengerDetailsArray.push(this.createPassengerDetailGroup(type));

// Remover item
this.passengerDetailsArray.removeAt(index);

// Acessar no template
@for (let passenger of passengerDetailsArray.controls; track $index) {
  <div [formGroupName]="$index">
    <!-- campos -->
  </div>
}

Ao remover o FormArray, o gerenciamento deixa de ser imperativo e passa a ser apenas atualização de estado.

Depois:

// Array simples no modelo
passengerDetails: PassengerDetail[]

// Adicionar item - update direto no modelo!
this.bookingModel.update((model) => ({
  ...model,
  passengerDetails: [
    ...model.passengerDetails,
    createDefaultPassenger(type)
  ]
}));

// Remover item
this.bookingModel.update((model) => ({
  ...model,
  passengerDetails: model.passengerDetails.filter((_, i) => i !== index)
}));

// Acessar no template - muito mais simples!
@for (passenger of bookingForm().passengerDetails; track $index) {
  <div>
    <!-- campos com [field] directive -->
  </div>
}

Validação de Arrays:

// Schema reutilizável para cada item do array
const passengerSchema = schema<PassengerDetail>((passengerPath) => {
  required(passengerPath.firstName, { message: 'First name is required' });
  minLength(passengerPath.firstName, 2, {
    message: 'First name must be at least 2 characters'
  });
  required(passengerPath.lastName, { message: 'Last name is required' });
  // ... mais validações
});

// Aplicar schema a cada item do array
applyEach(schemaPath.passengerDetails, passengerSchema);

Passo 5: Atualizar Templates

Antes (Reactive Forms):

<form [formGroup]="passengerDetailsArray.at($index)">
  <div class="form-group">
    <label [for]="'firstName-' + $index">First Name *</label>
    <input
      [id]="'firstName-' + $index"
      type="text"
      formControlName="firstName"
      [class.invalid]="isFieldInvalid(getPassengerControl($index, 'firstName'))"
    />
    @if (isFieldInvalid(getPassengerControl($index, 'firstName'))) {
      <span class="error-message">
        {{ getFieldError(getPassengerControl($index, 'firstName')) }}
      </span>
    }
  </div>
</form>

Depois (Signal Forms):

<!-- Muito mais limpo e declarativo! -->
@let firstNameField = passenger.firstName;

<div class="form-group">
  <label [for]="'firstName-' + $index">First Name *</label>
  <input
    [id]="'firstName-' + $index"
    type="text"
    [field]="firstNameField"
    [class.invalid]="isFieldInvalid(firstNameField)"
  />
  @if (isFieldInvalid(firstNameField)) {
    @for (error of firstNameField().errors(); track $index) {
      <app-form-error-message>
        {{ error.message }}
      </app-form-error-message>
    }
  }
</div>

Utilitários de Validação Reutilizáveis:

// shared/utils/form-validation.utils.ts
export function isFieldInvalid(
  field: FieldTree<unknown, string> | FieldState<unknown, string>
): boolean {
  const fieldState = typeof field === 'function' ? field() : field;
  return fieldState.invalid() && (fieldState.dirty() || fieldState.touched());
}

export function getFieldError(
  field: FieldTree<unknown, string> | FieldState<unknown, string>
): string | null {
  const fieldState = typeof field === 'function' ? field() : field;
  const errors = fieldState.errors();
  if (!errors) return null;

  const firstKey = Object.keys(errors)[0];
  const error = errors[firstKey];

  if (error && typeof error === 'object' && 'message' in error) {
    return (error as { message: string }).message;
  }
  return null;
}

Tratamento de Erros com Signal Forms

Erros Nativos no Template

Uma das grandes vantagens dos Signal Forms é que os erros são objetos tipados e acessíveis diretamente no template, tornando o tratamento de erros muito mais simples e declarativo.

Estrutura de Erros

// Cada field é um signal que retorna FieldState
const firstNameField = passenger.firstName;

// FieldState contém:
interface FieldState<T, K extends string> {
  value(): T;
  invalid(): boolean;
  valid(): boolean;
  pending(): boolean;
  disabled(): boolean;
  touched(): boolean;
  dirty(): boolean;
  errors(): Record<string, any> | null;
}

Exibição de Erros no Template

@let firstNameField = passenger.firstName;

<input
  [id]="'firstName-' + $index"
  type="text"
  [field]="firstNameField"
  [class.invalid]="firstNameField().invalid() && firstNameField().touched()"
  [attr.aria-invalid]="firstNameField().invalid()"
  [attr.aria-describedby]="firstNameField().invalid() ? 'firstName-' + $index + '-error' : null"
/>

<!-- Iteração sobre todos os erros -->
@if (firstNameField().invalid() && firstNameField().touched()) {
  <div [id]="'firstName-' + $index + '-error'" role="alert">
    @for (error of firstNameField().errors(); track $index) {
      <app-form-error-message>
        {{ error.message }}
      </app-form-error-message>
    }
  </div>
}

Atributos ARIA Dinâmicos

Como os Signal Forms expõem o estado de forma reativa, é fácil adicionar atributos de acessibilidade:

<input
  [field]="emailField"
  [attr.aria-invalid]="emailField().invalid()"
  [attr.aria-required]="true"
  [attr.aria-describedby]="emailField().invalid() ? 'email-error' : null"
/>

@if (emailField().invalid() && emailField().touched()) {
  <span id="email-error" role="alert" class="error-message">
    @for (error of emailField().errors(); track $index) {
      <span>{{ error.message }}</span>
    }
  </span>
}

Componente de Erro Reutilizável

Criar um componente reutilizável para exibição de erros torna o código mais consistente:

// shared/components/form-error-message/form-error-message.component.ts
import { Component, input } from '@angular/core';

@Component({
  selector: 'app-form-error-message',
  standalone: true,
  template: `
    <span
      class="error-message"
      role="alert"
      [id]="uniqueId()"
    >
      <ng-content></ng-content>
    </span>
  `,
  styles: [`
    .error-message {
      color: var(--error-color, #dc3545);
      font-size: 0.875rem;
      margin-top: 0.25rem;
      display: block;
    }
  `]
})
export class FormErrorMessageComponent {
  uniqueId = input<string>('');
}

Uso:

@if (firstNameField().invalid() && firstNameField().touched()) {
  @for (error of firstNameField().errors(); track $index) {
    <app-form-error-message [uniqueId]="'firstName-error-' + $index">
      {{ error.message }}
    </app-form-error-message>
  }
}

Erros Customizados com Validadores

// Validador customizado para email
validate(payment.pixDetails.email, ({ value }) => {
  const email = value();
  if (!email) return null;

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return {
      kind: 'invalidEmail',
      message: 'Please enter a valid email address'
    };
  }

  return null;
});

// Validador com lógica complexa para CPF
validate(payment.pixDetails.cpf, ({ value }) => {
  const cpf = value();
  if (!cpf) return null;

  // Remove caracteres não numéricos
  const cleanCpf = cpf.replace(/\D/g, '');

  if (cleanCpf.length !== 11) {
    return {
      kind: 'invalidCpfLength',
      message: 'CPF must have 11 digits'
    };
  }

  // Validação de dígitos verificadores
  if (!isValidCPF(cleanCpf)) {
    return {
      kind: 'invalidCpf',
      message: 'Invalid CPF number'
    };
  }

  return null;
});

Casos de Uso

Integração com APIs Externas (ViaCEP)

Trabalhar com APIs externas para preencher dados automaticamente:

Reactive Forms (Antes):

onCepChange(cep: string): void {
  if (cep.length === 8) {
    this.viaCepService.getAddress(cep)
      .pipe(takeUntil(this.destroy$))
      .subscribe({
        next: (address) => {
          const boletoControl = this.bookingForm.controls.payment
            .get('boletoDetails') as FormGroup;

          boletoControl.patchValue({
            street: address.logradouro,
            neighborhood: address.bairro,
            city: address.localidade,
            state: address.uf
          });
        },
        error: (error) => {
          console.error('Error fetching address:', error);
        }
      });
  }
}

Signal Forms (Depois):

async onCepChange(cep: string): Promise<void> {
  if (cep.length === 8) {
    try {
      const address = await firstValueFrom(
        this.viaCepService.getAddress(cep)
      );

      // Atualização direta no modelo!
      this.bookingModel.update((model) => ({
        ...model,
        payment: {
          ...model.payment,
          boletoDetails: {
            ...model.payment.boletoDetails!,
            address: {
              ...model.payment.boletoDetails!.address,
              street: address.logradouro,
              neighborhood: address.bairro,
              city: address.localidade,
              state: address.uf
            }
          }
        }
      }));
    } catch (error) {
      console.error('Error fetching address:', error);
    }
  }
}

Formulários Condicionais (Nested Dynamic Forms)

Criar formulários que mudam estrutura baseado em condições:

// Schema para payment com sub-formulários condicionais
const { payment } = schemaPath;

required(payment.paymentMethod, { message: 'Payment method is required' });

// Validação condicional baseada no método de pagamento
validate(payment, ({ valueOf }) => {
  const method = valueOf(payment.paymentMethod);

  switch (method) {
    case PAYMENT_METHOD.CREDIT_CARD:
    case PAYMENT_METHOD.DEBIT_CARD:
      // Valida apenas se cardDetails existe
      const cardDetails = valueOf(payment.cardDetails);
      if (!cardDetails) {
        return {
          kind: 'cardDetailsRequired',
          message: 'Card details are required'
        };
      }
      break;

    case PAYMENT_METHOD.PIX:
      const pixDetails = valueOf(payment.pixDetails);
      if (!pixDetails) {
        return {
          kind: 'pixDetailsRequired',
          message: 'PIX details are required'
        };
      }
      break;

    case PAYMENT_METHOD.BOLETO:
      const boletoDetails = valueOf(payment.boletoDetails);
      if (!boletoDetails) {
        return {
          kind: 'boletoDetailsRequired',
          message: 'Boleto details are required'
        };
      }
      break;
  }

  return null;
});

// Sub-schemas para cada tipo de pagamento
if (this.bookingModel().payment.cardDetails) {
  const cardSchema = schema<CardDetails>((cardPath) => {
    required(cardPath.cardNumber, { message: 'Card number is required' });
    pattern(cardPath.cardNumber, /^\d{16}$/, {
      message: 'Card number must be 16 digits'
    });

    required(cardPath.cardholderName, {
      message: 'Cardholder name is required'
    });

    required(cardPath.expirationDate, {
      message: 'Expiration date is required'
    });
    pattern(cardPath.expirationDate, /^\d{2}\/\d{2}$/, {
      message: 'Expiration date must be in MM/YY format'
    });

    required(cardPath.cvv, { message: 'CVV is required' });
    pattern(cardPath.cvv, /^\d{3,4}$/, {
      message: 'CVV must be 3 or 4 digits'
    });
  });

  // Aplicar schema ao cardDetails se existir
  applySchema(payment.cardDetails, cardSchema);
}

Computed Values e Derived State

Criar valores calculados automaticamente baseados no estado do formulário:

// Total de passageiros
protected readonly totalPassengers = computed(() => {
  const passengers = this.bookingModel().flightDetails.passengers;
  return passengers.adults + passengers.children;
});

Tabela Comparativa: Reactive Forms vs Signal Forms

Aspecto	Reactive Forms	Signal Forms
Importações	`ReactiveFormsModule`, `FormBuilder`, `FormGroup`, `FormControl`, `FormArray`, `Validators`	`@angular/forms/signal`, `form`, `schema`, validadores específicos
Definição de Modelo	Tipos específicos (`FormControl<T>`, `FormGroup<T>`)	Interfaces de domínio limpas
Criação de Form	`this.fb.group<T>({ ... })` com validadores inline	`form(signal, schema)` com validação centralizada
Validação	`Validators.required`, `Validators.minLength(n)`	`required(field, { message })`, `minLength(field, n, { message })`
Mensagens de Erro	Mapeamento manual de `errors` para strings	Mensagens inline no schema, tipadas
Template Binding	`formControlName="field"`	`[field]="fieldSignal"`
Acesso a Valores	`form.get('field')?.value`	`model().field`
Mudança de Valores	`form.patchValue({ ... })`	`model.update(m => ({ ...m, ... }))`
FormArray	`FormArray` com `push()`, `removeAt()`, `controls`	Array no modelo, manipulação direta
Validação de Arrays	Validadores em cada item ao criar	`applyEach(path, schema)`
Reatividade	`valueChanges.subscribe()`	`effect()` ou `computed()`
Gerenciamento de Subscrições	`takeUntil(destroy$)`, `ngOnDestroy`	Não necessário
Estado de Campo	`control.invalid`, `control.touched`, `control.dirty`	`field().invalid()`, `field().touched()`, `field().dirty()`
Erros	`control.errors` (Record ou null)	`field().errors()` (array tipado)
Validação Cross-Field	Validador customizado no FormGroup	`validate(field, ({ valueOf }) => ...)`
Validação Async	`AsyncValidatorFn`	`validateAsync(field, async ({ value }) => ...)`
Disabled Fields	`control.disable()`, `control.enable()`	`field().disabled()` (readonly state)
Reset	`form.reset()`	`model.set(defaultValue)`
Type Safety	Moderada (genéricos complexos)	Forte (inferência do modelo)
Boilerplate	Alto (FormBuilder, tipos, subscrições)	Baixo (modelo + schema)
Curva de Aprendizado	Moderada (conceitos RxJS)	Íngreme inicialmente (novo paradigma)
Performance	Boa (com OnPush)	Excelente (signals nativos, zoneless)
Compatibilidade	Angular 2+	Angular 21+ (experimental)

Conclusão

A migração de Reactive Forms para Signal Forms no Angular 21+ representa mais do que uma simples atualização de API - é uma mudança fundamental de paradigma na forma como pensamos e construímos formulários.

Principais Benefícios Observados

Redução Drástica de Boilerplate
- Eliminação de 60-70% do código de setup
- Não mais FormBuilder, ngOnDestroy, gerenciamento de subscrições
- Modelos de domínio limpos sem tipos específicos de formulário
Validação Centralizada e Declarativa
- Todo schema de validação em um único lugar
- Mensagens de erro co-locadas com regras
- Validação cross-field simplificada
- Reutilização de schemas com applyEach
Reatividade Nativa
- computed() para valores derivados
- effect() para side-effects caso necessário
- Sem gerenciamento manual de subscrições
- Performance superior com zoneless change detection
Developer Experience Melhorada
- Type safety forte com inferência automática
- Mensagens de erro tipadas e acessíveis
- Templates mais limpos e legíveis
- Debugging mais fácil (signals são rastreáveis)
Preparação para o Futuro
- Alinhado com a direção do Angular (signals em todo lugar)
- Compatível com zoneless mode
- Base para futuras features do framework

Desafios e Considerações

Status Experimental:

A API ainda é experimental e pode mudar
Nem toda funcionalidade dos Reactive Forms tem paridade
Documentação ainda está em desenvolvimento

Curva de Aprendizado:

Paradigma diferente
Equipe precisa se familiarizar com signals e o novo modelo
Pode ser confuso manter dois sistemas em paralelo

Ecossistema:

Bibliotecas de terceiros podem não ter suporte ainda
Exemplos e recursos da comunidade ainda são limitados
Ferramentas de dev (extensões, linters) podem não estar atualizadas

Reflexões Finais

Signal Forms representa uma evolução natural do Angular em direção a um modelo de reatividade mais simples e performático. A jornada de migração documentada neste artigo mostra que, apesar da curva de aprendizado inicial, os benefícios em termos de simplicidade, performance e maintainability fazem do Signal Forms uma adição valiosa ao ecossistema Angular.

O futuro dos formulários no Angular é reactivo por natureza, mas gerenciado por signals - e esse futuro já começou. Para desenvolvedores que buscam criar aplicações modernas, performáticas e de fácil manutenção, Signal Forms oferece uma base sólida e promissora.

Referências

Sobre o Projeto

Este artigo documenta a implementação real disponível em:

/flight-booking-legacy/ - Reactive Forms
/flight-booking/ - Signal Forms

Código completo, testes e documentação adicional disponíveis no repositório.

Conhecendo as novidades do Angular 21

Bruno Donatelli — Wed, 19 Nov 2025 20:19:00 +0000

Não é novidade que o time do Angular está sempre querendo modernizar o framework, e a versão 21 traz novas funcionalidades interessantes e evoluções importantes.

Como migro de versão?

Siga o guia de migração

Esse guia te disponibiliza como fazer a migração desde aplicações de pequeno porte até aplicações gigantes.

HttpClient habilitado por padrão

Sim!!! Quando criarmos novas aplicações, não será mais necessário adicionar o provider "provideHttpClient()" dentro dos providers do app.config.ts.

AH MAS MINHA APLICAÇÃO É COM SSR EU PRECISO DO FETCH API

Tá bom, tá bom... Aí você adiciona o provideHttpClient(withFetch())

export const appConfig: ApplicationConfig = {
  providers: [provideRouter(routes), provideHttpClient(withFetch())]
}

E sua aplicação vai poder usar fetch api sem problema nenhum.

Vitest

Finalmente estamos vendo de perto a substituição do Karma dentro do framework, para o Vitest.
Por padrão, na criação de um projeto Angular 21+, o Karma já não vai vir instalado junto do Jasmine, assim dando espaço ao Vitest (que virá instalado nas dependências do projeto).

E quando rodamos o comando de teste ng test, recebemos a seguinte mensagem:

NOTE: The "unit-test" builder is currently EXPERIMENTAL and not ready for production use.

Dentro do arquivo angular.json, na propriedade de "test"

"test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverageReporters": ["cobertura", "lcov", "html"]
          }
        }
      }

Dentro das options, se adicionarmos a propriedade "runner", veremos que o "default" é o Vitest, enquanto o karma ainda continua aparecendo mas já não é a opção padrão.
E caso precisemos configurar a cobertura do nosso projeto, dentro das options conseguimos fazer a configuração dos reporters, watermarks, threshold, include, exclude, coverage... enfim, várias opções que facilitam o nosso dia a dia dentro de um projeto Angular.

E é muito bom ver essa evolução com relação aos testes unitários, trocando o test runner.

"AI MAS E O JEST????"
Atualmente o Jest ainda possui problemas com ESModules, algo que projetos com Typescript e ainda mais Angular, usam bastante. Você pode utilizar o jest-preset-angular, porém sabendo que existe algo nativo do framework, fica mais fácil usar o que já vem pré pronto do que fazer mais uma configuração de mais um arquivo pra rodar seus testes unitários.

Tailwind

Durante a criação de um novo projeto Angular

ng new my-app

Foi colocada uma nova opção para os estilos. Além do lendário SCSS, Less e CSS, agora podemos escolher Tailwind diretamente.

Signals Form

O signals form é uma nova API pública do Angular na qual poderemos criar e gerenciar formulários reativos, com uso de Signals.

Essa nova API vem de maneira simplificada, melhorando a experiência do desenvolvedor, nos fazendo escrever um código mais limpo e performático de manter.

import { Component, signal } from '@angular/core';
import { form, minLength, required, schema, submit, Field, pattern } from '@angular/forms/signals';

type Login = {
  email: string;
  password: string;
};

const loginSchema = schema<Login>((path) => {
  required(path.email);
  required(path.password);

  minLength(path.password, 8);
  pattern(path.email, /^[^\s@]+@[^\s@]+\.[^\s@]+$/);
});

@Component({
  selector: 'app-root',
  imports: [Field],
  template: `<h1>Login</h1>
<form>
  <div>
    <label for="email">Email</label>
    <input id="email" type="email" name="email" [field]="loginForm.email" />
  </div>
  <div>
    <label for="password">Password:</label>
    <input id="password" type="password" name="password" [field]="loginForm.password" />
  </div>
  <button type="button" aria-label="Login" (click)="enter()">Login</button>
</form>
`,
  styleUrl: './app.css'
})
export class App {
  readonly login = signal<Login>({ email: '', password: '' });

  readonly loginForm = form(this.login, loginSchema);

  enter() {
    submit(this.loginForm, async (form) => {
      console.log('Submitted with', form);

      return null; // if everything is okay just return null
    });
  }
}

Zoneless

No angular 20.2, o time do Angular trabalhou em deixar o zoneless stable (anteriormente em developer preview). Na versão 21, zoneless é o padrão dentro do framework. Ou seja, estamos cada vez mais inclinados a ter uma aplicação menos dependente do zonejs, e seguindo cada vez mais firme na direção de uso com Signals.

É importante ressaltar que em processos assíncronos, devemos detectar mudanças. Então vamos ter que prestar mais atenção, porque se de um lado tínhamos uma biblioteca que por debaixo dos panos cuidava de processos assíncronos e notificava o framework que ocorreram mudanças, agora com o zoneless, em alguns momentos deveremos notificar o framework que alguma mudança possa ter acontecido (utilizando o ChangeDetectorRef).

Conclusão

Muitas são as novidades do framework, o caminho para aplicações mais reativas com signals + zoneless + OnPush está bem na nossa frente. Também melhorias pontuais como adicionar Tailwind de forma automática durante a criação de projeto, test runners novos. Essas pequenas mudanças estruturais, no fim do dia, nos fazem termos mais produtividade e escrevendo menos código.

Você pode checar as mudanças do Angular 21 no Blog do Angular

Simplifique modais com os atributos experimentais "command" e "commandfor"

Bruno Donatelli — Wed, 05 Mar 2025 17:00:00 +0000

Os modais são um padrão comum de UI utilizado para exibir informações importantes ou solicitar ações dos usuários sem que eles precisem sair da página atual. No entanto, criar modais funcionais exigia uma combinação bizarra de HTML, CSS e JavaScript.

Com a introdução dos novos atributos experimentais do elemento button, como command e commandfor, esse processo está se tornando mais declarativo e simplificado.

O que é um modal

Um modal é uma caixinha de diálogo ou janela que aparece sobre o conteúdo principal da página, interrompendo temporariamente o fluxo do usuário chamando sua atenção para uma tarefa ou mensagem específica. Modais são frequentemente utilizados para:

Exibir alertas ou confirmações.
Coletar entradas do usuário (por exemplo, formulários).
Mostrar informações ou opções adicionais.

Caso você queira que o foco fique apenas no modal quando ele for aberto, procure pela estratégia de "trap focus".

Como eram criados os modais anteriormente

Antes da introdução do elemento e da API Popover, as pessoas desenvolvedoras precisavam criar soluções personalizadas para implementar modais. Isso geralmente envolvia:

Usar uma <div> com role="dialog" e atributos ARIA para acessibilidade.
Gerenciar o foco manualmente com JavaScript para garantir uma navegação adequada pelo teclado.
Adicionar event listener para detectar a teclas e cliques no fundo para fechar o modal.
Estilizar o modal e o fundo com CSS para criar o efeito de sobreposição (background backdrop).
Embora funcional, essa abordagem exigia um esforço considerável para garantir acessibilidade e compatibilidade entre navegadores.

O Elemento `<dialog>` e Manipulação com JavaScript

O elemento <dialog>, introduzido no HTML5, facilitou a criação de modais ao oferecer um método nativo para lidar com modais. Seus principais recursos incluem:

Métodos embutidos como showModal(), show() e close().
O pseudo-elemento ::backdrop para estilizar o fundo da sobreposição.
Gerenciamento automático de foco quando o modal é aberto ou fechado. No entanto, as pessoas desenvolvedoras ainda precisavam usar JavaScript para manipular o atributo open e gerenciar interações, como abrir e fechar o modal. Por exemplo:

<button>Abrir modal</button>
<dialog id="modal">
  <button aria-label="Fechar modal">x</button>
  <p>Conteúdo do modal</p>
</dialog>

const modal = document.getElementById('modal');
document.querySelector('button').addEventListener('click', () => modal.showModal());
modal.querySelector('button').addEventListener('click', () => modal.close());

Embora essa abordagem tenha simplificado o processo, ainda é necessário escrever código JavaScript para garantir a funcionalidade básica.

Usando botões com os atributos experimentais command e commandfor

Os atributos command e commandfor levam o controle de modais à uma abordagem mais fluída e simples, permitindo interações declarativas. Esses atributos permitem que botões controlem diretamente elementos como dialog ou popover sem a necessidade de JavaScript adicional. Veja um exemplo:

<button command="show-modal" commandfor="modal">Abrir Modal</button>
<dialog id="modal">
  <p>Este é um modal.</p>
  <button command="close" commandfor="modal">Fechar</button>
</dialog>

Como funciona:

command="show-modal": Abre o modal especificado no atributo commandfor.
command="close": Fecha o modal especificado no atributo commandfor.
commandfor="id": Necessário atrelar o id do modal no atributo commandfor para que os "command" funcionem.

Levando em consideração a escrita semântica de HTML, o elemento dialog aceita conteúdos de fluxo

Melhorando a acessibilidade dos botões e dialog com atributos ARIA

<main>
  <button type="button" command="show-modal" commandfor="modalDialog" aria-label="abrir modal" aria-controls="modalDialog" aria-haspopup="dialog">
    Abrir modal
  </button>
</main>
<dialog id="modalDialog" aria-labelledby="modalTitle" aria-modal="true">
  <button commandfor="modalDialog" command="close" aria-label="Fechar modal">&#10006;</button>
  <h1 id="modalTitle">Modal</h1>
  <section aria-labelledby="contentTitle">
    <h2 id="contentTitle">Seção do modal</h2>
    <p>Lorem ipsum dolor sit amet.</p>
  </section>
</dialog>

aria-label: Define um rótulo acessível para o botão, que será lido por leitores de tela.
aria-controls: Indica que o botão controla ou está relacionado ao elemento com o id="modalDialog", que no caso é a <dialog>.
aria-haspopup="dialog": Indica que o botão abre um elemento de tipo dialog (modal). Isso informa leitores de tela que um diálogo será aberto ao interagir com esse botão.
aria-labelledby="modalTitle" (no com id="modalDialog"): Associa o modal ao título h1 com id="modalTitle", garantindo que leitores de tela leiam esse título como o nome do diálogo.

Nos casos em que um elemento interativo não tem um nome acessível, ou um nome acessível que não é preciso, e não há conteúdo visível no DOM que possa ser referenciado via aria-labelledby, o atributo aria-label pode ser usado para definir uma string que rotula o elemento interativo no qual está definido. Isso fornece ao elemento seu nome acessível. Mais sobre aria-labelledby

Atenção

Estes atributos ainda estão em fase experimental e podem sofrer alterações ao longo do desenvolvimento.
Por enquanto é possível reproduzir o exemplo nos seguintes navegadores:

Chrome/Edge: v135
Firefox Nightly
Safari TP
Chrome for Android: v135
WebView Android: v135

Você também pode checar a lista de compatibilidade toda na seção do elemento botão, no site da MDN. Button Element

Conclusão

A evolução da criação de modais — desde soluções personalizadas até o uso do elemento e, agora, atributos experimentais como command e commandfor — demonstra flexibilidade para um desenvolvimento web mais declarativo e acessível.

Ao adotar esses novos recursos, podemos criar modais com menos código e maior manutenibilidade.

Referências

aria-modal
button
dialog patterns
dialog w3schools
alert dialog
dialog MDN
Flow Content
aria-label
aria-controls
Gif feito por: https://dribbble.com/shots/2969595-Modal-UI-Animation

Projeção de Conteúdo em Angular: O Guia para ng-content e ngTemplateOutlet

Bruno Donatelli — Mon, 24 Feb 2025 13:00:00 +0000

Você já tentou adicionar um trecho de código HTML dentro de um componente Angular, mas o conteúdo não foi projetado como esperado? Isso pode parecer um desafio dentro do framework, principalmente quando se deseja criar componentes reutilizáveis. Felizmente, Angular oferece ferramentas poderosas para essa tarefa: ng-content e ngTemplateOutlet.

Antes de começar a leitura abaixo, eu gostaria que você entendesse os conceitos de ng-content, ng-template, ng-container e *ngTemplateOutlet nesse artigo da freeCodeCamp: Tudo o que você precisa saber sobre ng-template, ng-content, ng-container e *ngTemplateOutlet em Angular

O que é ng-content?

A diretiva ng-content permite a projeção de conteúdo dentro do componente, trabalhando de forma similar ao elemento HTML nativo slot, porém com algumas funcionalidades Angular.
Em suma, Essa diretiva funciona como um espaço reservado dentro de um componente, permitindo a inserção de conteúdo externo. Isso é particularmente útil quando se desenvolvem componentes que precisam ser altamente reutilizáveis e personalizados.

Exemplo básico de uso do ng-content

Vamos considerar um exemplo simples de um componente card que pode exibir conteúdo dinâmico:

card.component.ts

import { ChangeDetectionStrategy, Component } from '@angular/core';

@Component({
  selector: 'app-card',
  templateUrl: './card.component.html',
  styleUrl: './card.component.scss',
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class CardComponent {}

card.component.html

<article class="card">
  <header>
    <ng-content select="[title]"></ng-content>
  </header>
  <!-- body / content -->
  <section>
    <ng-content></ng-content>
  </section>
</article>

Neste exemplo, utilizamos a diretiva ng-content de duas maneiras:

Com o atributo select, para especificar qual parte do conteúdo projetado deve aparecer em diferentes seções do componente
Sem o atributo select, para projeção geral do componente.

A utilização do card fica desta forma:

app.parent.html

<app-card>
  <!-- ng-content select title attribute -->
  <h2 title>Lorem Ipsum</h2>
  <!-- ng-content general -->
  <div>
    <p>
      Lorem ipsum dolor sit amet consectetur, adipisicing elit. Voluptatum fuga
      reprehenderit adipisci expedita repellendus dolorem non laborum fugiat,
      voluptatem odit nihil quae rem laudantium. Quos deserunt numquam quae
      totam doloribus.
    </p>
  </div>
</app-card>

Com o componente card estruturado dessa forma, temos a flexibilidade de projetar conteúdos textuais, ou conteúdos com imagens - as possibilidades são infinitas!

Mas calma aí... isso ainda é muito estático, e eu procuro uma abordagem mais dinâmica. Tem jeito? TEM! Vamos para a próxima parte do artigo.

O que é ngTemplateOutlet?

Enquanto o ng-content é ótimo para a projeção de conteúdo estático, a diretiva ngTemplateOutlet oferece uma abordagem mais dinâmica, permitindo a projeção de conteúdo em tempo de execução.

Exemplo

Vamos adicionar uma mudança no nosso componente card, com um input de TemplateRef para podermos passar a projeção de conteúdo que queremos.
No template HTML, vamos remover todos os ng-content, e passar um ng-container que contém a diretiva de *ngTemplateOutlet, que vai receber o TemplateRef

<article class="card">
    <ng-container *ngTemplateOutlet="cardTemplateRef() ?? null"></ng-container>
</article>

import { CommonModule } from '@angular/common';
import { ChangeDetectionStrategy, Component, input, TemplateRef } from '@angular/core';

@Component({
  selector: 'app-card',
  standalone: true,
  imports: [CommonModule],
  templateUrl: './card.component.html',
  styleUrl: './card.component.scss',
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class CardOutletComponent {
  cardTemplateRef = input<TemplateRef<unknown>>();
}

Lembrando que precisamos adicionar o CommonModule para termos acesso ao *ngTemplateOutlet

E a utilização do nosso card com TemplateRef:

<app-card [cardTemplateRef]="textTemplate"></app-card-outlet>

<app-card [cardTemplateRef]="imageTemplate"></app-card-outlet>

<ng-template #textTemplate>
  <header>
    <h2>Lorem Ipsum</h2>
  </header>
  <section>
    <div>
      <p>
        Lorem, ipsum dolor sit amet consectetur adipisicing elit. Neque, fuga
        officiis ex ducimus, cupiditate, id culpa ipsa eligendi maiores autem
        quod architecto eum veniam expedita omnis. Vitae debitis quibusdam a?
      </p>
    </div>
  </section>
</ng-template>

<ng-template #imageTemplate>
  <header>
    <h2>Lorem Ipsum</h2>
  </header>
  <section>
    <img
      src="path/to/image"
      alt="my alt text IS IMPORTANT MAKE SURE YOU ARE ENHANCING A11Y IN YOUR PROJECT"
    />
    <p>
      Lorem ipsum, dolor sit amet consectetur adipisicing elit. Quia, tenetur
      recusandae? Quo minus iusto nihil explicabo assumenda recusandae magnam
      quia ipsum sint impedit, totam, nobis amet libero, dolorem harum cumque.
    </p>
  </section>
</ng-template>

Comparação

Embora ng-content e ngTemplateOutlet sejam usados para projeção de conteúdo, eles têm diferentes casos de uso e benefícios:

ng-content: ideal para conteúdo estático. Permite definir pontos específicos no componente para a inserção de conteúdo externo, sendo excelente para componentes de layout (como o nosso card).
ngTemplateOutlet: Melhor para projeção de conteúdo dinâmico. Permite a inserção de templates diferentes com base em condições lógicas ou variável de referência no ng-template. Oferece maior flexibilidade e controle em tempo de execução.

Conclusão

Entender e usar ng-content e ngTemplateOutlet pode aumentar significativamente a reutilização e a flexibilidade dos seus componentes Angular.
Ao entender e dominar essas funcionalidades, você estará mais bem equipado para criar aplicações Angular altamente dinâmicas e personalizáveis.

Referências

Migrando subscribe Callbacks para subscribe arguments no RxJS

Bruno Donatelli — Thu, 09 Jan 2025 11:00:00 +0000

Você, pessoa que usa rxjs no seu dia a dia, já deve ter reparado que desde a versão 6.4. o RxJS colocou uma anotação de deprecated no método subscribe:

@deprecated — Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments

A justificativa é que usar callbacks separadas gera uma pior leitura do método. Assim, é preferível usar argumentos subscribe fazendo a desestruturação das propriedades que o método retorna.

Para entendermos melhor na prática, vamos a um exemplo rápido:

data.js

import { Observable } from "rxjs";

/**
 * Cria um observable que emite valores numéricos de 1 até 5, e então se finaliza.
 *
 * @returns {Observable<number>} Um observable que emite números de 1 até 5 em sequência.
 */
export const data = () => {
  return new Observable((observer) => {
    for (let i = 1; i <= 5; i++) {
      observer.next(i);
    }

    observer.complete();
  });
};

/**
 * Cria um observable que emite um error imediatamente
 *
 * @returns {Observable<never>} Um observable que emite um erro.
 */
export const dataWithError = () => {
  return new Observable((observer) => {
    observer.error("Aconteceu um erro!");
  });
};

Este será o nosso arquivo base. O primeiro método emite, em sequência, números de 1 a 5 com o método .next(); assim que o loop é finalizado, o observable é completado com o método .complete();.

O segundo método cria um observable que emite um erro imediatamente

PS: quando o método .error() é chamado, o observable para de emitir valores e não pode continuar emitindo valores via .next() ou ser completado com o .complete().

A partir das informações acima, passamos ao ponto principal.

Usarei como primeiro exemplo a maneira que atualmente está depreciada; em seguida, vou mostrar como utilizar o argument observable.

import { data, dataWithError } from "./data.js";

data().subscribe(
  (value) => console.log(value),
  (error) => {},
  () => {
    console.log("completou");
  }
);

dataWithError().subscribe(
  () => {},
  (error) => {
    console.error({ error });
  }
);

Observe que, por ser um exemplo, é algo mais visível, mas que, ao mesmo tempo, é necessário saber a ordem de cada callback (next, error e complete).

Posteriormente, vamos analisar a forma de utilização dos argument observables:

import { data, dataWithError } from "./data.js";

data().subscribe({
  next: (data) => console.log(data),
  complete: () => console.log("completou"),
});

dataWithError()
    .subscribe({ error: (error) => console.error({ error })
    });

A partir deste ponto com os argument observables, temos uma leitura mais limpa do que estamos usando dentro do método subscribe. Dessa forma, não é necessário declarar callbacks ou argumentos que não serão utilizados.

É uma migração fácil de ser realizada, e deixará seu código sem mensagens de depreciação dessa API.

Entendendo o ControlValueAccessor

Bruno Donatelli — Sat, 20 Apr 2024 04:10:36 +0000

Introdução ao ControlValueAccessor

código do projeto
Formulários dentro do Angular podem ser tratados utilizando duas abordagens: Reactive forms ou Template Driven forms. Essas abordagens nos permitem capturar entrada de dados, validar campos que possam estar inválidos, e são baseados em um objeto que será enviado ao servidor.

Pensando, tanto em usar reactive forms ou template driven: quando componentizamos muitos elementos, podemos acabar sentindo uma dificuldade em: "como podemos criar um componente apartado de um formulário, e continuar tendo a referência do dado digitado pelo usuário, via bind, em nosso [(ngModel)] ou no formControlName"?

aka: como crio um control personalizado para o meu formulário

É aí que entra o PODEROSO ControlValueAccessor!

O que é o ControlValueAccessor

MAS O QUE É ESSE ControlValueAccessor???

O ControlValueAccessor é uma interface que atua como uma ponte entre elementos do DOM e a API de formulário do Angular. Implementando essa interface em um componente, podemos manipular valores através das propriedades dispostas pelo próprio FormsModule: ngModel; Ou no caso de um formulário reativo, o formControlName.

Os métodos obrigatórios a serem implementados dentro da classe são os seguintes:

interface ControlValueAccessor {
writeValue(obj: any): void
registerOnChange(fn: any): void
registerOnTouched(fn: any): void
setDisabledState(isDisabled: boolean)?: void
}

O writeValue escreve um novo valor ao elemento
O registerOnChange registra uma função callback que é chamada quando o valor do nosso controle muda na tela.
O registerOnTouched serve para atualizar o estado do formulário para touched (ou blurred). Então, assim que o usuário interage com nosso elemento no controle personalizado, podemos chamar a função salva no callback, para informar ao Angular que o controle recebeu uma alteração.
O setDisabledState vai ser chamado para avisar a API de formulários, que o controle sofreu alteração no estado de desabilitado (true para false, ou false para true).

Agora que entendemos como funciona a interface ControlValueAccessor, e quais métodos ela implementa, vamos ao nosso código.

Formulário de "Contact us"

Vamos criar um formulário básico, sobre "Contact us". É um formulário simples, onde teremos dois inputs e um textarea:

Digite seu nome;
Digite seu e-mail;
Digite uma mensagem;

O formulário será feito com template-driven e com Reactive forms.

Template Driven

// template-driven-form HTML

<form (ngSubmit)="submit()">
  <fieldset class="">
    <legend>Fale conosco</legend>
    <div class="data">
      <label for="yourName">Digite seu nome</label>
      <input
        type="text"
        id="yourName"
        name="yourName"
        [(ngModel)]="contactUs.name"
        placeholder="DevTo da Silva"
      />
    </div>
    <div class="data">
      <label for="yourEmail">Digite seu email</label>
      <input
        type="email"
        id="yourEmail"
        name="yourEmail"
        [(ngModel)]="contactUs.email"
        placeholder="example@mail.com"
      />
    </div>

    <div class="data">
      <label for="message">Deixe sua mensagem</label>
      <textarea
        name="message"
        id="message"
        cols="30"
        rows="10"
        [(ngModel)]="contactUs.message"
      ></textarea>
    </div>
  </fieldset>

  <button
    type="submit"
    aria-label="Enviar o motivo do contato"
    aria-describedby="sendContactUs"
  >
    Enviar
  </button>
  <span [hidden]="true" id="sendContactUs"
    >Ao clicar no botão, você envia os dados que foram preenchidos. Em breve retornaremos o contato.</span>
</form>

<pre>{{contactUs | json}}</pre>

e o nosso component .ts

// template-driven-form HTML

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { JsonPipe } from '@angular/common';

type ContactUsTemplateDriven = {
  name: string;
  email: string;
  message: string;
};

@Component({
  selector: 'app-template-driven-form-contactus',
  standalone: true,
  imports: [FormsModule, JsonPipe],
  templateUrl: './template-driven-form-contactus.component.html',
  styleUrl: './template-driven-form-contactus.component.scss',
})
export class TemplateDrivenFormContactusComponent {
  protected contactUs: ContactUsTemplateDriven = {
    name: '',
    email: '',
    message: '',
  };

  protected submit(): void {
    console.log('enviou', this.contactUs);
  }
}

Formulário Reativo

// reactive-forms-contactus.component

<form (ngSubmit)="submit()" [formGroup]="contactUsForm">
  <fieldset class="">
    <legend>Fale conosco</legend>
    <div class="data">
      <label for="name">Digite seu nome</label>
      <input
        type="text"
        id="name"
        name="name"
        formControlName="name"
        placeholder="DevTo da Silva"
      />
    </div>
    <div class="data">
      <label for="email">Digite seu email</label>
      <input
        type="email"
        id="email"
        name="email"
        formControlName="email"
        placeholder="example@mail.com"
      />
    </div>

    <div class="data">
      <label for="message">Deixe sua mensagem</label>
      <textarea name="message" id="message" cols="30" rows="10" formControlName="message"></textarea>
    </div>
  </fieldset>

  <button
    type="submit"
    aria-label="Enviar o motivo do contato"
    aria-describedby="sendContactUs"
  >
    Enviar
  </button>
  <span [hidden]="true" id="sendContactUs">
    Ao clicar no botão, você envia os dados que foram preenchidos. E assim que
    pudermos, retornaremos o contato
  </span>
</form>

<pre>{{contactUsForm.getRawValue() | json}}</pre>

// reactive-forms-contactus.component

type ContactUsReactiveForm = {
  name: FormControl<string>;
  email: FormControl<string>;
  message: FormControl<string>;
};

@Component({
  selector: 'app-reactive-form-contactus',
  standalone: true,
  imports: [FormsModule, ReactiveFormsModule, JsonPipe],
  templateUrl: './reactive-form-contactus.component.html',
  styleUrl: './reactive-form-contactus.component.scss',
})
export class ReactiveFormContactusComponent {
  private readonly formBuilder = inject(NonNullableFormBuilder);

  protected contactUsForm!: FormGroup<ContactUsReactiveForm>;

  constructor() {
    this.contactUsForm = this.formBuilder.group<ContactUsReactiveForm>({
      name: this.formBuilder.control({ value: '', disabled: false }),
      email: this.formBuilder.control(
        { value: '', disabled: false },
        { validators: [Validators.email] }
      ),
      message: this.formBuilder.control({ value: '', disabled: false }),
    });
  }

  protected submit() {
    console.log('enviou', this.contactUsForm.getRawValue());
  }
}

Agora que finalizamos nossos formulários, vamos criar nossos controles personalizados.

Iremos criar três componentes, que serão os dois inputs e o textarea.

Criando controles personalizados com ControlValueAccessor

Vamos criar um novo componente, utilizando o comando do angular-cli:

$ ng g c components/contact-us-name-input

Dentro do nosso componente, iremos implementar a interface ControlValueAccessor e seus respectivos métodos. Porém, só implementar a interface ControlValueAccessor não é o suficiente.
Precisamos também, registrar dentro dos providers do nosso component, o token NG_VALUE_ACCESSOR. Esse token é responsável pela integração do component, com a API de formulários do Angular.

Junto do NG_VALUE_ACCESSOR, também colocaremos o forwardRef. O uso do forwardRef se faz necessário porque estamos fazendo referência ao componente que estamos criando (nesse caso, para o "ContactUsNameInputComponent". Porém, faremos para todos os nossos controles personalizados.)

@Component({
  selector: 'app-contact-us-name-input',
  standalone: true,
  imports: [],
  templateUrl: './contact-us-name-input.component.html',
  styleUrl: './contact-us-name-input.component.scss',
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => ContactUsNameInputComponent),
      multi: true,
    },
  ],
})
export class ContactUsNameInputComponent implements ControlValueAccessor {
  @Input() public contactName = '';

  protected value = '';
  protected disabled = false;

  protected onChanged!: (value: string) => void;
  protected onTouched!: () => void;

  writeValue(value: string): void {
    this.value = value;
  }
  registerOnChange(fn: (value: string) => void): void {
    this.onChanged = fn;
  }
  registerOnTouched(fn: () => void): void {
    this.onTouched = fn;
  }

  setDisabledState?(isDisabled: boolean): void {
    this.disabled = isDisabled;
  }
}

<label for="name">Digite seu nome</label>
<input
  type="text"
  id="name"
  placeholder="DevTo da Silva"
  [value]="value"
  (input)="onChanged($any($event.target)?.value)"
/>

Vamos analisar o nosso código:

Registramos dentro dos providers do nosso component, o NG_VALUE_ACCESSOR e fizemos referência ao nosso componente.

Nota: Sempre precisamos fazer referência, no forwardRef, à classe que estamos trabalhando.

Implementamos os métodos obrigatórios da interface ControlValueAccessor, tipamos os parâmetros dos métodos da interface, e atribuímos os valores aos atributos do componente.
No nosso template html, colocamos um evento onInput, chamado o callback onChanged para escutar as mudanças que ocorrem no nosso input, e informar ao nosso formulário que as mudanças ocorreram

Tendo criado nosso primeiro componente, vamos implementá-lo em nossos componentes de formulário da seguinte forma:

Substituiremos a parte do label e input de nome, pelo nosso componente:

<form (ngSubmit)="submit()">
  <fieldset class="">
    <legend>Fale conosco</legend>
    <div class="data">
// essa parte aqui
// pelo nosso novo componente
     <app-contact-us-name-input
        name="yourName"
        [contactName]="contactUs.name"
        [(ngModel)]="contactUs.name"
        [ngModelOptions]="{ standalone: true }"
      />
    </div>
... rest of html

Como estamos trabalhando com standalone components, precisamos informar à instância do NgModel que o nosso control também é standalone.

Faremos o mesmo trabalho dentro do input de email, e o textarea, registrando o NG_VALUE_ACCESSOR, e fazendo uso do forwardRef para referência dos nossos componentes. (para não ficar muito extenso e repetitivo, o código está no meu github, e você poder ver tudo que foi feito nesse link ao lado: ContactUs - Github.

Nosso formulário, agora com nossos controles personalizados integrados, ficará dessa forma:

<form (ngSubmit)="submit()">
  <fieldset class="">
    <legend>Fale conosco</legend>
    <div class="data">
      <app-contact-us-name-input
        name="yourName"
        [contactName]="contactUs.name"
        [(ngModel)]="contactUs.name"
        [ngModelOptions]="{ standalone: true }"
      />
    </div>
    <div class="data">
      <app-contact-us-email-input
        name="email"
        [contactEmail]="contactUs.email"
        [(ngModel)]="contactUs.email"
        [ngModelOptions]="{ standalone: true }"
      />
    </div>

    <div class="data">
      <app-contact-us-message-text
        [(ngModel)]="contactUs.message"
        [ngModelOptions]="{ standalone: true }"
        [contactText]="contactUs.message"
      />
    </div>
  </fieldset>

  <button
    type="submit"
    aria-label="Enviar o motivo do contato"
    aria-describedby="sendContactUs"
  >
    Enviar
  </button>
  <span [hidden]="true" id="sendContactUs"
    >Ao clicar no botão, você envia os dados que foram preenchidos. E assim que
    pudermos, retornaremos o contato</span
  >
</form>

<pre>{{ contactUs | json }}</pre>

e nosso formulário reativo:

<form (ngSubmit)="submit()" [formGroup]="contactUsForm">
  <fieldset class="">
    <legend>Fale conosco</legend>
    <div class="data">
      <app-contact-us-name-input formControlName="name" />
    </div>
    <div class="data">
      <app-contact-us-email-input formControlName="email" />
    </div>
    <div class="data">
      <app-contact-us-message-text formControlName="message" />
    </div>
  </fieldset>

  <button
    type="submit"
    aria-label="Enviar o motivo do contato"
    aria-describedby="sendContactUs"
  >
    Enviar
  </button>
  <span [hidden]="true" id="sendContactUs">
    Ao clicar no botão, você envia os dados que foram preenchidos. E assim que
    pudermos, retornaremos o contato
  </span>
</form>

<pre>{{ contactUsForm.getRawValue() | json }}</pre>

Conclusão

Conseguimos entender como criar controles customizados, para serem reutilizados dentro de nossos formulários, independente da abordagem que foi utilizada. Também foi mostrado como usamos a interface ControlValueAccessor, entendemos também o uso do token NG_VALUE_ACCESSOR, e como fazer a referência do nosso componente enquanto ele não está definido, utilizando forwardRef.

Desenvolvendo Formulários Reativos e Acessíveis no Angular: Um Guia Passo a Passo

Bruno Donatelli — Fri, 01 Mar 2024 16:00:54 +0000

Glossário

Introdução
- O que é um formulário HTML;
- Relevância da acessibilidade dentro de um formulário;
Formulários tradicionais
- Como os formulários são tradicionalmente criados em aplicações web.
- Exemplo de código HTML para um formulário simples.
Formulários Reativos em Angular
- Criação de um formulário reativo no Angular.
- Implementando nosso formulário, em um componente Angular.
Acessibilidade em formulários
Demonstração de técnicas para tornar os formulários mais acessíveis
Conclusão

Observações:

A versão utilizada do Angular, foi a versão 17.2

Para versões versões anteriores, terá o código condizente no repositório deste artigo

Introdução

O que é um formulário HTML?

Formulários são um dos pontos de interação entre uma pessoa e uma aplicação web. No geral, formulários são a principal interface para a coleta de dados, login, inscrições e interações personalizadas.

Um formulário pode possuir campos de texto (linha única ou várias linhas), caixas de seleção, botões, checkboxes ou radio buttons. A maior parte do tempo, esses elementos são combinados com uma legenda que descreve seu objetivo.

Relevância da acessibilidade dentro de um formulário

Quando tornamos os formulários acessíveis, promovemos a igualdade de acesso à informação e serviços online para pessoas com diferentes habilidades e necessidades. Isso é especialmente importante considerando a diversidade de pessoas que utilizam a web, incluindo as com deficiências visuais, auditivas, motoras ou cognitivas.

Ao priorizarmos a acessibilidade na criação de formulários, não estamos só cumprindo as diretrizes e regulamentações internacionais, como as diretrizes da W3C e WCAG, mas também estamos promovendo uma experiência mais inclusiva e acessível para todas as pessoas na web.

Formulários tradicionais

Como os formulários são tradicionalmente criados em aplicações web.

Os formulários geralmente são construídos com tags, como:

form

input

textarea

button

Em suma:

o form é usado para agrupar os campos de entrada (input, textarea), e definir o método de envio de dados.
input e textarea são utilizados para coletar a informação ou as informações digitadas por uma pessoa.

Além disso, as pessoas desenvolvedoras podem adicionar atributos como placeholder, para exibir um texto de exemplo, quando o input ou textarea está vazio, mostrando à pessoa usuária da aplicação como ela deve inserir uma informação dentro desse campo. Ou seja: fornecer orientações visuais.

<input type="text" placeholder="algum exemplo aqui" />

O envio do formulário geralmente é tratado por meio de um botão com o tipo submit:

<button type="submit">Enviar formulário</button>

que, quando clicado, submete os dados para processamento pelo servidor.

Exemplo de código HTML para um formulário simples.

Vamos começar nosso exemplo com um formulário básico, que contém quatro campos de entrada e um botão de enviar os dados.

<form>
  <div>
    <input type="text" placeholder="informe seu nome" />
  </div>
  <div>
    <input type="text" placeholder="informe seu email" />
  </div>
  <div>
    <input type="text" placeholder="informe o motivo do contato" />
  </div>
  <div>
    <textarea
      name="mensagem"
      id="mensagem"
      cols="30"
      rows="5"
      placeholder="digite sua mensagem"
    ></textarea>
  </div>

  <button type="submit">Nos envie uma mensagem</button>
</form>

Analisando esse formulário, vemos que os inputs e textarea possuem placeholder, e o botão é do tipo submit, o qual vai fazer o envio dos dados desse formulário.
Tendo esse código HTML pronto, vamos integrá-lo em um componente Angular, utilizando Formulários reativos

Inicializando um projeto minimalista em Angular

Tenha instalado em sua máquina, o NodeJS ou bun (Apenas versões a partir do 17 do Angular suportam o bun)

Instalando o angular cli:

$ npm i -g @angular/cli@latest

Criando o projeto minimalista

$ ng new <NOME_DO_PROJETO> --minimal

Tendo isso, podemos começar a criar nosso formulário reativo!

Formulários Reativos em Angular

Formulários reativos oferecem uma abordagem orientada por modelos, lidando com valores que mudam com o tempo.
O modelo é criado na classe do componente, e utlizado via bind e propriedades dentro dos templates.

Necessário importar o FormsModule e o ReactiveFormsModule dentro do seu component.ts ou em seu módulo

Criação de um formulário reativo no Angular

Para criarmos um formulário reativo, precisamos utilizar as classes FormGroup e FormControl, ou então, utilizarmos o FormBuilder para as instâncias de criação de grupo e controles do formulário. Nesse primeiro exemplo, usaremos FormGroup e FormControl em forma de instância de classe, mas o formulário que criamos acima, vai ser feito utilizando FormBuilder.

exemplo retirado do guia de formulários reativos do site do Angular
Guia aqui

form.component.ts

import { Component } from '@angular/core';
import { FormGroup, FormControl } from '@angular/forms';

@Component({
  standalone: true,
  selector: 'app-profile-editor',
  templateUrl: './profile-editor.component.html',
  styleUrls: ['./profile-editor.component.css'],
})
export class ProfileEditorComponent {
  profileForm = new FormGroup({
    firstName: new FormControl(''),
    lastName: new FormControl(''),
  });
}

form.component.html

<form [formGroup]="profileForm">

  <label for="first-name">First Name: </label>
  <input id="first-name" type="text" formControlName="firstName">

  <label for="last-name">Last Name: </label>
  <input id="last-name" type="text" formControlName="lastName">

</form>

Explicação: O atributo profileForm recebe uma instância da class FormGroup, e para cada propriedade do objeto sendo criado dentro desse grupo, é passado uma instância de FormControl, com inicialização de um string vazio.

No template HTML, adicionamos o atributo formGroup na tag form, com property-bind, adicionando a propriedade do nosso component.ts, profileForm, para relacionarmos o formulário do template HTML, com o FormGroup criado dentro do componente.

Implementando nosso formulário, em um componente Angular

app.component.html

<form [formGroup]="contatoForm" (ngSubmit)="submitForm()">
  <div>
    <input type="text" formControlName="nome" />
  </div>
  <div>
    <label for=""></label>
    <input
      type="text"
      formControlName="email"
      required
      placeholder="exemplo@mail.com"
    />
  </div>
  <div>
    <input type="text" formControlName="assunto" />
  </div>
  <div>
    <textarea
      rows="5"
      cols="21"
      formControlName="mensagem"
      #textarea
      maxlength="300"
    >
    </textarea>
  </div>
  <button
    type="button"
  >
    Nos envie uma mensagem
  </button>
</form>

app.component.ts

import { CommonModule } from '@angular/common';
import { Component, inject } from '@angular/core';
import {
  FormGroup,
  FormsModule,
  NonNullableFormBuilder,
  ReactiveFormsModule,
  Validators,
} from '@angular/forms';
import { ContatoFormType } from './contatoForm';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, FormsModule, ReactiveFormsModule],
  templateUrl: './app.component.html',
  styles: [],
})
export class AppComponent {
  private readonly formBuilder: NonNullableFormBuilder = inject(
    NonNullableFormBuilder
  ); // INJEÇÃO DE DEPENDÊNCIA

  public contatoForm!: FormGroup<ContatoFormType>;

  constructor() {
    this.contatoForm = this.formBuilder.group({
      nome: this.formBuilder.control(
        { value: '', disabled: false },
        {
          validators: [Validators.required],
        }
      ),
      email: this.formBuilder.control(
        { value: '', disabled: false },
        {
          validators: [Validators.required, Validators.email],
        }
      ),
      assunto: this.formBuilder.control(
        {
          value: '',
          disabled: false,
        },
        { validators: [Validators.required] }
      ),
      mensagem: this.formBuilder.control(
        { value: '', disabled: false },
        { validators: [Validators.maxLength(300)] }
      ),
    });
  }

  public submitForm(): void {
    if (this.contatoForm.valid) {
      const contato = this.contatoForm.getRawValue();

      console.log({ contato });
    }
  }
}

No nosso template HTML, colocamos os atributos que o formsModule disponibiliza dentro dos inputs, form e textarea. E no nosso component, fizemos a injeção de dependência do NonNullableFormBuilder (é um recurso disponível desde o Angular 14), onde nosso formulário não aceitará valores nulos.

Também criamos nosso FormGroup estritamente tipado (também é um recurso disponível desde o Angular 14, onde podemos tipar nossos formulários). No nosso caso:

import { FormControl } from '@angular/forms';

export type ContatoFormType = {
  nome: FormControl<string>;
  email: FormControl<string>;
  assunto: FormControl<string>;
  mensagem: FormControl<string>;
};

e se esquecermos de colocar alguma propriedade criada em nosso type, a construção do formulário mostrará um erro:

Acessibilidade em formulários

A acessibilidade nos formulários é crucial para garantir que todos os usuários, independentemente de suas habilidades ou limitações, possam interagir com eficácia e eficiência. Ao seguir as diretrizes da World Wide Web Consortium (W3C) e as diretrizes de acessibilidade para conteúdo da web (WCAG), as pessoas desenvolvedoras podem criar formulários que são acessíveis a uma ampla variedade de pessoas.

A W3C fornece padrões e recomendações para a criação de conteúdo acessível na web, enquanto a WCAG oferece diretrizes específicas para garantir a acessibilidade de conteúdos web para pessoas com deficiência. Ao implementar práticas recomendadas de acessibilidade nos formulários, os desenvolvedores podem garantir que os usuários tenham uma experiência inclusiva e equitativa ao preencher e enviar informações.

Demonstração de técnicas para tornar os formulários mais acessíveis

Dentro do nosso template HTML, podemos ver que o campo de entrada para email, está com o type="text". Podemos mudar isso para type="email", assim, validando auto completar em dispositivos móveis, e também para pessoas que fazem uso de dispositivos assistivos.

Outra coisa que pode ser percebida, é que nosso inputs não possuem um texto informativo sobre o que ele significa, então podemos atrelar um label a ele.
Para atrelarmos um label ao input, precisamos colocar um id como propriedade do input, e então, dentro da tag label, no atributo for, colocarmos o id do input. ex:

    <label for="email">Digite seu email</label>
    <input
      type="email"
      formControlName="email"
      required
      placeholder="exemplo@mail.com"
      id="email"
    />

Podemos também, adicionar erros de validação dos nossos campos, utilizando o formgroup.controls.seuControl.errors, junto do touched e dirty, que são propriedades de validação exportadas pelo FormsModule
(Você pode ver mais sobre touched e dirty AQUI)

<div>
    <label for="email">Digite seu email</label>
    <input
      type="email"
      formControlName="email"
      required
      aria-required="true"
      aria-errormessage="emailInvalido"
      placeholder="exemplo@mail.com"
      aria-placeholder="exemplo de entrada: meuemail@mail.com"
      id="email"
      name="email"
    />
    @if (contatoForm.controls.email.errors && contatoForm.touched &&
    contatoForm.dirty) {
    <span id="emailInvalido" aria-live="assertive" role="alert"
      >Email inválido</span
    >
    }
  </div>

Nesse caso, fizemos uso do aria-live="assertive" para, toda vez que o input estiver com um erro, o leitor de tela vai avisar à pessoa que o email digitado está invalido.
Mais sobre aria-live

Podemos também, adicionar validações de desabilitar/habilitar o botão do formulário, caso ele esteja com status INVALID.
Também, adicionaremos o aria-label para as pessoas que usam tecnologias assistivas, possam saber sobre o que se trata esse botão.

  <button
    type="button"
    [disabled]="contatoForm.invalid"
    [ariaDisabled]="contatoForm.invalid"
    aria-label="Enviar sua mensagem ao nosso time"
  >
  Nos envie uma mensagem
  </button>

O restante do código você pode conferir no meu repositório github

Conclusão

Ao longo desse artigo, exploramos como funcionam formulários em aplicações web, e destacamos como a acessibilidade desempenha um papel fundamental na garantia de inclusão de pessoas. Criamos o formulário utilizando HTML puro, depois passamos ele para um componente Angular, adicionamos atributos necessários, módulos de Forms do próprio Angular, implantamos um formulário reativo que não aceita valores nulos, e adicionamos atributos ARIA-* dentro dos nossos inputs, a fim de melhorar a acessibilidade do formulário, tanto quanto outras tags que também nos auxiliaram a sinalizar melhor os campos de entrada.

É crucial que estejamos conscientes da importância da acessibilidade, e nos comprometermos a implementar práticas de design inclusivas em nossos projetos.

Obrigado!

Aprimorando acessibilidade em botões no HTML

Bruno Donatelli — Tue, 27 Feb 2024 14:31:07 +0000

A acessibilidade na web se refere à prática de tornar sites e aplicativos acessíveis para todas as pessoas. Isso ajuda a garantir inclusão digital, para que todas as pessoas possam perceber, entender, navegar e interagir com o conteúdo da web de forma eficaz.

ARIA (Accessible Rich Internet Applications)

A WAI-ARIA é uma especificação do W3C que fornece atributos adicionais para tornar o conteúdo da web mais acessível para pessoas com deficiência, permitindo uma melhor comunicação com dispositivos assistivos (como leitores de tela/talkback).
No HTML, podemos usar propriedades ARIA-* dos elementos (tags) para melhorar a acessibilidade do elemento.

WCAG (Web Content Accessibility Guidelines) e sua relação com WAI-ARIA

As diretrizes da WCAG são um conjunto de diretrizes desenvolvida pela W3C para garantir que o conteúdo da web seja acessível para todos, incluindo pessoas com deficiência.

As Diretrizes de Acessibilidade para Conteúdo da Web (WCAG) oferecem uma estrutura técnica e diretrizes claras para tornar o conteúdo online mais acessível em termos de percepção, operação e compreensão. Essas diretrizes são essenciais para garantir que todos os usuários, incluindo aqueles com deficiências, possam interagir de forma eficaz com o conteúdo da web.

A WAI-ARIA complementa as diretrizes da WCAG, fornecendo atributos adicionais que melhoram a acessibilidade para usuários de tecnologias assistivas. Ao integrar adequadamente a WAI-ARIA com as diretrizes da WCAG, os desenvolvedores têm a capacidade de criar interfaces web mais dinâmicas e interativas, mantendo a acessibilidade para todos os usuários.

"As diretrizes da WCAG podem exigir que todos os elementos interativos, como botões, sejam acessíveis através do teclado. Nesse caso, o uso apropriado de atributos da WAI-ARIA, como role="button", aria-label, aria-disabled (caso o botão seja desativado), é fundamental para atender a essa exigência e garantir que os usuários possam navegar e interagir de forma eficiente."

Além disso, a WCAG estabelece critérios de sucesso que podem ser alcançados através da implementação adequada de técnicas de acessibilidade, incluindo o uso de WAI-ARIA. Ao seguir as diretrizes da WCAG e incorporar as práticas recomendadas da WAI-ARIA, os desenvolvedores têm a capacidade de criar experiências web acessíveis e inclusivas para todos os usuários, independentemente de suas habilidades ou limitações.

Exemplos

Vamos seguir um passo a passo, melhorando a acessibilidade de um botão de enviar formulário.
ps: apenas usei NVDA como leitor de tela, então o que for escrito nesse artigo, foi com base no que vivenciei com a ferramenta.

<button type="submit">Enviar formulário</button>

Por padrão, o elemento "button" é um elemento focável (possui o comportamento do tabindex="0")
tabindex

Quando uma pessoa usuária de tecnologias assistivas (vou usar o NVDA como exemplo) faz a navegação via tab até chegar nesse elemento "button", a tecnologia não vai conseguir ler o que está escrito dentro do botão. Sem o uso do atributo aria-label, provavelmente o leitor de tela vai ler o botão como: "Botão clicável".

<button type="submit" aria-label="Enviar formulário">Enviar formulário</button>

A partir desse momento, quando o foco da navegação via teclado chegar no "button", a tecnologia assistiva vai ler o botão como "Botão clicável Enviar Formulário".

aria-label

Aumenta a compreensão para usuários de tecnologias assistivas: Para usuários que dependem de leitores de tela, o atributo aria-label fornece uma descrição auditiva clara e concisa da função do elemento. Isso ajuda as pessoas usuárias a entenderem o propósito do elemento, mesmo quando o texto visível não é suficientemente descritivo.
Melhora a usabilidade para pessoas com deficiência visual: Ao fornecer uma descrição textual adicional através do aria-label, as pessoas cegas ou com baixa visão podem identificar e entender os elementos interativos com mais facilidade, facilitando a navegação e interação na web.
Garante consistência na experiência do usuário: O uso consistente de aria-label em elementos sem texto visível, como ícones ou botões com apenas ícones, ajuda a manter a consistência na experiência da pessoa usuária, independentemente de suas habilidades ou tecnologias assistivas utilizadas.
Ajuda a atender aos critérios de sucesso do WCAG: O WCAG define critérios de sucesso para garantir a acessibilidade na web. O uso apropriado de aria-label pode ajudar os desenvolvedores a atender a esses critérios, especialmente aqueles relacionados à percepção e compreensão do conteúdo.

Em resumo, ao usar aria-label, os desenvolvedores podem melhorar significativamente a acessibilidade dos elementos na web, garantindo que todos as pessoas usuárias, independentemente de suas capacidades, possam entender e interagir com o conteúdo de forma eficaz.

Conclusão

A acessibilidade na web é fundamental para garantir que todas as pessoas usuárias, independentemente de suas capacidades ou deficiências, possam perceber, entender, navegar e interagir efetivamente com o conteúdo online. A implementação de padrões como WAI-ARIA e WCAG desempenha um papel crucial nesse processo, oferecendo diretrizes e recursos que capacitam os desenvolvedores a criar experiências web mais inclusivas. Ao integrar adequadamente atributos como aria-label, as pessoas desenvolvedoras podem melhorar significativamente a acessibilidade dos elementos na web, contribuindo para uma experiência online mais acessível.

Forem: Bruno Donatelli

Angular Forms Signal: O que as documentações não te falam

Uma Jornada de Transformação: Do Tradicional ao Moderno

Introdução

Índice de Navegação

Seções Principais

O Projeto: Sistema de Reserva de Voos

Arquitetura

As Etapas do Formulário

Step 1: Detalhes do Voo (Flight Details)

Step 2: Detalhes dos Passageiros (Passenger Details)

Step 3: Serviços (Services)

Step 4: Pagamento (Payment)

Reactive Forms: A Abordagem Tradicional

Como Reactive Forms Lidam com Formulários

Estrutura do Formulário Principal

Validadores Customizados

Gerenciamento de FormArray Dinâmico

Sub-formulários Dinâmicos de Pagamento

Tratamento de Erros no Template (Reactive Forms)

Template de Detalhes de Passageiros

Lógica de Validação no Component

Problemas e Limitações dos Reactive Forms

Forms/Signal: A Nova Era

O Que É Signal Forms?

O Que Signal Forms Resolve?

1. Eliminação do Boilerplate

2. Modelo como Fonte de Verdade

3. Validação Centralizada e Declarativa

4. Reatividade Automática com Signals

Migração: aplicando Signal Forms passo a passo

Passo 1: Converter FormGroups em Modelos de Domínio

Passo 2: Substituir FormBuilder por Signal + Form

Passo 3: Migrar Validação para Schema

Passo 4: Migrar FormArray para Array no Modelo

Passo 5: Atualizar Templates

Tratamento de Erros com Signal Forms

Erros Nativos no Template

Estrutura de Erros

Exibição de Erros no Template

Atributos ARIA Dinâmicos

Componente de Erro Reutilizável

Erros Customizados com Validadores

Casos de Uso

Integração com APIs Externas (ViaCEP)

Formulários Condicionais (Nested Dynamic Forms)

Computed Values e Derived State

Tabela Comparativa: Reactive Forms vs Signal Forms

Conclusão

Principais Benefícios Observados

Desafios e Considerações

Reflexões Finais

Referências

Conhecendo as novidades do Angular 21

Como migro de versão?

HttpClient habilitado por padrão

Vitest

Tailwind

Signals Form

Zoneless

Conclusão

Simplifique modais com os atributos experimentais "command" e "commandfor"

O que é um modal

Como eram criados os modais anteriormente

O Elemento <dialog> e Manipulação com JavaScript

Usando botões com os atributos experimentais command e commandfor

Como funciona:

Melhorando a acessibilidade dos botões e dialog com atributos ARIA

Atenção

Conclusão

Referências

Projeção de Conteúdo em Angular: O Guia para ng-content e ngTemplateOutlet

O que é ng-content?

Exemplo básico de uso do ng-content

O que é ngTemplateOutlet?

Exemplo

Comparação

Conclusão

Referências

Migrando subscribe Callbacks para subscribe arguments no RxJS

O Elemento `<dialog>` e Manipulação com JavaScript