@acropole/skills 1.7.1 → 1.8.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 (42) hide show
  1. package/README.md +5 -4
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/package.json +1 -1
  4. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +2 -2
  5. package/skills/angular/SKILL.md +2 -2
  6. package/skills/angular/references/dados.md +3 -3
  7. package/skills/angular/references/estrutura.md +6 -5
  8. package/skills/angular/references/features.md +5 -5
  9. package/skills/angular/references/testes-build.md +1 -1
  10. package/skills/auto-servico/SKILL.md +18 -14
  11. package/skills/express/references/dados.md +4 -1
  12. package/skills/express/references/estrutura.md +2 -1
  13. package/skills/fastapi/references/banco.md +6 -2
  14. package/skills/fastapi/references/estrutura.md +1 -1
  15. package/skills/hefesto/SKILL.md +6 -2
  16. package/skills/orfeu/SKILL.md +43 -13
  17. package/skills/orfeu/references/angular-api.md +39 -13
  18. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  19. package/skills/orfeu/references/angular-recipes.md +25 -12
  20. package/skills/orfeu/references/angular.md +37 -15
  21. package/skills/orfeu/references/diferencas.md +17 -8
  22. package/skills/orfeu/references/node-api.md +41 -9
  23. package/skills/orfeu/references/node-armadilhas.md +16 -2
  24. package/skills/orfeu/references/node-recipes.md +13 -4
  25. package/skills/orfeu/references/node.md +31 -12
  26. package/skills/orfeu/references/python-api.md +41 -16
  27. package/skills/orfeu/references/python-recipes.md +13 -9
  28. package/skills/orfeu/references/python.md +33 -12
  29. package/skills/orfeu/references/react.md +133 -0
  30. package/skills/trismegisto/SKILL.md +42 -29
  31. package/skills/trismegisto/references/angular-api.md +608 -6
  32. package/skills/trismegisto/references/angular-exports.md +479 -791
  33. package/skills/trismegisto/references/angular-recipes.md +13 -7
  34. package/skills/trismegisto/references/angular.md +32 -9
  35. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  36. package/skills/trismegisto/references/catalogo/seletores.json +90 -65
  37. package/skills/trismegisto/references/react-api.md +16864 -0
  38. package/skills/trismegisto/references/react.md +237 -0
  39. package/skills/trismegisto/references/spine-api.md +5565 -1973
  40. package/skills/trismegisto/references/spine-recipes.md +113 -26
  41. package/skills/trismegisto/references/spine.md +95 -33
  42. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: trismegisto
3
- description: "Interface de apps Angular com o design system Trismegisto (@trismegisto/*, componentes hm-*, tokens --hm-*, ícones) e o shell @trismegisto/spine. Use ao criar ou alterar a parte visual de uma tela — formulário, listagem, modal, menu, navegação, tema/família/fonte/densidade, ícone, gráfico, mapa, texto de interface — e antes de escrever HTML/CSS próprio nesses apps. Estrutura do app, rotas, serviços de dados e build são da skill angular (numa tela nova use as duas); login e sessão, da orfeu."
3
+ description: "Interface de apps Angular e React com o design system Trismegisto (@trismegisto/angular, @trismegisto/react, componentes hm-*, tokens --hm-*, ícones), gráficos/mapas/terminal e o shell spine (@trismegisto/angular/spine, @trismegisto/react/spine, núcleo @trismegisto/spine), inclusive a migração da 3.3.x para a 3.4.0. Use ao criar ou alterar a parte visual de uma tela — formulário, listagem, modal, menu, navegação, tema/família/fonte/densidade, ícone, gráfico, mapa, texto de interface — e antes de escrever HTML/CSS próprio nesses apps. Estrutura do app, rotas, serviços de dados e build são da skill angular (numa tela nova use as duas); login e sessão, da orfeu."
4
4
  ---
5
5
 
6
- # Trismegisto — interface dos apps Angular
6
+ # Trismegisto — interface dos apps Angular e React
7
7
 
8
- O Trismegisto é o design system Angular publicado no npm sob o scope `@trismegisto` (no código as classes
8
+ O Trismegisto é o design system publicado no npm sob o scope `@trismegisto` (no código as classes
9
9
  ainda levam o nome histórico **Hermes**: `HermesThemeService`, `provideHermesIcons`…). Entrega componentes
10
- standalone com prefixo **`hm-*`**, tokens CSS **`--hm-*`** (cor, espaço, tipografia, movimento, camadas) em
10
+ Angular (standalone) e React 19 com o mesmo DOM **`hm-*`**, tokens CSS **`--hm-*`** (cor, espaço, tipografia, movimento, camadas) em
11
11
  tema claro/escuro, 12 famílias de cor, duas densidades e quatro fontes, textos próprios em pt-BR/en/es e
12
12
  acessibilidade (teclado, leitor de tela, alto contraste, `prefers-reduced-motion`) já resolvida.
13
13
 
@@ -16,7 +16,9 @@ Divisão de trabalho entre as skills:
16
16
  não repete isso.
17
17
  - **trismegisto** (esta) — tudo que é **interface**: qual componente usar, tokens, tema, shell.
18
18
  - **orfeu** — sessão, token, guard e logout do `@orfeu/angular` (o spine depende dele).
19
- - Interface em React (`@trismegisto/react`) ainda não é coberta.
19
+ - **React** (`@trismegisto/react`, desde a 3.4.0): mesmas peças e regras, outra forma de usar — `references/react.md`
20
+ (escolha entre Angular e React no §1 de lá). As regras de ouro (§3) valem para os dois; os exemplos em `hm-*` abaixo
21
+ são Angular.
20
22
 
21
23
  > **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/trismegisto/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
22
24
  >
@@ -24,40 +26,48 @@ Divisão de trabalho entre as skills:
24
26
 
25
27
  ## 1. Pacotes
26
28
 
27
- Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular ← (maps, terminal, charts, spine)`. Todos na
28
- **mesma versão** (`^3.3.11`); as 0.9.x foram retiradas do registry. Não há versão maior depois da 3.x: a lib segue na 3.3.x, e uma faixa `^2.x` não aceita a 3.x (major).
29
+ Camadas: `tokens ← icons ← primitives (+ núcleos charts, maps, terminal, spine) ← core ← angular · react`. Todos na
30
+ **mesma versão** (`^3.4.0`); não há versão maior depois da 3.x (uma faixa `^2.x` não aceita a 3.x).
29
31
 
30
- > **Atualizando um app** (vindo da 1.x, 2.x ou 3.x)? Siga o guia da skill `acropole`:
31
- > [../acropole/references/fluxos/atualizar-libs-2026-10.md](../acropole/references/fluxos/atualizar-libs-2026-10.md) — quebras da 2.0, o que a 2.1, a 3.x e a 3.3.1 mudam no app e os contornos de CSS a remover.
32
+ > **Vindo da 3.3.x?** Na 3.4.0 `charts`, `maps`, `terminal` e `spine` viraram núcleos sem framework e os componentes
33
+ > foram para pontos de import do `@trismegisto/angular`: migração em `references/angular.md` §9 (gráficos, mapas,
34
+ > terminal) e `references/spine.md` §11 (shell). Vindo da 1.x/2.x, antes: guia da skill `acropole`,
35
+ > [../acropole/references/fluxos/atualizar-libs-2026-10.md](../acropole/references/fluxos/atualizar-libs-2026-10.md).
32
36
 
33
37
  | Pacote | Para quê |
34
38
  |---|---|
35
39
  | `@trismegisto/tokens` | variáveis CSS `--hm-*`, famílias de cor (`HERMES_FAMILIES`), breakpoints em TS. Sem framework |
36
40
  | `@trismegisto/icons` | catálogo de ícones SVG 24×24 (`@trismegisto/icons/catalog`). Sem framework |
37
41
  | `@trismegisto/primitives` | lógica sem framework: tema (`extendThemeConfig`), i18n (catálogos, `formatMessage`), máscaras, datas, árvore… |
38
- | `@trismegisto/core` | CSS dos componentes e utilitários (`.hm-stack`, `.hm-row`, `.hm-text-*`, `.hm-visually-hidden`…) |
39
- | `@trismegisto/angular` | os componentes `hm-*`, diretivas, pipes, serviços (`HermesThemeService`, `HermesDialogService`, `HermesToastService`…) e harnesses de teste (`/testing`); também as peças de domínio genérico (workflow, pessoas, comércio, monitoramento… — §6) |
40
- | `@trismegisto/charts` | gráficos (`hm-bar-chart`, `hm-line-chart`…, sparkline, bullet, waterfall, bolhas, medidor animado) com tabela acessível. Pesado: carregue sob demanda |
41
- | `@trismegisto/maps` | mapas (`hm-map`, coroplético, marcadores e agrupamento, GeoJSON, rota, street view) com mapas base embutidos |
42
- | `@trismegisto/terminal` | terminal (`hm-terminal`: tema `--hm-terminal-*`, ajuste ao tamanho, busca, links) e a classe `Terminal` com a API no formato da do xterm.js (`FitAddon`, `SearchAddon`, `WebLinksAddon`): substitui o `@xterm/xterm`. Publicado desde a 3.3.9; use a 3.3.11 (os tokens `--hm-terminal-*` vêm desde a 3.3.10) |
43
- | `@trismegisto/spine` | o **shell pronto**: cabeçalho, menu lateral vindo do servidor de autorização (Argos), workspace em abas, barra da página, login/callback, modal/painel/toast por serviço, configurações, novidades, auditoria, cliente GraphQL. O app entrega só as telas |
42
+ | `@trismegisto/core` | CSS dos componentes e utilitários (`.hm-stack`, `.hm-row`, `.hm-text-*`, `.hm-visually-hidden`…), dos dois frameworks |
43
+ | `@trismegisto/angular` | os componentes `hm-*`, diretivas, pipes, serviços (`HermesThemeService`, `HermesDialogService`, `HermesToastService`…), harnesses (`/testing`), peças de domínio genérico (§6) e, **fora do barrel**, as cascas `@trismegisto/angular/charts`, `/map`, `/terminal` e `/spine[/sub]` |
44
+ | `@trismegisto/react` | os mesmos componentes em React 19 (`Button`, `Modal`…, mesmo DOM `hm-*`), providers e hooks no lugar dos serviços; fora do barrel, `@trismegisto/react/charts`, `/map`, `/terminal` e `/spine[/sub]` (`references/react.md`) |
45
+ | `@trismegisto/charts` | núcleo dos gráficos: tipos dos dados (`ChartSeries`…), montagem, catálogos e o motor (`/engine`). Componentes: `@trismegisto/angular/charts` (`hm-bar-chart`…) / `@trismegisto/react/charts`. Pesado: carregue sob demanda |
46
+ | `@trismegisto/maps` | núcleo dos mapas: projeção, GeoJSON, mapas base embutidos (`/basemaps/<id>`), rotas, catálogos. Componentes: `@trismegisto/angular/map` (`hm-map`…) / `@trismegisto/react/map` |
47
+ | `@trismegisto/terminal` | emulador com a API no formato da do xterm.js (`Terminal`, `FitAddon`, `SearchAddon`, `WebLinksAddon`; substitui o `@xterm/xterm`). Componente: `@trismegisto/angular/terminal` (`hm-terminal`) / `@trismegisto/react/terminal` |
48
+ | `@trismegisto/spine` | núcleo do **shell pronto** (rotas, acesso, menu, config, catálogos). Cabeçalho, menu lateral vindo do servidor de autorização (Argos), workspace em abas, login/callback, modal/painel/toast por serviço, configurações, auditoria, GraphQL: casca `@trismegisto/angular/spine[/sub]` (`references/spine.md`) ou `@trismegisto/react/spine[/sub]`. O app entrega só as telas |
44
49
 
45
- ## 2. Instalação (3.3.11)
50
+ **Peers opcionais:** `charts`, `maps`, `terminal`, `spine` (e, para o shell, `@orfeu/*`, `react-router`, Apollo/GraphQL,
51
+ `marked`, `dompurify`) são `peerDependencies` **opcionais** do `angular` e do `react`: não vêm sozinhos. Instale só o
52
+ que o app usa, na mesma versão; sem o núcleo, o import da casca não resolve. A casca reexporta só **tipos** do núcleo:
53
+ constante, função e classe do núcleo se importam do núcleo (`@trismegisto/charts`, `@trismegisto/spine/<módulo>`…).
54
+
55
+ ## 2. Instalação (Angular, 3.4.0)
46
56
 
47
57
  ```bash
48
58
  # sem shell pronto
49
59
  npm install @trismegisto/angular @trismegisto/core @trismegisto/tokens @trismegisto/primitives @trismegisto/icons
50
- # com o shell (app que autentica no Argos)
51
- npm install @trismegisto/spine @trismegisto/angular @trismegisto/core @trismegisto/tokens \
52
- @trismegisto/primitives @trismegisto/icons @orfeu/angular
53
- # opcionais, na mesma versão
60
+ # com o shell (app que autentica no Argos): + núcleo do spine, Orfeu e o Markdown das telas
61
+ npm install @trismegisto/angular @trismegisto/core @trismegisto/tokens @trismegisto/primitives \
62
+ @trismegisto/icons @trismegisto/spine @orfeu/angular marked dompurify
63
+ # opcionais, na mesma versão, só se usar a peça
54
64
  npm install @trismegisto/charts @trismegisto/maps @trismegisto/terminal
55
65
  ```
56
66
 
57
- Peers: Angular **≥ 21** (`core`, `common`, `forms`, `router`, `platform-browser`), `rxjs` `^7.8`.
58
- `@angular/cdk` é peer **opcional** (só os harnesses de `@trismegisto/angular/testing`; instale como
59
- `devDependency`). O spine pede ainda `@orfeu/angular` `^1.0.0` (**uma cópia só** no app) e, só se usar
60
- `@trismegisto/spine/graphql`, `@apollo/client` `^4.2`, `apollo-angular` `^14.2`, `graphql` `^16`, `graphql-ws` `^6`.
67
+ React: `references/react.md` §2. Peers Angular: **≥ 21** (`core`, `common`, `forms`, `router`, `platform-browser`),
68
+ `rxjs` `^7.8`. `@angular/cdk` é peer **opcional** (só os harnesses de `@trismegisto/angular/testing`; instale como
69
+ `devDependency`). O shell pede `@orfeu/angular` (**uma cópia só** no app) e, só se usar
70
+ `@trismegisto/angular/spine/graphql`, `@apollo/client` `^4.2`, `apollo-angular` `^14.2`, `graphql` `^16`, `graphql-ws` `^6`.
61
71
 
62
72
  `angular.json` → `styles`, nesta ordem:
63
73
 
@@ -95,7 +105,8 @@ registra ícones, tema e toasts — não repita).
95
105
  contém a propagação com `(click)="$event.stopPropagation()"` **junto** do `(clicked)` (a ação fica no
96
106
  `(clicked)`; o verificador aceita esse `(click)`).
97
107
  6. **Standalone e lazy:** importe a classe no `imports` do componente (não existe `HermesModule`); importe da
98
- raiz `@trismegisto/angular` ou do ponto da peça (`@trismegisto/angular/data-grid`). Gráficos, mapas e
108
+ raiz `@trismegisto/angular` ou do ponto da peça (`@trismegisto/angular/data-grid`); gráficos, mapas, terminal
109
+ e spine **só** pelo ponto (`@trismegisto/angular/charts`…), fora da raiz. Gráficos, mapas e
99
110
  telas pesadas em `@defer`/rota lazy.
100
111
  7. **Teste por harness** (`@trismegisto/angular/testing`), nunca por classe interna do DOM da lib.
101
112
  8. **Peças de domínio genérico só mostram e emitem** (§6): os dados entram por input e a intenção sai por
@@ -116,7 +127,7 @@ Usar só tokens e a escala `--hm-space-*` já faz a tela acompanhar tudo isso.
116
127
 
117
128
  - **Com spine:** nada a fazer — o `provideUi` aplica no `<body>`, prefixa as chaves com o `clientId` e a
118
129
  pessoa escolhe em Configurações › Aparência. Por código: `ThemeService`, `DensityService`,
119
- `ThemePresetService` (`@trismegisto/spine`).
130
+ `ThemePresetService` (`@trismegisto/angular/spine`).
120
131
  - **Sem spine:** um `hermesTheme` no elemento raiz + `HERMES_THEME_CONFIG`; troca por `HermesThemeService`
121
132
  (`setMode`, `setFamily`, `setDensity`, `toggle`); seletor pronto: `hm-theme-picker`.
122
133
 
@@ -178,7 +189,7 @@ import { HERMES_THEME_CONFIG } from '@trismegisto/angular';
178
189
  <hm-state-page kind="outdated" (actionTriggered)="recarregar()" /> <!-- window.location.reload() -->
179
190
  ```
180
191
  O spine já mostra `outdated` sozinho quando a rota não carrega por chunk ausente; em `import()` dinâmico
181
- próprio, detecte com `isChunkLoadError(err)` (`@trismegisto/spine/routing`). Em código, os textos:
192
+ próprio, detecte com `isChunkLoadError(err)` (`@trismegisto/angular/spine/routing`). Em código, os textos:
182
193
  `statePagePreset(kind, inject(HERMES_MESSAGES))` (o `STATE_PAGE_PRESETS` fixo em pt-BR saiu na 3.3.1).
183
194
  - **`hm-state-screen situation="…"`** — o bloco genérico (título/descrição/ação livres): `empty`, `success`,
184
195
  `error`, `attention`, `done`, `locked`, `unlocked`, `forbidden`, `not-found`, `session-expired`; outro
@@ -231,8 +242,10 @@ Antes de compor à mão, procure aqui. Receita em `references/angular-recipes.md
231
242
  | `references/angular-types.md` | Ao montar dados para um componente (`MenuItem`, `GridColumn`, `SidebarNode`, enums de variante) |
232
243
  | `references/angular-api.md` | Para conferir seletor, inputs/models/outputs, slots e métodos exatos de um `hm-*` (gerado do código; busque pelo seletor) |
233
244
  | `references/angular-exports.md` | Para conferir o nome/assinatura de serviço, função, constante, token ou tipo antes de importar, por ponto de import (gerado; busque pelo nome) |
234
- | `references/spine.md` | App com `@trismegisto/spine`: pontos de entrada, bootstrap (`provideUi`/`provideShell`/`provideAutoService`/`provideGraphql`), telas por `router_id`, `X-Route-Id`/`X-Client-Id`, GraphQL com `unwrap`, serviços do shell, auditoria, i18n, armadilhas |
245
+ | `references/spine.md` | App Angular com o shell (`@trismegisto/angular/spine` + núcleo `@trismegisto/spine`): pontos de entrada, casca × núcleo, migração da 3.3.x (§11), bootstrap (`provideUi`/`provideShell`/`provideAutoService`/`provideGraphql`), telas por `router_id`, `X-Route-Id`/`X-Client-Id`, GraphQL com `unwrap`, serviços do shell, auditoria, i18n, armadilhas |
235
246
  | `references/spine-recipes.md` | Receitas do spine: bootstrap completo, página pública, tela nova com documentação, serviço REST/GraphQL, subscription, modal/painel, auditoria lazy, seção de configurações, novidades, marca, alterações não salvas e skip link, testes |
236
- | `references/spine-api.md` | Para conferir exports exatos de cada `@trismegisto/spine/*` (gerado do código) |
247
+ | `references/spine-api.md` | Para conferir exports exatos da casca `@trismegisto/angular/spine/*` e de cada módulo do núcleo `@trismegisto/spine/*` (gerado do código) |
248
+ | `references/react.md` | App React: Angular ou React, setup, regra das props (`onX`, `x`/`defaultX`/`onXChange`, slots), gráficos/mapas/terminal, shell `@trismegisto/react/spine` com React Router v7 e `@orfeu/react` |
249
+ | `references/react-api.md` | Para conferir componentes, props (`XProps`), hooks e tipos de cada `@trismegisto/react/*` (gerado do código) |
237
250
 
238
251
  Os arquivos `*-api.md` e `angular-exports.md` são grandes: use busca por nome em vez de ler inteiros.