@acropole/skills 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +181 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,390 @@
1
+ # @trismegisto/angular — guia de uso dos componentes `hm-*`
2
+
3
+ Escrito para a **API 1.0**; o que saiu ou está depreciado está em
4
+ [Depreciações e remoções](#6-depreciações-e-remoções). Pacotes, instalação, peers, tema/família/fonte,
5
+ páginas de estado e ilustrações estão no `SKILL.md` da skill. Nomes exatos: `angular-api.md` (seletores,
6
+ inputs, outputs, slots) e `angular-exports.md` (serviços, funções, tokens, tipos); tipos comentados:
7
+ `angular-types.md`; receitas prontas: `angular-recipes.md`. Se o app usa o shell `@trismegisto/spine`,
8
+ leia também `spine.md` — boa parte do setup abaixo ele já faz.
9
+
10
+ ## 1. Setup do app (sem spine)
11
+
12
+ Depois de instalar os cinco pacotes e pôr `tokens.css` + `core.css` no `styles` (ver `../SKILL.md` §2),
13
+ `app.config.ts`:
14
+
15
+ ```ts
16
+ import { provideHermesIcons, provideHermesI18n, HERMES_THEME_CONFIG } from '@trismegisto/angular';
17
+ import { HERMES_FAMILIES } from '@trismegisto/angular';
18
+ import { HERMES_ICONS } from '@trismegisto/icons/catalog';
19
+
20
+ export const appConfig: ApplicationConfig = {
21
+ providers: [
22
+ provideHermesIcons(HERMES_ICONS), // ícones que o APP usa (os componentes da lib já registram os deles)
23
+ // provideHermesI18n({ locale: 'en' }), // só se o app não começar em pt-BR (padrão)
24
+ { provide: HERMES_THEME_CONFIG, useValue: { storagePrefix: 'meuapp', defaultFamily: 'poseidon', families: HERMES_FAMILIES } },
25
+ ],
26
+ };
27
+ ```
28
+
29
+ - Sem `HERMES_THEME_CONFIG`, vale o padrão: `storagePrefix: 'hermes'`, família `hera`, todas as 12 famílias.
30
+ Famílias/fontes próprias do app (`extendThemeConfig`): `../SKILL.md` §4.
31
+ - Para bundle menor, registre só os ícones usados, importando-os por nome do mesmo `/catalog`:
32
+ `provideHermesIcons([addText, airplane])`. O export é em camelCase (`addText`); no template, o nome é
33
+ kebab-case (`shape="add-text"`).
34
+ - Se o app usa `@trismegisto/spine`, o `provideUi()` do spine já registra o catálogo.
35
+
36
+ Raiz do app (o shell): **um** `hermesTheme` no elemento que envolve tudo, e **um** `hm-toast-stack`.
37
+
38
+ ```html
39
+ <div class="shell" hermesTheme>
40
+ <router-outlet />
41
+ <hm-toast-stack />
42
+ </div>
43
+ ```
44
+
45
+ `hermesTheme` aplica `data-theme` (claro/escuro), `data-family` (12 paletas), `data-density`
46
+ (confortável/compacto) e `data-font`. Tudo dentro herda os tokens. Para trocar em runtime, injete
47
+ `HermesThemeService`: `setMode('light'|'dark'|'system')`, `setFamily(id)`, `setDensity('comfortable'|'compact')`,
48
+ `toggle()`, `toggleDensity()`. A escolha é persistida em `localStorage` com o `storagePrefix`. Para dar ao
49
+ usuário essa escolha pronta, use `hm-theme-picker`. Ele é apresentacional: ligue `families`, `family` e
50
+ `theme` ao `HermesThemeService` e trate `familyChosen`/`themeChosen` (ver `angular-recipes.md` §1).
51
+
52
+ Todos os componentes são **standalone**: importe a classe no `imports` do componente
53
+ (`ButtonComponent`, `ModalComponent`…). Não existe `HermesModule`.
54
+
55
+ - **Import:** de `@trismegisto/angular` (a raiz) ou do ponto de import da peça (`@trismegisto/angular/button`,
56
+ `@trismegisto/angular/data-grid`) — os dois deixam o bundler dividir por rota. Exceção: as ilustrações
57
+ (`IllustrationErrorComponent`…) só saem pelo ponto de import delas (`@trismegisto/angular/illustration-error`);
58
+ na tela de estado, prefira `hm-state-screen`, que já as carrega sob demanda.
59
+ - **Idiomas:** só o pt-BR vem embutido. `setLocale('en'|'es')` baixa o catálogo na primeira troca e devolve
60
+ `Promise<void>` (o idioma muda quando o catálogo chega). Para trocar sem espera, pré-carregue:
61
+ `provideAppInitializer(() => preloadHermesCatalog('en'))`. Para embutir: `provideHermesI18n({ catalogs:
62
+ { en: HERMES_MESSAGES_EN } })` com `import { HERMES_MESSAGES_EN } from '@trismegisto/primitives/messages/en'`.
63
+ Em spec que troca de idioma: `beforeAll(() => preloadHermesCatalog('en'))`.
64
+ - **Sem zone.js:** a lib é toda OnPush + signals e funciona com `provideZonelessChangeDetection()`.
65
+
66
+ ## 2. Regras que não podem ser quebradas
67
+
68
+ 1. **Nenhum valor visual cravado no app.** Cor, espaçamento, raio, sombra, duração e altura de controle vêm de
69
+ `var(--hm-*)`. Um `#hex` ou um `px` de espaçamento num SCSS de tela é bug: não acompanha tema escuro,
70
+ família nem densidade. Grupos principais:
71
+ - Cor: `--hm-surface`, `--hm-surface-raised`, `--hm-text`, `--hm-muted`, `--hm-border`, `--hm-divider`,
72
+ `--hm-accent`, `--hm-action`, `--hm-on-action`, `--hm-hover`, `--hm-focus-color`;
73
+ status: `--hm-{info,success,warning,danger}` e `--hm-{…}-bg`.
74
+ - Espaço: `--hm-space-{xxxs,nano,quarck,xs,sm,md,lg,xl,2xl,3xl}`. Controle: `--hm-control-height{,-dense,-large}`.
75
+ - Forma: `--hm-radius{,-control,-micro,-pill}`, `--hm-shadow-{lg,overlay,nav}`, `--hm-border-{thin,hairline}`.
76
+ - Tipografia: `--hm-font-sans`, `--hm-font-size-{xs,sm,md,lg,xl,xxl}`, `--hm-font-weight-{regular,medium,semibold,bold}`.
77
+ - Movimento: `--hm-duration-{quick,standard,medium,relaxed,slow}`, `--hm-ease{,-standard,-decelerate}`.
78
+ - Camadas: `--hm-z-sticky` (10), `--hm-z-menu`, `--hm-z-fixed`, `--hm-z-overlay` (100), `--hm-z-scene`
79
+ (200), `--hm-z-toast` (300, acima de menu e diálogo), `--hm-z-tooltip` (400).
80
+ - Destaque suave: `--hm-accent-subtle` (fundo de seleção leve, área de soltar ativa).
81
+ - Dados (gráficos, séries, mapas de calor): `--hm-data-categorical-{1..8}`, `--hm-data-sequential-{1..5}`,
82
+ `--hm-data-diverging-{1..7}` — já validados para contraste e daltonismo nos dois temas. Não invente
83
+ cores de série.
84
+ - Breakpoints: `--hm-breakpoint-{sm,md,lg,xl}` (640/768/1024/1400px). Custom property não funciona
85
+ dentro de `@media`: em TS use `HERMES_BREAKPOINTS` e `hermesMediaQuery('md', 'down')` de
86
+ `@trismegisto/tokens` (para `matchMedia`/`BreakpointObserver`).
87
+ Usar só a escala de espaço já faz a tela respeitar o modo compacto, sem código extra.
88
+ Texto solto de página (descrição, título de seção, nota) sem SCSS próprio: classes `.hm-text-{xs..xxl}`,
89
+ `.hm-text-{regular,medium,semibold,bold}` e `.hm-heading-{1..6}` do `@trismegisto/core`. A classe é só
90
+ visual — o nível continua sendo o elemento (`<h2 class="hm-heading-4">`).
91
+ Alto contraste (`forced-colors`) já vem tratado nos componentes; CSS próprio onde a cor carrega
92
+ informação (borda de controle, seleção, preenchimento) precisa do seu `@media (forced-colors: active)`
93
+ com cores de sistema (`CanvasText`, `Highlight`, `ButtonBorder`).
94
+ 2. **Todo controle tem rótulo.** `label` é obrigatório em campos, `hm-icon-button`, `hm-tabs`, `hm-tree`,
95
+ `hm-menu-button`, `hm-sidebar`, `hm-skeleton`. Para esconder visualmente, use `labelHidden` (continua para
96
+ leitor de tela). Nunca passe string vazia para satisfazer o tipo.
97
+ 3. **Textos do app são do app.** Os componentes já trazem os próprios textos (fechar, paginação, erros
98
+ padrão…) em pt-BR/en/es via `HERMES_MESSAGES`. Os rótulos e conteúdos que você passa por input são
99
+ responsabilidade do sistema de i18n do app. Quando o app trocar de idioma, chame também
100
+ `inject(HermesI18nService).setLocale(locale)`: os textos da lib, o formato de data digitada e os
101
+ plurais mudam na hora, sem recarregar. Não monte texto da lib por concatenação: use os templates do
102
+ catálogo com `formatMessage`/`pluralMessage`, e para sobrescrever passe `override` em
103
+ `provideHermesI18n`.
104
+ 4. **Não aninhe interativo em interativo.** `hm-card` não é clicável de propósito: ponha um `hm-button` ou
105
+ link dentro, não um `(click)` no card. Não ponha botão dentro de `hm-button`.
106
+ 5. **Landmarks com nome único.** `hm-card` com `heading` vira `region`; `hm-paginator` é `nav`. Dois na mesma
107
+ tela precisam de nomes diferentes. Se o card não precisa de título, não passe `heading`.
108
+ 6. **Ação destrutiva usa `intent="danger"`** (botão) ou `danger: true` (item de menu). A forma e o texto
109
+ sinalizam o perigo, não só a cor.
110
+ 7. **Ícone de componente do app**: use nomes que existam no catálogo. Nome desconhecido não dá erro, vira
111
+ ícone genérico (em modo de desenvolvimento sai um aviso `[hermes-icons]` no console). Confira em `@trismegisto/icons/catalog`.
112
+
113
+ ## 3. Formulários — use do jeito que o app já usa
114
+
115
+ Todo controle (`hm-input`, `hm-textarea`, `hm-select`, `hm-checkbox`, `hm-checkbox-group`, `hm-radio`, `hm-switch`,
116
+ `hm-combobox`, `hm-combobox-multi`, `hm-date-picker`, `hm-segmented-control`, `hm-file-upload`,
117
+ `hm-dual-list`, `hm-reorder-list`, `hm-bulk-input`) aceita os três modos —
118
+ escolha o que o resto do app usa, não misture no mesmo campo:
119
+
120
+ ```html
121
+ <!-- Reactive Forms -->
122
+ <form [formGroup]="form">
123
+ <hm-input label="E-mail" formControlName="email" />
124
+ </form>
125
+
126
+ <!-- template-driven -->
127
+ <hm-input label="E-mail" name="email" [(ngModel)]="model.email" required />
128
+
129
+ <!-- sem formulário -->
130
+ <hm-input label="Busca" [(value)]="term" />
131
+ ```
132
+
133
+ - Two-way sem formulário: `[(value)]` em todos, exceto `hm-checkbox` (`[(checked)]`),
134
+ `hm-combobox-multi` (`[(selected)]`, lista de valores), `hm-file-upload` (`[(files)]`, lista de
135
+ `UploadFile`) e `hm-reorder-list` (`[(items)]`, a lista na ordem nova). `hm-dual-list` usa `[(value)]`
136
+ com os ids escolhidos.
137
+ - **Obrigatório e erro**: com formulário, saem do controle (`Validators.required`/`requiredTrue`, erros de
138
+ validação) e o erro aparece depois de tocado (blur) ou alterado. Sem formulário, use os inputs
139
+ `[required]` e `[error]` (texto pronto; também serve para erro do servidor com formulário — tem
140
+ precedência).
141
+ - Texto por chave de erro: `[messages]="{ email: 'Informe um e-mail válido.' }"`; sem isso, catálogo da lib.
142
+ - Desabilitar: `form.disable()`/`control.disable()` ou o input `[disabled]` sem formulário.
143
+ - Texto de apoio: `hint` em todos (`help` ainda funciona, depreciado).
144
+ - `hm-field` virou **`hm-input`** (mesma API). `hm-field` ainda existe na 1.0, **depreciado** e com aviso no
145
+ console em desenvolvimento: não use em código novo.
146
+ - `[control]="form.controls.x"` (contrato 0.1.x) **foi removido** (depreciado desde 0.2.0): use
147
+ `[formControl]="form.controls.x"` (com `ReactiveFormsModule`) ou `formControlName="x"`. Só o
148
+ `hm-settings-section` mantém um `[control]` próprio (o `FormGroup` da seção).
149
+ - `hm-input`: `type` `text | email | tel | url | number | search | password`. Com `type="number"` o valor é
150
+ `number` (vazio = `null`) e `min`/`max`/`step` já validam (erros `min`, `max`, `number`) — não some
151
+ `Validators.min/max` repetidos. Máscara: `mask="cpf" | "cnpj" | "cep" | "phone"` ou padrão
152
+ (`'99.999-9'`: `9` dígito, `A` letra, `*` ambos); o modelo guarda o valor sem pontuação (`maskValue="raw"`,
153
+ padrão) ou com ela (`"masked"`). Para "CPF completo" use `isMaskComplete` de `@trismegisto/primitives` num
154
+ validator. `prefix`/`suffix` ("R$", "kg"), `maxLength` com contador.
155
+ - Campo de busca/filtro: `hm-search-field` (também nos três modos), com `(search)` já com `debounce`.
156
+ - Datas: valor ISO `AAAA-MM-DD` por padrão; `valueFormat="dd/mm/yyyy"` se o backend exigir.
157
+ - `hm-date-range-picker`: o valor é `DateRange` (`{ start, end }`) num controle só. Para obrigatório e
158
+ ordem use `DateRangeValidators.required`/`.order` — `Validators.required` não serve (o objeto vazio
159
+ não é "vazio" para ele). Atalhos: `[presets]="['today', 'last7Days', 'thisMonth', { label, range: () => ({ start, end }) }]"`
160
+ (ids prontos com texto do catálogo; não escreva "Hoje"/"Últimos 7 dias" à mão).
161
+ - `hm-code-input` funciona com formulários (`formControlName`/`ngModel`) mas não tem `required`/`error`
162
+ próprios.
163
+ - `hm-file-upload`: `Validators.required` falha com a lista vazia. Formatos e limites (`accept`,
164
+ `maxSize`, `maxTotalSize`, `maxFiles` com `multiple`) são validados **antes** de o arquivo entrar na
165
+ lista; recusas saem em `(rejected)` com o motivo. Não envia nada sozinho: ou o app envia e informa o
166
+ andamento com `update(id, { status, progress, error })`, ou passa `[uploader]` (receitas §11).
167
+
168
+ ## 4. Escolhendo o componente
169
+
170
+ | Preciso de… | Use |
171
+ |---|---|
172
+ | Ação | `hm-button` (`emphasis` high/medium/minimal × `intent` primary/success/warning/danger; `loading` para carregando, já desabilita; `busy` é o nome antigo, depreciado) |
173
+ | Ação só com ícone | `hm-icon-button` (`label` vira o nome acessível) |
174
+ | Botão que fica pressionado (negrito, fixar, silenciar) | `hm-button`/`hm-icon-button` com `toggle` + `[(pressed)]` (`aria-pressed`; o rótulo NÃO muda com o estado). Preferência com rótulo que aplica na hora é `hm-switch` |
175
+ | Vários botões de alternância juntos (formatação, alinhamento, lista/grade) | `hm-toggle-group` (`label` obrigatório; `[(value)]` texto = escolha única/`radiogroup`, `multiple` = lista/`aria-pressed`) + `hm-toggle-group-item` (`value`, `icon` + `label` quando só ícone); dentro de `hm-toolbar` o múltiplo cede as setas à barra. Campo de formulário é `hm-segmented-control` |
176
+ | Grupo de ações | `hm-button-group` |
177
+ | Menu de ações | `hm-menu-button` com `[items]: MenuItem[]` e `(chosen)` (id do item) |
178
+ | Menu ancorado manualmente | `hm-menu` com `[anchor]` |
179
+ | Itens de menu marcáveis (exibir/ocultar, ordenar por) | `MenuItem` com `type: 'checkbox'` (`checked`) ou `type: 'radio'` (`group`, `value`, `checked`) em `hm-menu`/`hm-menu-button`/`hm-menubar`; `(checkedChange)` traz `MenuItemChange` — aplique com `applyMenuItemChange(items, change)`; `closeOnCheck` fecha ao marcar |
180
+ | Barra de menus de aplicativo (Arquivo · Editar · Exibir) | `hm-menubar` (`[menus]: MenubarMenu[]`, `label`, `(chosen)`, `(checkedChange)`) — não use para navegação do site |
181
+ | Navegação principal com painéis (produtos, recursos) | `hm-navigation-menu` (`label`) + `hm-navigation-menu-item` (`label`, painel com `columns`, ou `href`/`route` direto) + `hm-navigation-menu-link` (`label`, `description`, `icon`, `href`/`route`, `current`); recolhe num botão em contêiner estreito |
182
+ | Menu de contexto (botão direito, `Shift+F10`) | diretiva `[hmContextMenu]="items"` + `(chosen)`; o host precisa ser focável; toda ação dele também precisa existir num botão visível |
183
+ | Conteúdo interativo curto ancorado num botão (filtros, detalhes) | `hm-popover` (`heading` ou `label`, `side`/`align`, `[(open)]`) + `[hmPopoverTrigger]="ref"` no botão |
184
+ | Pré-visualização ao passar o ponteiro/focar um link (cartão de perfil) | `hm-popover openOn="hover"` (`openDelay`/`closeDelay`) + `[hmPopoverTrigger]`; o conteúdo só complementa — o link continua levando ao destino |
185
+ | Navegação lateral | `hm-sidebar` + `hm-sidebar-node` (árvore) ou `hm-sidebar-group`/`hm-sidebar-link` |
186
+ | Cabeçalho do app | `hm-header` (slots `[shortcuts]` e `[actions]`; `[atalhos]`/`[acoes]` depreciados) |
187
+ | Cabeçalho da página (título, trilha, resumo, ações) | `hm-page-header` (`heading`, `level` — `<h1>` por padrão, só um por página —, `[breadcrumb]`, `description`, `summary` vivo, slots `[actions]`/`[meta]`) |
188
+ | Barra de busca/filtros/ações de uma tela | `hm-toolbar` (`label` obrigatório; slots `[start]`/`[end]`; setas entre controles) |
189
+ | Campo de busca | `hm-search-field` (`label` obrigatório, `debounce`, `(search)`; `[landmark]="false"` dentro de toolbar/tabela) |
190
+ | Trilha "você está aqui" | `hm-breadcrumb` com `[items]: BreadcrumbItem[]` (`label`, `routerLink`/`href`, `icon`); o último é a página atual; ações da página com o atributo `actions` |
191
+ | Abas de conteúdo | `hm-tabs` + `hm-tab` (`orientation`, overflow em menu "Mais", `[actions]`); conteúdo caro em `*hmTabContent` (monta na 1ª seleção; `destroyOnHide` recria) |
192
+ | Subnav de rotas (abas que trocam a URL) | `hm-tabs mode="nav"` + `hm-tab route` + `<router-outlet>` |
193
+ | Abas estilo navegador (abrir/fechar/reordenar) | `hm-tab-bar` (arrastar por mouse, toque longo e teclado — `Ctrl+Espaço` — já vem; `(reordered)` traz a posição final; fileiras com o mesmo `[tabGroup]` trocam abas via `(tabReceived)`) |
194
+ | Área dividida em painéis com abas | `hm-workspace` |
195
+ | Dois painéis redimensionáveis (lista e detalhe) | `hm-splitter` (`label` obrigatório, `[(position)]` em %, `min`/`max`) + `hm-splitter-panel primary`/`secondary` |
196
+ | Seções recolhíveis | `hm-accordion` + `hm-accordion-panel`; conteúdo caro em `*hmAccordionContent` (monta na 1ª abertura; `destroyOnClose`) |
197
+ | Tabela de dados | `hm-data-grid` (filtro, busca, paginação cliente/servidor, ordenação, seleção, ações de linha, detalhe) |
198
+ | Milhares de linhas sem paginar | `hm-data-grid` com `virtual` + `[paginated]="false"` (`rowHeight` estimado; mede as linhas reais) |
199
+ | Coluna-chave sempre visível ao rolar de lado | `hm-data-grid`: `pinned: 'start' \| 'end'` na coluna ou `[(pinnedColumns)]` (a pessoa também fixa pelo `columnManager`) |
200
+ | Escolher uma linha só | `hm-data-grid` com `selectionMode="single"` (rádio por linha; `selectable` = `'multiple'`) |
201
+ | Linha que não pode ser selecionada / sem detalhe | `hm-data-grid` com `[rowSelectable]="(row) => boolean"` (+ `rowSelectableReason` com o motivo anunciado; "selecionar todos" e Shift ignoram as travadas) e `rowDetailDisabled`/`rowDetailHidden` (`(row) => boolean`, detalhe abaixo e ao lado). Não filtre a seleção depois no `(selectionChange)` |
202
+ | Exportar a listagem (CSV/Excel) | `hm-data-grid` com `exportable` (botão na barra; `exportFileName`) ou `grid.exportCsv({ format, fileName, download })` por código; exporta linhas filtradas/ordenadas de todas as páginas, colunas visíveis na ordem da tela; `exportable: false` na coluna a tira |
203
+ | Agrupar linhas e totais | `hm-data-grid` com `[(groupBy)]="'chave'"` (o seletor de agrupamento é do app) e `[aggregates]="{ total: 'sum' }"` (`sum`/`avg`/`min`/`max`/`count`; rodapé de totais e linha por grupo; `aggregateFormatter` para moeda/unidade) |
204
+ | Filtro composto (coluna + operador + valor, E/OU) | `hm-data-grid` com `advancedFilter` + `[(filterQuery)]` (`GridFilterQuery`) |
205
+ | Pessoa escolher/ordenar/esconder colunas | `hm-data-grid` com `columnManager` + `[(columnOrder)]` (substitui o seletor de colunas do rodapé) |
206
+ | Grade lembrar ordenação/filtros/colunas/página | `hm-data-grid` com `persistKey="tela-x"` (`persistStorage` `local`/`session`; `clearPersistedState()` limpa) |
207
+ | Paginação avulsa | `hm-paginator`; em painel/cartão ou lista com cursor (sem total): `variant="simple"` + `[hasNext]`/`[hasPrevious]` → `(nextPage)`/`(previousPage)` |
208
+ | Agenda / calendário de eventos | `hm-event-calendar` (`[events]: CalendarEvent[]`, `[(view)]` month/week/day/list, `[(date)]`, `timeZone`; `(rangeChange)` para buscar no servidor, `(eventClick)`/`(dateClick)`) |
209
+ | Hierarquia selecionável | `hm-tree`: caixas tri-state (padrão, `selected`/`changed`) ou `selectionMode` `single`/`multiple` + `[(selection)]` (sem caixas); carga preguiçosa com `loadChildren` (paginada: devolva `{ children, hasMore }` e use `context.offset`; erro vira "Tentar de novo" no nó). Endereço/busca de explorador ficam no app |
210
+ | Pessoa reorganizar a árvore / ações por nó | `hm-tree` com `draggable` (+ `canDrop`) → `(moved)`: a árvore não muda `nodes`, o app aplica com `moveTreeNode` (`@trismegisto/primitives`); `[nodeActions]` (`MenuItem[]` ou `(node) => MenuItem[]`) → `(nodeAction)` |
211
+ | Arrastar e soltar genérico (cartões, listas próprias) | `[hmDraggable]` + `[hmDropZone]` (`[hmDragHandle]` opcional) ou `[(hmSortable)]` para reordenar; toque longo e teclado prontos; `hmDragContained` prende o item à própria lista; `(overPoint)` na zona dá o ponto do ponteiro (destino que depende de metade/borda) |
212
+ | Quadro de etapas (kanban) | `hm-kanban` com `[(columns)]: KanbanColumn<T>[]`, `itemLabel`, `canMove` → `(moved)`; colunas recolhíveis (`[(collapsed)]`) |
213
+ | Grade de cartões selecionáveis | `hm-card-container` (`[items]`, `selection` none/single/multiple, `[(selected)]`, `minCardWidth`, `loading`; painel personalizável: `reorderable`, `hideable`, `persistKey` + `itemKey` de texto, `[(order)]`/`[(hidden)]`) |
214
+ | Propriedades editáveis (painel de inspeção) | `hm-property-view` (`[properties]: PropertyDefinition[]`, `groups`, `[(values)]`, `editable`, `searchable`) |
215
+ | Escolha entre poucas opções visíveis | `hm-segmented-control` (2–4) ou `hm-radio` (`layout="inline"` para lado a lado) |
216
+ | Várias respostas para a mesma pergunta | `hm-checkbox-group` (`[options]`, valor `string[]`, `fieldset`/`legend`, `hint`, `Validators.required` = ao menos uma, `layout="inline"`) — não monte com `hm-checkbox` soltos |
217
+ | Escolha que precisa de explicação (operações, planos) | `hm-radio` com `description`/`icon` por opção, `danger` na destrutiva, `disabledReason` na indisponível (em vez de esconder); `appearance="card"` para cartões |
218
+ | Valor numérico numa faixa / intervalo | `hm-slider` (`label` obrigatório, `min`/`max`/`step`, `range` para `[início, fim]`, `marks`, `showValue`) |
219
+ | Horário | `hm-time-picker` (`label` obrigatório, valor `'HH:mm'`, `min`/`max`, `interval` em minutos, `hourCycle`) |
220
+ | Escolher vários itens de uma lista grande, vendo o escolhido à parte | `hm-dual-list` (`[items]: DualListItem[]`, valor = ids escolhidos; busca de cada lado; `label` obrigatório) |
221
+ | Pessoa definir a ordem de itens | `hm-reorder-list` (`[(items)]: ReorderListItem[]`; arrasto pela alça e teclado; `(moved)`; template de item opcional; `removable` → `(removed)`, foco ao vizinho) |
222
+ | Envio de arquivos | `hm-file-upload` (`label` obrigatório, `accept`, `multiple`, `maxFiles`, `maxSize`, `maxTotalSize`, `[uploader]` opcional; seção 3) |
223
+ | Colar uma lista vinda de fora (planilha, chamado) | `hm-bulk-input` (`label` obrigatório; valor = `string[]` dos válidos; `validate` regex ou função que devolve o motivo; `max`, `separators`, `textCase`, `ignoreCaseDuplicates`; `(parsed)` com válidos/inválidos/duplicados). Não procura nada na base |
224
+ | Escolha numa lista longa | `hm-select` (nativo) ou `hm-combobox` (com filtro); múltipla: `hm-combobox-multi` |
225
+ | Texto livre com sugestões (datalist) | `hm-combobox` com `[allowCustomValue]="true"` (valor = texto digitado; opções só sugerem) |
226
+ | Filtros por campo acima de uma tabela, com fichas e filtros salvos | `hm-filter-bar` (`[filters]: FilterBarField[]`, `[(value)]`, `savedFilters` + `storageKey`, `[storage]` p/ servidor); ligar à grade: `filterBarToGridQuery`/`applyFilterBar` — receitas §14 |
227
+ | Número, e-mail, telefone, CPF/CNPJ/CEP | `hm-input` com `type` (`number`, `email`, `tel`…) e/ou `mask` (seção 3) |
228
+ | Itens escolhidos/filtros aplicados, removíveis | `hm-chip` (`removable` + `(removed)`; quem escuta tira o item e decide o foco) — não é status |
229
+ | Fichas de filtro liga/desliga | `hm-chip-group` (`label`, `[(value)]: string[]`, `[multiple]="false"` = única) com `<hm-chip value="x">`; avulsa: `hm-chip selectable [(selected)]` (`aria-pressed`) |
230
+ | Liga/desliga imediato | `hm-switch` (`hm-checkbox` é para formulário com envio) |
231
+ | Código de verificação | `hm-code-input` |
232
+ | Mensagem na página | `hm-alert` (`variant` info/success/warning/error; `heading`; ação por slot `[actions]` ou `link`/`linkLabel`; `dismissKey` lembra o fechamento; `size="small"` em painel/cartão/formulário) |
233
+ | Aviso do sistema no topo da tela | `hm-alert appearance="banner"`; vários avisos: `hm-alert-group` (um por vez, "1 de 3") |
234
+ | Mensagem flutuante | `HermesToastService.success/error/info/warning(msg)` (fica acima de menus e diálogos, `--hm-z-toast`); "Desfazer": `{ action: { label, run } }` nas opções (fica ≥ 10 s, pausa no foco/ponteiro) |
235
+ | Diálogo fixo no template | `hm-modal` com `[(open)]`, `heading` e slot `[footer]`; `[beforeClose]="fn"` (síncrona ou `Promise<boolean>`) segura X/Esc/fundo — ex.: "descartar alterações?"; `size` small/medium/large/`xlarge`/`full` (tela cheia, com área segura) |
236
+ | Fluxo em etapas que a pessoa conduz, num diálogo | `hm-wizard` + `hm-step` (`[(open)]`, `linear` ligado por padrão, Cancelar/Voltar/Avançar/Concluir prontos, `confirmCancel`, `loading`, `(completed)`/`(cancelled)`; `mode="page"` sem modal; `[summary]="true"` + `summary` em cada `hm-step` monta a revisão final) — receitas §10 |
237
+ | Indicador de etapas com o conteúdo na página | `hm-stepper` + `hm-step` (`[(selectedIndex)]`, `linear`, `orientation`, `readOnly`; `next()`/`previous()`/`goTo()`/`reset()`); validação por etapa com `stepControl` ou `canAdvance` no `hm-step` |
238
+ | Trilha de algo que anda sozinho (pedido, chamado) | `hm-timeline` + `hm-timeline-item` (`current`, `outcome` running/completed/failed, `date`, `status`) — não é navegação; para fluxo que a pessoa conduz, `hm-stepper` |
239
+ | Confirmação / diálogo aberto por código | `HermesDialogService.confirm({ heading, message, danger })` → `Promise<boolean>`; `open(Componente, { heading, data })` → `ref.closed` |
240
+ | Painel lateral | `hm-drawer` (`position` end/start/bottom; `pinned` = painel no layout, sem véu; `[beforeClose]` como no modal; `size` até `xlarge`/`full`) |
241
+ | Janela que flutua sobre a tela (mover, redimensionar, minimizar) | `hm-floating-window` (`heading` obrigatório, `[(open)]`, `width`/`height`, slots `[actions]`/`[footer]`) |
242
+ | Ação principal flutuante | `hm-fab` (`label` obrigatório, `icon`, `extended`, `[actions]: FabAction[]` vira speed dial → `(chosen)`) — uma por tela |
243
+ | Paleta de comandos (Ctrl/⌘ K) | `hm-command-palette` (`[commands]: HermesCommand[]`, `shortcut="Mod+K"`, `recentLimit`, `(executed)`) |
244
+ | Busca global (resultados do servidor) | `hm-global-search` (`[search]: HermesSearchFn`, `debounce`, `shortcut`, `(selected)`); o `hm-header` emite `(searchRequested)` |
245
+ | Carregando | `hm-skeleton` (shape text/list/card/cards), `hm-spinner` (`size`, `inverse`, `label` anunciado em `role="status"`), `hm-loading-square`, ou `loading` no botão |
246
+ | Progresso de uma tarefa | `hm-progress` (`value`/`max`, `showValue`, `indeterminate`, `intent`, `hint` "3 de 8"); `label` diz **o que** progride |
247
+ | Nome curto no hover/foco | diretiva `hmTooltip="texto"` em qualquer elemento (`hmTooltipSide`); não substitui o `label` do `hm-icon-button` |
248
+ | Ajuda que abre no clique | `hm-toggletip` (`label` = sobre o que é a ajuda, `text` ou conteúdo projetado; `intent="danger"` para aviso de grupo) |
249
+ | Tela vazia/erro/sem permissão | `hm-state-screen` (`situation`: `empty`, `success`, `error`, `attention`, `done`, `locked`, `unlocked`, `forbidden`, `not-found`, `session-expired`; cada uma já traz a ilustração, carregada sob demanda; outro desenho vai no slot `[illustration]`) ou `hm-state-page` (página pronta por `kind`: `not-found`, `no-content`, `no-rights`…, com título/descrição/ação do catálogo; sobrescreva por input) |
250
+ | Área vazia dentro de cartão, painel, coluna ou tabela | `hm-empty` (`heading`, `description`, `icon`, ações projetadas; `appearance="dashed"` para área que recebe conteúdo; `size="small"`; `headingLevel` quando abre seção). Não é erro: falha ao carregar é `hm-alert` |
251
+ | Contador | `hm-badge` · Etiqueta/status | `hm-tag` (`color` primary/info/success/warning/danger/neutral; `error` é o nome antigo, depreciado) |
252
+ | Ficha de leitura (termo/valor) | `hm-description-list` + `hm-description-item` (`term`, `value` ou conteúdo) ou `[items]`; `columns`; item com filhos = bloco expansível; `editable` = edição inline (`[(value)]` ou `(valueChange)`) |
253
+ | Configurações com OK/Cancelar e validação por seção | `hm-settings-dialog [closeHandler]` (`onSubmit`/`onCancel` → `Promise<boolean>`) + `hm-settings-section [control]` |
254
+ | Legenda de cores/status/séries | `hm-legend` (`[items]: LegendItem[]`, `marker` dot/square/line) |
255
+ | Copiar um valor | `hm-copy-button` (`value` e `label` obrigatórios; confirma "Copiado" sozinho) |
256
+ | Certificado X.509 (titular, validade, impressões digitais, cadeia) | `hm-certificate-viewer` (`[certificate]` ou `[chain]` do final `[0]` à raiz, `CertificateInfo` já interpretado pelo app — não faz parser de PEM; `headingLevel`, `warningDays`, `[(selectedIndex)]`); a mesma regra de validade em TS: `certificateValidity(notBefore, notAfter, { warningDays })` |
257
+ | Página de login | não é componente: classes `.hm-login` (`__panel`, `__brand`, `__title`, `__subtitle`, `__error` com `role="alert" tabindex="-1"`, `__form`, `__options`, `__actions`, `__divider`, `__footer`; `--split` + `__aside`/`__main`) com `hm-input autocomplete="username"`/`type="password"` e `hm-button type="submit"`; SSO = mesmo layout com um botão — site › Padrões › Página de login |
258
+ | Separador | `hm-divider` (`orientation`, `label`; `decorative` quando o traço é só visual) |
259
+ | Contêiner | `hm-card` (slots `[actions]`, `[footer]`, `[media]`; `media` + `mediaAlt` ou `mediaDecorative`, `mediaPosition` top/start/end) |
260
+ | Linha de lista de registros (arquivo, pessoa, integração) com ações | `hm-item` (`heading`, `description`, `icon` ou `[itemMedia]`, ações em `[itemActions]`; `link` para navegar, `clickable` + `(clicked)` para ação) dentro de `hm-item-group` (`role="list"`, `divided`, `label`). Linha com controle de preferência é `hm-settings-row` |
261
+ | Conversa / chat | `hm-message-scroller` (`label`, `role="log"`; `hasMoreHistory` + `(loadHistory)`; `scrollToEnd()` depois de enviar) > `hm-message` (`author`, `time`, `align="end"` para quem está usando, `status`, `grouped`) > `hm-bubble` (`variant`, `reactions`, `typing`); `hm-message-divider` para datas — receitas |
262
+ | Arquivo anexado (mensagem, formulário, envio) | `hm-attachment` (`name`, `size`, `type`, `thumbnail`, `status` + `progress`/`error`, `removable` → `(removed)`, `retryable` → `(retried)`) em `hm-attachment-group` (`layout` list/inline/grid, `label`); escolher arquivos é `hm-file-upload` |
263
+ | Campo de prompt (texto + botões dentro da moldura, Enter envia) | `hm-textarea` com `autoGrow` + `maxRows`, `submitKey="enter"`/`"mod-enter"` → `(submitted)` e botões em `<… hmTextareaActions>`/`hmTextareaActionsEnd` (`hmTextareaPrefix`/`Suffix` para ícones) — receitas |
264
+ | Área com rolagem própria / mídia com proporção fixa | classes `.hm-scroll-area` (`--x`/`--y`, `--stable`, altura em `--hm-scroll-area-max`; dê `tabindex="0"`, `role="region"` e `aria-label`) e `.hm-aspect-ratio` (`--1-1`/`--4-3`/`--16-9` ou `--hm-aspect-ratio`; `--contain`) |
265
+ | Gráfico (barras, linhas/área, pizza/rosca, mapa de calor, calendário, dispersão, medidor, funil, radar, treemap, sankey, caixa) | `@trismegisto/charts`: o tipado do caso (`hm-bar-chart`, `hm-line-chart`, `hm-pie-chart`…) com dados prontos (`categories` + `series`, ou `data`), `label` obrigatório (nome acessível e legenda da tabela), `description` com a conclusão, `numberFormat` (`Intl.NumberFormat`); a tabela de dados e o resumo para leitor de tela vêm sozinhos. `hm-chart` (opção crua do motor) só para o que os tipados não cobrem. Carregue a tela sob demanda (`@defer`/rota lazy) — receitas |
266
+ | Mapa (mundo/Brasil, coroplético, marcadores, GeoJSON) | `@trismegisto/maps` (`HM_MAP_COMPONENTS`): `<hm-map>` com `hm-map-basemap` (mapas base embutidos, sem serviço externo: `world/50m`, `br/ufs`…), `hm-map-choropleth` para valor por região, `hm-map-marker`/`hm-map-popup`/`hm-map-geojson`/`hm-map-polyline`/`hm-map-polygon`/`hm-map-circle`; tiles raster só se o app quiser, por `tileUrl` + a `attribution` que o provedor exige; `label` em todo mapa e marcador, cores por `colorProperty` (paleta `--hm-data-*`), `[scrollWheelZoom]="false"` em página longa — receitas §36. Não há mapa de ruas próprio |
267
+ | Saber se o componente está em `rtl` | `isRtl(elemento)` / `elementDirection()` de `@trismegisto/angular` na hora do gesto (não guarde o valor) |
268
+ | Indicador (um número) | `hm-stat-card` (`description`, `details`, `trend`, `hint`, `size`, `loading`; filtro: `selectable` + `[selected]` + `(selectedChange)`, controlado) |
269
+ | Várias métricas sob um título + "ver mais" | `hm-stat-group` (`heading`, `[metrics]: StatGroupMetric[]`, `moreLabel`/`moreLink`/`moreAction` + `(more)`, `loading`) |
270
+ | Avatar | `hm-account-avatar` (foto → iniciais → ícone genérico; `size` small/medium/large, `loading`) · Carrossel | `hm-carousel` |
271
+ | Várias pessoas (responsáveis, participantes) | `hm-avatar-group` (`[people]: AvatarGroupPerson[]`, `max` antes do "+N", `label` do grupo) |
272
+ | Atalho de teclado num botão/campo | diretiva `hmShortcut="Mod+S"` + `hmShortcutDescription` (+ `hmShortcutGroup`); vale enquanto o elemento existe; `Mod` = Ctrl/⌘ |
273
+ | Atalho sem elemento (ação global) | `inject(HermesShortcutService).register({ keys, description, group, handler })` → função que remove |
274
+ | Painel "atalhos de teclado" (o `?`) | `hm-shortcut-list` dentro de um `hm-modal` (lista os registrados + `[items]` declarados; `searchable`; `characterKeysToggle` — WCAG 2.1.4) — receitas §13 |
275
+ | Grid de layout | classes `.hm-row` + `.hm-col-{1..12}` / `.hm-col-{sm,md,lg,xl}-N`; `.hm-col-{bp}-auto` desfaz o span; `.hm-offset-{bp}-N` (começa na coluna N+1, conta do início da linha); `.hm-order-{bp}-{first,last,0..5}` (só visual — Tab e leitor seguem o HTML) |
276
+ | Pilha, linha que quebra, dois lados, coluna de leitura | classes `.hm-stack`, `.hm-cluster`, `.hm-split`, `.hm-center`, `.hm-container` (+ `.hm-gap-*`; alinhamento `.hm-align-{start,center,end,stretch,baseline}`, `.hm-justify-{start,center,end,between}`, `.hm-fill`) |
277
+ | Margem/padding sem SCSS | `.hm-{m,p}{,t,b,s,e,x,y}-{0,quarck,xs,sm,md,lg,xl,2xl,3xl}` (lógicos, `!important`) e `.hm-m{…}-auto`; entre irmãos prefira `.hm-gap-*` |
278
+ | Mostrar/ocultar por largura | `.hm-hide-{sm,md,lg,xl}-up` / `-down` (`display: none`, some também do leitor — só para versões alternativas do mesmo conteúdo) |
279
+ | Truncar, alinhar, caixa, texto secundário | `.hm-truncate` (1 linha), `.hm-truncate-{2..5}`/`.hm-truncate-lines` + `--hm-truncate-lines`; `.hm-text-{start,center,end,justify}`, `.hm-text-{upper,lower,capitalize}`, `.hm-text-muted`, `.hm-break-word`, `.hm-nowrap` |
280
+ | Reagir a zoom de 200%/400% (reflow) | `provideHermesZoom()` + `inject(HermesZoomService)` (`level()`, `zoomed()`); CSS com `.hm-zoom-x2`/`.hm-zoom-x4` no `<html>` (cumulativas) |
281
+ | Formulário (vertical/horizontal/compacto), grupos e barra de ações | classes `.hm-form` (`--horizontal` por container query, `--compact`), `.hm-fieldset` + `.hm-fieldset__legend`, `.hm-form-actions` (`--sticky` dentro de drawer/modal); legenda: `hm-form-required-hint` |
282
+ | Tabela estática | classe `.hm-table` (`--compact`, `--borderless`, `--vertical` = cabeçalho na 1ª coluna com `<th scope="row">`) |
283
+ | Texto só para leitor de tela | classe `.hm-visually-hidden` (do `@trismegisto/core`; não crie `sr-only` local) |
284
+ | Tamanho/peso de texto ou título visual sem SCSS | classes `.hm-text-*` e `.hm-heading-{1..6}` (seção 2) |
285
+ | Lista de conteúdo, código, tecla, bloco de código | classes `.hm-list` (`--compact`, `--unstyled`/`--inline` + `role="list"`), `.hm-code`, `.hm-kbd` (uma por tecla; combinação = `<kbd>` externo), `.hm-pre` (+ `tabindex="0" role="region" aria-label`); HTML de terceiros (Markdown): escopo `.hm-prose` |
286
+ | Texto do catálogo / data no idioma ativo, no template | pipes `hmTranslate`, `hmDate`, `hmDateTime` (receitas, seção de i18n) — seguem `setLocale` ao vivo |
287
+ | Cores de série de gráfico/mapa | tokens `--hm-data-categorical/sequential/diverging-*` (seção 2) |
288
+ | Número de destaque que conta até o valor | `hm-animated-number` (`[value]`, `[format]` = opções do `Intl.NumberFormat`, `duration`); não em tabela nem em valor que se atualiza sozinho |
289
+ | Itens que deslizam ao reordenar (lista, kanban, grade) | diretiva `[hmFlip]="lista()"` no contêiner (`hmFlipItems=".cartao"` para itens mais fundos; ou `#f="hmFlip"` + `f.capture()` antes de mudar o estado) |
290
+ | Bloco que aparece ao rolar (conteúdo editorial) | diretiva `hmReveal` (`[hmRevealDelay]` para escalonar); nunca em formulário/erro. Movimento: tudo respeita `prefers-reduced-motion` sozinho |
291
+ | Pessoa criar/ajustar uma família de cor do app | `hm-theme-builder` (`baseFamily`, `exportFormats`, `headingLevel`, `(draftChange)`); a regra de contraste em TS: `familyContrastChecks(draftContrastInput(draft))` (`@trismegisto/primitives`). Trocar entre famílias prontas é `hm-theme-picker` |
292
+
293
+ Inputs exatos de cada um: `angular-api.md`.
294
+
295
+ ## 5. Quando não existe componente
296
+
297
+ Hoje não há peça genérica conhecida faltando. **Não invente** um `hm-*` que não esteja em `angular-api.md`
298
+ (ou, para mapas e gráficos, nos pacotes `@trismegisto/maps`/`@trismegisto/charts`): o build quebra.
299
+
300
+ Se a peça de que você precisa não está no catálogo (por exemplo, algo de domínio do app, como a marca ou um
301
+ cartão de negócio), componha com os `hm-*` existentes e as classes utilitárias do `@trismegisto/core`; só crie
302
+ HTML/CSS próprio quando nem isso resolver.
303
+
304
+ Ao criar algo local assim: use apenas tokens, mantenha acessível (rótulo, foco visível, teclado) e marque com
305
+ `// TODO(hermes): substituir por hm-<nome> quando existir` para facilitar a migração.
306
+
307
+ Se você está **desenvolvendo o próprio design system** (não um app consumidor), este guia não basta: siga as
308
+ convenções do repositório dele.
309
+
310
+ ## 6. Depreciações e remoções
311
+
312
+ Na 1.0.0 tudo o que esta skill descreve está publicado. Ao migrar código de uma 0.x:
313
+
314
+ - **Scope**: código escrito para uma versão anterior com outro nome de pacote passa a importar de
315
+ `@trismegisto/angular` (e `@trismegisto/core`, `tokens`, `primitives`, `icons`): troque os nomes no
316
+ `package.json`, nos imports e nos `@use`. O prefixo `hm-` dos seletores e o `--hm-*` dos tokens não mudaram.
317
+ - **Removidos** (não compilam mais):
318
+ - `[control]` dos controles de formulário → `[formControl]`/`formControlName` (seção 3);
319
+ - `hm-mark` (marca) → o app desenha o próprio logotipo; `hm-opening-scene` agora só anima o conteúdo projetado;
320
+ - ilustrações `hm-illustration-file-upload`, `hm-illustration-file-transfer`, `hm-illustration-message` e as
321
+ situações `uploading`, `transfer` e `message` do `hm-state-screen` → use outra situação (ex.: `empty`) ou
322
+ projete outro desenho no slot `[illustration]`.
323
+ - **Depreciados** (ainda funcionam, com aviso em desenvolvimento; não use em código novo): `hm-field` → `hm-input`;
324
+ `help` → `hint`; `busy` → `loading` (botão); `hm-tag color="error"` → `"danger"`; `[startControl]`/`[endControl]`
325
+ e `start`/`end` do `hm-date-range-picker` → valor `DateRange`; slots `[atalhos]`/`[acoes]` do `hm-header` →
326
+ `[shortcuts]`/`[actions]`; `STATE_PAGE_PRESETS` (fixo em pt-BR) → `statePagePreset(kind, messages)`.
327
+ `angular-api.md` marca cada item depreciado.
328
+ - **Ilustrações** (modo adesivo) e páginas de estado (`hm-state-page`, inclusive `outdated`): `../SKILL.md` §5.
329
+
330
+ Ao atualizar a versão do pacote, confira `angular-api.md` e `angular-exports.md` (gerados do código da
331
+ versão) antes de reaproveitar código escrito para a versão anterior.
332
+
333
+ ## 7. Testes do app — harnesses
334
+
335
+ Para testar telas que usam o Hermes, use os harnesses de `@trismegisto/angular/testing` (CDK component harness,
336
+ o padrão do Angular Material). **Nunca** teste
337
+ por classe interna (`querySelector('.hm-field__control')`): o DOM da lib muda entre versões, o harness não.
338
+
339
+ - Instale `@angular/cdk` como `devDependency` do app (é peer **opcional** do `@trismegisto/angular`) e importe os
340
+ harnesses só em `.spec.ts`. A raiz `@trismegisto/angular` não os reexporta.
341
+ - Ache pelo que está na tela: campos `with({ label })`, `HermesButtonHarness.with({ text })` (no `hm-icon-button`,
342
+ o rótulo acessível), `HermesModalHarness.with({ heading })`, abas/menu `with({ label })`,
343
+ `HermesDataGridHarness.with({ caption })`.
344
+ - O que vai para o `<body>` (diálogo do `HermesDialogService`) pede
345
+ `TestbedHarnessEnvironment.documentRootLoader(fixture)`; combobox, `hm-menu-button` e filtro de coluna da grade
346
+ já procuram lá sozinhos.
347
+ - Métodos assíncronos que digitam/clicam como a pessoa: `setValue` (limpa e digita; chame `blur()` para marcar
348
+ tocado), `selectOption`, `check`/`uncheck`, `getErrorText`, `isInvalid`, `isRequired`; date picker no padrão do
349
+ idioma (`'15/03/2026'`, já faz o blur); grade: `getRows`, `getCellTextByIndex`, `getColumnTexts`, `sortBy`,
350
+ `search`, `filterColumn(título, termo | rótulos[])`, `goToPage`, `setPageSize`, `toggleSelectAll`, `row.select()`;
351
+ menu: `clickItem({ text: 'Exportar' }, { text: 'CSV' })` (item → subitem).
352
+
353
+ ```ts
354
+ const loader = TestbedHarnessEnvironment.loader(fixture);
355
+ const name = await loader.getHarness(HermesInputHarness.with({ label: 'Hostname' }));
356
+ await name.setValue('web-01');
357
+ await (await loader.getHarness(HermesButtonHarness.with({ text: 'Salvar' }))).click();
358
+ expect(await name.getErrorText()).toBe('');
359
+ ```
360
+
361
+ ## 8. Armadilhas conhecidas
362
+
363
+ - **Evento de botão é `(clicked)`**, não `(click)` (em `hm-button`, `hm-icon-button` e afins); a lista de
364
+ outputs de cada peça está em `angular-api.md`. O `clicked` **não carrega o evento** (não dá para chamar
365
+ `stopPropagation()` nele): botão dentro de linha clicável usa os dois juntos —
366
+ `(click)="$event.stopPropagation()"` só para conter o clique e a ação no `(clicked)`:
367
+ ```html
368
+ <hm-icon-button icon="trash" label="Excluir" intent="danger"
369
+ (click)="$event.stopPropagation()" (clicked)="excluir(linha)" />
370
+ ```
371
+ - **Ação destrutiva sem confirmação.** `intent="danger"` só pinta; a confirmação é
372
+ `await dialogs.confirm({ heading, message, danger: true })` (`HermesDialogService`) antes de chamar o serviço.
373
+ - **`[disabled]` em `hm-input`/`hm-select`/… ligado a `[formControl]`/`formControlName`**: o Angular avisa e o
374
+ controle segue habilitado no modelo. Desabilite pelo controle (`control.disable()`).
375
+ - **Skeleton no lugar de erro.** Falha ao carregar é `hm-alert variant="error"` com "Tentar novamente", não
376
+ skeleton eterno nem `hm-empty` (vazio é outra coisa).
377
+ - **Toast sem `<hm-toast-stack />` no shell não aparece.** Monte um só, na raiz, junto do único `hermesTheme`.
378
+ - **Menu dentro de overlay** (modal, drawer, janela flutuante): use `layer="above-invoker"` no `hm-menu`/
379
+ `hm-menu-button` (`hmContextMenuLayer` no `[hmContextMenu]`), senão o menu abre atrás do diálogo.
380
+ - **Ilustrações não saem da raiz**: `import { IllustrationErrorComponent } from '@trismegisto/angular'` não
381
+ compila. Use `hm-state-screen` (já carrega a ilustração) ou o ponto de import da ilustração.
382
+ - **`label=""` para satisfazer o tipo é bug de acessibilidade**: dê um rótulo real e use `labelHidden` se não
383
+ quiser mostrá-lo.
384
+ - **`Validators.required` não serve no `hm-date-range-picker`**: use `DateRangeValidators.required`/`.order`.
385
+ - **Ícone com nome errado não quebra o build**: vira ícone genérico com aviso `[hermes-icons]` no console. Confira
386
+ o nome no catálogo.
387
+ - **Não sobrescreva o DOM interno** (`.hm-btn__…`, `.hm-field__…`) nem teste por ele: muda entre versões. Ajuste
388
+ por input, slot ou token; teste por harness.
389
+ - **Gráficos pesam** (~215 kB gzip): carregue `@trismegisto/charts` sob demanda (`@defer` ou rota lazy).
390
+ - **Cor própria só por token**: um `#hex` no SCSS da tela não acompanha tema escuro, família nem alto contraste.