@acropole/skills 1.7.0 → 1.7.1

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.
@@ -24,11 +24,11 @@ Divisão de trabalho entre as skills:
24
24
 
25
25
  ## 1. Pacotes
26
26
 
27
- Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular ← (maps, charts, spine)`. Todos na
28
- **mesma versão** (`^2.1.2`); as 0.9.x foram retiradas do registry.
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
29
 
30
- > **Atualizando um app** (vindo da 1.x ou da 2.0.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 muda no app e os contornos de CSS a remover.
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
32
 
33
33
  | Pacote | Para quê |
34
34
  |---|---|
@@ -36,12 +36,13 @@ Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular
36
36
  | `@trismegisto/icons` | catálogo de ícones SVG 24×24 (`@trismegisto/icons/catalog`). Sem framework |
37
37
  | `@trismegisto/primitives` | lógica sem framework: tema (`extendThemeConfig`), i18n (catálogos, `formatMessage`), máscaras, datas, árvore… |
38
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`) |
40
- | `@trismegisto/charts` | gráficos (`hm-bar-chart`, `hm-line-chart`…) com tabela acessível. Pesado: carregue sob demanda |
41
- | `@trismegisto/maps` | mapas (`hm-map`, coroplético, marcadores, GeoJSON) com mapas base embutidos |
42
- | `@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, tour, auditoria, cliente GraphQL. O app entrega só as telas |
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 |
43
44
 
44
- ## 2. Instalação (2.1.2)
45
+ ## 2. Instalação (3.3.11)
45
46
 
46
47
  ```bash
47
48
  # sem shell pronto
@@ -50,7 +51,7 @@ npm install @trismegisto/angular @trismegisto/core @trismegisto/tokens @trismegi
50
51
  npm install @trismegisto/spine @trismegisto/angular @trismegisto/core @trismegisto/tokens \
51
52
  @trismegisto/primitives @trismegisto/icons @orfeu/angular
52
53
  # opcionais, na mesma versão
53
- npm install @trismegisto/charts @trismegisto/maps
54
+ npm install @trismegisto/charts @trismegisto/maps @trismegisto/terminal
54
55
  ```
55
56
 
56
57
  Peers: Angular **≥ 21** (`core`, `common`, `forms`, `router`, `platform-browser`), `rxjs` `^7.8`.
@@ -82,7 +83,11 @@ registra ícones, tema e toasts — não repita).
82
83
  no console. Confira em `@trismegisto/icons/catalog`.
83
84
  4. **i18n:** a lib traz os próprios textos (fechar, paginação, erros) em pt-BR/en/es; os rótulos que você
84
85
  passa são do i18n do app. Ao trocar de idioma, chame também `inject(HermesI18nService).setLocale(locale)`
85
- (o spine troca junto). Não monte texto da lib por concatenação.
86
+ (o spine troca junto). Não monte texto da lib por concatenação. As peças novas (§6) têm catálogo próprio
87
+ por pasta, que segue o idioma ativo; para trocar um texto numa instância, passe só as chaves no input
88
+ parcial da peça, que tem o mesmo nome em todas: `texts` (também nos recursos novos de peças antigas: edição do
89
+ `hm-data-grid`, menções do `hm-textarea`, reações do `hm-message`, mês do `hm-calendar`). Em campo de
90
+ formulário, `messages` continua sendo o texto por chave de erro (`{ required: '…' }`).
86
91
  5. **Acessibilidade:** todo controle tem `label` real (use `labelHidden` para esconder, nunca `label=""`);
87
92
  não aninhe interativo em interativo (`hm-card` não é clicável); landmarks com nome único; ação destrutiva
88
93
  com `intent="danger"` **e confirmação** (`HermesDialogService.confirm({ …, danger: true })`); evento de
@@ -93,7 +98,11 @@ registra ícones, tema e toasts — não repita).
93
98
  raiz `@trismegisto/angular` ou do ponto da peça (`@trismegisto/angular/data-grid`). Gráficos, mapas e
94
99
  telas pesadas em `@defer`/rota lazy.
95
100
  7. **Teste por harness** (`@trismegisto/angular/testing`), nunca por classe interna do DOM da lib.
96
- 8. **Estados da tela**: carregando (`hm-skeleton`), vazio (`hm-empty`) e erro (`hm-alert variant="error"` com
101
+ 8. **Peças de domínio genérico só mostram e emitem** (§6): os dados entram por input e a intenção sai por
102
+ output (`taskChange`, `eventChange`, `laneChange`, `transition`, `book`…); buscar, validar no servidor e
103
+ gravar é do app, que devolve o input atualizado. Edição é **opt-in** (`editable` no `hm-gantt` e no
104
+ `hm-event-calendar`, `allowLaneChange` no `hm-swimlane-board`): sem ela, nada muda para quem já usa.
105
+ 9. **Estados da tela**: carregando (`hm-skeleton`), vazio (`hm-empty`) e erro (`hm-alert variant="error"` com
97
106
  o botão "Tentar novamente") são três estados distintos; skeleton nunca fica no lugar de uma falha. Campo
98
107
  `hm-*` ligado a formulário reativo desabilita por `control.disable()`, não por `[disabled]` (skill
99
108
  `angular`).
@@ -170,7 +179,7 @@ import { HERMES_THEME_CONFIG } from '@trismegisto/angular';
170
179
  ```
171
180
  O spine já mostra `outdated` sozinho quando a rota não carrega por chunk ausente; em `import()` dinâmico
172
181
  próprio, detecte com `isChunkLoadError(err)` (`@trismegisto/spine/routing`). Em código, os textos:
173
- `statePagePreset(kind, inject(HERMES_MESSAGES))` (o `STATE_PAGE_PRESETS` fixo em pt-BR está depreciado).
182
+ `statePagePreset(kind, inject(HERMES_MESSAGES))` (o `STATE_PAGE_PRESETS` fixo em pt-BR saiu na 3.3.1).
174
183
  - **`hm-state-screen situation="…"`** — o bloco genérico (título/descrição/ação livres): `empty`, `success`,
175
184
  `error`, `attention`, `done`, `locked`, `unlocked`, `forbidden`, `not-found`, `session-expired`; outro
176
185
  desenho vai no slot `[illustration]`. Vazio **dentro** de cartão/tabela é `hm-empty`; falha ao carregar é
@@ -181,17 +190,49 @@ import { HERMES_THEME_CONFIG } from '@trismegisto/angular';
181
190
  da raiz (`@trismegisto/angular/illustration-error`…); prefira `hm-state-screen`/`hm-state-page`, que as
182
191
  carregam sob demanda.
183
192
 
184
- ## 6. Índice das referências (leia sob demanda)
193
+ ## 6. Famílias novas (lacunas e domínio genérico)
194
+
195
+ Antes de compor à mão, procure aqui. Receita em `references/angular-recipes.md`; inputs em `angular-api.md`
196
+ (gerado do código atual: se a peça não está lá, a versão instalada ainda não a tem).
197
+
198
+ | Família | Peças | Receita |
199
+ |---|---|---|
200
+ | Formatação e moeda | pipes `hmNumber`, `hmCurrency`, `hmPercent`, `hmRelativeTime`, `hmDuration`, `hmFileSize` (e `formatCurrency`… em TS); `hm-currency-input`, `hm-percent-input` | §39 |
201
+ | Data, hora e hierarquia | `hm-datetime-picker`, `hm-month-picker`, `hm-time-range`, `hm-tree-select(-multi)`, `hm-cascader` | §40 |
202
+ | Formulário acessível | `hm-form-error-summary` (`formErrorsFrom`), `HermesAnnouncer`/`[hmAnnounce]`, `hm-skip-link`, `hermesUnsavedChangesGuard`/`registerUnsavedChanges`, `hm-save-status`, `hm-anchor-nav` | §41 |
203
+ | Overlays e ações | `hm-popconfirm`, `hm-split-button`, `hm-tour`, `hm-bottom-sheet`, `hm-progress shape="circle"`, `hm-bottom-navigation` | §42 |
204
+ | Grade editável | `hm-data-grid` `editMode` + `hmCellEditor`, `treeChildren` (`treePagination`, `treeChildPageSize`), `columnGroups`, `striped` | §43 |
205
+ | Gráficos novos | `hm-sparkline-chart`, `hm-bullet-chart`, `hm-waterfall-chart`, bolhas (`size` no `hm-scatter-chart`), `hm-gauge-chart` animado | §44 |
206
+ | Campos e visualizadores | `hm-tag-input`, `hm-color-picker`, `hm-rating`; `hm-json-viewer`, `hm-log-viewer`, `hm-image-gallery`/`hm-lightbox`, `hm-pdf-viewer` | §45 |
207
+ | Workflow e tarefas | status, escalas, responsável, aprovação, prazo/SLA, tarefas, `hm-swimlane-board`, `hm-backlog`, `hm-workload`, `hm-workflow-editor`, `hm-gantt`, riscos | §46 |
208
+ | Pessoas e conta | `hm-entity-picker`, `hm-user-card`, `hm-member-list`, `hm-org-chart`, `hm-permission-matrix`, acesso; cadastro, senha, passkey, consentimento; presença, menções, reações | §47 |
209
+ | Calendário, arquivos, relatórios, dev | recorrência e edição no `hm-event-calendar`, `hm-slot-picker`, `hm-resource-calendar`; `hm-file-list`, versões, permissões, cota; `hm-report-schedule`; `hm-api-exchange`, `hm-feature-flags` | §48 |
210
+ | Comércio, pagamentos, finanças | produto, preço, `hm-cart`, pedido, entrega, devolução; meios de pagamento, `hm-payment-form`, fatura, planos, finanças | §49 |
211
+ | Monitoramento, integrações, mapas, entradas | saúde, incidentes, alertas, métricas, trace, deploy; integrações, webhooks, sincronização; `hm-map-cluster`, `hm-map-route`, `hm-street-view`; endereço `PostalAddress` + `hm-address-field`, placa, documentos | §50 |
212
+
213
+ - **Endereço é um só:** modelo `PostalAddress` (`@trismegisto/primitives`), campo `hm-address-field` (com
214
+ `hm-location-select`), exibição `hm-address-view`/`-card`/`-picker` (mesma `formatAddressLines`). Não crie tipo
215
+ de endereço próprio nem monte o texto à mão.
216
+ - **Signal Forms:** todo campo `hm-*` aceita `[formField]` (`@angular/forms/signals`) além dos três modos de
217
+ `references/angular.md` §3, inclusive os que têm validador próprio (número, moeda, documento, IBAN, placa,
218
+ endereço).
219
+ - **`hm-modal` deixa a página de trás `inert`** enquanto está aberto (e devolve ao fechar); não marque `inert`
220
+ nem `aria-hidden` à mão.
221
+ - **Exemplos integrados** (telas inteiras só com peças da lib, referência de implementação; site do Trismegisto ›
222
+ Componentes, aba Código): Calendar app, Org chart explorer, Projects app, Store app, Billing app, Ops console
223
+ app, People admin app, Files app, Developer portal — mapa em `references/angular-recipes.md` §51.
224
+
225
+ ## 7. Índice das referências (leia sob demanda)
185
226
 
186
227
  | Arquivo | Quando ler |
187
228
  |---|---|
188
229
  | `references/angular.md` | **Primeiro**, ao construir qualquer tela: setup sem spine, tokens em detalhe, formulários (Reactive/template/sem form), tabela "Preciso de… / Use", depreciações, harnesses, armadilhas |
189
- | `references/angular-recipes.md` | Ao montar um padrão completo: shell sem spine, listagem com data grid, formulário, wizard, filtros, kanban, árvore, agenda, upload, atalhos, login, theme builder, i18n/pipes, testes, gráficos e mapas (§1–§37) |
230
+ | `references/angular-recipes.md` | Ao montar um padrão completo: shell sem spine, listagem com data grid, formulário, wizard, filtros, kanban, árvore, agenda, upload, atalhos, login, theme builder, i18n/pipes, testes, gráficos e mapas (§1–§38); famílias novas e exemplos integrados (§39–§51) |
190
231
  | `references/angular-types.md` | Ao montar dados para um componente (`MenuItem`, `GridColumn`, `SidebarNode`, enums de variante) |
191
232
  | `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) |
192
233
  | `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) |
193
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 |
194
- | `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, testes |
235
+ | `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 |
195
236
  | `references/spine-api.md` | Para conferir exports exatos de cada `@trismegisto/spine/*` (gerado do código) |
196
237
 
197
238
  Os arquivos `*-api.md` e `angular-exports.md` são grandes: use busca por nome em vez de ler inteiros.