@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.
- package/README.md +2 -1
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +4 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +382 -0
- package/skills/auto-servico/SKILL.md +14 -8
- package/skills/auto-servico/references/diagnostico.md +2 -1
- package/skills/auto-servico/references/tools.md +7 -2
- package/skills/hefesto/SKILL.md +11 -5
- package/skills/hefesto/references/mcp-diagnostico.md +2 -1
- package/skills/hefesto/references/mcp-tools.md +13 -3
- package/skills/orfeu/SKILL.md +32 -6
- package/skills/orfeu/references/angular-api.md +14 -6
- package/skills/orfeu/references/angular-armadilhas.md +17 -2
- package/skills/orfeu/references/angular-recipes.md +23 -8
- package/skills/orfeu/references/angular.md +16 -7
- package/skills/orfeu/references/diferencas.md +13 -6
- package/skills/orfeu/references/node-api.md +68 -8
- package/skills/orfeu/references/node-armadilhas.md +40 -6
- package/skills/orfeu/references/node-recipes.md +26 -12
- package/skills/orfeu/references/node.md +66 -12
- package/skills/orfeu/references/python-api.md +53 -13
- package/skills/orfeu/references/python-recipes.md +22 -22
- package/skills/orfeu/references/python.md +68 -10
- package/skills/trismegisto/SKILL.md +5 -2
- package/skills/trismegisto/references/angular-api.md +43 -4
- package/skills/trismegisto/references/angular-exports.md +127 -3
- package/skills/trismegisto/references/angular-recipes.md +31 -0
- package/skills/trismegisto/references/angular-types.md +2 -1
- package/skills/trismegisto/references/catalogo/seletores.json +152 -0
- package/skills/trismegisto/references/catalogo/tokens.json +1 -0
- package/skills/trismegisto/references/spine-api.md +519 -7
- package/skills/trismegisto/references/spine-recipes.md +15 -11
- 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 **
|
|
4
|
-
> print(m.version('orfeu'))"`).
|
|
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
|
-
-
|
|
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
|
|
44
|
-
|
|
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 (
|
|
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
|
|
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
|
|
89
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
4
|
-
> Gerado do código-fonte do `@trismegisto/angular` 2.
|
|
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.
|
|
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
|
|
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`
|
|
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; }
|