angular-best-practices

name	angular-best-practices
description	Create functional, maintainable, performant, and accessible Angular applications following Angular and TypeScript best practices. Includes guidance on llms.txt files and Angular CLI MCP server for AI-assisted development.

O que eu faço

• TypeScript Best Practices: Oriento o uso de type checking estrito, preferência por inferência de tipos quando óbvia, e evito o tipo any (usando unknown quando o tipo é incerto).

• Angular Best Practices: Garanto o uso de componentes standalone (relying on default in Angular v20+), uso de signals para gerenciamento de estado, lazy loading para rotas de funcionalidades, e hospedagem de bindings dentro do objeto host dos decorators em vez de @HostBinding e @HostListener.

• Accessibility Requirements: Asseguro que todo código passe em todas as verificações AXE e siga os mínimos WCAG AA, incluindo gerenciamento de foco, contraste de cores e atributos ARIA.

• Exemplo de Implementação:

  // src/app/components/file-upload/file-upload.component.ts
  import { Component } from '@angular/core';
  import { NgOptimizedImage } from '@angular/common';
  import { signal, computed } from '@angular/core';
  
  @Component({
    selector: 'app-file-upload',
    imports: [NgOptimizedImage],
    template: `
      <div class="upload-container" [class.dragging]="isDragging()">
        <h2>Upload File</h2>
        
        <ng-content></ng-content>
        
        <div class="drop-zone"
             (dragover)="onDragOver($event)"
             (dragleave)="onDragLeave($event)"
             (drop)="onFileDrop($event)">
          <ng-optimized-image src="/assets/upload-icon.png" 
                             width="64" 
                             height="64" 
                             alt="Upload icon"
                             class="upload-icon">
          </ng-optimized-image>
          <p>Arraste e solte um arquivo aqui ou clique para selecionar</p>
          <input type="file" 
                 (change)="onFileSelected($event)" 
                 class="file-input"
                 aria-label="Selecionar arquivo para upload">
        </div>
        
        @if (isUploading()) {
          <div class="upload-progress">
            <progress [value]="progress()" max="100"></progress>
            <span>{{ progress() }}%</span>
          </div>
        }
        
        @if (errorMessage()) {
          <div class="error-message" role="alert">
            {{ errorMessage() }}
          </div>
        }
        
        @if (successMessage()) {
          <div class="success-message" role="status">
            {{ successMessage() }}
          </div>
        }
      </div>
    `,
    styles: [`
      .upload-container {
        padding: 2rem;
        border: 2px dashed #ccc;
        border-radius: 8px;
        text-align: center;
        transition: all 0.2s ease;
      }
      
      .upload-container.dragging {
        border-color: #007bff;
        background-color: #f8f9ff;
      }
      
      .drop-zone {
        cursor: pointer;
        padding: 3rem;
      }
      
      .file-input {
        display: none;
      }
      
      .upload-progress {
        margin-top: 1.5rem;
      }
      
      .error-message {
        background-color: #f8d7da;
        color: #721c24;
        padding: 1rem;
        border-radius: 4px;
        margin-top: 1rem;
      }
      
      .success-message {
        background-color: #d4edda;
        color: #155724;
        padding: 1rem;
        border-radius: 4px;
        margin-top: 1rem;
      }
    `],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
      class: 'file-upload-component',
      '[attr.aria-label]': "'File upload component'",
      '(keydown)': 'handleKeyDown($event)'
    }
  })
  export class FileUploadComponent {
    // Inputs and outputs using signal functions
    readonly acceptedTypes = input<string[]>(['.pdf', '.jpg', '.png']);
    readonly maxSizeMB = input<number>(10);
    
    readonly uploadComplete = output<File>();
    readonly uploadFailed = output<{file: File; error: string}>();
    
    // Signals for state management
    private readonly isDragging = signal(false);
    private readonly isUploading = signal(false);
    private readonly progress = signal(0);
    private readonly errorMessage = signal<string | null>(null);
    private readonly successMessage = signal<string | null>(null);
    
    // Computed signals for derived state
    readonly uploadStatus = computed(() => {
      if (this.isUploading()) {
        return 'uploading';
      }
      if (this.errorMessage()) {
        return 'error';
      }
      if (this.successMessage()) {
        return 'success';
      }
      return 'idle';
    });
    
    constructor(private fileService: FileService) {}
    
    // Event handlers using signals
    onDragOver(event: DragEvent) {
      event.preventDefault();
      event.stopPropagation();
      this.isDragging.set(true);
    }
    
    onDragLeave(event: DragEvent) {
      event.preventDefault();
      event.stopPropagation();
      this.isDragging.set(false);
    }
    
    async onFileDrop(event: DragEvent) {
      event.preventDefault();
      event.stopPropagation();
      this.isDragging.set(false);
      
      const files = event.dataTransfer?.files;
      if (files && files.length > 0) {
        await this.handleFileUpload(files[0]);
      }
    }
    
    async onFileSelected(event: Event) {
      const input = event.target as HTMLInputElement;
      if (input.files && input.files.length > 0) {
        await this.handleFileUpload(input.files[0]);
        input.value = ''; // Reset input
      }
    }
    
    private async handleFileUpload(file: File): Promise<void> {
      // Validate file type
      const fileExt = `.${file.name.split('.').pop().toLowerCase()}`;
      if (!this.acceptedTypes().includes(fileExt)) {
        this.uploadFailed.emit({ file, error: `Tipo de arquivo não permitido. Tipos aceitos: ${this.acceptedTypes().join(', ')}` });
        return;
      }
      
      // Validate file size
      const maxSizeBytes = this.maxSizeMB() * 1024 * 1024;
      if (file.size > maxSizeBytes) {
        this.uploadFailed.emit({ file, error: `Arquivo muito grande. Tamanho máximo: ${this.maxSizeMB()}MB` });
        return;
      }
      
      this.isUploading.set(true);
      this.progress.set(0);
      this.errorMessage.set(null);
      this.successMessage.set(null);
      
      try {
        // Simulate upload progress
        for (let i = 0; i <= 100; i += 10) {
          await new Promise(resolve => setTimeout(resolve, 50));
          this.progress.set(i);
        }
        
        // Actual upload
        await this.fileService.uploadFile(file);
        
        this.successMessage.set(`Arquivo "${file.name}" enviado com sucesso!`);
        this.progress.set(100);
        this.uploadComplete.emit(file);
      } catch (error) {
        this.errorMessage.set(`Erro ao enviar arquivo: ${error.message}`);
        this.uploadFailed.emit({ file, error: error.message });
      } finally {
        // Reset after delay
        setTimeout(() => {
          this.isUploading.set(false);
          this.progress.set(0);
          this.errorMessage.set(null);
          this.successMessage.set(null);
        }, 3000);
      }
    }
    
    // Keyboard accessibility
    handleKeyDown(event: KeyboardEvent) {
      if (event.key === 'Enter' || event.key === ' ') {
        event.preventDefault();
        // Trigger file input click
        const fileInput = document.querySelector('.file-input') as HTMLInputElement;
        fileInput?.click();
      }
    }
  }
  

  // src/app/services/file.service.ts
  import { Injectable } from '@angular/core';
  import { HttpClient } from '@angular/common/http';
  import { inject } from '@angular/core';
  import { firstValueFrom } from 'rxjs';
  
  @Injectable({
    providedIn: 'root'
  })
  export class FileService {
    private http = inject(HttpClient);
    private apiUrl = '/api/files';
  
    async uploadFile(file: File): Promise<void> {
      const formData = new FormData();
      formData.append('file', file);
      
      try {
        await firstValueFrom(this.http.post(`${this.apiUrl}/upload`, formData));
      } catch (error) {
        throw error;
      }
    }
    
    // Using inject() instead of constructor injection
    // Services designed around single responsibility
  }
  

  // src/app/app.routes.ts
  import { Routes } from '@angular/router';
  import { FileUploadComponent } from './components/file-upload/file-upload.component';
  import { FileListComponent } from './components/file-list/file-list.component';
  
  export const routes: Routes = [
    {
      path: '',
      redirectTo: '/files',
      pathMatch: 'full'
    },
    {
      path: 'files',
      loadComponent: () => import('./components/file-list/file-list.component')
                    .then(m => m.FileListComponent),
      title: 'File List'
    },
    {
      path: 'upload',
      component: FileUploadComponent,
      title: 'Upload File'
    }
  ];
  

  // src/app/main.ts
  import { bootstrapApplication } from '@angular/platform-browser';
  import { appConfig } from './app/app.config';
  import { AppComponent } from './app/app.component';
  
  bootstrapApplication(AppComponent, appConfig)
    .catch(err => console.error(err));
  

  // src/app/app.config.ts
  import { ApplicationConfig } from '@angular/core';
  import { provideRouter } from '@angular/router';
  import { provideHttpClient } from '@angular/common/http';
  import { routes } from './app.routes';
  
  export const appConfig: ApplicationConfig = {
    providers: [
      provideRouter(routes),
      provideHttpClient()
    ]
  };
  

AI Integration Resources

• llms.txt Support: Oriento a inclusão de arquivos llms.txt e llms-full.txt na raiz do projeto para melhorar a compreensão de LLMs sobre o código Angular. Esses arquivos fornecem contexto estruturado para ferramentas de geração de código.

• Angular CLI MCP Server: Oriento o uso do servidor MCP (Model Context Protocol) integrado ao Angular CLI para interação com assistentes de IA. O servidor fornece ferramentas como:

  • ai_tutor: Tutor interativo alimentado por IA
  • find_examples: Encontra exemplos de código autoritativos
  • get_best_practices: Recupera o guia de melhores práticas do Angular
  • list_projects: Lista projetos no workspace Angular
  • onpush_zoneless_migration: Plano para migração para change detection OnPush
  • search_documentation: Pesquisa na documentação oficial do Angular
  • E ferramentas experimentais como build, devserver.*, e2e, modernize, test

  Para usar, execute ng mcp e configure seu ambiente de desenvolvimento conforme a documentação do Angular.