@acropole/skills 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +14 -11
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/bin/install.js +41 -9
  4. package/package.json +1 -1
  5. package/skills/acropole/SKILL.md +2 -2
  6. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
  7. package/skills/angular/SKILL.md +4 -3
  8. package/skills/angular/references/armadilhas.md +3 -3
  9. package/skills/angular/references/dados.md +3 -3
  10. package/skills/angular/references/estrutura.md +6 -5
  11. package/skills/angular/references/features.md +5 -5
  12. package/skills/angular/references/testes-build.md +1 -1
  13. package/skills/auto-servico/SKILL.md +18 -14
  14. package/skills/auto-servico/references/roteiros.md +1 -1
  15. package/skills/auto-servico/references/tools.md +1 -1
  16. package/skills/express/references/dados.md +4 -1
  17. package/skills/express/references/estrutura.md +2 -1
  18. package/skills/fastapi/references/banco.md +6 -2
  19. package/skills/fastapi/references/estrutura.md +1 -1
  20. package/skills/hefesto/SKILL.md +13 -6
  21. package/skills/hefesto/references/diagnostico.md +1 -0
  22. package/skills/hefesto/references/mcp-roteiros.md +48 -7
  23. package/skills/orfeu/SKILL.md +43 -13
  24. package/skills/orfeu/references/angular-api.md +39 -13
  25. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  26. package/skills/orfeu/references/angular-recipes.md +25 -12
  27. package/skills/orfeu/references/angular.md +37 -15
  28. package/skills/orfeu/references/diferencas.md +17 -8
  29. package/skills/orfeu/references/node-api.md +41 -9
  30. package/skills/orfeu/references/node-armadilhas.md +16 -2
  31. package/skills/orfeu/references/node-recipes.md +13 -4
  32. package/skills/orfeu/references/node.md +31 -12
  33. package/skills/orfeu/references/python-api.md +41 -16
  34. package/skills/orfeu/references/python-recipes.md +13 -9
  35. package/skills/orfeu/references/python.md +33 -12
  36. package/skills/orfeu/references/react.md +133 -0
  37. package/skills/orquestracao/SKILL.md +3 -1
  38. package/skills/orquestracao/scripts/coord.sh +10 -2
  39. package/skills/trismegisto/SKILL.md +89 -35
  40. package/skills/trismegisto/references/angular-api.md +4548 -344
  41. package/skills/trismegisto/references/angular-exports.md +8275 -2579
  42. package/skills/trismegisto/references/angular-recipes.md +327 -6
  43. package/skills/trismegisto/references/angular-types.md +92 -0
  44. package/skills/trismegisto/references/angular.md +96 -16
  45. package/skills/trismegisto/references/catalogo/icones.json +7 -0
  46. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  47. package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
  48. package/skills/trismegisto/references/catalogo/tokens.json +114 -0
  49. package/skills/trismegisto/references/react-api.md +16864 -0
  50. package/skills/trismegisto/references/react.md +237 -0
  51. package/skills/trismegisto/references/spine-api.md +5904 -1361
  52. package/skills/trismegisto/references/spine-recipes.md +140 -46
  53. package/skills/trismegisto/references/spine.md +121 -49
  54. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -0,0 +1,237 @@
1
+ # `@trismegisto/react` — interface de apps React
2
+
3
+ Desde a **3.4.0** o Trismegisto tem a lib React (`@trismegisto/react`, React 19), irmã do `@trismegisto/angular`: **as
4
+ mesmas peças, o mesmo DOM** (o host é a mesma tag `hm-*`, com o mesmo markup, classes e ARIA), o **mesmo CSS**
5
+ (`@trismegisto/core`) e a **mesma lógica** (`@trismegisto/primitives` e os núcleos). Tudo o que o `SKILL.md` diz de
6
+ tokens, ícones, tema, i18n, acessibilidade, estados da tela e peças de domínio vale igual; muda a forma de usar.
7
+ Nomes exatos de cada componente, hook e tipo: `react-api.md` (gerado do código; busque pelo nome). Login e sessão:
8
+ skill `orfeu` (`references/react.md`).
9
+
10
+ ## 1. Angular ou React?
11
+
12
+ - **Siga o framework do app.** `@angular/core` no `package.json` → `@trismegisto/angular` (`angular.md`); `react` →
13
+ `@trismegisto/react` (este arquivo). Não misture as duas libs no mesmo app.
14
+ - **App novo:** a plataforma é Angular (skill `angular`, shell `@trismegisto/angular/spine`, todos os apps de
15
+ referência). React é para quem já tem um app React ou foi pedido explicitamente; o shell React
16
+ (`@trismegisto/react/spine`) tem as mesmas telas e recursos.
17
+ - O nome do componente e das props segue a regra do §3; a API Angular (`angular-api.md`) continua sendo a melhor
18
+ descrição do comportamento, e o `react-api.md` dá as props exatas.
19
+
20
+ ## 2. Instalação e setup
21
+
22
+ ```bash
23
+ npm install @trismegisto/react @trismegisto/core @trismegisto/tokens @trismegisto/primitives @trismegisto/icons
24
+ # opcionais (peers opcionais do @trismegisto/react), só se usar a peça, na mesma versão:
25
+ npm install @trismegisto/charts # @trismegisto/react/charts
26
+ npm install @trismegisto/maps # @trismegisto/react/map
27
+ npm install @trismegisto/terminal # @trismegisto/react/terminal
28
+ npm install @trismegisto/spine @orfeu/react@^1.7.1 react-router marked dompurify # @trismegisto/react/spine
29
+ ```
30
+
31
+ Peers: `react` e `react-dom` **≥ 19** (o host `hm-*` é custom element; o React 19 converte `className` em `class`).
32
+ CSS uma vez, na entrada do app, nesta ordem:
33
+
34
+ ```tsx
35
+ import '@trismegisto/tokens/tokens.css';
36
+ import '@trismegisto/core/core.css';
37
+ ```
38
+
39
+ ```tsx
40
+ import { HermesThemeProvider, HermesThemeRoot } from '@trismegisto/react/theme';
41
+ import { HermesI18nProvider } from '@trismegisto/react/i18n';
42
+ import { HermesToastProvider, ToastStack } from '@trismegisto/react/toast';
43
+ import { HermesDialogProvider } from '@trismegisto/react/dialog';
44
+
45
+ export function App() {
46
+ return (
47
+ <HermesI18nProvider config={{ locale: 'pt-BR' }}>
48
+ <HermesThemeProvider>
49
+ <HermesToastProvider>
50
+ <HermesDialogProvider>
51
+ <HermesThemeRoot className="app"> {/* o [hermesTheme] do Angular: aplica tema/família/densidade/fonte */}
52
+ <Telas />
53
+ <ToastStack /> {/* uma vez, no layout */}
54
+ </HermesThemeRoot>
55
+ </HermesDialogProvider>
56
+ </HermesToastProvider>
57
+ </HermesThemeProvider>
58
+ </HermesI18nProvider>
59
+ );
60
+ }
61
+ ```
62
+
63
+ - Sem provider, tema, idioma e fila de toasts usam um store padrão do módulo (funciona, mas o provider é o lugar da
64
+ configuração: `HermesThemeProvider config` = o `HERMES_THEME_CONFIG`, com `extendThemeConfig` do primitives para
65
+ famílias e fontes próprias, `SKILL.md` §4).
66
+ - Idioma: `useHermesI18n().setLocale('en')` troca a lib (e gráficos, mapas, terminal e spine) sem recarregar.
67
+ - Ícones do app: `registerIcons(...)`/`loadIcons(...)` de `@trismegisto/icons`; os que os componentes usam por dentro
68
+ já vêm registrados. Nome no catálogo em kebab-case (`<Icon shape="add-text" />`), como no Angular.
69
+ - Com o shell spine, quase tudo isso vem pronto: §5.
70
+
71
+ ## 3. De Angular para React: a regra das props
72
+
73
+ | Angular | React |
74
+ |---|---|
75
+ | `ButtonComponent` / `<hm-button>` | `Button` (`@trismegisto/react/button`) — mesma pasta do Angular |
76
+ | input `[label]` | prop `label` (mesmo nome) |
77
+ | output `(clicked)`, `(closed)`, `(rowClick)` | `onClick` (o `clicked`), `onClosed`, `onRowClick` |
78
+ | `model()` `[(value)]`, `[(open)]` | controlado `value` + `onValueChange`, `open` + `onOpenChange`; não controlado `defaultValue`, `defaultOpen` (o componente guarda o estado quando o controlado é `undefined`) |
79
+ | `<ng-content>` padrão | `children` |
80
+ | slot nomeado (`<div footer>`, `[mark]`, `[hmPrefix]`) | prop `ReactNode` com o nome do slot (`footer`, `mark`, `prefixSlot`) |
81
+ | `<ng-template #x>` / `TemplateRef` | função de render |
82
+ | serviço (`HermesToastService`, `HermesDialogService`, `HermesThemeService`, `HermesI18nService`) | provider + hook (`HermesToastProvider`/`useHermesToast`, `HermesDialogProvider`/`useHermesDialog`, `HermesThemeProvider`/`useHermesTheme`, `HermesI18nProvider`/`useHermesI18n`) |
83
+ | diretiva (`hmTooltip`, `hmShortcut`) | componente que envolve o filho e/ou hook (`useTooltip`, `useShortcut`) |
84
+ | `HermesFormFieldBase` (Reactive Forms, `ngModel`) | `FormFieldProps`: `value`/`defaultValue`/`onValueChange`, `name`, `disabled`, `required`, `error`, `messages`, `validators`, `errors`, `touched`, `onTouched`; `FormFieldsProvider` (`@trismegisto/react/forms`) em volta = `form.disable()`/`markAllAsTouched()` |
85
+ | `texts` (sobrescrita de textos da peça) | `texts` (mesmo nome) |
86
+
87
+ Atributos soltos (`id`, `data-*`, `aria-*`, `className`) vão para o host `hm-*`, como no Angular. Alguns nomes mudam
88
+ para não colidir com o DOM ou o React: o `hm-map` é `MapView`, o `hm-terminal` é `HermesTerminal`, os gráficos
89
+ perdem o `Hm` (`BarChart`, `LineChart`…). Na dúvida, busque o seletor no `react-api.md` ("no mesmo `<hm-x>` do
90
+ Angular").
91
+
92
+ ### Exemplo: formulário com confirmação
93
+
94
+ ```tsx
95
+ import { useState } from 'react';
96
+ import { Button } from '@trismegisto/react/button';
97
+ import { Input } from '@trismegisto/react/input';
98
+ import { Modal } from '@trismegisto/react/modal';
99
+ import { useHermesDialog } from '@trismegisto/react/dialog';
100
+ import { useHermesToast } from '@trismegisto/react/toast';
101
+
102
+ export function EditarEquipe({ equipe, salvar, excluir }: Props) {
103
+ const [aberto, setAberto] = useState(false);
104
+ const [nome, setNome] = useState(equipe.nome);
105
+ const dialog = useHermesDialog();
106
+ const toast = useHermesToast();
107
+
108
+ async function remover() {
109
+ const ok = await dialog.confirm({ heading: 'Excluir equipe?', message: 'Não dá para desfazer.', danger: true });
110
+ if (ok) { await excluir(equipe.id); toast.success('Equipe excluída.'); }
111
+ }
112
+
113
+ return (
114
+ <>
115
+ <Button onClick={() => setAberto(true)}>Editar</Button>
116
+ <Button intent="danger" onClick={remover}>Excluir</Button>
117
+ <Modal heading="Editar equipe" open={aberto} onOpenChange={setAberto}
118
+ footer={<Button intent="primary" onClick={() => salvar({ ...equipe, nome })}>Salvar</Button>}>
119
+ <Input label="Nome" value={nome} onValueChange={setNome} required />
120
+ </Modal>
121
+ </>
122
+ );
123
+ }
124
+ ```
125
+
126
+ O equivalente Angular: `<hm-button (clicked)>`, `<hm-modal [(open)]>` com `<div footer>`, `<hm-input [(value)]>` e
127
+ `HermesDialogService.confirm({ …, danger: true })`. As regras de ouro do `SKILL.md` §3 valem iguais: `label` real em
128
+ todo controle, ação destrutiva com `intent="danger"` **e** confirmação, estados carregando/vazio/erro distintos,
129
+ nenhum valor visual cravado.
130
+
131
+ ## 4. Gráficos, mapas e terminal (núcleo + casca)
132
+
133
+ Mesma regra do Angular (`angular.md` §9): o núcleo sem framework é **peer opcional**, a casca React fica **fora do
134
+ barrel** `@trismegisto/react` e só se importa pelo ponto. A casca reexporta só tipos; valor do núcleo vem do núcleo.
135
+
136
+ | Peça | Instale | Casca React | Do núcleo |
137
+ |---|---|---|---|
138
+ | Gráficos | `@trismegisto/charts` | `@trismegisto/react/charts`: `BarChart`, `LineChart`, `PieChart`, `HeatmapChart`, `CalendarHeatmap`, `ScatterChart`, `GaugeChart`, `FunnelChart`, `RadarChart`, `TreemapChart`, `SankeyChart`, `BoxplotChart`, `SparklineChart`, `BulletChart`, `WaterfallChart`, `Chart` (opção crua), `ChartsMessagesProvider`, `useChartsI18n` | `ChartSeries`, `ChartDatum`, `CHARTS_MESSAGES_*` |
139
+ | Mapas | `@trismegisto/maps` | `@trismegisto/react/map`: `MapView`, `MapMarker`, `MapPopup`, `MapCluster`, `MapPolyline`, `MapPolygon`, `MapCircle`, `MapGeoJson`, `MapBasemap`, `MapChoropleth`, `MapRoute`, `RouteDirections`, `StreetView`, `MapsMessagesProvider` | `GeoJsonFeatureCollection`, `BasemapLayer`, `MAPS_MESSAGES_*` |
140
+ | Terminal | `@trismegisto/terminal` | `@trismegisto/react/terminal`: `HermesTerminal`, `TerminalMessagesProvider`, `useTerminalMessages` | `Terminal`, `FitAddon`, `SearchAddon`, `WebLinksAddon` |
141
+
142
+ ```tsx
143
+ import { lazy, Suspense } from 'react';
144
+ import type { ChartSeries } from '@trismegisto/charts';
145
+ import { Skeleton } from '@trismegisto/react/skeleton';
146
+ const BarChart = lazy(() => import('@trismegisto/react/charts').then((m) => ({ default: m.BarChart })));
147
+
148
+ const receita: ChartSeries[] = [{ name: '2026', data: [140, 150, null, 160] }]; // null = lacuna
149
+ <Suspense fallback={<Skeleton shape="card" label="Carregando gráfico" />}>
150
+ <BarChart label="Receita por trimestre" categories={['T1', 'T2', 'T3', 'T4']} series={receita}
151
+ numberFormat={{ style: 'currency', currency: 'BRL', notation: 'compact' }} />
152
+ </Suspense>
153
+ ```
154
+
155
+ Gráficos e mapas pesam: carregue sob demanda (`lazy`/rota lazy), como o `@defer` do Angular. `label` é
156
+ obrigatório nos gráficos (nome acessível e legenda da tabela).
157
+
158
+ ## 5. Shell spine em React (`@trismegisto/react/spine`)
159
+
160
+ Mesmas telas e recursos da casca Angular (cabeçalho, menu lateral vindo do `/view` do Argos, área de trabalho em
161
+ abas, barra da página, login/callback, configurações, busca, novidades, avaliações, sugestões, agente de IA,
162
+ auto-serviço, auditoria), sobre o **React Router v7 em modo data** e o **`@orfeu/react`**. Decisões (acesso, cadeia de
163
+ rotas, menu, catálogos `SpineMessages`) vêm do mesmo núcleo `@trismegisto/spine`. Peers opcionais a instalar:
164
+ `@trismegisto/spine`, `react-router` (`^7`), `@orfeu/react` (`^1.7.1`, nunca `@latest`), `marked`, `dompurify` e, só com
165
+ `/graphql`, `@apollo/client`, `graphql`, `graphql-ws`, `rxjs`.
166
+
167
+ ```tsx
168
+ // main.tsx
169
+ import { createRoot } from 'react-dom/client';
170
+ import { createBrowserRouter, RouterProvider } from 'react-router';
171
+ import { OrfeuProvider, createAuthClient } from '@orfeu/react';
172
+ import { applyRuntimeEnvironment, loadRuntimeConfig, type SpineConfig } from '@trismegisto/spine';
173
+ import { HermesThemeProvider } from '@trismegisto/react/theme';
174
+ import { HermesToastProvider } from '@trismegisto/react/toast';
175
+ import { SpineProvider, createSpineRoutes, type SpineComponentRoute } from '@trismegisto/react/spine';
176
+ import { GraphqlProvider } from '@trismegisto/react/spine/graphql';
177
+ import { environment } from './environment';
178
+
179
+ await loadRuntimeConfig(environment, { required: import.meta.env.PROD }); // config.json do deploy (imagem única)
180
+ applyRuntimeEnvironment(environment);
181
+
182
+ const auth = createAuthClient(environment.authorizationServer);
183
+ const config: SpineConfig = { clientId: environment.authorizationServer.clientId, appName: 'Meu App' };
184
+ const components: SpineComponentRoute[] = [
185
+ {
186
+ id: '<router_id da tela>', // o router da tela no Argos, como no Angular
187
+ load: () => import('./telas/pedidos'), // módulo com default, ou o componente
188
+ document: { load: () => import('./telas/pedidos/README.md?raw').then((m) => m.default) },
189
+ },
190
+ ];
191
+ const router = createBrowserRouter(createSpineRoutes({ auth, components, config }));
192
+ auth.connectRouter(router);
193
+
194
+ createRoot(document.getElementById('root')!).render(
195
+ <OrfeuProvider client={auth}>
196
+ <HermesThemeProvider>
197
+ <HermesToastProvider>
198
+ <SpineProvider config={config} adminApi={environment.adminApi}>
199
+ <GraphqlProvider endpoints={environment.graphql}> {/* opcional */}
200
+ <RouterProvider router={router} />
201
+ </GraphqlProvider>
202
+ </SpineProvider>
203
+ </HermesToastProvider>
204
+ </HermesThemeProvider>
205
+ </OrfeuProvider>,
206
+ );
207
+ ```
208
+
209
+ (`import.meta.env.PROD` e `?raw` são do Vite; ajuste ao bundler do app. Sem top-level await, encadeie com `.then`.)
210
+
211
+ | Angular (`@trismegisto/angular/spine…`) | React (`@trismegisto/react/spine…`) |
212
+ |---|---|
213
+ | `provideUi(config)` + `provideSpineMessages` | `<SpineProvider config messages packageInfo adminApi>` |
214
+ | `APP_ROUTES` + `provideShell({ appComponents })` + `ViewGuard` | `createSpineRoutes({ auth, components, children, search, settingsSections, config })` (o `loader` do coringa é o `ViewGuard`) |
215
+ | `ComponentRoute` (`id`, `load`, `document`) | `SpineComponentRoute` (`id`, `load`, `document`, `hidePageBar`) |
216
+ | `provideSpineSearch` / `provideSettingsSection` | `search` / `settingsSections` do `createSpineRoutes` |
217
+ | `LoggerService`, trilha, título | `useSpineChain`, `useSpineBreadcrumbs`, `useSpineTitle`, `useSpineDocumentTitle`, `useSpineNavigate`; `spineRenderLink` liga o `renderLink` das peças ao `<Link>` |
218
+ | `ModalService` / `SidePanelService` (`/modal`, `/side-panel`) | `useSpineModal()` / `useSpineSidePanel()`: `open(config)` devolve **`Promise`** com o resultado ou `null`; o conteúdo expõe `{ getResult, isValid }` pelo `ref` (`useImperativeHandle`) |
219
+ | `NotificationService` (`/notification`) | `useSpineNotification()` (`addNotification`, `processErrorNotification`, `resolveAlertType`) |
220
+ | `provideGraphql` + `injectGraphqlClient` + `unwrap` (`/graphql`) | `<GraphqlProvider endpoints>` + `useGraphqlClient(nome)` (`query`/`mutate`/`subscribe`) + `unwrap`; `useSpineApolloClient(nome)` para os hooks do Apollo |
221
+ | `provideAutoService({ adminApi })` (`/auto-service`) | `<AutoServiceProvider>` (opcional: sem ele vale o `adminApi` do `SpineProvider`) + `autoServiceComponentRoutes()` somado a `components` |
222
+ | `<spine-audit>`, `<spine-login-attempts>` (`/audit`) | `SpineAudit`, `SpineLoginAttempts` (`scope="admin"` ou `"client"` + `clientId`); carregue sob demanda |
223
+ | `SpineNoticesService`, `SpineNewsService`, `SpineLogoutService`… (`/layout`) | `useSpineNotices`, `useSpineNews`, `useSpineLogout`, `useSpineSettings`, `useSpinePreferences`, `useSpineQuickAccess`, `useSpineWorkspace`… |
224
+ | `registerSpineUnsavedChanges` | `useRegisterSpineUnsavedChanges` |
225
+ | páginas do agente e de sugestões | `registerSpinePages({ config, adminApi })` **antes** do `createBrowserRouter` (F5 em `/agente`, `/sugestoes`) |
226
+
227
+ Regras que mudam pouco do Angular (`spine.md` §10): tela identificada pelo `router_id`; a tela não repete título nem
228
+ descrição (vêm da barra da página); telas sempre por `import()`; envelope GraphQL sempre por `unwrap`;
229
+ `GraphqlEnvelopeError`, `AlertType`, `routerIdOf` e as constantes vêm do núcleo `@trismegisto/spine`; uma cópia só do
230
+ `@orfeu/react`. O token vai em `x-access-token` também aqui (o `GraphqlProvider` já faz; REST do app: skill `orfeu`).
231
+
232
+ ## 6. Testes
233
+
234
+ Testing Library sobre o DOM `hm-*` real: procure por papel e nome (`getByRole('button', { name: 'Salvar' })`), nunca
235
+ por classe interna. Não há harness como no Angular. Envolva o componente nos providers que ele usa (tema, i18n,
236
+ toast, dialog); com o spine, use um `createMemoryRouter` com as rotas do `createSpineRoutes` e um `AuthClient` com
237
+ `fetch` falso (skill `orfeu`, no `references/react.md` §7 dela).