@trismegisto/angular

Os componentes Angular do Hermes Design System: mais de cem peças hm-* standalone (botão, campos de formulário, modal, menus, data grid, abas, árvore, toast…), o tema (hermesTheme, HermesThemeService), os textos da lib em pt-BR/en/es (HermesI18nService), os ícones (hm-icon) e harnesses de teste.

Na cadeia de camadas (tokens ← icons ← primitives ← core ← angular ← maps · charts · spine) é a casca fina: o estilo vem do @trismegisto/core, o comportamento do @trismegisto/primitives, os valores visuais do @trismegisto/tokens. @trismegisto/maps, @trismegisto/charts e @trismegisto/spine são montados sobre este pacote.

Instalação

npm install @trismegisto/angular @trismegisto/core @trismegisto/tokens @trismegisto/primitives @trismegisto/icons

Os cinco andam juntos e na mesma versão. Peers: @angular/core, common, forms, platform-browser e router (≥ 21) e rxjs ^7.8. @angular/cdk é opcional: só o ponto @trismegisto/angular/testing precisa dele.

Configuração do app

1. CSS, no angular.json → styles, nesta ordem:

"node_modules/@trismegisto/tokens/dist/tokens.css",
"node_modules/@trismegisto/core/dist/core.css"

2. Providers, no app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { HERMES_FAMILIES, HERMES_THEME_CONFIG, provideHermesI18n, provideHermesIconLoader } from '@trismegisto/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    // Ícones que o APP usa (os componentes da lib já registram os deles). Catálogo inteiro num chunk à parte:
    provideHermesIconLoader(() => import('@trismegisto/icons/catalog').then((m) => m.HERMES_ICONS)),
    // Só se o app não começa em pt-BR (o padrão):
    // provideHermesI18n({ locale: 'en' }),
    // Prefixo próprio das preferências salvas (tema, família, densidade, fonte):
    { provide: HERMES_THEME_CONFIG, useValue: { storagePrefix: 'meuapp', defaultFamily: 'hera', families: HERMES_FAMILIES } },
  ],
};

3. Raiz do app: um hermesTheme no elemento que envolve tudo e um hm-toast-stack.

<div class="shell" hermesTheme>
  <router-outlet />
  <hm-toast-stack />
</div>

hermesTheme (HermesThemeDirective) aplica data-theme (claro/escuro), data-family (12 paletas), data-density (comfortable/compact) e data-font; tudo dentro herda os tokens. Para trocar em tempo de execução, injete HermesThemeService (setMode('light' | 'dark' | 'system'), setFamily(id), setDensity(...), setFont(...), toggle(), toggleDensity()); a escolha fica salva em localStorage. hm-theme-picker é o seletor pronto para o usuário.

Uso

Todo componente é standalone: importe a classe no imports do componente. Não existe HermesModule.

import { Component } from '@angular/core';
import { ButtonComponent, InputComponent } from '@trismegisto/angular';

@Component({
  imports: [ButtonComponent, InputComponent],
  template: `
    <hm-input label="E-mail" type="email" [(value)]="email" />
    <hm-button intent="primary" (clicked)="save()">Salvar</hm-button>
  `,
})
export class ProfileForm { /* ... */ }

Os controles de formulário aceitam os três modos (Reactive Forms, ngModel e [(value)] sem formulário): use o que o resto do app já usa.

Pontos de entrada

| Import | Conteúdo | | --- | --- | | @trismegisto/angular | Tudo, com nomes explícitos. É o import recomendado. | | @trismegisto/angular/<pasta> | Cada pasta de src/ é um ponto de entrada próprio (@trismegisto/angular/button, /data-grid, /i18n, /theme, /direction…). O bundler divide a lib por arquivo, então importar da raiz já não leva a lib inteira para o carregamento inicial. | | @trismegisto/angular/illustration-* | As 14 ilustrações (IllustrationErrorComponent…). Só saem por aqui, de propósito: o hm-state-screen as carrega por @defer. Na tela de estado, prefira ele. | | @trismegisto/angular/testing | Harnesses do CDK (HermesButtonHarness, HermesInputHarness, HermesModalHarness, HermesDataGridHarness…). Fora da raiz porque é o único ponto que importa @angular/cdk. |

Regras que o app precisa saber

• Ícones são opt-in. O app registra os que ele passa em shape/icon: o catálogo inteiro (provideHermesIconLoader, acima) ou só os nomeados (provideHermesIcons([bell, heart]), de @trismegisto/icons/catalog). Nome não registrado desenha um ícone genérico e avisa no console em desenvolvimento ([hermes-icons]). Ver @trismegisto/icons.
• Idiomas. Só o pt-BR vem embutido. inject(HermesI18nService).setLocale('en' | 'es') baixa o catálogo na primeira troca e devolve uma Promise; os textos da lib, o formato de data digitada e os plurais mudam sem recarregar. Para trocar sem espera, provideAppInitializer(() => preloadHermesCatalog('en')). Para sobrescrever textos, provideHermesI18n({ override: { ... } }). Os textos que o app passa por input (rótulos, conteúdo) são do i18n do próprio app.
• Todo controle tem rótulo. label é obrigatório em campos, hm-icon-button, hm-tabs, hm-tree, hm-menu-button, hm-sidebar, hm-skeleton; para esconder visualmente, labelHidden.
• Nada de valor visual cravado no CSS do app: cor, espaço, raio, sombra e duração vêm de var(--hm-*). Só assim a tela acompanha tema escuro, família e densidade compacta.
• Sem zone.js: a lib é toda OnPush + signals e funciona com provideZonelessChangeDetection().
• Overlay próprio movido para o <body> precisa de copyThemeScope() (@trismegisto/primitives) para não perder o tema.

Skill para agentes de IA

A skill de uso para agentes (Claude Code) está no pacote @acropole/skills: npx @acropole/skills (skill trismegisto). Ela não vai mais dentro deste pacote.

Os catálogos de API da skill (angular-api.md: seletores, inputs e outputs; angular-exports.md: tudo que cada ponto de import exporta) são gerados pelo @acropole/skills, que lê o src/ deste pacote (rode npm run sync -- --trismegisto <pasta do trismegisto> em packages/acropole).

Documentação

• Site de documentação (docs/website): uma página por componente (/components/<id>, com abas Visão Geral, Código, API e Acessibilidade) e as páginas "Começando" (/pages/introduction, /pages/theming, /pages/i18n, /pages/api-conventions, /pages/accessibility, /pages/migration).
• Mudanças por versão: CHANGELOG.md.
• Arquitetura e regras: docs/architecture e CLAUDE.md.

Desenvolvimento do pacote

npm test (checagem de ícones e de textos fora do catálogo + specs) e npm run build (gera os ícones internos, empacota com ng-packagr em dist/, copia este README e roda o check-bundle, a guarda de tamanho). Fluxo completo em docs/guides.