@acropole/skills 0.0.0-stage → 1.0.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 (90) hide show
  1. package/README.md +180 -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 +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,581 @@
1
+ # Receitas — @trismegisto/spine 1.0.0
2
+
3
+ Padrões prontos para um app que usa o spine. Todos os componentes são standalone (importe as classes no
4
+ `imports`). Os componentes `hm-*` usados no conteúdo das telas são do `@trismegisto/angular` — a API deles está
5
+ em `angular.md` e `angular-api.md`. Nomes como `MeuApp`, `principal`,
6
+ `Equipes` e os UUIDs são exemplos: troque pelos do seu app.
7
+
8
+ ## 1. Bootstrap completo
9
+
10
+ `src/environments/environment.ts` (valores `CHANGE_ME` são derivados em tempo de execução por
11
+ `applyRuntimeEnvironment` quando o app está atrás de proxy, sem porta na URL):
12
+
13
+ ```ts
14
+ import type { GraphqlEndpoint } from '@trismegisto/spine/graphql';
15
+
16
+ export const environment = {
17
+ production: false,
18
+ adminApi: 'https://auth.exemplo.com/argos/admin/api',
19
+ authorizationServer: {
20
+ authority: 'https://auth.exemplo.com/argos',
21
+ realmId: '<realmId do app no Argos>',
22
+ clientId: '<clientId do app no Argos>',
23
+ redirectUrl: 'CHANGE_ME', // derivado: <origem><base href>/callback
24
+ postLogoutRedirectUri: 'CHANGE_ME', // derivado: <origem><base href>/logoff
25
+ scope: 'openid profile email offline_access',
26
+ },
27
+ graphql: {
28
+ principal: { namedClient: 'principal', http: 'CHANGE_ME', ws: 'CHANGE_ME' },
29
+ } satisfies Record<string, GraphqlEndpoint>,
30
+ };
31
+ ```
32
+
33
+ `src/main.ts`:
34
+
35
+ ```ts
36
+ import { bootstrapApplication } from '@angular/platform-browser';
37
+ import { applyRuntimeEnvironment } from '@trismegisto/spine';
38
+ import { AppComponent } from './app/app.component';
39
+ import { appConfig } from './app/app.config';
40
+ import { environment } from './environments/environment';
41
+
42
+ applyRuntimeEnvironment(environment);
43
+ bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
44
+ ```
45
+
46
+ `src/app/app.config.ts`:
47
+
48
+ ```ts
49
+ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
50
+ import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
51
+ import { provideRouter } from '@angular/router';
52
+ import { provideAuth } from '@orfeu/angular/core';
53
+ import { provideUi } from '@trismegisto/spine';
54
+ import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
55
+ import { provideAutoService } from '@trismegisto/spine/auto-service';
56
+ import { provideGraphql } from '@trismegisto/spine/graphql';
57
+ import { components } from './features/features.routes';
58
+ import { environment } from '../environments/environment';
59
+ import packageInfo from '../../package.json';
60
+
61
+ export const appConfig: ApplicationConfig = {
62
+ providers: [
63
+ provideZoneChangeDetection({ eventCoalescing: true }),
64
+ provideHttpClient(withInterceptorsFromDi()),
65
+ provideUi({
66
+ clientId: environment.authorizationServer.clientId,
67
+ appName: 'Meu App',
68
+ logo: { light: 'assets/images/logo.svg', dark: 'assets/images/logo-dark.svg' },
69
+ favicon: 'assets/favicon.ico',
70
+ technicalDocs: !environment.production,
71
+ }),
72
+ provideRouter(APP_ROUTES),
73
+ provideAuth(environment.authorizationServer),
74
+ provideAutoService({ adminApi: environment.adminApi }),
75
+ provideShell({ appComponents: components, packageInfo }),
76
+ provideGraphql({ endpoints: environment.graphql }),
77
+ ],
78
+ };
79
+ ```
80
+
81
+ `src/app/app.component.ts`:
82
+
83
+ ```ts
84
+ import { Component } from '@angular/core';
85
+ import { RouterOutlet } from '@angular/router';
86
+
87
+ @Component({ selector: 'app-root', imports: [RouterOutlet], template: '<router-outlet />' })
88
+ export class AppComponent {}
89
+ ```
90
+
91
+ `angular.json` (trechos de `architect.build.options`):
92
+
93
+ ```json
94
+ "assets": [{ "glob": "**/*", "input": "src/assets", "output": "assets" }],
95
+ "styles": [
96
+ "node_modules/@trismegisto/tokens/dist/tokens.css",
97
+ "node_modules/@trismegisto/core/dist/core.css",
98
+ "src/styles.scss"
99
+ ],
100
+ "loader": { ".md": "text" }
101
+ ```
102
+
103
+ `tsconfig.json`: `"resolveJsonModule": true` (para o `package.json`). `src/markdown.d.ts`:
104
+
105
+ ```ts
106
+ declare module '*.md' {
107
+ const content: string;
108
+ export default content;
109
+ }
110
+ ```
111
+
112
+ Arquivos de marca: `src/assets/images/logo.svg` (legível sobre o cabeçalho escuro), opcional
113
+ `logo-dark.svg`, e `src/assets/favicon.ico`.
114
+
115
+ ## 2. Rotas com uma página pública em `/`
116
+
117
+ `APP_ROUTES` manda `/` para o login. Para ter uma página pública antes dele, componha as mesmas peças:
118
+
119
+ ```ts
120
+ import { Routes } from '@angular/router';
121
+ import { PrivateGuard } from '@orfeu/angular/core';
122
+ import { LayoutComponent } from '@trismegisto/spine/layout';
123
+ import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/spine/shell';
124
+
125
+ export const ROUTES: Routes = [
126
+ { path: '', pathMatch: 'full', loadComponent: () => import('./public/landing.component').then((m) => m.LandingComponent) },
127
+ ...PUBLIC_ROUTES,
128
+ {
129
+ path: '',
130
+ component: LayoutComponent,
131
+ canActivate: [PrivateGuard],
132
+ canActivateChild: [PrivateGuard],
133
+ children: PRIVATE_ROUTES,
134
+ },
135
+ { path: '**', redirectTo: '' },
136
+ ];
137
+ ```
138
+
139
+ No `app.config.ts`: `provideRouter(ROUTES)` e `provideAuth(environment.authorizationServer, { eagerInit: false })`
140
+ (a página pública não espera a renovação de sessão; o `PrivateGuard` cuida disso na primeira rota privada).
141
+ A ordem importa: a rota pública vem antes de `PUBLIC_ROUTES` (que tem `'' → login`).
142
+
143
+ ## 3. Tela nova, ligada pelo `router_id`
144
+
145
+ 1. No Argos, crie a rota e o **router** da tela (com descrição — é ela que aparece na barra da página) e dê
146
+ acesso aos grupos. Anote o `router_id` do router (o do client, não o `route_id` da rota).
147
+ 2. Crie a tela **sem** cabeçalho próprio (título e descrição vêm do router):
148
+
149
+ ```ts
150
+ // src/app/features/equipes/equipes.component.ts
151
+ import { ChangeDetectionStrategy, Component } from '@angular/core';
152
+
153
+ @Component({
154
+ selector: 'app-equipes',
155
+ changeDetection: ChangeDetectionStrategy.OnPush,
156
+ template: `<!-- direto ao conteúdo: barra de ferramentas, filtros, grade… -->`,
157
+ })
158
+ export class EquipesComponent {}
159
+ ```
160
+
161
+ 3. Registre por `id` = `router_id`, sempre com `import()` (code-splitting por tela):
162
+
163
+ ```ts
164
+ // src/app/features/features.routes.ts
165
+ import { ComponentRoute } from '@trismegisto/spine/routing';
166
+
167
+ export const components: ComponentRoute[] = [
168
+ {
169
+ id: '3f2a9c10-0000-4000-8000-000000000001', // router_id da tela "Equipes"
170
+ load: () => import('./equipes/equipes.component').then((m) => m.EquipesComponent),
171
+ document: {
172
+ load: () => import('./equipes/README.md').then((m) => m.default), // manual de uso
173
+ loadTechnical: () => import('./equipes/ESPECIFICACAO.md').then((m) => m.default), // só com technicalDocs
174
+ // title/group opcionais: sem eles valem o nome da rota e o módulo na árvore
175
+ },
176
+ },
177
+ ];
178
+ ```
179
+
180
+ A tela aparece no menu lateral, na busca (`Mod+K`), na barra da página com título/descrição/trilha e no
181
+ índice de documentação — tudo a partir da árvore do Argos. Sem acesso à tela, ela some de tudo (inclusive do
182
+ índice de documentação).
183
+
184
+ Sem entrada para um router que existe na árvore, o painel mostra "tela não publicada" com o código — é assim
185
+ que se descobre um `id` errado.
186
+
187
+ ## 4. Serviço REST (token + cabeçalhos de correlação)
188
+
189
+ ```ts
190
+ import { HttpClient, HttpHeaders } from '@angular/common/http';
191
+ import { Injectable, inject } from '@angular/core';
192
+ import { firstValueFrom } from 'rxjs';
193
+ import { AuthorizationService } from '@orfeu/angular/core';
194
+ import { environment } from '../../environments/environment';
195
+
196
+ export interface Equipe { id: string; nome: string; membros: number }
197
+
198
+ @Injectable({ providedIn: 'root' })
199
+ export class EquipesService {
200
+ private readonly http = inject(HttpClient);
201
+ private readonly auth = inject(AuthorizationService);
202
+
203
+ private get headers(): HttpHeaders {
204
+ return new HttpHeaders({ 'x-access-token': this.auth.getToken() ?? '' });
205
+ }
206
+
207
+ listar(): Promise<Equipe[]> {
208
+ // X-Route-Id e X-Client-Id entram sozinhos (RouteIdInterceptor, com withInterceptorsFromDi()).
209
+ return firstValueFrom(this.http.get<Equipe[]>(`${environment.apiUrl}/equipes`, { headers: this.headers }));
210
+ }
211
+ }
212
+ ```
213
+
214
+ ## 5. Serviço GraphQL com envelope e a tela com estados
215
+
216
+ ```ts
217
+ // equipes.service.ts — ListEquipesDocument/CriarEquipeDocument: TypedDocumentNode gerados pelo codegen
218
+ import { Injectable } from '@angular/core';
219
+ import { injectGraphqlClient, unwrap } from '@trismegisto/spine/graphql';
220
+ import { CriarEquipeDocument, ListEquipesDocument } from '../../graphql/generated';
221
+
222
+ @Injectable({ providedIn: 'root' })
223
+ export class EquipesGqlService {
224
+ private readonly gql = injectGraphqlClient('principal'); // = environment.graphql.principal.namedClient
225
+
226
+ async listar() {
227
+ return unwrap((await this.gql.query(ListEquipesDocument)).equipes);
228
+ }
229
+
230
+ async criar(nome: string) {
231
+ // Sucesso com `message` e qualquer falha já viram toast (provideGraphql); a tela não avisa de novo.
232
+ return unwrap((await this.gql.mutate(CriarEquipeDocument, { nome })).criarEquipe);
233
+ }
234
+
235
+ async sondar() {
236
+ // A tela trata a falha sozinha: sem toast automático.
237
+ return unwrap((await this.gql.query(ListEquipesDocument, {}, { silenceEnvelope: true })).equipes);
238
+ }
239
+ }
240
+ ```
241
+
242
+ ```ts
243
+ // equipes.component.ts
244
+ import { ChangeDetectionStrategy, Component, computed, inject, resource } from '@angular/core';
245
+ import { AlertComponent, ButtonComponent, DataGridColumn, DataGridComponent, SkeletonComponent } from '@trismegisto/angular';
246
+ import { GraphqlEnvelopeError } from '@trismegisto/spine/graphql';
247
+ import { EquipesGqlService } from './equipes.service';
248
+
249
+ type Equipe = { id: string; nome: string; membros: number };
250
+
251
+ @Component({
252
+ selector: 'app-equipes',
253
+ imports: [AlertComponent, ButtonComponent, DataGridComponent, SkeletonComponent],
254
+ changeDetection: ChangeDetectionStrategy.OnPush,
255
+ template: `
256
+ @if (equipes.isLoading() && !equipes.hasValue()) {
257
+ <hm-skeleton shape="list" label="Carregando equipes" />
258
+ } @else if (erro(); as texto) {
259
+ <hm-alert variant="error" heading="Não foi possível carregar as equipes">
260
+ {{ texto }}
261
+ <hm-button actions emphasis="medium" (clicked)="equipes.reload()">Tentar de novo</hm-button>
262
+ </hm-alert>
263
+ } @else {
264
+ <hm-data-grid caption="Equipes" [columns]="colunas" [rows]="equipes.value() ?? []" [rowId]="idDe" />
265
+ }
266
+ `,
267
+ })
268
+ export class EquipesComponent {
269
+ private readonly service = inject(EquipesGqlService);
270
+
271
+ protected readonly equipes = resource({ loader: () => this.service.listar() as Promise<Equipe[]> });
272
+
273
+ protected readonly erro = computed(() => {
274
+ const err = this.equipes.error();
275
+ if (!err) return '';
276
+ if (err instanceof GraphqlEnvelopeError && err.status === 403) return 'Você não tem acesso a esta lista.';
277
+ return err instanceof Error ? err.message : String(err);
278
+ });
279
+
280
+ protected readonly colunas: DataGridColumn<Equipe>[] = [
281
+ { key: 'nome', title: 'Nome', value: (e) => e.nome, sortable: true },
282
+ { key: 'membros', title: 'Membros', value: (e) => String(e.membros), raw: (e) => e.membros, type: 'number', align: 'end' },
283
+ ];
284
+ protected readonly idDe = (e: Equipe) => e.id;
285
+ }
286
+ ```
287
+
288
+ Os textos fixos deste exemplo estão em português por brevidade; num app com i18n eles vêm do catálogo do app.
289
+
290
+ ## 6. Subscription com ressincronização na reconexão
291
+
292
+ ```ts
293
+ import { DestroyRef, Injectable, inject, signal } from '@angular/core';
294
+ import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
295
+ import { filter } from 'rxjs';
296
+ import { injectGraphqlClient, unwrap, wsReconnected$ } from '@trismegisto/spine/graphql';
297
+ import { EquipeAlteradaDocument, ListEquipesDocument } from '../../graphql/generated';
298
+
299
+ @Injectable()
300
+ export class EquipesAoVivo {
301
+ private readonly gql = injectGraphqlClient('principal');
302
+ readonly equipes = signal<unknown[]>([]);
303
+
304
+ constructor() {
305
+ const destroy = inject(DestroyRef);
306
+ void this.recarregar();
307
+ // Evento de subscription não tem envelope: vem o `data` direto.
308
+ this.gql.subscribe(EquipeAlteradaDocument).pipe(takeUntilDestroyed(destroy)).subscribe(() => void this.recarregar());
309
+ // O socket reassina sozinho, mas não reenvia o que passou durante a queda: recarregue.
310
+ wsReconnected$.pipe(filter((client) => client === 'principal'), takeUntilDestroyed(destroy))
311
+ .subscribe(() => void this.recarregar());
312
+ }
313
+
314
+ private async recarregar() {
315
+ this.equipes.set(unwrap((await this.gql.query(ListEquipesDocument)).equipes));
316
+ }
317
+ }
318
+ ```
319
+
320
+ Forneça `EquipesAoVivo` no `providers` da tela (ela vive enquanto a aba existir — `keepAlive`).
321
+
322
+ ## 7. Modal e painel lateral do shell
323
+
324
+ Conteúdo (o mesmo serve aos dois):
325
+
326
+ ```ts
327
+ import { ChangeDetectionStrategy, Component, OnInit, input, signal } from '@angular/core';
328
+ import { InputComponent } from '@trismegisto/angular';
329
+ import { ModalContent } from '@trismegisto/spine/modal';
330
+
331
+ @Component({
332
+ selector: 'app-renomear-equipe',
333
+ imports: [InputComponent],
334
+ changeDetection: ChangeDetectionStrategy.OnPush,
335
+ template: `<hm-input label="Nome" [(value)]="nome" [required]="true" />`,
336
+ })
337
+ export class RenomearEquipeComponent implements ModalContent<string>, OnInit {
338
+ readonly data = input<{ nome: string }>(); // recebe ModalConfig.data
339
+ protected readonly nome = signal('');
340
+ ngOnInit() { this.nome.set(this.data()?.nome ?? ''); }
341
+ isValid() { return this.nome().trim().length > 0; } // Confirmar desabilitado enquanto false
342
+ getResult() { return this.nome().trim(); } // vira o valor do Observable
343
+ }
344
+ ```
345
+
346
+ Abrindo:
347
+
348
+ ```ts
349
+ import { inject } from '@angular/core';
350
+ import { HermesLoadingState } from '@trismegisto/angular';
351
+ import { ModalService } from '@trismegisto/spine/modal';
352
+ import { SidePanelService } from '@trismegisto/spine/side-panel';
353
+
354
+ private readonly modal = inject(ModalService);
355
+ private readonly painel = inject(SidePanelService);
356
+
357
+ renomear(equipe: { id: string; nome: string }) {
358
+ this.modal
359
+ .open<string, { nome: string }>({ title: 'Renomear equipe', size: 'md', component: RenomearEquipeComponent, data: { nome: equipe.nome } })
360
+ .subscribe((nome) => {
361
+ if (nome === null) return; // cancelado, fechado ou substituído por outro modal
362
+ void this.service.renomear(equipe.id, nome);
363
+ });
364
+ }
365
+
366
+ detalhes(equipe: { id: string; nome: string }) {
367
+ // Painel lateral: mesma API; size 'sm' | 'md' | 'lg' | 'xl' | 'full'; showActions: false = sem Cancelar/Confirmar
368
+ this.painel.open({ title: equipe.nome, size: 'lg', component: DetalhesEquipeComponent, data: equipe, showActions: false });
369
+ }
370
+
371
+ aviso() {
372
+ this.modal.open({ title: 'Atenção', text: 'Texto simples, sem componente.' }); // Confirmar devolve true
373
+ }
374
+ ```
375
+
376
+ Só um modal (e um painel) por vez: abrir outro completa o anterior com `null`. Para "salvando…" no botão
377
+ Confirmar, `this.modal.setState(HermesLoadingState.LOADING)` antes de fechar com `confirm(resultado)`/`close()`.
378
+ Confirmação simples ("Excluir?") não precisa do spine: `HermesDialogService.confirm(...)` do `@trismegisto/angular`.
379
+
380
+ ## 8. Toasts
381
+
382
+ ```ts
383
+ import { inject } from '@angular/core';
384
+ import { AlertType, NotificationService } from '@trismegisto/spine/notification';
385
+
386
+ private readonly toasts = inject(NotificationService);
387
+
388
+ this.toasts.addNotification({ timer: 4, hermesAlertType: AlertType.SUCCESS, message: 'Equipe criada.' });
389
+ this.toasts.addNotification({ timer: 6, hermesAlertType: 422, message: 'Nome já usado.', hermesAlertClosable: true }); // status → tipo
390
+ this.toasts.processErrorNotification(); // erro genérico do catálogo
391
+ ```
392
+
393
+ Não duplique toast do GraphQL: mutation que falha (ou devolve `message`) já avisa sozinha (§5).
394
+
395
+ ## 9. Auditoria numa tela (sempre lazy)
396
+
397
+ Uma tela que só embrulha a auditoria. Como toda tela registrada em `ComponentRoute.load`, ela já é carregada
398
+ por `import()` — então o import estático de `@trismegisto/spine/audit` **dentro dela** é seguro:
399
+
400
+ ```ts
401
+ // src/app/features/auditoria/auditoria.component.ts
402
+ import { ChangeDetectionStrategy, Component } from '@angular/core';
403
+ import { SpineAuditComponent } from '@trismegisto/spine/audit';
404
+ import { environment } from '../../../environments/environment';
405
+
406
+ @Component({
407
+ selector: 'app-auditoria',
408
+ imports: [SpineAuditComponent],
409
+ changeDetection: ChangeDetectionStrategy.OnPush,
410
+ template: `<spine-audit scope="admin" [adminApi]="adminApi" />`,
411
+ // Escopo de um projeto: <spine-audit scope="client" [clientId]="clientId" />
412
+ // ([adminApi] é opcional quando o app já fornece SPINE_ADMIN_API, ex.: via provideAutoService)
413
+ })
414
+ export class AuditoriaComponent {
415
+ protected readonly adminApi = environment.adminApi;
416
+ }
417
+ ```
418
+
419
+ ```ts
420
+ // features.routes.ts
421
+ { id: '<router_id da tela Auditoria>', load: () => import('./auditoria/auditoria.component').then((m) => m.AuditoriaComponent) },
422
+ ```
423
+
424
+ Dentro de uma tela que **não** é só auditoria (ex.: uma aba), adie com `@defer`:
425
+
426
+ ```html
427
+ @defer (on viewport) {
428
+ <spine-audit scope="client" [clientId]="clientId()" />
429
+ } @placeholder {
430
+ <div style="min-block-size: 20rem"></div>
431
+ }
432
+ ```
433
+
434
+ Nunca importe `@trismegisto/spine/audit` em `app.config.ts`, serviço `providedIn: 'root'` usado no boot ou
435
+ componente do bundle inicial. Com `provideAutoService`, a auditoria do projeto já existe (aba em Aplicações e
436
+ página própria) — não crie outra.
437
+
438
+ ## 10. Seção própria no painel de configurações
439
+
440
+ ```ts
441
+ // app.config.ts
442
+ import { provideSettingsSection } from '@trismegisto/spine/layout';
443
+
444
+ provideSettingsSection({
445
+ key: 'notificacoes', // também abre por ?settings=notificacoes
446
+ label: 'Notificações',
447
+ icon: 'bell',
448
+ description: 'Quando avisar você.',
449
+ keywords: 'alerta aviso e-mail',
450
+ component: NotificacoesSettingsComponent, // de preferência hm-settings-row (a busca acha cada linha)
451
+ }),
452
+ ```
453
+
454
+ ```ts
455
+ import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
456
+ import { SettingsRowComponent, SwitchComponent } from '@trismegisto/angular';
457
+
458
+ @Component({
459
+ selector: 'app-notificacoes-settings',
460
+ imports: [SettingsRowComponent, SwitchComponent],
461
+ changeDetection: ChangeDetectionStrategy.OnPush,
462
+ template: `
463
+ <hm-settings-row label="Avisar por e-mail" description="Resumo diário das mudanças nas suas equipes.">
464
+ <hm-switch label="Avisar por e-mail" labelPosition="before" [(value)]="email" />
465
+ </hm-settings-row>
466
+ `,
467
+ })
468
+ export class NotificacoesSettingsComponent {
469
+ protected readonly email = signal(false);
470
+ }
471
+ ```
472
+
473
+ As seções do app aparecem depois das do spine (Aparência, Região, Atalhos, Conta) e antes de "Sobre". Não
474
+ repita as chaves de `SPINE_SETTINGS_KEYS` (`aparencia`, `regiao`, `atalhos`, `conta`, `sobre`). Abrir por código:
475
+ `inject(SpineSettingsService).open('notificacoes')`.
476
+
477
+ ## 11. Novidades da versão
478
+
479
+ ```ts
480
+ import { provideSpineNews } from '@trismegisto/spine';
481
+
482
+ provideSpineNews([
483
+ {
484
+ id: 'equipes-2026-10', // trocar o id faz reaparecer para todo mundo
485
+ until: '2026-12-31', // opcional: some depois desta data
486
+ slides: [
487
+ {
488
+ title: 'Equipes',
489
+ text: 'Agora dá para organizar pessoas em equipes.',
490
+ illustration: { icon: 'users', satellites: [{ icon: 'user', label: 'Membros' }] },
491
+ },
492
+ ],
493
+ },
494
+ ]),
495
+ ```
496
+
497
+ Abre sozinha uma vez por navegador (depois do tour) e fica no menu do perfil enquanto vigente.
498
+
499
+ ## 12. Marca em componente
500
+
501
+ ```ts
502
+ import { ChangeDetectionStrategy, Component } from '@angular/core';
503
+ import { SPINE_BRAND } from '@trismegisto/spine/layout';
504
+
505
+ @Component({
506
+ selector: 'app-marca',
507
+ changeDetection: ChangeDetectionStrategy.OnPush,
508
+ template: `<svg viewBox="0 0 24 24" width="28" height="28" aria-hidden="true"><circle cx="12" cy="12" r="10" fill="currentColor" /></svg>`,
509
+ })
510
+ export class MarcaComponent {}
511
+
512
+ // app.config.ts
513
+ { provide: SPINE_BRAND, useValue: MarcaComponent },
514
+ ```
515
+
516
+ Tem prioridade sobre `logo`. Fica dentro do link da marca: sem link/botão dentro; se for só imagem, deixe
517
+ `showAppName` ligado (padrão) para o link ter nome.
518
+
519
+ ## 13. Idioma e textos do shell
520
+
521
+ ```ts
522
+ import { provideHermesI18n } from '@trismegisto/angular';
523
+ import { provideSpineMessages } from '@trismegisto/spine';
524
+
525
+ providers: [
526
+ provideHermesI18n({ locale: 'en' }), // idioma inicial da lib E do spine
527
+ provideSpineMessages({
528
+ override: { header: { searchPlaceholder: 'Search screens and modules' } }, // só as chaves que mudam
529
+ }),
530
+ ]
531
+ ```
532
+
533
+ Trocar em tempo de execução (lib + spine juntos): `inject(HermesI18nService).setLocale('es')`, ou
534
+ `inject(SpinePreferencesService).setLanguage('es')` para também salvar a escolha da pessoa. Ler um texto do
535
+ spine em código: `inject(SPINE_MESSAGES).header.search`.
536
+
537
+ ## 14. Testes de tela
538
+
539
+ As telas não dependem do layout: teste-as isoladas, trocando os serviços do spine por dublês.
540
+
541
+ ```ts
542
+ import { TestBed } from '@angular/core/testing';
543
+ import { NotificationService } from '@trismegisto/spine/notification';
544
+ import { ModalService } from '@trismegisto/spine/modal';
545
+ import { of } from 'rxjs';
546
+ import { EquipesComponent } from './equipes.component';
547
+ import { EquipesGqlService } from './equipes.service';
548
+
549
+ beforeEach(() => {
550
+ TestBed.configureTestingModule({
551
+ imports: [EquipesComponent],
552
+ providers: [
553
+ { provide: EquipesGqlService, useValue: { listar: async () => [{ id: '1', nome: 'Rede', membros: 3 }] } },
554
+ { provide: NotificationService, useValue: { addNotification: vi.fn() } },
555
+ { provide: ModalService, useValue: { open: vi.fn(() => of(null)) } },
556
+ ],
557
+ });
558
+ });
559
+ ```
560
+
561
+ - Dublê no serviço de domínio (não no Apollo): `injectGraphqlClient` exige `provideGraphql` e Apollo reais.
562
+ - Para erro de envelope: `listar: async () => { throw new GraphqlEnvelopeError(403, 'Sem acesso'); }`.
563
+ - Interações com `hm-*`: harnesses de `@trismegisto/angular/testing` (`angular.md` §7).
564
+
565
+ ### Mapa de telas
566
+
567
+ ```ts
568
+ import { reflectComponentType } from '@angular/core';
569
+ import { components } from './features.routes';
570
+
571
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
572
+
573
+ it('ids UUID únicos (sem diferenciar maiúsculas) e todo load() resolve para componente', async () => {
574
+ const ids = components.map((c) => String(c.id).toLowerCase());
575
+ expect(new Set(ids).size).toBe(ids.length);
576
+ for (const id of ids) expect(id).toMatch(UUID);
577
+ for (const rota of components) expect(reflectComponentType((await rota.load!()) as any)).not.toBeNull();
578
+ });
579
+ ```
580
+
581
+ O `import()` quebrado não falha o build (a tela é lazy); só aparece em runtime como "tela não publicada".