@acropole/skills 1.4.1 → 1.6.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 (33) hide show
  1. package/README.md +2 -1
  2. package/package.json +1 -1
  3. package/skills/acropole/SKILL.md +4 -2
  4. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +382 -0
  5. package/skills/auto-servico/SKILL.md +14 -8
  6. package/skills/auto-servico/references/diagnostico.md +2 -1
  7. package/skills/auto-servico/references/tools.md +7 -2
  8. package/skills/hefesto/SKILL.md +11 -5
  9. package/skills/hefesto/references/mcp-diagnostico.md +2 -1
  10. package/skills/hefesto/references/mcp-tools.md +13 -3
  11. package/skills/orfeu/SKILL.md +32 -6
  12. package/skills/orfeu/references/angular-api.md +14 -6
  13. package/skills/orfeu/references/angular-armadilhas.md +17 -2
  14. package/skills/orfeu/references/angular-recipes.md +23 -8
  15. package/skills/orfeu/references/angular.md +16 -7
  16. package/skills/orfeu/references/diferencas.md +13 -6
  17. package/skills/orfeu/references/node-api.md +68 -8
  18. package/skills/orfeu/references/node-armadilhas.md +40 -6
  19. package/skills/orfeu/references/node-recipes.md +26 -12
  20. package/skills/orfeu/references/node.md +66 -12
  21. package/skills/orfeu/references/python-api.md +53 -13
  22. package/skills/orfeu/references/python-recipes.md +22 -22
  23. package/skills/orfeu/references/python.md +68 -10
  24. package/skills/trismegisto/SKILL.md +5 -2
  25. package/skills/trismegisto/references/angular-api.md +43 -4
  26. package/skills/trismegisto/references/angular-exports.md +127 -3
  27. package/skills/trismegisto/references/angular-recipes.md +31 -0
  28. package/skills/trismegisto/references/angular-types.md +2 -1
  29. package/skills/trismegisto/references/catalogo/seletores.json +152 -0
  30. package/skills/trismegisto/references/catalogo/tokens.json +1 -0
  31. package/skills/trismegisto/references/spine-api.md +519 -7
  32. package/skills/trismegisto/references/spine-recipes.md +15 -11
  33. package/skills/trismegisto/references/spine.md +21 -3
@@ -1,7 +1,8 @@
1
1
  # orfeu (Python) — guia de uso (FastAPI, Flask, Django, Strawberry)
2
2
 
3
- > Escrito para a **API 1.0.0** (versão instalada: `python -c "import importlib.metadata as m;
4
- > print(m.version('orfeu'))"`). Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
3
+ > Escrito para a **1.4.0** (anda junto com `@orfeu/node` e `@orfeu/angular`; versão instalada:
4
+ > `python -c "import importlib.metadata as m; print(m.version('orfeu'))"`). A 1.3.0 trouxe as correções da
5
+ > auditoria de segurança (§5). Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
5
6
  > em relação ao Node e ao Angular está em [diferencas.md](diferencas.md). Estrutura do serviço FastAPI em si
6
7
  > (camadas, banco, configuração): skill `fastapi`. Flask, Django e Strawberry ainda não têm skill de
7
8
  > padrões — aqui só a integração com o Orfeu.
@@ -36,12 +37,14 @@ pip install "orfeu[flask]" # ou [django], [strawberry]; sem extra = s
36
37
  - **Python ≥ 3.11** (`requires-python = ">=3.11"`; usa `enum.StrEnum`). Testado em 3.11–3.14.
37
38
  - Dependências fixas: `httpx>=0.27`, `PyJWT[crypto]>=2.8`. O adapter FastAPI foi testado com FastAPI
38
39
  0.111.0, 0.116.1, 0.137.0 e 0.142.2.
39
- - Fixe a versão maior no app: `orfeu[fastapi]>=1.0,<2`.
40
+ - No `requirements.txt` do app, versão exata: `orfeu[fastapi]==1.4.0` (mesma versão das libs `@orfeu/*` do app).
40
41
 
41
42
  ## 2. Configuração
42
43
 
43
- A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(...)` dos adapters ou
44
- `OrfeuClient(...)`), exceto no Django, que lê `settings`.
44
+ A configuração entra pelo construtor (`Orfeu(...)` dos adapters ou `OrfeuClient(...)`); o Django lê `settings`.
45
+ Exceção (1.3+): sem o argumento, `allowed_clients`, `issuer_url` e `trusted_proxies` leem `ORFEU_ALLOWED_CLIENTS`,
46
+ `ORFEU_ISSUER_URL` e `ORFEU_TRUSTED_PROXIES` do ambiente. Prefira passar pelas settings do app; um argumento
47
+ passado vence a variável, e `allowed_clients=[]` **desliga** (passe `None` quando a lista estiver vazia).
45
48
 
46
49
  | Parâmetro | Obrigatório | O que é |
47
50
  |---|---|---|
@@ -51,10 +54,17 @@ A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(..
51
54
  | `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
52
55
  | `tls_verify` | não, só por nome (`*`) | `True` (padrão). `False` desliga a verificação TLS **só** nas chamadas ao Argos (certificado autoassinado em desenvolvimento). Não é global. |
53
56
  | `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
54
- | `permissions_refresh` | não, só por nome (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) | `True` (padrão: revalida o catálogo com os grupos liberados a cada 60 s ±20%, com `If-None-Match`; mantém o anterior se o Argos cair), `False` ou `PermissionsRefreshOptions(enabled, interval_s, jitter)`. Django: `ORFEU_PERMISSIONS_REFRESH`. |
57
+ | `permissions_refresh` | não, só por nome (`orfeu` ≥ 1.1) | `True` (padrão: revalida o catálogo com os grupos liberados a cada 60 s ±20%, com `If-None-Match`; mantém o anterior se o Argos cair), `False` ou `PermissionsRefreshOptions(enabled, interval_s, jitter)`. Django: `ORFEU_PERMISSIONS_REFRESH`. |
58
+ | `accept_any_realm` | não, só por nome (`orfeu` ≥ 1.2) | `False` (padrão). `True` aceita `x-access-token`/`x-app-token` de qualquer realm, buscando o JWKS do realm do token (limites em [diferencas.md](diferencas.md)). Django: `ORFEU_ACCEPT_ANY_REALM`. |
59
+ | `allowed_clients` | não, só por nome (1.3+) | `client_id`s aceitos no token de usuário (`x-access-token` e `x-app-token`); `client_id`/`azp` fora da lista → 401. Sem o argumento, `ORFEU_ALLOWED_CLIENTS` (vírgula). Padrão desligado. |
60
+ | `issuer_url` | não, só por nome (1.3+) | URL pública do Argos (`SERVER_URL`): `iss` esperado = `{issuer_url}/realms/{realm_id}`. Sem o argumento, `ORFEU_ISSUER_URL`. |
61
+ | `trusted_proxies` | não, só por nome (1.3+) | proxies cujo `x-forwarded-for` vale para o IP da auditoria. Padrão `orfeu.trace.DEFAULT_TRUSTED_PROXIES` (loopback + redes privadas); sem o argumento, `ORFEU_TRUSTED_PROXIES`; `[]` = nenhum. |
62
+ | `check_revocation` | não, só por nome (1.3+) | `False` (padrão), lista de operações sensíveis ou `True`: confere o `x-access-token` na introspecção RFC 7662 do Argos (cache 10 s/60 s, fail-closed). Django: `ORFEU_CHECK_REVOCATION`. |
55
63
 
56
64
  Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
57
- sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY` e `ORFEU_AUDIT` (opcionais).
65
+ sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY`, `ORFEU_AUDIT`, `ORFEU_PERMISSIONS_REFRESH`,
66
+ `ORFEU_ACCEPT_ANY_REALM`, `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES` e
67
+ `ORFEU_CHECK_REVOCATION` (opcionais).
58
68
 
59
69
  Nos outros frameworks o app escolhe os nomes das variáveis. Convenção sugerida (a mesma do Django):
60
70
  `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET`, `ORFEU_TLS_VERIFY`.
@@ -75,6 +85,8 @@ orfeu = Orfeu(
75
85
  realm_id=os.environ["ORFEU_REALM_ID"],
76
86
  app_id=os.environ["ORFEU_APP_ID"],
77
87
  secret=os.environ["ORFEU_SECRET"],
88
+ allowed_clients=["<client_id do front>"], # backend de front próprio: ligue (§5)
89
+ issuer_url=os.environ.get("ORFEU_ISSUER_URL") or None,
78
90
  )
79
91
 
80
92
  @app.get("/items")
@@ -85,8 +97,9 @@ async def list_items(request: Request):
85
97
  ```
86
98
 
87
99
  - `Orfeu(app, ...)` instala um middleware ASGI e **embrulha o lifespan** do app: no startup roda
88
- token do app → JWKS → sync das operações → busca das operações com grupos (e, com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1, agenda a recarga
89
- periódica delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
100
+ token do app → JWKS → sync das operações → busca das operações com grupos (e agenda a recarga periódica
101
+ delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e
102
+ com `on_startup`. Não chame nada no seu lifespan.
90
103
  - O startup **falha** (e o app não sobe) se o Argos recusar as credenciais (`OrfeuAuthError`), o sync falhar
91
104
  (`OrfeuSyncError`), o JWKS não vier (`OrfeuError`) ou **nenhuma** `@operation` estiver registrada
92
105
  (`OrfeuConfigError`). Não há retentativa: o Argos precisa estar acessível no boot.
@@ -122,7 +135,27 @@ async def create_form(...): ...
122
135
  Headers (`x-access-token` → `x-app-token` → `x-api-token`, vale a primeira presente; `Authorization` é
123
136
  ignorado) e a regra 401/403 estão no `SKILL.md` §4 — idêntica em FastAPI HTTP/WebSocket, Flask, Django e
124
137
  Strawberry. Específico do Python: o JWT precisa ser RS256 com `kid` no header; introspecção com cache de 60 s
125
- (token inativo: 10 s); tokens de outro realm são sempre recusados (não há `acceptAnyRealm`).
138
+ (token inativo: 10 s); tokens de outro realm são recusados, salvo `accept_any_realm=True` (1.2+). Busca forçada
139
+ do JWKS (por `kid` desconhecido) no máximo uma vez a cada 30 s por realm: chave recém-rotacionada pode levar até
140
+ 30 s para ser aceita.
141
+
142
+ O `x-access-token` é recusado (401) quando (1.3+): algoritmo diferente de `RS256`; assinatura ou `kid` não
143
+ conferem; falta `exp`, `sub` ou `iss`, ou venceu; o `iss` não é o do realm do token (com `issuer_url`, exatamente
144
+ `{issuer_url}/realms/{realm_id}`; sem, uma URL http(s) terminada em `/realms/{realm_id}` — o `authorizer_url`
145
+ costuma ser endereço interno e não serve); o realm não é o do app; é token **de aplicação** (`type: "app"`,
146
+ client_credentials); ou `allowed_clients` está ligado e o `client_id`/`azp` não está na lista.
147
+
148
+ **Argos fora não vira 500** (1.3+): JWKS indisponível ou `/apps/token` recusando ao introspectar tratam o token
149
+ como não validado — `public` segue anônimo, `private`/`protected`/`optional` respondem 401. Alerta que olhava 500
150
+ não pega mais isso: monitore a taxa de 401 e a saúde do Argos.
151
+
152
+ **`allowed_clients`**: o access token do Argos é do realm inteiro e traz os grupos do usuário no client que fez o
153
+ login. Sem a lista, um usuário com qualquer grupo em **outro** client do realm passa nas operações `private`.
154
+ Ligue em todo backend que atende o front do próprio app (valor = `client_id` do front); serviço chamado por
155
+ gateways de vários apps lista os fronts de todos; não ligue no que atende qualquer app do realm de propósito.
156
+
157
+ **Revogação**: a validação local não enxerga revogação — um access token revogado vale até o `exp` (até 10 min
158
+ no Argos). Operações sensíveis: `check_revocation=["pedidos.delete"]` (introspecção RFC 7662, fail-closed).
126
159
 
127
160
  O que o handler FastAPI recebe (`request.state` / `websocket.state`):
128
161
 
@@ -139,6 +172,25 @@ Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`
139
172
  `user.raw.get("preferred_username") or user.raw.get("email") or user.sub`. `user.get(...)` lança
140
173
  `AttributeError: 'TokenClaims' object has no attribute 'get'` (500 na rota).
141
174
 
175
+ ### Rota máquina-a-máquina: token de serviço (1.4+)
176
+
177
+ Desde a 1.3 o token client_credentials de uma aplicação (`type: "app"`) não vale como usuário: rota que outra
178
+ aplicação chamava com ele via `@operation` passou a dar 401 (e teste com o `validate_token` mockado não pega). Use:
179
+
180
+ ```python
181
+ from orfeu import service_route
182
+
183
+ @router.post("/interno/sincronizar")
184
+ @service_route(allowed_apps=[settings.app_origem_id]) # não combine com @operation
185
+ async def sincronizar(request: Request):
186
+ return ok({"de": request.state.service.app_id})
187
+ ```
188
+
189
+ Vale em FastAPI (HTTP e WebSocket, `request.state.service`), Flask (`g.orfeu_service`) e Django
190
+ (`request.orfeu_service`); no Strawberry, chame `await client.validate_service_token(token, ...)` no contexto. O
191
+ realm de verificação nunca vem do token (`realm_for`); `allowed_clients` não se aplica; a rota não entra no catálogo
192
+ nem na auditoria de operação. Detalhes em [python-api.md](python-api.md) §3.
193
+
142
194
  ## 6. Respostas, erros e status
143
195
 
144
196
  | Situação | Resposta |
@@ -183,6 +235,10 @@ annotate_operation(target_type="form", target_id=form_id, details={"campos": ["t
183
235
  Cada chamada guardada tem um `OrfeuTrace`: com `traceparent` W3C válido na entrada, o trace continua
184
236
  (`entry=False`, mesmo `trace_id`); sem ele (ou inválido), começa um novo (`entry=True`).
185
237
 
238
+ IP do cliente na auditoria (1.3+): o primeiro `x-forwarded-for` nunca é usado. Conexão direta de fora de
239
+ `trusted_proxies` → IP do socket; de proxy confiável → a entrada mais à direita do `x-forwarded-for` que não é
240
+ proxy. Usuários na rede privada sem proxy: configure `trusted_proxies` só com os proxies.
241
+
186
242
  Para chamar outro serviço **em nome da requisição atual**, use `orfeu_headers(request)`:
187
243
 
188
244
  ```python
@@ -221,6 +277,8 @@ orfeu.client.check_permission = MagicMock(return_value=True)
221
277
  ```
222
278
 
223
279
  Detalhes (registro global, `clear_registry()`, capturar eventos de auditoria, logs): [python-recipes.md](python-recipes.md) §9.
280
+ Teste que assina JWT de verdade (sem mock do `validate_token`): desde a 1.3 o token precisa de `exp`, `sub` e
281
+ `iss` (`<url>/realms/<realm_id>`), sem `type: "app"`, e do `client_id` da lista quando `allowed_clients` está ligado.
224
282
 
225
283
  ## 11. Regras que não podem ser quebradas
226
284
 
@@ -25,7 +25,10 @@ Divisão de trabalho entre as skills:
25
25
  ## 1. Pacotes
26
26
 
27
27
  Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular ← (maps, charts, spine)`. Todos na
28
- **mesma versão** (`^2.0.1`); as 0.9.x foram retiradas do registry.
28
+ **mesma versão** (`^2.1.2`); as 0.9.x foram retiradas do registry.
29
+
30
+ > **Atualizando um app** (vindo da 1.x ou da 2.0.x)? Siga o guia da skill `acropole`:
31
+ > [../acropole/references/fluxos/atualizar-libs-2026-10.md](../acropole/references/fluxos/atualizar-libs-2026-10.md) — quebras da 2.0, o que a 2.1 muda no app e os contornos de CSS a remover.
29
32
 
30
33
  | Pacote | Para quê |
31
34
  |---|---|
@@ -38,7 +41,7 @@ Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular
38
41
  | `@trismegisto/maps` | mapas (`hm-map`, coroplético, marcadores, GeoJSON) com mapas base embutidos |
39
42
  | `@trismegisto/spine` | o **shell pronto**: cabeçalho, menu lateral vindo do servidor de autorização (Argos), workspace em abas, barra da página, login/callback, modal/painel/toast por serviço, configurações, tour, auditoria, cliente GraphQL. O app entrega só as telas |
40
43
 
41
- ## 2. Instalação (2.0.1)
44
+ ## 2. Instalação (2.1.2)
42
45
 
43
46
  ```bash
44
47
  # sem shell pronto
@@ -1,7 +1,7 @@
1
1
  # Catálogo de API — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills.
4
- > Gerado do código-fonte do `@trismegisto/angular` 2.0.1. Confira a versão instalada no `package.json` do pacote em `node_modules`.
3
+ > **Gerado** a partir do código-fonte da versão 2.1.2, a cada `npm run sync` do @acropole/skills.
4
+ > Gerado do código-fonte do `@trismegisto/angular` 2.1.2. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
5
 
6
6
  Legenda: `input` = `[prop]`; `model` = two-way `[(prop)]`; `output` = `(evento)`.
7
7
  Slots são os seletores de `<ng-content>`: projete com o atributo (ex.: `<div footer>`).
@@ -720,7 +720,7 @@ Métodos públicos: `exportCsv(options: DataGridExportOptions = {}): string`, `c
720
720
  | `rows` | input (obrigatório) | `readonly T[]` | | |
721
721
  | `rowId` | input (obrigatório) | `(row: T) => string` | | |
722
722
  | `caption` | input (obrigatório) | `string` | | Nome acessível da tabela (`<caption>`). |
723
- | `rowActions` | input | `readonly DataGridRowAction<T>[]` | `[]` | |
723
+ | `rowActions` | input | `readonly DataGridRowAction<T>[]` | `[]` | Ações por linha: um menu (⋮) na PRIMEIRA coluna da grade — depois da seleção, antes do detalhe e dos dados. Fica fora do gerenciador de colunas, da ordem/estad… |
724
724
  | `loading` | input | `boolean` | `false` | |
725
725
  | `error` | input | `string` | `''` | |
726
726
  | `emptyMessage` | input | `string` | `''` | |
@@ -1591,6 +1591,44 @@ Legenda: o que cada cor quer dizer, em texto. Lista nomeada; o marcador é só d
1591
1591
  | `marker` | input | `LegendMarker` | `'dot'` | |
1592
1592
  | `label` | input | `string` | `''` | Nome da lista para leitor de tela; vazio usa o texto do catálogo ("Legenda"). |
1593
1593
 
1594
+ ## `hm-list-editor`
1595
+
1596
+ `ListEditorComponent` · `ControlValueAccessor` · estende `HermesFormFieldBase` — import de `@trismegisto/angular/list-editor` (também na raiz)
1597
+
1598
+ Editor de lista (`hm-list-editor`): um campo para acrescentar itens e, embaixo, a lista ordenável dos itens (o `hm-reorder-list`: arrasto pela alça e teclado), com ✕ por item e edição opcional. Para listas curtas em que a ORDEM importa: URIs de redirecionamento, funcionalidades de um plano, etapas.
1599
+
1600
+ Métodos públicos: `submit(): void`
1601
+
1602
+ | Nome | Tipo | Tipo TS | Padrão | Descrição |
1603
+ |---|---|---|---|---|
1604
+ | `items` | model | `readonly T[]` | `[]` | Os itens, na ordem atual. Two-way: recebe a lista nova a cada adição, remoção, edição ou movimento. |
1605
+ | `label` | input (obrigatório) | `string` | | Nome da lista (visível, salvo `labelHidden`). |
1606
+ | `labelHidden` | input | `boolean` | `false` | |
1607
+ | `hint` | input | `string` | `''` | |
1608
+ | `placeholder` | input | `string` | `''` | Exemplo no campo de texto (ou no título, no modo par). |
1609
+ | `descriptionPlaceholder` | input | `string` | `''` | Exemplo no campo de descrição (modo par). |
1610
+ | `pair` | input | `boolean` | `false` | Itens com título + descrição (`{ title, description }`) em vez de texto simples. |
1611
+ | `itemLabel` | input | `string` | `''` | Rótulo do campo de texto simples (fica só para leitor de tela). Vazio = catálogo ("Novo item"). |
1612
+ | `titleLabel` | input | `string` | `''` | Rótulo do campo de título (modo par). Vazio = catálogo ("Título"). |
1613
+ | `descriptionLabel` | input | `string` | `''` | Rótulo do campo de descrição (modo par). Vazio = catálogo ("Descrição"). |
1614
+ | `addLabel` | input | `string` | `''` | Texto do botão de adicionar. Vazio = catálogo ("Adicionar"). |
1615
+ | `emptyText` | input | `string` | `''` | Texto da lista vazia. Vazio = catálogo ("Nenhum item na lista."). |
1616
+ | `descriptionRequired` | input | `boolean` | `false` | No modo par, a descrição também é obrigatória. |
1617
+ | `allowDuplicates` | input | `boolean` | `false` | Aceita itens repetidos (comparados pelo texto, ou pelo título no modo par). |
1618
+ | `ignoreCase` | input | `boolean` | `false` | Ao procurar repetidos, ignora maiúsculas/minúsculas. |
1619
+ | `max` | input | `number \| null, unknown` | `null` | Quantidade máxima de itens (`null` = sem limite). Com limite, o rótulo mostra "{n} de {max}". |
1620
+ | `validate` | input | `ListEditorValidator<T> \| null` | `null` | Validação do item novo/editado: devolve a mensagem de erro ou `null`. |
1621
+ | `editable` | input | `boolean` | `false` | Lápis por item para editar o texto no lugar. |
1622
+ | `readonly` | input | `boolean` | `false` | Só leitura: mostra a lista, sem campo, alças nem ações. |
1623
+ | `added` | output | `ListEditorAdded<T>` | | |
1624
+ | `removed` | output | `ListEditorRemoved<T>` | | |
1625
+ | `moved` | output | `ListEditorMoved<T>` | | |
1626
+ | `edited` | output | `ListEditorEdited<T>` | | |
1627
+ | `disabled` | input (herdado) | `boolean` | `false` | Desabilita o campo sem depender de formulário. |
1628
+ | `required` | input (herdado) | `boolean` | `false` | Marca o campo como obrigatório (marca visual e ARIA). Sozinho não gera mensagem de erro. |
1629
+ | `error` | input (herdado) | `string` | `''` | Erro definido pelo app (ex.: resposta do servidor). Vence o erro do controle. |
1630
+ | `messages` | input (herdado) | `Readonly<Record<string, string>>` | `{}` | Texto por chave de erro do controle (`{ required: 'Informe o nome.' }`). |
1631
+
1594
1632
  ## `hm-loading-square`
1595
1633
 
1596
1634
  `LoadingSquareComponent` — import de `@trismegisto/angular/loading-square` (também na raiz)
@@ -2020,6 +2058,7 @@ Lista reordenável (`hm-reorder-list`) por arrasto **e** por teclado. A interaç
2020
2058
  | `hint` | input | `string` | `''` | |
2021
2059
  | `size` | input | `ReorderListSize` | `'medium'` | |
2022
2060
  | `removable` | input | `boolean` | `false` | Mostra em cada linha o botão que remove o item da lista. |
2061
+ | `emptyText` | input | `string` | `''` | Texto da lista vazia. Vazio = catálogo ("Nada para ordenar."). |
2023
2062
  | `moved` | output | `ReorderListMove` | | Movimento confirmado: item, posição de origem e de destino (índices a partir de 0). |
2024
2063
  | `removed` | output | `ReorderListRemoval` | | Item removido pelo ✕ (a lista nova já foi publicada em `items`/formulário). |
2025
2064
  | `disabled` | input (herdado) | `boolean` | `false` | Desabilita o campo sem depender de formulário. |
@@ -2164,7 +2203,7 @@ Slots: `[settingsNavFooter]`, `(padrão)`
2164
2203
 
2165
2204
  Uma preferência dentro de `hm-settings-section`: nome e explicação à esquerda, controle (`hm-segmented-control`, `hm-switch`, `hm-select`, botão...) à direita — a linha típica de um painel de configurações. `stacked` põe o controle embaixo do texto, para controles largos (grade de cores, tabela).
2166
2205
 
2167
- Slots: `[rowDescription]`, `(padrão)`
2206
+ Slots: `[rowHelp]`, `[rowDescription]`, `(padrão)`
2168
2207
 
2169
2208
  | Nome | Tipo | Tipo TS | Padrão | Descrição |
2170
2209
  |---|---|---|---|---|
@@ -1,6 +1,6 @@
1
1
  # Exports por ponto de import — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
3
+ > **Gerado** a partir do código-fonte da versão 2.1.2, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
4
4
 
5
5
  Tudo que cada `@trismegisto/angular/<ponto>` exporta: serviços (com os membros públicos), funções, constantes,
6
6
  tokens de injeção e tipos (com a declaração). Componentes, diretivas e pipes aparecem só pelo nome — inputs,
@@ -559,7 +559,7 @@ type DataGridActionConfirm = Omit<HermesConfirmOptions, 'danger' | 'confirmLabel
559
559
  };
560
560
  ```
561
561
 
562
- - `DataGridRowAction` — Ação por linha, desenhada como item do menu da última coluna.
562
+ - `DataGridRowAction` — Ação por linha, desenhada como item do menu da coluna de ações (a primeira da grade, depois da seleção).
563
563
 
564
564
  ```ts
565
565
  interface DataGridRowAction<T = unknown> {
@@ -1306,6 +1306,7 @@ interface HermesI18nConfig {
1306
1306
  readonly base?: HermesMessages;
1307
1307
  readonly catalogs?: Readonly<Record<string, HermesMessages | HermesCatalogLoader>>;
1308
1308
  readonly override?: HermesMessagesOverride;
1309
+ readonly regionalFormat?: HermesRegionalFormat;
1309
1310
  }
1310
1311
  ```
1311
1312
 
@@ -1323,8 +1324,11 @@ type HermesCatalogLoader = () => Promise<HermesMessages>;
1323
1324
  ```ts
1324
1325
  class HermesI18nService {
1325
1326
  readonly locale = signal(…)
1327
+ readonly regionalFormat = signal(…)
1326
1328
  readonly messages = computed(…)
1329
+ readonly formatLocale = computed(…)
1327
1330
  setLocale(locale: string): Promise<void>
1331
+ setRegionalFormat(format: HermesRegionalFormat): void
1328
1332
  registerCatalog(locale: string, catalog: HermesMessages): void
1329
1333
  setOverride(override: HermesMessagesOverride): void
1330
1334
  format(template: string, params?: MessageParams): string
@@ -1792,6 +1796,48 @@ interface LegendItem {
1792
1796
 
1793
1797
  - `LegendComponent` — `hm-legend` (ver angular-api.md)
1794
1798
 
1799
+ ## `@trismegisto/angular/list-editor`
1800
+
1801
+ - `ListEditorAdded` — Item acrescentado pelo campo: o item (já aparado) e a posição em que entrou.
1802
+
1803
+ ```ts
1804
+ interface ListEditorAdded<T extends ListEditorValue = ListEditorValue> {
1805
+ readonly item: T;
1806
+ readonly index: number;
1807
+ }
1808
+ ```
1809
+
1810
+ - `ListEditorRemoved` — Item removido pelo ✕: o item e a posição que ocupava.
1811
+
1812
+ ```ts
1813
+ interface ListEditorRemoved<T extends ListEditorValue = ListEditorValue> {
1814
+ readonly item: T;
1815
+ readonly index: number;
1816
+ }
1817
+ ```
1818
+
1819
+ - `ListEditorMoved` — Item reordenado (arrasto ou teclado): o item, a posição de origem e a de destino.
1820
+
1821
+ ```ts
1822
+ interface ListEditorMoved<T extends ListEditorValue = ListEditorValue> {
1823
+ readonly item: T;
1824
+ readonly from: number;
1825
+ readonly to: number;
1826
+ }
1827
+ ```
1828
+
1829
+ - `ListEditorEdited` — Item editado (`editable`): o valor novo, o anterior e a posição.
1830
+
1831
+ ```ts
1832
+ interface ListEditorEdited<T extends ListEditorValue = ListEditorValue> {
1833
+ readonly item: T;
1834
+ readonly previous: T;
1835
+ readonly index: number;
1836
+ }
1837
+ ```
1838
+
1839
+ - `ListEditorComponent` — `hm-list-editor` (ver angular-api.md)
1840
+
1795
1841
  ## `@trismegisto/angular/loading-square`
1796
1842
 
1797
1843
  - `LoadingSquareComponent` — `hm-loading-square` (ver angular-api.md)
@@ -1881,6 +1927,16 @@ type MessageScrollerLive = 'polite' | 'off';
1881
1927
  - `AnimatedNumberComponent` — `hm-animated-number` (ver angular-api.md)
1882
1928
  - `FlipDirective` — `[hmFlip]` (ver angular-api.md)
1883
1929
  - `RevealDirective` — `[hmReveal]` (ver angular-api.md)
1930
+ - **`HermesMotionService`** (classe)
1931
+
1932
+ ```ts
1933
+ class HermesMotionService {
1934
+ readonly preference
1935
+ readonly systemReduced
1936
+ readonly reduced = computed(…)
1937
+ setPreference(preference: HermesMotionPreference): void
1938
+ }
1939
+ ```
1884
1940
 
1885
1941
  ## `@trismegisto/angular/navigation-menu`
1886
1942
 
@@ -3152,6 +3208,7 @@ type TimelineOrientation = 'vertical' | 'horizontal';
3152
3208
  ```ts
3153
3209
  class HermesToastService {
3154
3210
  readonly toasts = computed(…)
3211
+ readonly activeStack = computed(…)
3155
3212
  push(variant: AlertVariant, message: string, options?: ToastPushOptions): void
3156
3213
  error(message: string, options?: ToastPushOptions): void
3157
3214
  warning(message: string, options?: ToastPushOptions): void
@@ -3160,6 +3217,7 @@ class HermesToastService {
3160
3217
  dismiss(id: string): void
3161
3218
  pause(): void
3162
3219
  resume(): void
3220
+ attachStack(owner: object): () => void
3163
3221
  }
3164
3222
  ```
3165
3223
 
@@ -3384,6 +3442,8 @@ class HermesZoomService {
3384
3442
  readonly level = computed(…)
3385
3443
  readonly pixelRatio = computed(…)
3386
3444
  readonly zoomed = computed(…)
3445
+ readonly textScale
3446
+ setTextScale(scale: number): void
3387
3447
  }
3388
3448
  ```
3389
3449
 
@@ -3484,6 +3544,34 @@ type HermesZoomLevel = 'none' | 'x2' | 'x4';
3484
3544
 
3485
3545
  - `const HERMES_ZOOM_BREAKPOINTS =` — Abaixo de qual largura (px CSS) cada nível vale.
3486
3546
  - `const HERMES_ZOOM_CLASSES =` — Classes que o nível põe no elemento raiz (`<html>`). São cumulativas: `hm-zoom-x2` quer dizer "200% ou mais" (também presente em `'x4'`) e `hm-zoom-x4`, "400% ou mais". Assim um estilo de reflow escrito para 200% contin…
3547
+ - `const HERMES_TEXT_SCALES = [1, 1.1, 1.25, 1.5] as const` — Os tamanhos oferecidos: 100%, 110%, 125% e 150%.
3548
+ - `HermesMotionPreference` — Movimento escolhido no app, por cima do `prefers-reduced-motion` do sistema: `'system'` segue o sistema; `'reduce'` reduz sempre; `'full'` anima mesmo com o sistema pedindo menos movimento.
3549
+
3550
+ ```ts
3551
+ type HermesMotionPreference = 'system' | 'reduce' | 'full';
3552
+ ```
3553
+
3554
+ - `HermesRegionalFormat` — Formato regional escolhido pela pessoa por cima do padrão do idioma: relógio de 12/24 horas e primeiro dia da semana. `null`/ausente = o do idioma.
3555
+
3556
+ ```ts
3557
+ interface HermesRegionalFormat {
3558
+ readonly hourCycle?: TimeHourCycle | null;
3559
+ readonly firstDayOfWeek?: Weekday | null;
3560
+ }
3561
+ ```
3562
+
3563
+ - `TimeHourCycle` — Relógio de exibição: `h12` (1–12 + AM/PM) ou `h23` (0–23). `h11`/`h24` do Intl caem nesses dois.
3564
+
3565
+ ```ts
3566
+ type TimeHourCycle = 'h12' | 'h23';
3567
+ ```
3568
+
3569
+ - `Weekday` — Dia da semana: 0 = domingo … 6 = sábado (o mesmo de `Date.getDay()`).
3570
+
3571
+ ```ts
3572
+ type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
3573
+ ```
3574
+
3487
3575
  - `const HERMES_FAMILIES: readonly HermesFamily[]` — Doze famílias com nomes da mitologia grega. A primeira (`hera`) é o padrão do sistema: uma família desconhecida cai nela. Contraste medido por `scripts/check-families.mjs` (WCAG: accent ≥ 4,5:1 nos dois temas; borda do…
3488
3576
  - `HermesFamily` — As 12 famílias de cor: cada uma com o par accent (cor de ação, `--hm-accent`/`--hm-action`) e panelBg (banda escura do painel de marca, `--hm-panel-bg`), em claro e escuro. No claro é o tom mais escuro da família; no es…
3489
3577
 
@@ -3883,7 +3971,7 @@ interface DateRange {
3883
3971
  type DateValueFormat = 'iso' | 'dd/mm/yyyy';
3884
3972
  ```
3885
3973
 
3886
- - `IsoDate` — Datas do hm-date-picker / hm-date-range-picker, sem framework. O VALOR é sempre ISO `AAAA-MM-DD` (o mesmo do `<input type="date">` que ele substitui — comparável como texto, sem fuso); o que a pessoa vê e digita é `dd/m…
3974
+ - `IsoDate`
3887
3975
 
3888
3976
  ```ts
3889
3977
  type IsoDate = string;
@@ -4079,6 +4167,42 @@ interface DualListItem {
4079
4167
  }
4080
4168
  ```
4081
4169
 
4170
+ - `ListEditorPair` — Item com título e descrição (modo `pair` do `hm-list-editor`). Campos extras do app são preservados na edição.
4171
+
4172
+ ```ts
4173
+ interface ListEditorPair {
4174
+ readonly title: string;
4175
+ readonly description?: string;
4176
+ }
4177
+ ```
4178
+
4179
+ - `ListEditorValue` — Valor de um item do editor: texto simples ou par título + descrição.
4180
+
4181
+ ```ts
4182
+ type ListEditorValue = string | ListEditorPair;
4183
+ ```
4184
+
4185
+ - `ListEditorValidator` — Validação do app: recebe o item já normalizado (aparado) e a lista atual (sem o item em edição) e devolve a mensagem de erro, ou `null` quando o item vale.
4186
+
4187
+ ```ts
4188
+ type ListEditorValidator<T extends ListEditorValue = ListEditorValue> = (item: T, items: readonly T[]) => string | null;
4189
+ ```
4190
+
4191
+ - `ListEditorRejection`
4192
+
4193
+ ```ts
4194
+ interface ListEditorRejection {
4195
+ readonly reason: ListEditorRejectionReason;
4196
+ readonly message?: string;
4197
+ }
4198
+ ```
4199
+
4200
+ - `ListEditorRejectionReason` — Por que o item não entrou: campo vazio, descrição vazia (obrigatória), repetido, acima do limite ou recusado pelo app.
4201
+
4202
+ ```ts
4203
+ type ListEditorRejectionReason = 'empty' | 'emptyDescription' | 'duplicate' | 'limit' | 'custom';
4204
+ ```
4205
+
4082
4206
  - `ShortcutDisplay` — Um atalho: os passos em ordem (`G` depois `H`).
4083
4207
 
4084
4208
  ```ts
@@ -115,6 +115,8 @@ export class Servers {
115
115
  - Busca, filtro por coluna, ordenação e paginação já vêm prontos no modo cliente. Para paginação no servidor,
116
116
  passe `[totalItems]` e busque a página ao mudar `pageState`.
117
117
  - Detalhe da linha: `<ng-template #detailPane let-row>…</ng-template>` dentro da grade.
118
+ - `rowActions` vira um menu (⋮) na **primeira** coluna da grade (depois da seleção, antes do detalhe e dos dados),
119
+ fora do gerenciador de colunas, do estado persistido e da exportação. Não crie coluna própria de ações no fim.
118
120
 
119
121
  ## 3. Formulário reativo
120
122
 
@@ -1881,3 +1883,32 @@ Cada um já traz: cores de `--hm-data-*`, resumo automático no idioma ativo lig
1881
1883
  (`HmChartOption`) e `points` para teclado/tabela: use só quando nenhum tipado servir. O pacote é grande
1882
1884
  (~215 kB gzip): carregue a tela de gráficos com `@defer` ou rota lazy. Textos seguem `setLocale`; para
1883
1885
  sobrescrever, `provideChartsMessages({ override })`.
1886
+
1887
+ ## 38. Listas ordenadas digitadas (`hm-list-editor`, 2.2+)
1888
+
1889
+ Lista curta em que a pessoa digita os itens e a ORDEM importa (redirect URIs, funcionalidades de um plano, etapas):
1890
+ `hm-list-editor`, não `hm-input` + chips com ✕. Ele junta o campo de adicionar, a lista ordenável (`hm-reorder-list`:
1891
+ alça e teclado), o ✕ por item e a edição opcional, e funciona com `formControl`/`ngModel` ou `[(items)]`.
1892
+
1893
+ ```html
1894
+ <!-- texto simples, validado e sem duplicados -->
1895
+ <hm-list-editor label="Redirect URIs" placeholder="https://app.exemplo.com/callback" ignoreCase
1896
+ [validate]="httpUrl" formControlName="redirectUris" />
1897
+ <!-- título + descrição: cada item é uma linha (título em destaque, descrição embaixo) -->
1898
+ <hm-list-editor pair editable label="Funcionalidades" descriptionPlaceholder="O que a pessoa ganha"
1899
+ [max]="6" [(items)]="features" />
1900
+ ```
1901
+
1902
+ ```ts
1903
+ import { ListEditorComponent } from '@trismegisto/angular/list-editor';
1904
+ import type { ListEditorPair, ListEditorValidator } from '@trismegisto/primitives';
1905
+
1906
+ readonly httpUrl: ListEditorValidator<string> = (u) => (/^https?:\/\/\S+$/i.test(u) ? null : 'Use http:// ou https://.');
1907
+ readonly features = signal<readonly (ListEditorPair & { id?: string })[]>([]);
1908
+ // ao salvar, a ordem vem do índice: features().map((f, i) => ({ ...f, sort_order: i }))
1909
+ ```
1910
+
1911
+ - Nunca junte título e descrição num texto só ("Título: Descrição" num chip): use `pair`.
1912
+ - Campos extras do item (`id`, `sort_order`...) sobrevivem à edição; recalcule a ordem pelo índice ao salvar.
1913
+ - Colar vários itens de uma vez é o `hm-bulk-input`.
1914
+
@@ -117,7 +117,8 @@ interface DataGridRowAction<T> {
117
117
  readonly id: string; readonly icon: string; readonly label: string;
118
118
  readonly danger?: boolean; readonly separatorAbove?: boolean;
119
119
  readonly available?: (row: T) => boolean;
120
- }
120
+ readonly confirm?: DataGridActionConfirm | ((row: T) => DataGridActionConfirm); // pede confirmação antes de emitir
121
+ } // menu (⋮) na PRIMEIRA coluna, depois da seleção
121
122
 
122
123
  interface DataGridActionTriggered<T> { readonly action: string; readonly row: T; }
123
124
  interface GridSort { readonly key: string; readonly direction: SortDirection; }