# semmet-angular **Interfaces Angular acessíveis como código do seu projeto.** > **Agentes de IA:** antes de gerar ou editar código com o Semmet, leia o [guia de uso com IA](./AI_USAGE_GUIDE.md). Ele explica como mapear padrões do Figma para comandos, o que pode ser personalizado com segurança e quais contratos de acessibilidade devem ser preservados. Semmet Angular ajuda você a criar componentes acessíveis, fluxos financeiros e estruturas para organizar, testar e publicar aplicações Angular. Escolha o recurso de que precisa, gere os arquivos e personalize o resultado de acordo com o design, o conteúdo e as regras de negócio do seu produto. Você também pode usar o Semmet em fluxos com Figma e agentes de IA para transformar padrões visuais em uma base Angular acessível. ## O que você pode criar O Semmet oferece pontos de partida acessíveis para interfaces e tarefas comuns de um projeto Angular. O resultado pode receber o layout, as cores, a tipografia e os comportamentos específicos da sua aplicação. Use componentes isolados para criar interfaces de aplicação precisas e blocos iniciais opcionais para estruturas editáveis de seções comuns. Na prática, você pode: - gerar interfaces Angular acessíveis com mais rapidez; - testar o comportamento gerado com testes unitários e testes de ponta a ponta opcionais do Playwright; - verificar a aplicação com scripts npm comuns; - empacotar e implantar com arquivos padrão do Angular, integração contínua, Docker e hospedagem. ## Início rápido Instale a coleção na raiz de um workspace Angular: ```bash ng add semmet-angular ``` Em seguida, gere o menor componente que representa o padrão da interface: ```bash ng generate semmet-angular:button save-button ``` O comando cria arquivos Angular standalone que passam a pertencer à aplicação: ```text save-button.ts save-button.html save-button.css save-button.spec.ts ``` ## Fluxo de trabalho do Figma assistido por IA Use o Semmet como base de acessibilidade e entrega em um processo de implementação orientado pelo Figma. Ciclo recomendado: 1. Copie uma seleção do Figma ou descreva a tela desejada. 2. Peça a um agente de IA para identificar campos de formulário, navegação, caixas de diálogo, tabelas, listas, abas, cartões, botões, estados de feedback e outros padrões de interface. 3. Mapeie cada padrão para o menor schematic útil do Semmet. 4. Gere os componentes ou as diretivas sem estilo visual obrigatório com `ng generate`. 5. Monte a página na aplicação Angular consumidora. 6. Substitua o conteúdo provisório e edite o HTML/CSS localmente para corresponder ao design real do Figma. 7. Preserve rótulos, relações ARIA, gerenciamento de foco, comportamento de teclado e controles nativos durante os ajustes visuais. 8. Execute a compilação e os testes; depois, adicione estruturas de testes de ponta a ponta, integração contínua, Docker ou implantação quando o projeto estiver pronto. O agente deve tratar a saída do Semmet como código da aplicação: editável, legível e seguro para reformulação visual, mantendo intacto o contrato de acessibilidade. Para obter um prompt pronto para copiar e colar e uma lista de verificação de mapeamento, consulte [AI_USAGE_GUIDE.md](./AI_USAGE_GUIDE.md). ## Exemplos de geração ```bash ng add semmet-angular ng generate semmet-angular:button cta-button ng generate semmet-angular:list-group feature-list ng generate semmet-angular:currency-input transfer-amount ng generate semmet-angular:transaction-list account-activity ng generate semmet-angular:account-selector source-account ng generate semmet-angular:beneficiary-form new-beneficiary ng generate semmet-angular:pix-payment pix-transfer ng generate semmet-angular:authorization-queue approval-queue ng generate semmet-angular:confirmation-summary transfer-review ng generate semmet-angular:transaction-detail transaction-receipt ng generate semmet-angular:block section-card ng generate semmet-angular:feature payments ng generate semmet-angular:api-resource payments --path src/app/payments ng generate semmet-angular:e2e ng generate semmet-angular:ci ng generate semmet-angular:docker ng generate semmet-angular:deploy ``` Os testes de ponta a ponta do Playwright são opcionais: ```bash ng generate semmet-angular:button cta-button --e2e ``` Use `--e2e` somente quando a aplicação consumidora tiver o Playwright configurado. Caso contrário, execute primeiro `ng generate semmet-angular:e2e`. O comando `ng add semmet-angular` mantém a instalação leve e não configura o Playwright por padrão. ## Componentes versus blocos iniciais ### Componentes Componentes e diretivas são o núcleo do Semmet Angular. Eles são a melhor escolha quando a aplicação consumidora precisa de controle preciso sobre marcação, layout e design visual. Eles fornecem o contrato de acessibilidade e deixam o layout e o design visual a cargo da aplicação: - elementos raiz semânticos nos casos em que o elemento nativo é importante; - diretivas sem estilo visual obrigatório nos casos em que a acessibilidade resulta das relações entre os elementos; - atributos ARIA e nomes/descrições acessíveis; - comportamento de teclado e foco; - estado baseado em signals; - projeção de conteúdo rico por meio de `ng-template`, quando necessário; - entradas visuais abertas, como `variant` e `size`, do tipo `string`, em vez de uniões visuais fechadas. Exemplos: ```bash ng generate semmet-angular:button save-button ng generate semmet-angular:card testimonial-card ng generate semmet-angular:input-group search-box ng generate semmet-angular:list-group feature-list ng generate semmet-angular:tabs settings-tabs ``` ### Blocos iniciais Os blocos são estruturas opcionais de seções. Eles são úteis para criar rapidamente os primeiros rascunhos, seções comuns de marketing/produto e a estrutura inicial da aplicação. Eles não são uma API pública de interface e não se destinam a preservar um layout do Semmet. Um bloco gerado é código local da aplicação. Se a interface desejada precisar de outra estrutura, substitua a marcação do bloco ou use componentes isolados. ```bash ng generate semmet-angular:block hero ng generate semmet-angular:block section-card ng generate semmet-angular:block section-pricing ng generate semmet-angular:block section-table ng generate semmet-angular:block section-form ng generate semmet-angular:block section-tabs ng generate semmet-angular:block section-list-group ng generate semmet-angular:block header-navbar ng generate semmet-angular:block footer-navigation ``` O HTML do bloco gerado inclui um comentário em linha para lembrar aos desenvolvedores que a estrutura pode ser editada e substituída. ## CSS funcional mínimo O CSS gerado é intencionalmente enxuto. Mantenha o CSS somente quando ele contribuir para a estrutura, o comportamento ou a acessibilidade: - estado aberto/fechado; - posicionamento de sobreposições; - foco visível; - conteúdo oculto; - herança de controles nativos; - comportamento básico de caixa necessário ao componente. Não trate o CSS gerado como um tema. Tipografia, cores, raios de borda, sombras, bordas decorativas, estados visuais de interação, ritmo de espaçamento e layout final pertencem ao projeto consumidor. ## Conteúdo projetado O conteúdo rico usa padrões de projeção do Angular em vez de APIs limitadas a strings. Exemplo após gerar `search-box`: ```html {{ query().length }} ``` Exemplo após gerar `testimonial-card`: ```html

Depoimento de cliente

O Semmet fornece a estrutura de acessibilidade; esta aplicação é responsável pelo conteúdo e pelo layout.

``` Exemplo após gerar `feature-list`: ```html ``` ## Schematics de entrega ```bash ng generate semmet-angular:e2e ng generate semmet-angular:ci ng generate semmet-angular:docker ng generate semmet-angular:deploy ``` Os schematics de entrega são explícitos e opcionais: - `e2e` configura o Playwright e o axe-core (dependências, scripts npm e `playwright.config.ts`), cria uma base determinística de harness em `src/app/semmet-e2e`, falha quando há testes ignorados e incorpora `npm run e2e` a um script `verify` existente. - Os componentes gerados posteriormente com `--e2e` recebem um host pertencente ao projeto, uma rota filha determinística e cobertura automática do axe. Conecte `SEMMET_E2E_ROUTES` sob a rota pai `/__semmet-e2e` na configuração de rotas de teste/local da aplicação consumidora; mantenha essa rota pai fora da produção. - Use `ng generate semmet-angular:e2e --register-route` para registrar essa rota pai em um `app.routes.ts` reconhecido. Isso continua opcional, e o shell da aplicação deve renderizar um `RouterOutlet`. - `ci` gera um fluxo de trabalho do GitHub Actions a partir dos scripts existentes no pacote. - `docker` gera arquivos de empacotamento Docker/Nginx para uma SPA Angular. - `deploy` gera uma configuração mínima de implantação para as plataformas compatíveis. ## Limite opcional de funcionalidade Os comandos existentes de componentes e blocos permanecem independentes. Use `feature` somente quando o projeto consumidor se beneficiar de uma pequena estrutura inicial fornecida pelo Semmet: ```bash ng generate semmet-angular:feature payments ``` Por padrão, são gerados somente um shell de página standalone e rotas preparadas para carregamento lazy: ```text src/app/payments/ ├── payments-page/ │ ├── payments-page.ts │ ├── payments-page.html │ ├── payments-page.css │ └── payments-page.spec.ts └── payments.routes.ts ``` Não são gerados interface de pagamento, acesso à API, estado ou modelos, e a rota pai não é registrada, a menos que isso seja solicitado explicitamente. Gere as partes acessíveis de forma independente e coloque-as onde a arquitetura da aplicação exigir: ```bash ng generate semmet-angular:currency-input amount --path src/app/payments ng generate semmet-angular:confirmation-summary review --path src/app/payments ng generate semmet-angular:feature reports --register-route ``` Use `--page=false` ou `--routing=false` para obter um limite menor. Presets expandidos de funcionalidades e a composição de API/estado estão reservados para fases futuras do roadmap e, no momento, falham com uma mensagem clara em vez de gerar silenciosamente uma arquitetura incompleta. ## Recursos HTTP tipados `api-resource` é independente de `feature`. Ele gera código HTTP Angular editável, com contratos separados de transporte/aplicação, mapeamento puro e testes de requisição: ```bash ng generate semmet-angular:api-resource payments \ --entity payment \ --operations list \ --operations get \ --operations create \ --path src/app/payments ``` As opções de array do Angular CLI devem ser repetidas uma vez para cada valor; um valor separado por vírgulas, como `--operations list,get,create`, é tratado como uma única operação inválida. Arquivos gerados: ```text payments-api.ts payments-api.spec.ts payment.dto.ts payment.model.ts payment.mapper.ts ``` O serviço usa `inject(HttpClient)`, e o teste usa `provideHttpClient()` seguido de `provideHttpClientTesting()`. Ele não adiciona autenticação, não faz inscrições internamente, não oculta erros nem tenta adivinhar os campos do backend. Substitua os contratos iniciais, que contêm apenas `id`, pelo contrato real da API ou use um cliente gerado por OpenAPI quando houver um disponível. ## Interceptadores HTTP funcionais Gere um `HttpInterceptorFn` Angular testado a partir de uma receita explícita: ```bash ng generate semmet-angular:interceptor correlation-id ng generate semmet-angular:interceptor problem-details ng generate semmet-angular:interceptor auth-token ng generate semmet-angular:interceptor logging ``` Por padrão, o comando cria apenas o interceptador e seu teste HTTP isolado em `src/app/http/`. O registro é explícito: ```bash ng generate semmet-angular:interceptor correlation-id --register ``` `--register` atualiza um `app.config.ts` reconhecido com `provideHttpClient(withInterceptors([...]))`. Quando a configuração existente não pode ser editada com segurança, o schematic a preserva e exibe o trecho para registro manual. A receita `auth-token` usa uma fonte abstrata de token, permite credenciais somente para a mesma origem ou para origens explicitamente confiáveis e exclui os prefixos de URLs públicas configurados. Ela não impõe `localStorage`, filas de renovação de token, comportamento de logout ou um modelo de autenticação específico de uma empresa. A receita `logging` expõe hooks apenas para metadados e exclui intencionalmente cabeçalhos, corpos e parâmetros de consulta. ## Contrato de transporte do token de autenticação O template `interceptor/auth-token` anexa `Authorization: Bearer ` apenas em origens explicitamente permitidas (`AUTH_ALLOWED_ORIGINS`) e **nunca lê nem escreve cookie**. Essa é uma decisão deliberada, não uma omissão: enquanto o token viaja só pelo header, a proteção XSRF embutida do `HttpClient` (baseada em cookie) é irrelevante para esta biblioteca, e nenhum `app.config.ts` gerado precisa de `withXsrfConfiguration()`. Esse contrato é compartilhado com o backend de referência [semmet-spring-boot-cli](https://github.com/daniloagostinho/semmet-spring-boot-cli) — o `JwtAuthenticationFilter` gerado lá também só lê o token do header `Authorization`, nunca de cookie. Os dois lados concordam hoje, mas por convenção, não por um contrato imposto em código. Se um projeto migrar o token para um cookie `httpOnly` (reduz a superfície de exfiltração via XSS, ao custo de reintroduzir CSRF), a mudança precisa ser feita **nos dois lados ao mesmo tempo**: reativar `csrf` no `SecurityConfig` do Spring e configurar `withXsrfConfiguration()` aqui. Fazer só de um lado quebra a autenticação ou reabre uma vulnerabilidade que o outro lado já tinha fechado. Veja `SECURITY_ROADMAP.md` para o estado atual desse acompanhamento. ## Comandos de componentes disponíveis O catálogo de componentes está dividido em duas famílias práticas: - componentes genéricos de aplicação para padrões comuns de interface, como botões, caixas de diálogo, abas, formulários, campos de entrada, navegação, tabelas, feedback, sobreposições e estrutura de layout; - componentes financeiros e bancários para fluxos específicos do domínio, como Pix, boletos, seleção de contas, gerenciamento de beneficiários, aprovações, controles de cartões, gerenciamento de limites, simulação de empréstimos, avisos de conformidade, extratos, comprovantes e transferências. Sobreposições e conteúdo expansível: - `accordion` - `alert-dialog` - `dialog` - `disclosure` - `menu-button` - `offcanvas` - `popover` - `tooltip` Navegação e estrutura: - `breadcrumb` - `card` - `landmarks` - `list-group` - `navbar` - `navigation-menu` - `pagination` - `skip-link` - `tabs` - `toolbar` - `tree-view` Formulários e campos de entrada: - `checkbox` - `combobox` - `currency-input` - `form` - `input` - `input-group` - `listbox` - `meter` - `progress-bar` - `radio-group` - `select` - `slider` - `spinbutton` - `switch` - `textarea` Financeiros e bancários: - `account-selector` - `account-summary` - `authorization-queue` - `beneficiary-form` - `beneficiary-list` - `card-controls` - `compliance-alert` - `confirmation-summary` - `currency-input` - `limit-manager` - `loan-simulator` - `otp-input` - `payment-card` - `payment-slip` - `pix-payment` - `scheduled-payment` - `secure-code-input` - `transaction-detail` - `transaction-filter` - `transaction-list` - `transfer-form` Feedback, mídia e exibição: - `alert` - `avatar` - `badge` - `button` - `button-group` - `carousel` - `close-button` - `rating` - `skeleton` - `spinner` - `steps` - `table` - `toast` ## Opções Opções comuns dos componentes: - `name`: obrigatório e posicional. - `project`: projeto Angular de destino. - `path`: diretório de destino. - `e2e`: booleano opcional. Gera um teste do Playwright somente quando solicitado explicitamente. ## Licença MIT