@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.
@@ -501,7 +501,7 @@ export class ResumosSettingsComponent {
501
501
  ```
502
502
 
503
503
  As seções do app aparecem depois das do spine e antes de "Sobre". Não repita as chaves de `SPINE_SETTINGS_KEYS`
504
- (`aparencia`, `acessibilidade`, `regiao`, `atalhos`, `ajuda`, `notificacoes`, `dados`, `conta`, `mfa`, `sessoes`,
504
+ (`aparencia`, `acessibilidade`, `regiao`, `atalhos`, `ajuda`, `notificacoes`, `dados`, `conta`, `mfa`, `sessoes`, `grupos`,
505
505
  `sobre`; `seguranca` é alias antigo de `mfa`). Abrir por código: `inject(SpineSettingsService).open('resumos')`.
506
506
 
507
507
  Antes de criar seção própria, veja se o spine já oferece (`SpineConfig.features`, `references/spine.md` §3.2):
@@ -510,25 +510,13 @@ inatividade, tela inicial, crachá padrão, atividade da conta e agente de IA ta
510
510
 
511
511
  ## 11. Novidades da versão
512
512
 
513
- ```ts
514
- import { provideSpineNews } from '@trismegisto/spine';
515
-
516
- provideSpineNews([
517
- {
518
- id: 'equipes-2026-10', // trocar o id faz reaparecer para todo mundo
519
- until: '2026-12-31', // opcional: some depois desta data
520
- slides: [
521
- {
522
- title: 'Equipes',
523
- text: 'Agora dá para organizar pessoas em equipes.',
524
- illustration: { icon: 'users', satellites: [{ icon: 'user', label: 'Membros' }] },
525
- },
526
- ],
527
- },
528
- ]),
529
- ```
530
-
531
- Abre sozinha uma vez por navegador (depois do tour) e fica no menu do perfil enquanto vigente.
513
+ Não ficam no código: quem administra o app cadastra no Argos (tela **Novidades** do auto-serviço, na raiz do menu, ou
514
+ a aba Novidades do cliente no painel central). Três tipos: **informativo** (só texto), **implementação** (abertura e a
515
+ lista "O que mudou") e **alteração** (antes e agora, lado a lado). Mais título, resumo, publicação (no futuro =
516
+ agendada), validade e público (grupos de acesso; vazio = todos). O spine lê de `argos-admin /me/news` com
517
+ `SPINE_ADMIN_API` (o `provideAutoService` já fornece): avisa uma vez por novidade na entrada, mostra "Novidades (N)" no
518
+ menu do perfil e o card do Início, e o painel lista por mês, com busca, "Não lidas" e "Favoritas" (no navegador).
519
+ Abrir por código: `inject(SpineNewsService).showAll()`.
532
520
 
533
521
  ## 12. Marca em componente
534
522
 
@@ -568,7 +556,26 @@ Trocar em tempo de execução (lib + spine juntos): `inject(HermesI18nService).s
568
556
  `inject(SpinePreferencesService).setLanguage('es')` para também salvar a escolha da pessoa. Ler um texto do
569
557
  spine em código: `inject(SPINE_MESSAGES).header.search`.
570
558
 
571
- ## 14. Testes de tela
559
+ ## 14. Tela com formulário: alterações não salvas e skip link
560
+
561
+ ```ts
562
+ // app.config.ts
563
+ provideUi({ clientId, features: { skipLink: true, unsavedChanges: true } }),
564
+ ```
565
+ ```ts
566
+ import { registerSpineUnsavedChanges } from '@trismegisto/spine/layout';
567
+
568
+ export class PedidoPage {
569
+ readonly form = new FormGroup({ /* … */ });
570
+ readonly #alteracoes = registerSpineUnsavedChanges(() => this.form.dirty); // presa à aba desta tela
571
+ salvar(): void { /* … grava; depois */ this.form.markAsPristine(); }
572
+ }
573
+ ```
574
+ No spine, use `registerSpineUnsavedChanges` (não o `hermesUnsavedChangesGuard` nas rotas): quem fecha a tela é a aba
575
+ do workspace, não a navegação. O resto do formulário segue `angular-recipes.md` §41 (resumo de erros, indicador de
576
+ salvamento, anúncio).
577
+
578
+ ## 15. Testes de tela
572
579
 
573
580
  As telas não dependem do layout: teste-as isoladas, trocando os serviços do spine por dublês.
574
581
 
@@ -9,7 +9,7 @@ O spine é o **esqueleto pronto** de um app Angular: cabeçalho (marca, busca de
9
9
  tema, perfil), menu lateral montado da árvore de rotas do servidor de autorização (Argos), área de trabalho
10
10
  em abas (`hm-workspace`), barra da página (título, descrição, trilha, favoritar, copiar link, documentação),
11
11
  telas de login/callback/saída/sem permissão/bloqueado, modal, painel lateral e toasts por serviço, painel
12
- de configurações, tour de boas-vindas, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
12
+ de configurações, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
13
13
  vem do spine.
14
14
 
15
15
  Ele fica na ponta da cadeia `tokens ← icons ← primitives ← core ← angular ← spine` e é **acoplado à
@@ -29,7 +29,7 @@ Se as telas tiverem documentação (`document.load` com `import('./README.md')`)
29
29
 
30
30
  | Import | Para quê |
31
31
  |---|---|
32
- | `@trismegisto/spine` | `provideUi`, `SpineConfig`/`SPINE_CONFIG`, `Route` + `routerIdOf`, `applyRuntimeEnvironment`, `SPINE_ADMIN_API`, `provideSpineNews`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, catálogos), `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, logo/favicon (`SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon`) |
32
+ | `@trismegisto/spine` | `provideUi`, `SpineConfig`/`SPINE_CONFIG`, `Route` + `routerIdOf`, `applyRuntimeEnvironment`, `SPINE_ADMIN_API`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, catálogos), `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, logo/favicon (`SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon`) |
33
33
  | `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
34
34
  | `@trismegisto/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`, resolução de cadeia (`resolveRouteChain`, `findFirstNavigable`…) |
35
35
  | `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `OnboardingService`, `ShortcutService` e as peças do layout |
@@ -114,8 +114,9 @@ export const appConfig: ApplicationConfig = {
114
114
 
115
115
  O que cada provider faz:
116
116
 
117
- - **`provideUi(config?: SpineConfig)`** — registra o catálogo de ícones **inteiro** (`HERMES_ICONS`; o app
118
- não precisa de `provideHermesIcons`), aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
117
+ - **`provideUi(config?: SpineConfig)`** — registra os ícones do próprio spine (`SPINE_ICONS`) e carrega o catálogo
118
+ inteiro **sob demanda** (`provideHermesIconLoader`, desde a 3.3.1): ícone do app não registrado aparece quando o
119
+ chunk chega (para desenhar já no 1º quadro, `provideHermesIcons(...)` com os do app); aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
119
120
  fornece `SPINE_CONFIG` e usa `hermes_<clientId>` como prefixo de **todas** as chaves salvas (tema, menu
120
121
  lateral, abas do workspace, idioma, fuso, novidades, favoritos…): apps na mesma origem não misturam
121
122
  preferências. Aplica `favicon` no bootstrap se configurado. Opções de `SpineConfig`:
@@ -135,13 +136,15 @@ O que cada provider faz:
135
136
 
136
137
  | Campo | O que liga |
137
138
  |---|---|
138
- | `aiAgent: { servers: SpineMcpServer[] }` | Sessões › "Conectar um agente de IA": token de aplicação + `.mcp.json` pronto (precisa de `SPINE_ADMIN_API`) |
139
+ | `mcpConnect: { servers: SpineMcpServer[] }` | Sessões › "Conectar um agente de IA": token de aplicação + `.mcp.json` pronto (precisa de `SPINE_ADMIN_API`). `onlyBadges`/`exceptBadges` em cada servidor (nome do badge) mostram só os servidores do nível da pessoa; com um só, sem seletor |
139
140
  | `accountActivity: true` | MFA › "Atividade da conta": entradas e tentativas que falharam (últimos 90 dias) |
140
141
  | `idleTimeout: true \| { min?, max? }` | Conta › "Encerrar por inatividade" (com `max`, some o "Nunca") |
141
142
  | `startPage: true` | Conta › "Tela inicial" depois do login: início, um favorito ou a última tela |
142
143
  | `defaultBadge: true` | Conta › "Crachá padrão" (nível de acesso do login, guardado no Argos) |
143
144
  | `notices: { types: SpineNoticeType[] }` | seção Notificações: liga/desliga cada tipo de aviso e o aviso do navegador; o app emite com `SpineNoticesService.notify(tipo, { title, body?, url?, intent? })` (`@trismegisto/spine/layout`) |
144
145
  | `accountPreferences: true` | guarda as preferências (aparência, região, acessibilidade, favoritos, tela inicial…) também na conta do Argos |
146
+ | `skipLink: true` | link "Pular para o conteúdo" (`hm-skip-link`) como primeira parada do Tab, levando à área de trabalho |
147
+ | `unsavedChanges: true` | aviso de alterações não salvas: a tela registra com `registerSpineUnsavedChanges(() => form.dirty)` (`@trismegisto/spine/layout`, num campo da classe); fechar a aba/painel dela ou trocar de tela dentro dela pergunta antes, e o navegador avisa ao recarregar |
145
148
 
146
149
  - **`provideRouter(APP_ROUTES)`** — `APP_ROUTES` = `PUBLIC_ROUTES` (`/login`, `/callback`, `/logoff`,
147
150
  `/blocked`, `''` → `login`) + `{ path: '', component: LayoutComponent, canActivate/canActivateChild:
@@ -157,10 +160,16 @@ O que cada provider faz:
157
160
  se um `id` do app repetir um id das telas base do shell.
158
161
  - **`provideAutoService({ adminApi })`** — liga as 6 telas do auto-serviço (Início, Grupos, Aplicações,
159
162
  Cliente, Auditoria, Tentativas de login) pelo `source_template_router_id` do template do Argos, todas **lazy**, e fornece
160
- `SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação). O app não declara
161
- nada disso em `features.routes.ts`: basta o client estar vinculado ao template de auto-serviço no Argos.
162
- Sem auto-serviço, o painel de configurações ainda pode listar tokens se o app fornecer
163
- `{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essa parte se esconde.
163
+ `SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação e para a seção
164
+ **Grupos**). O app não declara nada disso em `features.routes.ts`: basta o client estar vinculado ao template de
165
+ auto-serviço no Argos. Sem auto-serviço, o painel de configurações ainda pode listar tokens e grupos se o app
166
+ fornecer `{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essas partes se escondem.
167
+ - **Seção Grupos** (desde a 3.2.0, `?settings=grupos`): vem pronta, sem nada no app. Lista os grupos da aplicação
168
+ logada de que a pessoa é membro (argos-admin `/me/groups`); cada um abre a tela de membros. A **função** no grupo
169
+ (não o crachá) decide: Administrador inclui como Administrador, Editor ou membro, troca funções e remove qualquer
170
+ um menos a si mesmo; Editor inclui e remove só membros sem função; o membro sem função só vê. A regra é do
171
+ argos-admin; a seção some sem grupo nenhum ou com um argos-admin que ainda não tem a rota. A lista de membros é
172
+ carregada inteira em páginas de 200 do servidor, uma depois da outra, com a busca local (desde a 3.3.4).
164
173
  - **`provideGraphql({ endpoints })`** — um cliente Apollo nomeado por backend (seção 6).
165
174
 
166
175
  ### 3.3 Componente raiz
@@ -171,9 +180,9 @@ export class AppComponent {}
171
180
  ```
172
181
 
173
182
  Só isso. O tema já está no `<body>`: **não** ponha `hermesTheme`, `hm-header`, `hm-sidebar` nem
174
- `hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace,
175
- `spine-notification`, `spine-modal`, `spine-side-panel`, painel de atalhos, configurações, documentação,
176
- novidades e tour.
183
+ `hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace, a pilha de
184
+ toasts (`hm-toast-stack`, onde saem o `NotificationService` e o `HermesToastService`), `spine-modal`,
185
+ `spine-side-panel`, painel de atalhos, configurações, documentação e novidades.
177
186
 
178
187
  ### 3.4 Sessão e aviso de conexão (`@orfeu/angular`)
179
188
 
@@ -283,7 +292,7 @@ async listTeams() {
283
292
 
284
293
  | Preciso de… | Use |
285
294
  |---|---|
286
- | Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos. `processErrorNotification()` = erro genérico do catálogo |
295
+ | Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos e sai na pilha de toasts do `HermesToastService` (3.3.0; antes era uma coluna de `hm-alert` à parte). `processErrorNotification()` = erro genérico do catálogo |
287
296
  | Modal com componente | `ModalService.open<R, D>({ title, component, data, size: 'sm'\|'md'\|'lg'\|'xl', closable, showActions })` → `Observable<R \| null>` (`null` = cancelado/substituído). O componente implementa `ModalContent` (`getResult()`, `isValid?()`), recebe `data` por `readonly data = input<D>()` e o botão Confirmar fica desabilitado enquanto `isValid()` for falso. Só um aberto por vez |
288
297
  | Modal só texto | `ModalService.open({ title, text })` |
289
298
  | Painel lateral | `SidePanelService.open(...)` — mesma API (`SidePanelContent` = `ModalContent`), `size` aceita também `'full'` |
@@ -291,7 +300,7 @@ async listTeams() {
291
300
  | Diálogo de confirmação simples | `HermesDialogService.confirm(...)` do `@trismegisto/angular` (não precisa do spine) |
292
301
  | Abrir configurações | `SpineSettingsService.open(SPINE_SETTINGS_KEYS.appearance)` ou link `?settings=aparencia` |
293
302
  | Abrir documentação | `SpineDocsService.openIndex()` / `openForRoute(routerId)` |
294
- | Reabrir tour / novidades | `OnboardingService.restart()` / `SpineNewsService.showAll()` |
303
+ | Reabrir novidades | `SpineNewsService.showAll()` (tour guiado de uma tela: `hm-tour`, do `@trismegisto/angular`; o spine não tem tour próprio) |
295
304
  | Fuso e idioma da pessoa | `SpinePreferencesService.effectiveTimeZone()` (sinal; IANA) e `language()`; também `hourCycle()`, `weekStart()`, `textScale()`, `motion()` |
296
305
  | Avisar a pessoa de um acontecimento | `SpineNoticesService.notify('tipo', { title, body?, url? })` com o tipo declarado em `SpineConfig.features.notices` — respeita o liga/desliga de Configurações › Notificações |
297
306
  | Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/spine/routing`) |
@@ -346,7 +355,7 @@ sozinho no painel `?`. Não reuse essas combinações.
346
355
  2. **Telas sempre lazy.** `ComponentRoute.load` é `() => import('./x.component').then((m) => m.X)`. Nunca
347
356
  importe a classe de uma tela estaticamente em `features.routes.ts`, `app.config.ts` ou serviço global.
348
357
  Um `features.routes.spec.ts` confere que todo `load()` resolve e que os `id` são UUID únicos, sem
349
- diferenciar maiúsculas (receitas §14).
358
+ diferenciar maiúsculas (receitas §15).
350
359
  3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/spine/audit` em código do bundle
351
360
  inicial (só em rota/`import()`/`@defer`). As telas do auto-serviço nem são exportadas; não tente
352
361
  alcançá-las por caminho interno. (O pacote confere isso no próprio build com `scripts/check-lazy.mjs`: um
@@ -355,7 +364,7 @@ sozinho no painel `?`. Não reuse essas combinações.
355
364
  4. **`COMPONENT_ROUTES` é `multi`.** Contribua pelo `provideShell` (ou com `{ provide: COMPONENT_ROUTES,
356
365
  useValue: [...], multi: true }`). Sem `multi: true` o Angular lança erro de provider inconsistente.
357
366
  5. **Id da tela = `router_id`** (`routerIdOf`). `routed_id`/`web.routes.route_id` não acha componente; é o que
358
- vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` são nomes antigos depreciados (use `id`/`load`).
367
+ vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` saíram na 3.3.1 (use `id`/`load`).
359
368
  6. **Uma cópia do `@orfeu/angular`.** App e spine precisam resolver o mesmo pacote; duas cópias (versões
360
369
  diferentes, `file:` duplicado, SDK antigo no app) dão `NullInjectorError` em `AUTH_CONFIG` ou uma segunda
361
370
  sessão. Confira com `npm ls @orfeu/angular`.
@@ -367,11 +376,12 @@ sozinho no painel `?`. Não reuse essas combinações.
367
376
  troca de aba (`keepAlive`): recarregue dados por ação da pessoa, `wsReconnected$` ou sinal, não por
368
377
  `ngOnInit` a cada visita.
369
378
  10. **Envelope GraphQL sempre por `unwrap`.** Não confie no HTTP 200.
370
- 11. **Detecção de mudanças:** os apps de referência usam `provideZoneChangeDetection`; parte do shell ainda usa
371
- a estratégia `Eager` e `NgZone`. Funcionamento sem zone.js não é garantido.
379
+ 11. **Detecção de mudanças:** desde a 3.3.1 todo o shell é `OnPush` (os apps de referência usam
380
+ `provideZoneChangeDetection`). Tela e componente aberto no `ModalService`/`SidePanelService` ficam sob pai
381
+ `OnPush`: estado que muda depois de `await`/`subscribe` vai em signal (ou `markForCheck()`).
372
382
  12. **Documentação de tela** é markdown cru importado como texto (loader `.md: "text"`); o texto vai no chunk
373
383
  da tela e o índice só lista telas que a pessoa enxerga.
374
- 13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e tour.
384
+ 13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e novidades vistas.
375
385
  14. **Logo** é arquivo do app (`src/assets/images/logo.svg` por convenção), legível sobre o fundo escuro do
376
386
  cabeçalho **nos dois temas**; marca em componente via `SPINE_BRAND` (sem link/botão dentro).
377
387