@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.
- package/README.md +5 -4
- package/agents/revisor-orfeu.md +2 -1
- package/package.json +1 -1
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +2 -2
- package/skills/angular/SKILL.md +2 -2
- package/skills/angular/references/dados.md +3 -3
- package/skills/angular/references/estrutura.md +6 -5
- package/skills/angular/references/features.md +5 -5
- package/skills/angular/references/testes-build.md +1 -1
- package/skills/auto-servico/SKILL.md +18 -14
- package/skills/express/references/dados.md +4 -1
- package/skills/express/references/estrutura.md +2 -1
- package/skills/fastapi/references/banco.md +6 -2
- package/skills/fastapi/references/estrutura.md +1 -1
- package/skills/hefesto/SKILL.md +6 -2
- package/skills/orfeu/SKILL.md +43 -13
- package/skills/orfeu/references/angular-api.md +39 -13
- package/skills/orfeu/references/angular-armadilhas.md +18 -1
- package/skills/orfeu/references/angular-recipes.md +25 -12
- package/skills/orfeu/references/angular.md +37 -15
- package/skills/orfeu/references/diferencas.md +17 -8
- package/skills/orfeu/references/node-api.md +41 -9
- package/skills/orfeu/references/node-armadilhas.md +16 -2
- package/skills/orfeu/references/node-recipes.md +13 -4
- package/skills/orfeu/references/node.md +31 -12
- package/skills/orfeu/references/python-api.md +41 -16
- package/skills/orfeu/references/python-recipes.md +13 -9
- package/skills/orfeu/references/python.md +33 -12
- package/skills/orfeu/references/react.md +133 -0
- package/skills/trismegisto/SKILL.md +42 -29
- package/skills/trismegisto/references/angular-api.md +608 -6
- package/skills/trismegisto/references/angular-exports.md +479 -791
- package/skills/trismegisto/references/angular-recipes.md +13 -7
- package/skills/trismegisto/references/angular.md +32 -9
- package/skills/trismegisto/references/catalogo/imports.json +1627 -0
- package/skills/trismegisto/references/catalogo/seletores.json +90 -65
- package/skills/trismegisto/references/react-api.md +16864 -0
- package/skills/trismegisto/references/react.md +237 -0
- package/skills/trismegisto/references/spine-api.md +5565 -1973
- package/skills/trismegisto/references/spine-recipes.md +113 -26
- package/skills/trismegisto/references/spine.md +95 -33
- package/skills/trismegisto/scripts/checar.mjs +66 -1
|
@@ -1,6 +1,8 @@
|
|
|
1
|
-
# Receitas —
|
|
1
|
+
# Receitas — spine (casca Angular, 3.4.0)
|
|
2
2
|
|
|
3
|
-
Padrões prontos para um app que usa o spine.
|
|
3
|
+
Padrões prontos para um app Angular que usa o spine. Componentes, serviços e providers vêm da casca
|
|
4
|
+
(`@trismegisto/angular/spine[/sub]`); valores sem framework (`GraphqlEnvelopeError`, `AlertType`, `applyRuntimeEnvironment`…), do
|
|
5
|
+
núcleo `@trismegisto/spine` (`spine.md` §2). Receitas em React: `react.md` §5. Todos os componentes são standalone (importe as classes no
|
|
4
6
|
`imports`). Os componentes `hm-*` usados no conteúdo das telas são do `@trismegisto/angular` — a API deles está
|
|
5
7
|
em `angular.md` e `angular-api.md`. Nomes como `MeuApp`, `principal`,
|
|
6
8
|
`Equipes` e os UUIDs são exemplos: troque pelos do seu app.
|
|
@@ -17,7 +19,7 @@ Detalhes de `angular.json`, scripts e Docker: skill **angular** (`references/est
|
|
|
17
19
|
`postLogoutRedirectUri` são sempre derivados):
|
|
18
20
|
|
|
19
21
|
```ts
|
|
20
|
-
import type { GraphqlEndpoint } from '@trismegisto/spine/graphql';
|
|
22
|
+
import type { GraphqlEndpoint } from '@trismegisto/angular/spine/graphql';
|
|
21
23
|
|
|
22
24
|
export const environment = {
|
|
23
25
|
production: false, // true vem do config.json de homol/prod
|
|
@@ -76,10 +78,10 @@ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
|
|
|
76
78
|
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
|
|
77
79
|
import { provideRouter } from '@angular/router';
|
|
78
80
|
import { provideAuth } from '@orfeu/angular/core';
|
|
79
|
-
import { provideUi } from '@trismegisto/spine';
|
|
80
|
-
import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
|
|
81
|
-
import { provideAutoService } from '@trismegisto/spine/auto-service';
|
|
82
|
-
import { provideGraphql } from '@trismegisto/spine/graphql';
|
|
81
|
+
import { provideUi } from '@trismegisto/angular/spine';
|
|
82
|
+
import { APP_ROUTES, provideShell } from '@trismegisto/angular/spine/shell';
|
|
83
|
+
import { provideAutoService } from '@trismegisto/angular/spine/auto-service';
|
|
84
|
+
import { provideGraphql } from '@trismegisto/angular/spine/graphql';
|
|
83
85
|
import { components } from './features/features.routes';
|
|
84
86
|
import { environment } from '../environments/environment';
|
|
85
87
|
import packageInfo from '../../package.json';
|
|
@@ -149,8 +151,8 @@ Arquivos de marca: `src/assets/images/logo.svg` (legível sobre o cabeçalho esc
|
|
|
149
151
|
```ts
|
|
150
152
|
import { Routes } from '@angular/router';
|
|
151
153
|
import { PrivateGuard } from '@orfeu/angular/core';
|
|
152
|
-
import { LayoutComponent } from '@trismegisto/spine/layout';
|
|
153
|
-
import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/spine/shell';
|
|
154
|
+
import { LayoutComponent } from '@trismegisto/angular/spine/layout';
|
|
155
|
+
import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/angular/spine/shell';
|
|
154
156
|
|
|
155
157
|
export const ROUTES: Routes = [
|
|
156
158
|
{ path: '', pathMatch: 'full', loadComponent: () => import('./public/landing.component').then((m) => m.LandingComponent) },
|
|
@@ -192,7 +194,7 @@ export class EquipesComponent {}
|
|
|
192
194
|
|
|
193
195
|
```ts
|
|
194
196
|
// src/app/features/features.routes.ts
|
|
195
|
-
import { ComponentRoute } from '@trismegisto/spine/routing';
|
|
197
|
+
import { ComponentRoute } from '@trismegisto/angular/spine/routing';
|
|
196
198
|
|
|
197
199
|
export const components: ComponentRoute[] = [
|
|
198
200
|
{
|
|
@@ -246,7 +248,7 @@ export class EquipesService {
|
|
|
246
248
|
```ts
|
|
247
249
|
// equipes.service.ts — ListEquipesDocument/CriarEquipeDocument: TypedDocumentNode gerados pelo codegen
|
|
248
250
|
import { Injectable } from '@angular/core';
|
|
249
|
-
import { injectGraphqlClient, unwrap } from '@trismegisto/spine/graphql';
|
|
251
|
+
import { injectGraphqlClient, unwrap } from '@trismegisto/angular/spine/graphql';
|
|
250
252
|
import { CriarEquipeDocument, ListEquipesDocument } from '../../graphql/generated';
|
|
251
253
|
|
|
252
254
|
@Injectable({ providedIn: 'root' })
|
|
@@ -273,7 +275,7 @@ export class EquipesGqlService {
|
|
|
273
275
|
// equipes.component.ts
|
|
274
276
|
import { ChangeDetectionStrategy, Component, computed, inject, resource } from '@angular/core';
|
|
275
277
|
import { AlertComponent, ButtonComponent, DataGridColumn, DataGridComponent, SkeletonComponent } from '@trismegisto/angular';
|
|
276
|
-
import { GraphqlEnvelopeError } from '@trismegisto/spine/graphql';
|
|
278
|
+
import { GraphqlEnvelopeError } from '@trismegisto/spine/graphql'; // valor do núcleo (classe, para instanceof)
|
|
277
279
|
import { EquipesGqlService } from './equipes.service';
|
|
278
280
|
|
|
279
281
|
type Equipe = { id: string; nome: string; membros: number };
|
|
@@ -323,7 +325,7 @@ Os textos fixos deste exemplo estão em português por brevidade; num app com i1
|
|
|
323
325
|
import { DestroyRef, Injectable, inject, signal } from '@angular/core';
|
|
324
326
|
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
|
|
325
327
|
import { filter } from 'rxjs';
|
|
326
|
-
import { injectGraphqlClient, unwrap, wsReconnected$ } from '@trismegisto/spine/graphql';
|
|
328
|
+
import { injectGraphqlClient, unwrap, wsReconnected$ } from '@trismegisto/angular/spine/graphql';
|
|
327
329
|
import { EquipeAlteradaDocument, ListEquipesDocument } from '../../graphql/generated';
|
|
328
330
|
|
|
329
331
|
@Injectable()
|
|
@@ -356,7 +358,7 @@ Conteúdo (o mesmo serve aos dois):
|
|
|
356
358
|
```ts
|
|
357
359
|
import { ChangeDetectionStrategy, Component, OnInit, input, signal } from '@angular/core';
|
|
358
360
|
import { InputComponent } from '@trismegisto/angular';
|
|
359
|
-
import { ModalContent } from '@trismegisto/spine/modal';
|
|
361
|
+
import { ModalContent } from '@trismegisto/angular/spine/modal';
|
|
360
362
|
|
|
361
363
|
@Component({
|
|
362
364
|
selector: 'app-renomear-equipe',
|
|
@@ -378,8 +380,8 @@ Abrindo:
|
|
|
378
380
|
```ts
|
|
379
381
|
import { inject } from '@angular/core';
|
|
380
382
|
import { HermesLoadingState } from '@trismegisto/angular';
|
|
381
|
-
import { ModalService } from '@trismegisto/spine/modal';
|
|
382
|
-
import { SidePanelService } from '@trismegisto/spine/side-panel';
|
|
383
|
+
import { ModalService } from '@trismegisto/angular/spine/modal';
|
|
384
|
+
import { SidePanelService } from '@trismegisto/angular/spine/side-panel';
|
|
383
385
|
|
|
384
386
|
private readonly modal = inject(ModalService);
|
|
385
387
|
private readonly painel = inject(SidePanelService);
|
|
@@ -411,7 +413,8 @@ Confirmação simples ("Excluir?") não precisa do spine: `HermesDialogService.c
|
|
|
411
413
|
|
|
412
414
|
```ts
|
|
413
415
|
import { inject } from '@angular/core';
|
|
414
|
-
import {
|
|
416
|
+
import { NotificationService } from '@trismegisto/angular/spine/notification';
|
|
417
|
+
import { AlertType } from '@trismegisto/spine/notification'; // enum do núcleo
|
|
415
418
|
|
|
416
419
|
private readonly toasts = inject(NotificationService);
|
|
417
420
|
|
|
@@ -425,12 +428,12 @@ Não duplique toast do GraphQL: mutation que falha (ou devolve `message`) já av
|
|
|
425
428
|
## 9. Auditoria numa tela (sempre lazy)
|
|
426
429
|
|
|
427
430
|
Uma tela que só embrulha a auditoria. Como toda tela registrada em `ComponentRoute.load`, ela já é carregada
|
|
428
|
-
por `import()` — então o import estático de `@trismegisto/spine/audit` **dentro dela** é seguro:
|
|
431
|
+
por `import()` — então o import estático de `@trismegisto/angular/spine/audit` **dentro dela** é seguro:
|
|
429
432
|
|
|
430
433
|
```ts
|
|
431
434
|
// src/app/features/auditoria/auditoria.component.ts
|
|
432
435
|
import { ChangeDetectionStrategy, Component } from '@angular/core';
|
|
433
|
-
import { SpineAuditComponent } from '@trismegisto/spine/audit';
|
|
436
|
+
import { SpineAuditComponent } from '@trismegisto/angular/spine/audit';
|
|
434
437
|
import { environment } from '../../../environments/environment';
|
|
435
438
|
|
|
436
439
|
@Component({
|
|
@@ -461,7 +464,7 @@ Dentro de uma tela que **não** é só auditoria (ex.: uma aba), adie com `@defe
|
|
|
461
464
|
}
|
|
462
465
|
```
|
|
463
466
|
|
|
464
|
-
Nunca importe `@trismegisto/spine/audit` em `app.config.ts`, serviço `providedIn: 'root'` usado no boot ou
|
|
467
|
+
Nunca importe `@trismegisto/angular/spine/audit` em `app.config.ts`, serviço `providedIn: 'root'` usado no boot ou
|
|
465
468
|
componente do bundle inicial. Com `provideAutoService`, a auditoria do projeto já existe (aba em Aplicações e
|
|
466
469
|
página própria) — não crie outra.
|
|
467
470
|
|
|
@@ -469,7 +472,7 @@ página própria) — não crie outra.
|
|
|
469
472
|
|
|
470
473
|
```ts
|
|
471
474
|
// app.config.ts
|
|
472
|
-
import { provideSettingsSection } from '@trismegisto/spine/layout';
|
|
475
|
+
import { provideSettingsSection } from '@trismegisto/angular/spine/layout';
|
|
473
476
|
|
|
474
477
|
provideSettingsSection({
|
|
475
478
|
key: 'resumos', // também abre por ?settings=resumos
|
|
@@ -522,7 +525,7 @@ Abrir por código: `inject(SpineNewsService).showAll()`.
|
|
|
522
525
|
|
|
523
526
|
```ts
|
|
524
527
|
import { ChangeDetectionStrategy, Component } from '@angular/core';
|
|
525
|
-
import { SPINE_BRAND } from '@trismegisto/spine/layout';
|
|
528
|
+
import { SPINE_BRAND } from '@trismegisto/angular/spine/layout';
|
|
526
529
|
|
|
527
530
|
@Component({
|
|
528
531
|
selector: 'app-marca',
|
|
@@ -542,7 +545,7 @@ Tem prioridade sobre `logo`. Fica dentro do link da marca: sem link/botão dentr
|
|
|
542
545
|
|
|
543
546
|
```ts
|
|
544
547
|
import { provideHermesI18n } from '@trismegisto/angular';
|
|
545
|
-
import { provideSpineMessages } from '@trismegisto/spine';
|
|
548
|
+
import { provideSpineMessages } from '@trismegisto/angular/spine';
|
|
546
549
|
|
|
547
550
|
providers: [
|
|
548
551
|
provideHermesI18n({ locale: 'en' }), // idioma inicial da lib E do spine
|
|
@@ -563,7 +566,7 @@ spine em código: `inject(SPINE_MESSAGES).header.search`.
|
|
|
563
566
|
provideUi({ clientId, features: { skipLink: true, unsavedChanges: true } }),
|
|
564
567
|
```
|
|
565
568
|
```ts
|
|
566
|
-
import { registerSpineUnsavedChanges } from '@trismegisto/spine/layout';
|
|
569
|
+
import { registerSpineUnsavedChanges } from '@trismegisto/angular/spine/layout';
|
|
567
570
|
|
|
568
571
|
export class PedidoPage {
|
|
569
572
|
readonly form = new FormGroup({ /* … */ });
|
|
@@ -581,8 +584,8 @@ As telas não dependem do layout: teste-as isoladas, trocando os serviços do sp
|
|
|
581
584
|
|
|
582
585
|
```ts
|
|
583
586
|
import { TestBed } from '@angular/core/testing';
|
|
584
|
-
import { NotificationService } from '@trismegisto/spine/notification';
|
|
585
|
-
import { ModalService } from '@trismegisto/spine/modal';
|
|
587
|
+
import { NotificationService } from '@trismegisto/angular/spine/notification';
|
|
588
|
+
import { ModalService } from '@trismegisto/angular/spine/modal';
|
|
586
589
|
import { of } from 'rxjs';
|
|
587
590
|
import { EquipesComponent } from './equipes.component';
|
|
588
591
|
import { EquipesGqlService } from './equipes.service';
|
|
@@ -620,3 +623,87 @@ it('ids UUID únicos (sem diferenciar maiúsculas) e todo load() resolve para co
|
|
|
620
623
|
```
|
|
621
624
|
|
|
622
625
|
O `import()` quebrado não falha o build (a tela é lazy); só aparece em runtime como "tela não publicada".
|
|
626
|
+
|
|
627
|
+
## 16. Busca do cabeçalho com provedores, menu sem módulos e overlays presos ao conteúdo
|
|
628
|
+
|
|
629
|
+
A paleta do cabeçalho (`Ctrl K`, `/`) procura as telas e, com provedores, os itens do app. O app só diz o que procurar
|
|
630
|
+
e para onde o resultado leva; o Spine espera a digitação, cancela o pedido anterior, aplica tempo-limite, ordena pela
|
|
631
|
+
relevância (telas por último) e mostra "Ver mais".
|
|
632
|
+
|
|
633
|
+
```ts
|
|
634
|
+
// app.config.ts
|
|
635
|
+
import { provideSpineSearch, provideUi } from '@trismegisto/angular/spine';
|
|
636
|
+
import type { SpineConfig, SpineSearchProvider } from '@trismegisto/spine';
|
|
637
|
+
|
|
638
|
+
export const spineConfig: SpineConfig = {
|
|
639
|
+
clientId: environment.authorizationServer.clientId,
|
|
640
|
+
navigation: { modules: false }, // menu numa árvore só, sem lista de módulos
|
|
641
|
+
overlays: { scope: 'content' }, // hm-drawer/hm-modal das telas presos à área de conteúdo (um palco por aba)
|
|
642
|
+
};
|
|
643
|
+
|
|
644
|
+
function pedidosProviders(): SpineSearchProvider[] {
|
|
645
|
+
const api = inject(PedidosService);
|
|
646
|
+
return [{
|
|
647
|
+
id: 'vendas.pedidos', label: 'Pedidos', icon: 'cart', prefixes: ['pedido'],
|
|
648
|
+
// Devolva até `limit + 1`: o item a mais faz aparecer o "Ver mais".
|
|
649
|
+
search: async (termo, { signal, limit }) => (await api.buscar({ q: termo, limit }, signal)).map((p) => ({
|
|
650
|
+
id: p.id, label: `Pedido ${p.numero}`, description: p.cliente, score: p.relevancia,
|
|
651
|
+
target: { route: '/vendas/pedidos', params: { pedido: p.id } },
|
|
652
|
+
})),
|
|
653
|
+
}];
|
|
654
|
+
}
|
|
655
|
+
|
|
656
|
+
providers: [provideUi(spineConfig), provideSpineSearch(pedidosProviders)];
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
A tela de destino abre o item pelos parâmetros da própria aba (funciona também com a aba já aberta):
|
|
660
|
+
|
|
661
|
+
```ts
|
|
662
|
+
private readonly tab = inject(SPINE_TAB, { optional: true });
|
|
663
|
+
constructor() {
|
|
664
|
+
effect(() => {
|
|
665
|
+
const id = this.tab?.params()['pedido'];
|
|
666
|
+
if (id) untracked(() => this.abrirPedido(id));
|
|
667
|
+
});
|
|
668
|
+
}
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
- Sem `requires`, o provedor vale para todos; com `requires: { route: '/vendas/pedidos' }`, só para quem alcança a tela;
|
|
672
|
+
com `requires: { badges: ['Operador'] }`, só nesse crachá.
|
|
673
|
+
- Cache dentro do provedor (o catálogo, a resposta reaproveitada no "Ver mais") vai por crachá (`badge` do contexto) e
|
|
674
|
+
com prazo curto: cada nível de acesso enxerga outro recorte, e a permissão pode mudar com o app aberto.
|
|
675
|
+
- `hm-drawer`/`hm-modal` aceitam `scope="viewport"` para cobrir a página inteira mesmo com `overlays.scope = 'content'`.
|
|
676
|
+
Com o drawer preso à área, largura e limites de arraste se medem pela camada dele (`.hm-drawer`), não pela janela: o
|
|
677
|
+
menu lateral fixo aberto deixa a área bem menor que a janela.
|
|
678
|
+
|
|
679
|
+
## 17. Trilha da tela na barra da página e modo apresentação
|
|
680
|
+
|
|
681
|
+
Tela com navegação interna pelos parâmetros do endereço (central › cooperativa › PA; pasta › subpasta) continua a trilha
|
|
682
|
+
do Spine em vez de desenhar a própria: "Módulo › Painel › Central 1003 › PA 12".
|
|
683
|
+
|
|
684
|
+
```ts
|
|
685
|
+
import { SPINE_TAB, hasSpinePageTrail, spinePageTrail } from '@trismegisto/angular/spine/layout';
|
|
686
|
+
|
|
687
|
+
export class PainelComponent {
|
|
688
|
+
private readonly tab = inject(SPINE_TAB, { optional: true });
|
|
689
|
+
/** No shell a trilha vai para a barra; fora dele (teste, tela sozinha), a tela mostra a dela. */
|
|
690
|
+
protected readonly trilhaNaBarra = hasSpinePageTrail();
|
|
691
|
+
|
|
692
|
+
constructor() {
|
|
693
|
+
spinePageTrail(() => this.niveis().map((n, i, todos) => i === todos.length - 1
|
|
694
|
+
? { label: n.rotulo } // onde a pessoa está: sem link
|
|
695
|
+
: { label: n.rotulo, params: { central: n.central, cooperativa: n.cooperativa ?? null } })); // null tira
|
|
696
|
+
// A tela segue o endereço da aba (o clique num degrau, o link, a busca do cabeçalho):
|
|
697
|
+
effect(() => {
|
|
698
|
+
const q = this.tab?.params() ?? {};
|
|
699
|
+
untracked(() => this.irPara(q['central'] ? { central: q['central'], cooperativa: q['cooperativa'] } : this.inicial()));
|
|
700
|
+
});
|
|
701
|
+
}
|
|
702
|
+
}
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
- Cada degrau aplica os `params` sobre a query atual da aba (os filtros ficam). O nome da tela vira link para ela sem
|
|
706
|
+
parâmetros: trate o endereço sem nível como "voltar ao início" da tela.
|
|
707
|
+
- Modo apresentação: o botão "Apresentar em tela cheia" da barra põe a aba em `?present=1` (nome reservado pelo Spine) e
|
|
708
|
+
mostra só o conteúdo da tela, cobrindo a janela. Para uma TV de monitoramento, abra o link com `present=1` (o navegador
|
|
709
|
+
em modo quiosque cuida da tela cheia). `SpinePresentationService.active()` diz se o painel focado está apresentando.
|
|
@@ -1,9 +1,14 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Spine — guia do shell (casca Angular)
|
|
2
2
|
|
|
3
|
-
Escrito para a **
|
|
3
|
+
Escrito para a **3.4.0**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
|
|
4
4
|
prontas: `spine-recipes.md`. O conteúdo das telas (componentes `hm-*`, tokens, formulários) é do
|
|
5
5
|
`@trismegisto/angular`: `angular.md`. Sessão, token, `PrivateGuard`, logout e troca de crachá são do
|
|
6
|
-
`@orfeu/angular` — skill **orfeu**.
|
|
6
|
+
`@orfeu/angular` — skill **orfeu**. Shell em React: `react.md` §5.
|
|
7
|
+
|
|
8
|
+
**Forma desde a 3.4.0 (decisão A19):** o pacote `@trismegisto/spine` virou só o **núcleo sem framework** (tipos, regras,
|
|
9
|
+
constantes, catálogos de texto); a **casca Angular** (componentes, serviços, providers, rotas) mora no
|
|
10
|
+
`@trismegisto/angular`, nos pontos `@trismegisto/angular/spine` e `@trismegisto/angular/spine/<sub>`, fora do barrel
|
|
11
|
+
`@trismegisto/angular`. Os nomes da casca são os de antes; só o caminho mudou. Migração da 3.3.x: §11.
|
|
7
12
|
|
|
8
13
|
O spine é o **esqueleto pronto** de um app Angular: cabeçalho (marca, busca de telas, apps,
|
|
9
14
|
tema, perfil), menu lateral montado da árvore de rotas do servidor de autorização (Argos), área de trabalho
|
|
@@ -12,14 +17,17 @@ telas de login/callback/saída/sem permissão/bloqueado, modal, painel lateral e
|
|
|
12
17
|
de configurações, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
|
|
13
18
|
vem do spine.
|
|
14
19
|
|
|
15
|
-
|
|
20
|
+
A casca fica na ponta da cadeia `tokens ← icons ← primitives (+ núcleo spine) ← core ← angular` e é **acoplada à
|
|
16
21
|
autenticação** do `@orfeu/angular` (OIDC + PKCE contra o Argos). Não serve a app que não se autentica no
|
|
17
22
|
Argos — para esse caso, monte o shell à mão com o `@trismegisto/angular` (`angular-recipes.md` §1).
|
|
18
23
|
|
|
19
24
|
## 1. Instalação
|
|
20
25
|
|
|
21
|
-
Pacotes, peers e `styles` do `angular.json`: `../SKILL.md` §2.
|
|
22
|
-
`
|
|
26
|
+
Pacotes, peers e `styles` do `angular.json`: `../SKILL.md` §2. Para o shell o app instala, além dos pacotes base:
|
|
27
|
+
`@trismegisto/spine` (núcleo), `@orfeu/angular`, `marked` e `dompurify` — todos **peers opcionais** do
|
|
28
|
+
`@trismegisto/angular`, então não vêm sozinhos: declare cada um no `package.json` do app (até a 3.3.x `marked` e
|
|
29
|
+
`dompurify` vinham como dependência do spine). Só com `/graphql`: `@apollo/client`, `apollo-angular`, `graphql`,
|
|
30
|
+
`graphql-ws`. `@orfeu/angular` precisa ser **uma cópia só** no app (ver armadilhas).
|
|
23
31
|
|
|
24
32
|
Se as telas tiverem documentação (`document.load` com `import('./README.md')`), o loader de texto em
|
|
25
33
|
`build.options`: `"loader": { ".md": "text" }` + um `src/markdown.d.ts` com
|
|
@@ -27,18 +35,37 @@ Se as telas tiverem documentação (`document.load` com `import('./README.md')`)
|
|
|
27
35
|
|
|
28
36
|
## 2. Pontos de entrada
|
|
29
37
|
|
|
38
|
+
**Casca Angular** (componentes, serviços, providers; a casca reexporta também os **tipos** do núcleo que usa):
|
|
39
|
+
|
|
30
40
|
| Import | Para quê |
|
|
31
41
|
|---|---|
|
|
32
|
-
| `@trismegisto/spine` | `provideUi`, `
|
|
33
|
-
| `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
|
|
34
|
-
| `@trismegisto/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`,
|
|
35
|
-
| `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `
|
|
36
|
-
| `@trismegisto/spine/modal` | `ModalService`, `ModalConfig`, `ModalContent` |
|
|
37
|
-
| `@trismegisto/spine/side-panel` | `SidePanelService`, `SidePanelConfig`, `SidePanelContent` |
|
|
38
|
-
| `@trismegisto/spine/notification` | `NotificationService
|
|
39
|
-
| `@trismegisto/spine/graphql` | `provideGraphql`, `injectGraphqlClient`, `unwrap`, `
|
|
40
|
-
| `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`, `AutoServiceService`,
|
|
41
|
-
| `@trismegisto/spine/audit` | `SpineAuditComponent` (`spine-audit`), `SpineAuditService`,
|
|
42
|
+
| `@trismegisto/angular/spine` | `provideUi`, `SPINE_CONFIG`, `SPINE_ADMIN_API`, `APP_PACKAGE_INFO`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, `currentSpineMessages`), `provideSpineSearch`, `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, `SpineUserStorage`, `SPINE_ICONS` |
|
|
43
|
+
| `@trismegisto/angular/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
|
|
44
|
+
| `@trismegisto/angular/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`, `resolveSpineRoute`, `isChunkLoadError` |
|
|
45
|
+
| `@trismegisto/angular/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `SPINE_TAB`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `SpineInitialSetupService`, `ShortcutService`, `SpineLogoutService`, `SpineNoticesService`, `SpineWorkspaceNavService`, `registerSpineUnsavedChanges`, `spinePageTrail` e as peças do layout |
|
|
46
|
+
| `@trismegisto/angular/spine/modal` | `ModalService`, `ModalConfig`, `ModalContent` |
|
|
47
|
+
| `@trismegisto/angular/spine/side-panel` | `SidePanelService`, `SidePanelConfig`, `SidePanelContent` |
|
|
48
|
+
| `@trismegisto/angular/spine/notification` | `NotificationService` |
|
|
49
|
+
| `@trismegisto/angular/spine/graphql` | `provideGraphql`, `injectGraphqlClient`, `unwrap`, `failedEnvelopes`, `wsReconnected$`, `GraphqlClient`; tipos `GraphqlEndpoint`/`GraphqlEnvelope` (reexportados do núcleo) |
|
|
50
|
+
| `@trismegisto/angular/spine/auto-service` | `provideAutoService({ adminApi })`, `AutoServiceService`, `AUTO_SERVICE_SCREENS`, `AUTO_SERVICE_DOCUMENTS` |
|
|
51
|
+
| `@trismegisto/angular/spine/audit` | `SpineAuditComponent` (`spine-audit`), `SpineLoginAttemptsComponent`, `SpineAuditService`, `AUDIT_PAGE_SIZE` — **importe só de código lazy** |
|
|
52
|
+
|
|
53
|
+
**Núcleo sem framework** (`@trismegisto/spine` e `@trismegisto/spine/<módulo>`): tipos e **valores** (constante, função,
|
|
54
|
+
classe) que não dependem de Angular. A casca **não** reexporta valor do núcleo (só tipo): esses se importam daqui.
|
|
55
|
+
A raiz reexporta quase todos os módulos (fora `ai-agent`, `ai-agent-transcript`, `markdown`, `markdown-sanitize`).
|
|
56
|
+
|
|
57
|
+
| Módulo | Exemplos |
|
|
58
|
+
|---|---|
|
|
59
|
+
| `@trismegisto/spine` (raiz) / `runtime-environment` | `loadRuntimeConfig` (do primitives, só na raiz), `applyRuntimeEnvironment` |
|
|
60
|
+
| `config`, `brand` | tipos `SpineConfig`, `SpineFeatures`, `SpineMcpServer`, `SpineNoticeType`, `PackageInfo`; `SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon` |
|
|
61
|
+
| `route`, `route-chain` | `Route`, `routerIdOf`, `resolveRouteChain`, `findFirstNavigable` |
|
|
62
|
+
| `notification` | `AlertType`, `Notification` |
|
|
63
|
+
| `graphql` | `GraphqlEnvelopeError`, `isEnvelopeOk`, `envelopesOf` |
|
|
64
|
+
| `settings`, `workspace-nav`, `search`, `quick-access` | `SPINE_SETTINGS_KEYS`, `SPINE_SETTINGS_ALIASES`; `SPINE_WORKSPACE_LIMITS`; `SpineSearchProvider`, `SpineSearchResult`; `QuickAccessItem` |
|
|
65
|
+
| `auto-service`, `audit`, `login-attempts` | `AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`; `buildAuditQuery`, `auditApiBase`… |
|
|
66
|
+
| `messages` (`/en`, `/es`) | `SpineMessages`, `SPINE_MESSAGES_PT_BR`/`_EN`/`_ES` |
|
|
67
|
+
|
|
68
|
+
Lista completa dos valores que saíram da casca na 3.4.0: §11.
|
|
42
69
|
|
|
43
70
|
## 3. Bootstrap
|
|
44
71
|
|
|
@@ -65,7 +92,7 @@ loadRuntimeConfig(environment, { required: !isDevMode() })
|
|
|
65
92
|
.catch((err) => console.error(err));
|
|
66
93
|
```
|
|
67
94
|
|
|
68
|
-
`loadRuntimeConfig(environment, { file?, required? })` (3.1.0; do `@trismegisto/primitives`, reexportado
|
|
95
|
+
`loadRuntimeConfig(environment, { file?, required? })` (3.1.0; do `@trismegisto/primitives`, reexportado na raiz do núcleo `@trismegisto/spine`)
|
|
69
96
|
busca `config.json` (ou `file`) relativo ao `<base href>` e o mescla no `environment` (objetos chave a chave;
|
|
70
97
|
arrays e valores simples substituem). É o que permite **uma imagem por versão**: o build não sabe o ambiente, o
|
|
71
98
|
deploy põe ao lado do `index.html` a cópia de `src/brand/config/<ambiente>.json`. Com `required`, falta ou JSON
|
|
@@ -88,10 +115,10 @@ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
|
|
|
88
115
|
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
|
|
89
116
|
import { provideRouter } from '@angular/router';
|
|
90
117
|
import { provideAuth } from '@orfeu/angular/core';
|
|
91
|
-
import { provideUi } from '@trismegisto/spine';
|
|
92
|
-
import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
|
|
93
|
-
import { provideAutoService } from '@trismegisto/spine/auto-service';
|
|
94
|
-
import { provideGraphql } from '@trismegisto/spine/graphql';
|
|
118
|
+
import { provideUi } from '@trismegisto/angular/spine';
|
|
119
|
+
import { APP_ROUTES, provideShell } from '@trismegisto/angular/spine/shell';
|
|
120
|
+
import { provideAutoService } from '@trismegisto/angular/spine/auto-service';
|
|
121
|
+
import { provideGraphql } from '@trismegisto/angular/spine/graphql';
|
|
95
122
|
import { components } from './features/features.routes';
|
|
96
123
|
import { environment } from '../environments/environment';
|
|
97
124
|
import packageInfo from '../../package.json';
|
|
@@ -141,10 +168,10 @@ O que cada provider faz:
|
|
|
141
168
|
| `idleTimeout: true \| { min?, max? }` | Conta › "Encerrar por inatividade" (com `max`, some o "Nunca") |
|
|
142
169
|
| `startPage: true` | Conta › "Tela inicial" depois do login: início, um favorito ou a última tela |
|
|
143
170
|
| `defaultBadge: true` | Conta › "Crachá padrão" (nível de acesso do login, guardado no Argos) |
|
|
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`) |
|
|
171
|
+
| `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/angular/spine/layout`) |
|
|
145
172
|
| `accountPreferences: true` | guarda as preferências (aparência, região, acessibilidade, favoritos, tela inicial…) também na conta do Argos |
|
|
146
173
|
| `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 |
|
|
174
|
+
| `unsavedChanges: true` | aviso de alterações não salvas: a tela registra com `registerSpineUnsavedChanges(() => form.dirty)` (`@trismegisto/angular/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 |
|
|
148
175
|
|
|
149
176
|
- **`provideRouter(APP_ROUTES)`** — `APP_ROUTES` = `PUBLIC_ROUTES` (`/login`, `/callback`, `/logoff`,
|
|
150
177
|
`/blocked`, `''` → `login`) + `{ path: '', component: LayoutComponent, canActivate/canActivateChild:
|
|
@@ -215,7 +242,7 @@ A árvore de navegação **não está no app**: vem do `/view` do Argos (`ViewSe
|
|
|
215
242
|
router. Chunk que sumiu do servidor (build novo com a aba aberta, `isChunkLoadError`): página pronta
|
|
216
243
|
`hm-state-page kind="outdated"` ("Nova versão disponível") com o botão "Recarregar" (`window.location.reload()`).
|
|
217
244
|
Não há nada a configurar; em telas próprias que fazem `import()` dinâmico, use `isChunkLoadError(err)` para
|
|
218
|
-
mostrar a mesma página (`isChunkLoadError` sai de `@trismegisto/spine/routing`).
|
|
245
|
+
mostrar a mesma página (`isChunkLoadError` sai de `@trismegisto/angular/spine/routing`).
|
|
219
246
|
- **Título e descrição** da tela aparecem na `spine-page-bar` do painel: título = `route_display_name`,
|
|
220
247
|
descrição = `Route.description` (`web.router.description`, editada no Argos), ícone = `route_icon` (ou o do
|
|
221
248
|
módulo). **A tela não repete título nem descrição** no próprio template — comece direto pelo conteúdo
|
|
@@ -246,7 +273,7 @@ interceptor em silêncio e nenhum evento de auditoria sai com tela/app.
|
|
|
246
273
|
O interceptor **não** põe o token. Nas APIs REST do app, mande `x-access-token` com
|
|
247
274
|
`inject(AuthorizationService).getToken()` (receitas §4; detalhes na skill orfeu).
|
|
248
275
|
|
|
249
|
-
## 6. GraphQL (`@trismegisto/spine/graphql`)
|
|
276
|
+
## 6. GraphQL (`@trismegisto/angular/spine/graphql`)
|
|
250
277
|
|
|
251
278
|
```ts
|
|
252
279
|
// environment.ts (vazio = derivado atrás do proxy; URL explícita vem do config.json do ambiente)
|
|
@@ -286,13 +313,14 @@ async listTeams() {
|
|
|
286
313
|
- Trate o erro como **estado da tela** (`resource().error()`, `catch` → `hm-alert`/`hm-state-screen`), não
|
|
287
314
|
`console.error` nem `?? []`. Decida por `err.status` (403 sem acesso, 404 vazio, 5xx tentar de novo). Mostre
|
|
288
315
|
`message` como texto, nunca por `innerHTML`.
|
|
289
|
-
- Utilitários: `isEnvelopeOk(status)`, `envelopesOf(data)
|
|
316
|
+
- Utilitários: `failedEnvelopes(data)` (casca); `isEnvelopeOk(status)`, `envelopesOf(data)` e a classe
|
|
317
|
+
`GraphqlEnvelopeError` (para `instanceof`) vêm do núcleo `@trismegisto/spine/graphql` (desde a 3.4.0 a casca não os reexporta).
|
|
290
318
|
|
|
291
319
|
## 7. Serviços do shell para as telas
|
|
292
320
|
|
|
293
321
|
| Preciso de… | Use |
|
|
294
322
|
|---|---|
|
|
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 |
|
|
323
|
+
| Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/angular/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 |
|
|
296
324
|
| 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 |
|
|
297
325
|
| Modal só texto | `ModalService.open({ title, text })` |
|
|
298
326
|
| Painel lateral | `SidePanelService.open(...)` — mesma API (`SidePanelContent` = `ModalContent`), `size` aceita também `'full'` |
|
|
@@ -303,7 +331,7 @@ async listTeams() {
|
|
|
303
331
|
| Reabrir novidades | `SpineNewsService.showAll()` (tour guiado de uma tela: `hm-tour`, do `@trismegisto/angular`; o spine não tem tour próprio) |
|
|
304
332
|
| Fuso e idioma da pessoa | `SpinePreferencesService.effectiveTimeZone()` (sinal; IANA) e `language()`; também `hourCycle()`, `weekStart()`, `textScale()`, `motion()` |
|
|
305
333
|
| 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 |
|
|
306
|
-
| Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/spine/routing`) |
|
|
334
|
+
| Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/angular/spine/routing`) |
|
|
307
335
|
| Tema/densidade por código | `ThemeService.setMode('light'\|'dark'\|'system')`, `setTheme`, `DensityService.setDensity('comfortable'\|'compact')`, `toggleDensity()`, `ThemePresetService.setPreset(family)` — sincronizam entre abas. Em geral **não precisa**: o painel de configurações já oferece tudo |
|
|
308
336
|
|
|
309
337
|
Atalhos globais já registrados: `G H` (início), `G 1…9` (favoritos), `Mod+K` (busca), `Mod+,`
|
|
@@ -317,7 +345,7 @@ sozinho no painel `?`. Não reuse essas combinações.
|
|
|
317
345
|
(`AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`) e ficam em chunks próprios (`AUTO_SERVICE_SCREENS`). As classes das
|
|
318
346
|
telas **não são exportadas** de propósito. `AutoServiceService` expõe o HTTP (`{adminApi}/auto-service/...`)
|
|
319
347
|
para quem precisar.
|
|
320
|
-
- **Auditoria** (`@trismegisto/spine/audit`): `<spine-audit scope="admin" />` (todos os apps,
|
|
348
|
+
- **Auditoria** (`@trismegisto/angular/spine/audit`): `<spine-audit scope="admin" />` (todos os apps,
|
|
321
349
|
`{adminApi}/admin/audit/*`) ou `<spine-audit scope="client" [clientId]="id" />` (apps do projeto do client,
|
|
322
350
|
`{adminApi}/auto-service/:clientId/audit/*`, recorte no servidor). `adminApi` pelo input `[adminApi]` ou
|
|
323
351
|
pelo `SPINE_ADMIN_API`. Inclui período rápido, filtros (com filtros salvos), KPIs, linha do tempo,
|
|
@@ -356,11 +384,12 @@ sozinho no painel `?`. Não reuse essas combinações.
|
|
|
356
384
|
importe a classe de uma tela estaticamente em `features.routes.ts`, `app.config.ts` ou serviço global.
|
|
357
385
|
Um `features.routes.spec.ts` confere que todo `load()` resolve e que os `id` são UUID únicos, sem
|
|
358
386
|
diferenciar maiúsculas (receitas §15).
|
|
359
|
-
3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/spine/audit` em código do bundle
|
|
387
|
+
3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/angular/spine/audit` em código do bundle
|
|
360
388
|
inicial (só em rota/`import()`/`@defer`). As telas do auto-serviço nem são exportadas; não tente
|
|
361
|
-
alcançá-las por caminho interno. (O
|
|
362
|
-
`export` estático de tela faria o
|
|
363
|
-
|
|
389
|
+
alcançá-las por caminho interno. (O `@trismegisto/angular` confere isso no próprio build com
|
|
390
|
+
`scripts/check-spine-lazy.mjs`: um `export` estático de tela faria o bundler colar a tela no bundle inicial de
|
|
391
|
+
todo app.) Pelo mesmo motivo, código que entra no `main` importa do ponto (`@trismegisto/angular/spine/...`),
|
|
392
|
+
nunca do barrel `@trismegisto/angular`.
|
|
364
393
|
4. **`COMPONENT_ROUTES` é `multi`.** Contribua pelo `provideShell` (ou com `{ provide: COMPONENT_ROUTES,
|
|
365
394
|
useValue: [...], multi: true }`). Sem `multi: true` o Angular lança erro de provider inconsistente.
|
|
366
395
|
5. **Id da tela = `router_id`** (`routerIdOf`). `routed_id`/`web.routes.route_id` não acha componente; é o que
|
|
@@ -385,5 +414,38 @@ sozinho no painel `?`. Não reuse essas combinações.
|
|
|
385
414
|
14. **Logo** é arquivo do app (`src/assets/images/logo.svg` por convenção), legível sobre o fundo escuro do
|
|
386
415
|
cabeçalho **nos dois temas**; marca em componente via `SPINE_BRAND` (sem link/botão dentro).
|
|
387
416
|
|
|
417
|
+
15. **Valor do núcleo vem do núcleo.** `GraphqlEnvelopeError`, `isEnvelopeOk`, `AlertType`, `routerIdOf`,
|
|
418
|
+
`SPINE_SETTINGS_KEYS`, `AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`… se importam de `@trismegisto/spine[/módulo]`. Importados
|
|
419
|
+
da casca, dão `TS1362 ('X' cannot be used as a value because it was exported using 'export type')` ou `has no
|
|
420
|
+
exported member`. Tipos podem vir de qualquer um dos dois.
|
|
421
|
+
|
|
422
|
+
## 11. Migração da 3.3.x para a 3.4.0
|
|
423
|
+
|
|
424
|
+
1. **`package.json`:** todos os `@trismegisto/*` em `^3.4.0`; acrescente `marked` e `dompurify` (antes vinham com o
|
|
425
|
+
spine; agora são peers opcionais) e mantenha `@trismegisto/spine` e `@orfeu/angular` (peers opcionais da casca).
|
|
426
|
+
2. **Imports da casca** (troca mecânica, mesmos nomes):
|
|
427
|
+
|
|
428
|
+
| 3.3.x | 3.4.0 |
|
|
429
|
+
|---|---|
|
|
430
|
+
| `@trismegisto/spine` (`provideUi`, `SPINE_CONFIG`, `SPINE_ADMIN_API`, `SPINE_MESSAGES`, `provideSpineMessages`, `provideSpineSearch`, `ThemeService`…) | `@trismegisto/angular/spine` |
|
|
431
|
+
| `@trismegisto/spine/<sub>` (`layout`, `shell`, `routing`, `modal`, `notification`, `side-panel`, `graphql`, `auto-service`, `audit`) | `@trismegisto/angular/spine/<sub>` |
|
|
432
|
+
| `@trismegisto/spine` (`applyRuntimeEnvironment`, `loadRuntimeConfig`, `Route`, `routerIdOf`, tipos de `SpineConfig`…) | continua `@trismegisto/spine` (núcleo) |
|
|
433
|
+
|
|
434
|
+
3. **Valores que saíram da casca** (agora só no núcleo; tabela completa no `docs/migration/apps-impact.md` do Trismegisto):
|
|
435
|
+
|
|
436
|
+
| Estavam em | Agora em | Exemplos |
|
|
437
|
+
|---|---|---|
|
|
438
|
+
| `…/spine/graphql` | `@trismegisto/spine/graphql` | `GraphqlEnvelopeError`, `isEnvelopeOk`, `envelopesOf` |
|
|
439
|
+
| `…/spine/notification` | `@trismegisto/spine/notification` | `AlertType` |
|
|
440
|
+
| `…/spine/audit` | `@trismegisto/spine/audit` e `/login-attempts` | `AUDIT_*` (menos `AUDIT_PAGE_SIZE`, que fica na casca), `buildAuditQuery`, `auditApiBase`, `LOGIN_ATTEMPT_*` |
|
|
441
|
+
| `…/spine/auto-service` | `@trismegisto/spine/auto-service` | `AUTO_SERVICE_*_TEMPLATE_ROUTER_ID` |
|
|
442
|
+
| `…/spine/layout` | `@trismegisto/spine/settings`, `/workspace-nav`, `/suggestions`, `/ratings`, `/markdown-sanitize`, `/idle`, `/inbox`, `/account-preferences`, `/account-security`, `/app-tokens`, `/start-page`, `/ai-agent-page` | `SPINE_SETTINGS_KEYS`, `SPINE_SETTINGS_ALIASES`, `resolveSettingsSection`, `SPINE_WORKSPACE_LIMITS`, `SPINE_PRESENT_PARAM`, `SPINE_SUGGESTION_*`, `spineStarFills`, `SPINE_MARKDOWN_PURIFY_CONFIG`, `SPINE_IDLE_WARNING_SECONDS`, `SPINE_INBOX_POLL_MS`, `argosAccountApi`, `buildMcpConfig`, `isInternalPath`, `SPINE_AI_AGENT_PAGE_PATH` |
|
|
443
|
+
|
|
444
|
+
Os documentos do auto-serviço (`news|ratings|suggestions.{usage,technical}`) ficam só em
|
|
445
|
+
`@trismegisto/spine/auto-service-docs/*`.
|
|
446
|
+
4. **Gráficos, mapas e terminal**, se usados: `angular.md` §9.
|
|
447
|
+
5. `npm install`, `ng build` e os testes: qualquer import esquecido vira erro de compilação (nada falha em silêncio).
|
|
448
|
+
Para conferir: `grep -rn "@trismegisto/spine/" src` só pode achar módulos do núcleo.
|
|
449
|
+
|
|
388
450
|
Se você está **desenvolvendo o próprio spine** (não um app consumidor), siga as convenções do repositório
|
|
389
451
|
dele; este guia é para quem consome o pacote.
|
|
@@ -29,6 +29,34 @@ for (const s of SELETORES) {
|
|
|
29
29
|
}
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
+
/** Caminhos de import desde a 3.4.0: o que cada casca Angular exporta e os valores/tipos de cada módulo do núcleo do spine. */
|
|
33
|
+
const IMPORTS = ler('imports.json');
|
|
34
|
+
const NUCLEO_SPINE = '@trismegisto/spine';
|
|
35
|
+
/** Nome → pontos da casca do spine que o exportam. */
|
|
36
|
+
const NA_CASCA = new Map();
|
|
37
|
+
for (const [ponto, nomes] of Object.entries(IMPORTS.casca)) {
|
|
38
|
+
if (!ponto.startsWith('@trismegisto/angular/spine')) continue;
|
|
39
|
+
for (const n of nomes) NA_CASCA.set(n, [...(NA_CASCA.get(n) ?? []), ponto]);
|
|
40
|
+
}
|
|
41
|
+
/** Valor do núcleo → módulos que o exportam. Tudo o que a raiz `@trismegisto/spine` pode exportar. */
|
|
42
|
+
const VALOR_NO_NUCLEO = new Map();
|
|
43
|
+
const NA_RAIZ_DO_NUCLEO = new Set(['loadRuntimeConfig', 'LoadRuntimeConfigOptions']);
|
|
44
|
+
for (const [modulo, { valores, tipos }] of Object.entries(IMPORTS.nucleo)) {
|
|
45
|
+
for (const n of valores) VALOR_NO_NUCLEO.set(n, [...(VALOR_NO_NUCLEO.get(n) ?? []), modulo]);
|
|
46
|
+
for (const n of [...valores, ...tipos]) NA_RAIZ_DO_NUCLEO.add(n);
|
|
47
|
+
}
|
|
48
|
+
/** Componentes e providers das cascas de gráficos, mapas e terminal (que até a 3.3.x saíam do pacote do núcleo). */
|
|
49
|
+
const CASCA_DA_PECA = { '@trismegisto/charts': '@trismegisto/angular/charts', '@trismegisto/maps': '@trismegisto/angular/map', '@trismegisto/terminal': '@trismegisto/angular/terminal' };
|
|
50
|
+
const PROPRIO_DA_CASCA = /Component$|^HM_|^provide\w+Messages$|I18nService$|_I18N_CONFIG$|^(?:MAPS|TERMINAL)_MESSAGES$/;
|
|
51
|
+
|
|
52
|
+
/** `import { a, type b } from 'x'` (também `import type`), com a posição de cada um. */
|
|
53
|
+
function* importsNomeados(texto) {
|
|
54
|
+
for (const m of texto.matchAll(/\bimport\s+(type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
|
|
55
|
+
const nomes = m[2].split(',').map((n) => n.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim()).filter(Boolean);
|
|
56
|
+
yield { origem: m[3], nomes, pos: m.index };
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
32
60
|
/** Distância de edição (para sugerir o nome mais próximo). */
|
|
33
61
|
function distancia(a, b) {
|
|
34
62
|
const d = Array.from({ length: a.length + 1 }, (_, i) => [i]);
|
|
@@ -195,6 +223,43 @@ const regras = [
|
|
|
195
223
|
return out;
|
|
196
224
|
},
|
|
197
225
|
},
|
|
226
|
+
{
|
|
227
|
+
id: 'import-3-4',
|
|
228
|
+
resumo: 'import pelo caminho anterior à 3.4.0 (casca do spine, gráficos, mapas e terminal no @trismegisto/angular; valores no núcleo)',
|
|
229
|
+
aceita: (a) => a.ext === '.ts',
|
|
230
|
+
checar(arq) {
|
|
231
|
+
const out = [];
|
|
232
|
+
const achado = (pos, mensagem, correcao) => out.push({ linha: arq.linhaDe(pos), mensagem, correcao });
|
|
233
|
+
for (const imp of importsNomeados(arq.limpo)) {
|
|
234
|
+
const { origem, nomes, pos } = imp;
|
|
235
|
+
// 1. Casca do spine importada pelo pacote do núcleo (`@trismegisto/spine[/sub]`).
|
|
236
|
+
if (origem === NUCLEO_SPINE || origem.startsWith(NUCLEO_SPINE + '/')) {
|
|
237
|
+
const doModulo = origem === NUCLEO_SPINE ? NA_RAIZ_DO_NUCLEO : new Set([...(IMPORTS.nucleo[origem]?.valores ?? []), ...(IMPORTS.nucleo[origem]?.tipos ?? [])]);
|
|
238
|
+
for (const n of nomes) {
|
|
239
|
+
if (doModulo.has(n) || !NA_CASCA.has(n)) continue;
|
|
240
|
+
const destino = NA_CASCA.get(n).find((p) => p.endsWith(origem.slice(NUCLEO_SPINE.length))) ?? NA_CASCA.get(n)[0];
|
|
241
|
+
achado(pos, `\`${n}\` não está em \`${origem}\` desde a 3.4.0: o pacote virou só o núcleo do spine e a casca Angular mudou de lugar`, `importe de \`${destino}\` (references/spine.md §11)`);
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
// 2. Valor do núcleo importado da casca (a casca só reexporta tipos: TS1362).
|
|
245
|
+
if (IMPORTS.casca[origem] && origem.startsWith('@trismegisto/angular/spine')) {
|
|
246
|
+
for (const n of nomes) {
|
|
247
|
+
if (IMPORTS.casca[origem].includes(n) || !VALOR_NO_NUCLEO.has(n)) continue;
|
|
248
|
+
achado(pos, `\`${n}\` é valor do núcleo e não sai de \`${origem}\` (a casca reexporta só tipos)`, `importe de \`${VALOR_NO_NUCLEO.get(n)[0]}\` (references/spine.md §11)`);
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
// 3. Componente/provider de gráfico, mapa ou terminal importado do pacote do núcleo.
|
|
252
|
+
const casca = CASCA_DA_PECA[origem];
|
|
253
|
+
if (casca) {
|
|
254
|
+
for (const n of nomes) {
|
|
255
|
+
if (!PROPRIO_DA_CASCA.test(n) || !IMPORTS.casca[casca]?.includes(n)) continue;
|
|
256
|
+
achado(pos, `\`${n}\` saiu de \`${origem}\` na 3.4.0 (o pacote virou só o núcleo sem framework)`, `importe de \`${casca}\`; tipos de dados e catálogos continuam em \`${origem}\` (references/angular.md §9)`);
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
return out;
|
|
261
|
+
},
|
|
262
|
+
},
|
|
198
263
|
];
|
|
199
264
|
|
|
200
265
|
/** Tokens `--hm-*` que o próprio app declara (tema/família exportados do theme builder etc.). */
|
|
@@ -209,7 +274,7 @@ function preparar(arquivos, ctx) {
|
|
|
209
274
|
|
|
210
275
|
process.exitCode = executar({
|
|
211
276
|
skill: 'trismegisto',
|
|
212
|
-
descricao: 'cores cravadas, tokens/seletores/ícones inexistentes
|
|
277
|
+
descricao: 'cores cravadas, tokens/seletores/ícones inexistentes, (click) em botão do Trismegisto e imports anteriores à 3.4.0.',
|
|
213
278
|
regras,
|
|
214
279
|
extensoes: ['.ts', '.html', '.css', '.scss', '.less'],
|
|
215
280
|
preparar,
|