@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
@@ -1836,10 +1836,13 @@ com `[announce]="false"` para não ser lido como mensagem.
1836
1836
  `submitKey="enter"`: Enter envia e Shift+Enter quebra linha; `mod-enter` exige Ctrl/⌘. Os anexos usam os
1837
1837
  mesmos textos de estado do `hm-file-upload` (`UploadFile` serve de modelo).
1838
1838
 
1839
- ## 36. Mapa com marcadores e GeoJSON (`@trismegisto/maps`)
1839
+ ## 36. Mapa com marcadores e GeoJSON (`@trismegisto/angular/map`)
1840
+
1841
+ Instale o núcleo `@trismegisto/maps` (peer opcional) e importe as peças da casca, que fica fora do barrel:
1840
1842
 
1841
1843
  ```ts
1842
- import { HM_MAP_COMPONENTS } from '@trismegisto/maps';
1844
+ import { HM_MAP_COMPONENTS } from '@trismegisto/angular/map';
1845
+ import type { GeoJsonFeatureCollection } from '@trismegisto/maps'; // tipos e dados do núcleo
1843
1846
  ```
1844
1847
  ```html
1845
1848
  <hm-map
@@ -1861,12 +1864,15 @@ import { HM_MAP_COMPONENTS } from '@trismegisto/maps';
1861
1864
  Tiles raster por `tileUrl` com a `attribution` exigida pelo provedor (OpenStreetMap, servidor próprio ou
1862
1865
  contratado); sem `tileUrl`, um mapa base embutido (`<hm-map-basemap layer="br/ufs" />`); valor por região é
1863
1866
  `hm-map-choropleth`. Textos do mapa seguem
1864
- `setLocale`; para sobrescrever, `provideMapsMessages({ override })`.
1867
+ `setLocale`; para sobrescrever, `provideMapsMessages({ override })` (`@trismegisto/angular/map`).
1868
+
1869
+ ## 37. Gráficos (`@trismegisto/angular/charts`)
1865
1870
 
1866
- ## 37. Gráficos (`@trismegisto/charts`)
1871
+ Instale o núcleo `@trismegisto/charts` (peer opcional). Componentes da casca; tipos dos dados, do núcleo:
1867
1872
 
1868
1873
  ```ts
1869
- import { HmBarChartComponent, HmLineChartComponent, type ChartSeries } from '@trismegisto/charts';
1874
+ import { HmBarChartComponent, HmLineChartComponent } from '@trismegisto/angular/charts';
1875
+ import type { ChartSeries } from '@trismegisto/charts';
1870
1876
  ```
1871
1877
  ```html
1872
1878
  <hm-bar-chart label="Receita por trimestre" description="O 4º trimestre puxou o ano."
@@ -1882,7 +1888,7 @@ Cada um já traz: cores de `--hm-data-*`, resumo automático no idioma ativo lig
1882
1888
  `null` em `data` é lacuna (a linha interrompe, a tabela mostra traço). `hm-chart` recebe a opção crua do motor
1883
1889
  (`HmChartOption`) e `points` para teclado/tabela: use só quando nenhum tipado servir. O pacote é grande
1884
1890
  (~215 kB gzip): carregue a tela de gráficos com `@defer` ou rota lazy. Textos seguem `setLocale`; para
1885
- sobrescrever, `provideChartsMessages({ override })`.
1891
+ sobrescrever, `provideChartsMessages({ override })` (`@trismegisto/angular/charts`).
1886
1892
 
1887
1893
  ## 38. Listas ordenadas digitadas (`hm-list-editor`, 2.2+)
1888
1894
 
@@ -1912,3 +1918,318 @@ readonly features = signal<readonly (ListEditorPair & { id?: string })[]>([]);
1912
1918
  - Campos extras do item (`id`, `sort_order`...) sobrevivem à edição; recalcule a ordem pelo índice ao salvar.
1913
1919
  - Colar vários itens de uma vez é o `hm-bulk-input`.
1914
1920
 
1921
+ ## 39. Formatação no idioma ativo e campos de moeda/percentual
1922
+
1923
+ ```html
1924
+ <p>{{ total | hmCurrency }} · {{ 0.155 | hmPercent }} · {{ 15.5 | hmPercent: 'points' }}</p>
1925
+ <p>{{ arquivo.bytes | hmFileSize }} · enviado {{ arquivo.enviadoEm | hmRelativeTime: { now: relogio() } }}</p>
1926
+ <p>Duração: {{ execucao.ms | hmDuration }}</p>
1927
+
1928
+ <hm-currency-input label="Valor do pedido" currency="BRL" formControlName="valor" />
1929
+ <hm-percent-input label="Desconto" valueScale="points" formControlName="desconto" />
1930
+ ```
1931
+ ```ts
1932
+ import { formatCurrency } from '@trismegisto/primitives';
1933
+ readonly relogio = signal(Date.now()); // atualize a cada minuto para "há 5 minutos" envelhecer
1934
+ // fora do template (CSV, título da aba): a mesma regra, com o locale explícito
1935
+ const texto = formatCurrency(1234.5, 'pt-BR', 'BRL'); // 'R$ 1.234,50'
1936
+ ```
1937
+ - Os campos guardam **número** no modelo (moeda em unidades, não centavos) e escrevem no formato do idioma; não use
1938
+ `hm-input type="number"` com prefixo "R$".
1939
+ - `hmPercent` recebe fração (`0.155` → 16%); valor já em pontos leva `'points'`. A moeda é dado, não idioma: em
1940
+ inglês, reais continuam reais.
1941
+
1942
+ ## 40. Data com hora, mês, faixa de horário e seleção hierárquica
1943
+
1944
+ ```html
1945
+ <hm-datetime-picker label="Início da manutenção" [interval]="15" defaultTime="08:00" formControlName="inicio" />
1946
+ <hm-month-picker label="Competência" formControlName="competencia" /> <!-- 'AAAA-MM' -->
1947
+ <hm-time-range label="Expediente" [interval]="30" overnight showDuration formControlName="expediente" />
1948
+
1949
+ <hm-tree-select label="Centro de custo" [nodes]="centros()" leavesOnly showPath searchable formControlName="centro" />
1950
+ <hm-tree-select-multi label="Unidades" [nodes]="unidades()" [maxChips]="3" formControlName="unidades" />
1951
+ <hm-cascader label="Categoria" [nodes]="categorias()" [loadChildren]="carregarFilhos" formControlName="categoria" />
1952
+ ```
1953
+ - `nodes` é `TreeNode[]` (o mesmo do `hm-tree`); carga sob demanda por `loadChildren`.
1954
+ - `hm-time-range` vale `{ start, end }` (`'HH:mm'`); `overnight` aceita virar a meia-noite (plantão 22:00–06:00).
1955
+ - Mês sem dia é `hm-month-picker`, não um `hm-date-picker` com o dia 1 escondido.
1956
+
1957
+ ## 41. Formulário acessível: resumo de erros, anúncio, skip link e alterações não salvas
1958
+
1959
+ ```html
1960
+ <form [formGroup]="form" (ngSubmit)="enviar()" novalidate>
1961
+ <hm-form-error-summary [errors]="erros()" />
1962
+ <hm-input formControlName="nome" label="Nome" />
1963
+ <hm-input formControlName="email" label="E-mail" type="email" />
1964
+ <hm-save-status [status]="salvamento()" [savedAt]="salvoEm()" retryable (retry)="enviar()" />
1965
+ <hm-button type="submit">Salvar</hm-button>
1966
+ </form>
1967
+ ```
1968
+ ```ts
1969
+ import { formErrorsFrom, HERMES_MESSAGES, HermesAnnouncer, registerUnsavedChanges, type FormErrorItem } from '@trismegisto/angular';
1970
+ private readonly catalogo = inject(HERMES_MESSAGES);
1971
+ private readonly anunciador = inject(HermesAnnouncer);
1972
+ readonly #alteracoes = registerUnsavedChanges(() => this.form.dirty); // campo da classe (contexto de injeção)
1973
+ readonly erros = signal<FormErrorItem[]>([]);
1974
+
1975
+ enviar(): void {
1976
+ this.form.markAllAsTouched();
1977
+ // a lista é o retrato do envio: montada aqui, não a cada tecla
1978
+ this.erros.set(formErrorsFrom(this.form, { nome: 'Nome', email: 'E-mail' }, this.catalogo));
1979
+ if (this.form.invalid) return;
1980
+ // … salvar; depois: this.form.markAsPristine(); this.anunciador.announce('Cadastro salvo.');
1981
+ }
1982
+ ```
1983
+ ```ts
1984
+ // rotas + app
1985
+ { path: 'pedido/:id', component: PedidoPage, canDeactivate: [hermesUnsavedChangesGuard] }
1986
+ providers: [provideHermesUnsavedChanges({ beforeUnload: true })] // aviso nativo ao recarregar/fechar
1987
+ ```
1988
+ - O resumo recebe o foco quando aparece; cada link leva ao campo. Sem erros, não desenha nada.
1989
+ - `hm-skip-link` é o primeiro item da página (`target` = id do conteúdo; vazio = o `<main>`). Com spine, ligue
1990
+ `SpineConfig.features.skipLink` e `features.unsavedChanges` (a tela registra com `registerSpineUnsavedChanges`).
1991
+ - Não crie região `aria-live` na tela: `HermesAnnouncer.announce(texto)` (ou `[hmAnnounce]`).
1992
+ - `hm-modal` já deixa a página de trás `inert` enquanto está aberto; não ponha `inert`/`aria-hidden` à mão.
1993
+
1994
+ ## 42. Overlays e ações: popconfirm, split button, tour e bottom sheet
1995
+
1996
+ ```html
1997
+ <hm-button intent="danger" emphasis="medium" [hmPopconfirmTrigger]="confirmar">Arquivar</hm-button>
1998
+ <hm-popconfirm #confirmar heading="Arquivar o projeto?" message="Ele sai da lista, mas pode ser restaurado."
1999
+ intent="danger" (confirmed)="arquivarProjeto()" />
2000
+
2001
+ <hm-split-button label="Salvar" [items]="variacoes" (clicked)="salvar()" (chosen)="salvarComo($event)" />
2002
+
2003
+ <hm-tour [(open)]="tourAberto" [steps]="passos" (finished)="marcarVisto()" (skipped)="marcarVisto()" />
2004
+
2005
+ <hm-bottom-sheet [(open)]="acoesAbertas" heading="Arquivo" [actions]="acoesArquivo" (chosen)="executar($event)" />
2006
+ <hm-progress shape="circle" label="Envio" [value]="enviados()" [max]="total()" showValue />
2007
+ ```
2008
+ ```ts
2009
+ import type { MenuItem } from '@trismegisto/angular';
2010
+ import type { BottomSheetAction, TourStep } from '@trismegisto/primitives';
2011
+ readonly variacoes: MenuItem[] = [{ id: 'rascunho', label: 'Salvar como rascunho' }, { id: 'copia', label: 'Salvar uma cópia' }];
2012
+ readonly passos: TourStep[] = [
2013
+ { target: '#novo-pedido', title: 'Novo pedido', body: 'Comece por aqui.' },
2014
+ { target: '#filtros', title: 'Filtros', body: 'Refine a lista e salve combinações.' },
2015
+ ];
2016
+ readonly acoesArquivo: BottomSheetAction[] = [{ id: 'baixar', label: 'Baixar', icon: 'download' }, { id: 'excluir', label: 'Excluir', intent: 'danger' }];
2017
+ ```
2018
+ - Popconfirm é para ação reversível ou de baixo risco; exclusão definitiva continua `HermesDialogService.confirm({ danger: true })`.
2019
+ - `hm-bottom-sheet` com `snapPoints` (`[0.5, 0.9]`) vira painel com alturas de parada; com `actions`, é action sheet.
2020
+ - Os textos padrão (Cancelar, Pular, Concluir…) vêm do catálogo da peça; troque só o que precisar pelo input
2021
+ `texts` (ex.: `[texts]="{ … }"` no `hm-popconfirm`).
2022
+
2023
+ ## 43. Data grid com edição inline e tree table
2024
+
2025
+ ```html
2026
+ <hm-data-grid caption="Itens do orçamento" [rows]="itens()" [columns]="colunas" editMode="cell" editBatch
2027
+ (editSaved)="salvar($event)">
2028
+ <ng-template hmCellEditor="centro" let-row let-value="value" let-set="set" let-commit="commit" let-label="label">
2029
+ <hm-tree-select [label]="label" labelHidden [nodes]="centros()" [value]="value" (valueChange)="set($event); commit()" />
2030
+ </ng-template>
2031
+ </hm-data-grid>
2032
+
2033
+ <hm-data-grid caption="Estrutura" [rows]="raizes()" [columns]="colunasArvore"
2034
+ [treeChildren]="filhos" [columnGroups]="grupos" [striped]="false"
2035
+ treePagination="roots" [treeChildPageSize]="10" itemsLabel="estruturas" />
2036
+ ```
2037
+ ```ts
2038
+ readonly colunas: GridColumn<Item>[] = [
2039
+ { key: 'descricao', title: 'Descrição', value: (i) => i.descricao, editor: { required: true } },
2040
+ { key: 'quantidade', title: 'Qtd.', type: 'number', value: (i) => String(i.quantidade),
2041
+ editor: { min: 1, validate: (v) => (Number(v) > 999 ? 'Máximo 999.' : null) } },
2042
+ { key: 'centro', title: 'Centro de custo', value: (i) => i.centroNome,
2043
+ editor: { type: 'custom', value: (i) => i.centro } },
2044
+ ];
2045
+ salvar({ changes }: DataGridEditSave<Item>): void {
2046
+ // a grade não grava nada: persista e devolva as linhas novas em `rows`
2047
+ }
2048
+ readonly filhos = (linha: No) => linha.filhos ?? null;
2049
+ readonly grupos: GridColumnGroup[] = [{ key: 'plano', title: 'Planejado', columns: ['inicio', 'fim'] }];
2050
+ ```
2051
+ - Coluna sem `editor` não edita. `editMode="row"` abre a linha inteira com Salvar/Cancelar.
2052
+ - Textos da edição: `texts` (parcial). Métodos: `editRow(id)`, `saveEdits()`, `discardEdits()`.
2053
+ - Paginação da tree table (3.3.11): por padrão (`treePagination="rows"`) a página corta a lista visível, filhos
2054
+ inclusive. Com `"roots"`, a página conta só as raízes e cada uma vem com todos os filhos abertos, sem separar
2055
+ uma raiz dos filhos entre páginas. `treeChildPageSize` mostra os N primeiros filhos de cada pai e a linha
2056
+ "Mostrar mais"; com busca, todos os achados aparecem.
2057
+
2058
+ ## 44. Gráficos novos: sparkline, bullet, waterfall, bolhas e medidor animado
2059
+
2060
+ ```ts
2061
+ import { HmSparklineChartComponent, HmBulletChartComponent, HmWaterfallChartComponent, HmScatterChartComponent,
2062
+ HmGaugeChartComponent } from '@trismegisto/angular/charts';
2063
+ ```
2064
+ ```html
2065
+ <hm-stat-card label="Receita" [value]="receita()">
2066
+ <hm-sparkline-chart footer label="Receita nos últimos 30 dias" [data]="ultimos30()" [categories]="dias()" [area]="true" />
2067
+ </hm-stat-card>
2068
+ <hm-bullet-chart label="Metas do trimestre" [items]="[{ name: 'Vendas', value: 72, target: 80, ranges: [50, 80, 100] }]" />
2069
+ <hm-waterfall-chart label="Do bruto ao líquido" [steps]="[{ name: 'Bruto', value: 1000 }, { name: 'Impostos', value: -180 }, { name: 'Líquido', total: true }]" />
2070
+ <hm-scatter-chart label="Lojas" xLabel="Ticket médio" yLabel="Margem" sizeLabel="Clientes"
2071
+ [series]="[{ name: 'Lojas', data: [{ x: 120, y: 0.18, size: 900, name: 'Centro' }] }]" />
2072
+ <hm-gauge-chart label="Uso do disco" [value]="72" [animated]="true" [needle]="true" caption="72% de 500 GB" />
2073
+ ```
2074
+ - Bolhas não são um componente novo: é o `hm-scatter-chart` com `size` nos pontos (área proporcional; a tabela
2075
+ ganha a coluna de tamanho).
2076
+ - O medidor anima arco, agulha e número juntos e respeita `prefers-reduced-motion`.
2077
+ - Burndown/burnup: `burndownSeries({ start, end, scope, completed, today })` (`@trismegisto/primitives`) +
2078
+ `hm-line-chart`; com `today`, os dias futuros saem `null` (não preencha com zero).
2079
+
2080
+ ## 45. Campos e visualizadores: tags, cor, avaliação, JSON, logs, galeria e PDF
2081
+
2082
+ ```html
2083
+ <hm-tag-input label="Etiquetas" [suggestions]="sugestoes" [max]="8" [validate]="semEspaco" formControlName="tags" />
2084
+ <hm-color-picker label="Cor do quadro" [swatches]="cores" clearable formControlName="cor" />
2085
+ <hm-rating label="Nota do atendimento" allowHalf formControlName="nota" />
2086
+
2087
+ <hm-json-viewer label="Resposta" [data]="payload()" [expandDepth]="1" searchable copyable />
2088
+ <hm-log-viewer label="Saída do job" [entries]="linhas()" [(follow)]="seguir" height="24rem" />
2089
+ <hm-image-gallery label="Fotos da vistoria" [images]="fotos()" />
2090
+ <hm-pdf-viewer label="Contrato" [src]="contratoUrl()" fileName="contrato.pdf" />
2091
+ ```
2092
+ - Os textos dessas sete peças são sobrescritos pelo input `texts` (parcial); `messages` nelas continua sendo o
2093
+ texto por chave de erro do formulário.
2094
+ - `hm-image-gallery` abre o `hm-lightbox` sozinho; o `hm-lightbox` avulso serve para abrir a partir de outra lista.
2095
+
2096
+ ## 46. Workflow e tarefas: status com motivo, Gantt editável e raias
2097
+
2098
+ ```html
2099
+ <hm-status-select label="Situação" [definition]="fluxo" [(value)]="chamado.status" [apply]="false"
2100
+ (transition)="mudarStatus($event)" />
2101
+ <hm-level-select label="Prioridade" scale="priority" [(value)]="chamado.prioridade" allowEmpty />
2102
+
2103
+ <hm-gantt label="Cronograma" [items]="cronograma()" editable [editStep]="1" (taskChange)="remarcar($event)" />
2104
+
2105
+ <hm-swimlane-board [(columns)]="colunas" [lanes]="raias" [laneOf]="raiaDe" [itemLabel]="tituloDe"
2106
+ allowLaneChange [canMoveLane]="podeTrocar" (laneChange)="trocarRaia($event)">
2107
+ <ng-template hmKanbanCard let-tarefa>
2108
+ <hm-task-card [task]="tarefa" [statuses]="fluxo.statuses" [showStatus]="false" />
2109
+ </ng-template>
2110
+ </hm-swimlane-board>
2111
+ ```
2112
+ ```ts
2113
+ import type { GanttTaskChange, StatusTransitionEvent } from '@trismegisto/angular';
2114
+ import type { TaskItem, WorkflowDefinition } from '@trismegisto/primitives';
2115
+ readonly fluxo: WorkflowDefinition = {
2116
+ statuses: [
2117
+ { id: 'aberto', label: 'Aberto', category: 'todo' },
2118
+ { id: 'andamento', label: 'Em andamento', category: 'active' },
2119
+ { id: 'resolvido', label: 'Resolvido', category: 'done' },
2120
+ ],
2121
+ transitions: [
2122
+ { from: 'aberto', to: 'andamento' },
2123
+ { from: 'andamento', to: 'resolvido', reason: 'required' }, // pede o motivo antes de emitir
2124
+ ],
2125
+ };
2126
+ async mudarStatus(e: StatusTransitionEvent): Promise<void> { /* grava e.to e e.reason; depois atualiza o valor */ }
2127
+ remarcar(e: GanttTaskChange): void { /* grava e.start/e.end e devolve `items` atualizado */ }
2128
+ readonly raiaDe = (t: TaskItem) => t.assignee?.id ?? 'sem-responsavel';
2129
+ readonly tituloDe = (t: TaskItem) => t.title;
2130
+ ```
2131
+ - Sem `editable`, o Gantt só mostra; com ele, e sem tratar `(taskChange)`, a barra volta ao lugar ao soltar.
2132
+ - Sem `allowLaneChange`, o cartão só muda de coluna dentro da raia (comportamento antigo).
2133
+ - As peças não gravam: o app aplica a mudança e devolve o input (`items`, `columns`, `value`).
2134
+
2135
+ ## 47. Pessoas, acesso e conta
2136
+
2137
+ ```html
2138
+ <hm-entity-picker label="Responsáveis" kind="user" multiple [entities]="pessoas()" formControlName="responsaveis" />
2139
+ <hm-member-list label="Membros da equipe" [members]="membros()" [roles]="papeis" editable invitable
2140
+ (roleChange)="trocarPapel($event)" (remove)="remover($event)" (invite)="convidar()" />
2141
+ <hm-permission-matrix label="Permissões por papel" [roles]="papeis" [permissions]="permissoes" [(grants)]="concessoes" />
2142
+ <hm-org-chart label="Organograma" [nodes]="organograma()" [expandDepth]="2" zoomable (nodeSelect)="abrir($event)" />
2143
+ <hm-account-avatar [name]="pessoa.nome" [imageUrl]="pessoa.foto" presence="online" />
2144
+
2145
+ <hm-sign-up-form [policy]="politicaSenha" requireTerms (submitted)="cadastrar($event)" />
2146
+ <hm-passkey-button mode="sign-in" [state]="estadoPasskey()" (activate)="entrarComPasskey()" />
2147
+ <hm-cookie-banner [categories]="categoriasCookies" (saved)="gravarConsentimento($event)" />
2148
+ ```
2149
+ - Seletor de pessoa/equipe/papel/grupo é `hm-entity-picker` (`kind`), não um combobox montado à mão.
2150
+ - A cerimônia WebAuthn (`navigator.credentials`) e o login social são do app; os botões só emitem e mostram o
2151
+ `state` devolvido. Com o login por SSO dos apps, os formulários de conta servem para provedores próprios.
2152
+ - Acesso efetivo (papéis da matriz + política): `effectiveAccess`/`canAccess` (`@trismegisto/primitives`).
2153
+
2154
+ ## 48. Agenda editável, horários, arquivos, relatórios e dev
2155
+
2156
+ ```html
2157
+ <hm-event-calendar label="Agenda da equipe" [events]="eventos()" [(view)]="vista" editable [snapMinutes]="15"
2158
+ (rangeChange)="buscar($event)" (eventChange)="mover($event)" />
2159
+ <hm-recurrence-editor label="Repetir" [(rule)]="regra" [startDate]="inicio" />
2160
+ <hm-slot-picker label="Escolha um horário" [availability]="disponibilidade" [booked]="ocupados()"
2161
+ [duration]="30" (book)="reservar($event)" />
2162
+
2163
+ <hm-file-list label="Arquivos" [files]="arquivos()" [(collection)]="colecao" (open)="abrir($event)"
2164
+ (favoriteChange)="favoritar($event)" />
2165
+ <hm-file-versions label="Versões" [versions]="versoes()" restorable (restore)="restaurar($event)" />
2166
+ <hm-report-history label="Envios" [runs]="execucoes()" (retry)="reenviar($event)" />
2167
+ <hm-api-exchange [request]="req()" [response]="res()" [sensitiveHeaders]="['authorization']" />
2168
+ ```
2169
+ - Evento que se repete: `recurrence` no `CalendarEvent` (regra ou RRULE); a agenda expande as ocorrências.
2170
+ `(eventChange)` traz `kind` (move/resize), `start`, `end`: o app grava e devolve `events`.
2171
+ - `.ics`: `formatICalendar`/`parseICalendar`; horários em comum: `commonFreeRanges` (`@trismegisto/primitives`).
2172
+
2173
+ ## 49. Comércio, pagamento e endereço
2174
+
2175
+ ```html
2176
+ <hm-cart [lines]="linhas()" [discounts]="descontos()" [shipping]="frete()" currency="BRL" showCoupon
2177
+ [couponError]="erroCupom()" (quantityChange)="alterar($event)" (remove)="remover($event)"
2178
+ (applyCoupon)="aplicarCupom($event)" (checkout)="finalizar()" />
2179
+
2180
+ <hm-address-field country="BR" legend="Endereço de entrega" formControlName="entrega"
2181
+ (postalCodeComplete)="buscarCep($event)" />
2182
+
2183
+ <hm-payment-form [amount]="total()" currency="BRL" [methods]="meiosSalvos()" [tokenize]="tokenizar"
2184
+ [maxInstallments]="6" [shippingAddress]="form.value.entrega" (submitted)="pagar($event)" />
2185
+ ```
2186
+ ```ts
2187
+ import type { PostalAddress } from '@trismegisto/primitives';
2188
+ import { formatAddressLines } from '@trismegisto/primitives';
2189
+ // o número do cartão nunca chega ao app: o provedor tokeniza
2190
+ readonly tokenizar: CardTokenizer = (cartao) => this.provedor.criarToken(cartao);
2191
+ pagar(p: PaymentSubmission): void { /* p.token ou p.methodId, p.installments, p.billingAddress */ }
2192
+ const linhas = formatAddressLines(endereco); // exibir/imprimir na convenção do país
2193
+ ```
2194
+ - Endereço é sempre `PostalAddress` + `hm-address-field` (exibição: `hm-address-view`/`hm-address-card`/
2195
+ `hm-address-picker`). Não crie modelo de endereço próprio.
2196
+ - O carrinho não guarda estado: recebe `lines` e emite pedidos; validar estoque e cupom é do app (`couponError`).
2197
+
2198
+ ## 50. Monitoramento, integrações, mapas e entradas especializadas
2199
+
2200
+ ```html
2201
+ <hm-incident-card [incident]="incidente()" (action)="agir($event)" />
2202
+ <hm-alert-rule-editor label="Regra de alerta" [metrics]="metricas" [channels]="canais" [(value)]="regra" (save)="gravar()" />
2203
+ <hm-metric-explorer label="Latência" [metrics]="metricas" [(query)]="consulta" [series]="series()" />
2204
+ <hm-integration-catalog [integrations]="integracoes()" (connect)="conectar($event)" (disconnect)="desconectar($event)" />
2205
+ <hm-sync-status [run]="ultimaSync()" [now]="agora()" (syncNow)="sincronizar()" />
2206
+
2207
+ <hm-map label="Entregas de hoje">
2208
+ <hm-map-cluster>
2209
+ @for (e of entregas(); track e.id) { <hm-map-marker [position]="e.posicao" [label]="e.cliente" /> }
2210
+ </hm-map-cluster>
2211
+ </hm-map>
2212
+ <hm-vehicle-plate-input label="Placa" formControlName="placa" />
2213
+ <hm-identity-document-input label="Documento" [(country)]="pais" formControlName="documento" />
2214
+ ```
2215
+ - Essas peças recebem tudo pronto e só emitem (`action`, `connect`, `syncNow`…); autorização OAuth, rota e imagens
2216
+ do street view vêm do provedor do app. `hm-sync-status` não tem relógio: atualize `now`.
2217
+ - Textos de monitoramento/integrações: input `texts` (parcial), como nas outras peças.
2218
+
2219
+ ## 51. Exemplos integrados (referência de implementação)
2220
+
2221
+ Telas inteiras feitas só com peças da lib, como um app consumidor faria, com dados, estado e cada diálogo em
2222
+ arquivo próprio (site do Trismegisto › Componentes › página do exemplo › aba Código). Antes de montar uma tela
2223
+ dessas áreas, leia o exemplo correspondente:
2224
+
2225
+ | Exemplo | Grupo do site | Mostra |
2226
+ |---|---|---|
2227
+ | Calendar app | Calendário | `hm-event-calendar` com séries e arrastar, convidados, locais com conflito, disponibilidade, horário em comum, `.ics` |
2228
+ | Org chart explorer | Pessoas e acesso | `hm-org-chart` com centenas de pessoas: busca, filtro, zoom, painel de detalhe |
2229
+ | Projects app | Workflow e projetos | tarefas, raias, backlog/sprints, Gantt, carga, aprovações, riscos, SLA, burndown |
2230
+ | Store app | Comércio | vitrine com filtros, produto, carrinho com cupom, checkout, pagamento tokenizado, pedidos, devolução |
2231
+ | Billing app | Pagamentos e finanças | troca de plano com proração, meios de pagamento, faturas, conciliação |
2232
+ | Ops console app | Monitoramento | métricas, alertas que viram incidentes, deploys, manutenção, integrações |
2233
+ | People admin app | Pessoas e acesso | diretório, organograma, papéis e permissões, pedidos de acesso, troca de conta |
2234
+ | Files app | Arquivos | árvore de pastas, grade/lista, envio, visor por tipo, versões, compartilhamento, cota |
2235
+ | Developer portal | Dev | relatórios agendados, catálogo de endpoints com console de API, feature flags |
@@ -491,3 +491,95 @@ type TextareaSubmitKey = 'none' | 'mod-enter' | 'enter';
491
491
  type TextareaAddonSlot = 'prefix' | 'suffix' | 'actions' | 'actionsEnd';
492
492
  type HermesDirection = 'ltr' | 'rtl'; // elementDirection(el) / isRtl(el)
493
493
  ```
494
+
495
+ ## Famílias novas (formatação, formulários, workflow, pessoas, agenda, comércio)
496
+
497
+ Quase todos vêm de `@trismegisto/primitives` (a lógica mora lá); os das peças de grade, status e pagamento saem
498
+ também de `@trismegisto/angular`. Na dúvida, procure o nome em `angular-exports.md`.
499
+
500
+ ```ts
501
+ // Formulário e grade
502
+ interface FormErrorItem { readonly target: string; readonly label?: string; readonly message: string } // hm-form-error-summary [errors]; target = id ou formControlName
503
+ type SaveStatus = 'idle' | 'dirty' | 'saving' | 'saved' | 'error'; // hm-save-status [status]
504
+ type DataGridEditMode = 'none' | 'cell' | 'row'; // hm-data-grid editMode
505
+ type GridEditorType = 'text' | 'number' | 'select' | 'date' | 'checkbox' | 'custom';
506
+ interface GridColumnEditor<T> { // GridColumn.editor; sem ele a coluna não edita
507
+ readonly type?: GridEditorType; readonly options?: readonly GridFilterOption[];
508
+ readonly editable?: (row: T) => boolean; readonly value?: (row: T) => unknown;
509
+ readonly required?: boolean; readonly validate?: (value: unknown, row: T) => string | null | undefined;
510
+ readonly format?: (value: unknown, row: T) => string; readonly apply?: (row: T, value: unknown) => T;
511
+ readonly min?: number; readonly max?: number; readonly step?: number; readonly placeholder?: string;
512
+ }
513
+ interface DataGridEditSave<T> { readonly changes: readonly DataGridRowChange<T>[] } // (editSaved): o app grava e devolve rows
514
+ interface DataGridRowChange<T> { readonly id: string; readonly row: T; readonly values: Readonly<Record<string, unknown>> }
515
+ interface GridColumnGroup { readonly key: string; readonly title: string; readonly columns: readonly string[] } // columnGroups
516
+ interface TimeRange { readonly start: IsoTime | null; readonly end: IsoTime | null } // hm-time-range ('HH:mm')
517
+
518
+ // Endereço (único modelo da lib: hm-address-field, hm-address-view/-card/-picker, hm-payment-form)
519
+ interface PostalAddress {
520
+ readonly recipient?: string; readonly phone?: string; readonly street?: string; readonly number?: string;
521
+ readonly complement?: string; readonly district?: string; readonly city?: string; readonly region?: string;
522
+ readonly postalCode?: string; readonly country?: string;
523
+ }
524
+
525
+ // Workflow e tarefas
526
+ type WorkflowTone = 'primary' | 'info' | 'success' | 'warning' | 'danger' | 'neutral';
527
+ type WorkflowStatusCategory = 'todo' | 'active' | 'done' | 'canceled'; // done/canceled podem não ter saída
528
+ interface WorkflowStatus { readonly id: string; readonly label: string; readonly tone?: WorkflowTone; readonly category?: WorkflowStatusCategory; readonly description?: string }
529
+ interface WorkflowTransition { readonly from: string; readonly to: string; readonly label?: string; readonly confirm?: boolean; readonly reason?: 'none' | 'optional' | 'required'; readonly danger?: boolean }
530
+ interface WorkflowDefinition { readonly statuses: readonly WorkflowStatus[]; readonly transitions?: readonly WorkflowTransition[]; readonly initial?: string } // sem transitions = fluxo livre
531
+ interface WorkflowAssignee { readonly id: string; readonly name: string; readonly imageUrl?: string | null; readonly kind?: 'person' | 'team' | 'queue'; readonly detail?: string }
532
+ type LevelScaleKind = 'priority' | 'severity' | 'criticality' | 'urgency' | 'impact' | 'likelihood' | 'risk'; // escalas prontas (nomes no catálogo)
533
+ interface LevelScale { readonly label: string; readonly levels: readonly { readonly value: string; readonly label: string; readonly tone: WorkflowTone; readonly rank: number }[] }
534
+ interface GanttItem {
535
+ readonly id: string; readonly label: string; readonly start: WorkflowDateValue; readonly end?: WorkflowDateValue;
536
+ readonly progress?: number | null; readonly milestone?: boolean; readonly dependsOn?: readonly string[];
537
+ readonly group?: string; readonly tone?: WorkflowTone;
538
+ }
539
+ interface GanttTaskChange { readonly id: string; readonly item: GanttItem; readonly mode: GanttEditMode; readonly start: Date; readonly end: Date; readonly via: 'pointer' | 'keyboard'; readonly conflicts: readonly GanttItem[] }
540
+ interface SwimlaneLane { readonly id: string; readonly title: string }
541
+ type WorkflowDateValue = Date | string | number | null | undefined;
542
+
543
+ // Pessoas
544
+ type PeopleEntityKind = 'user' | 'team' | 'organization' | 'department' | 'role' | 'permission' | 'group';
545
+ interface PeopleEntity { readonly id: string; readonly name: string; readonly kind?: PeopleEntityKind; readonly description?: string; readonly imageUrl?: string | null; readonly icon?: string; readonly disabled?: boolean }
546
+ type PresenceStatus = 'online' | 'away' | 'busy' | 'offline'; // hm-account-avatar presence, hm-user-card
547
+ interface OrgChartNode {
548
+ readonly id: string; readonly name: string; readonly title?: string; readonly imageUrl?: string | null;
549
+ readonly presence?: PresenceStatus | null; readonly children?: readonly OrgChartNode[]; readonly subtitle?: string;
550
+ readonly vacancy?: boolean; readonly assistant?: boolean; readonly level?: string; readonly peers?: readonly OrgChartNode[];
551
+ }
552
+ interface MentionCandidate { readonly id: string; readonly name: string; readonly handle?: string; readonly description?: string; readonly imageUrl?: string | null }
553
+
554
+ // Agenda
555
+ interface CalendarEvent { // hm-event-calendar [events] (campos novos: recurrence, seriesId, occurrenceDate, editable, pending)
556
+ readonly id: string; readonly title: string; readonly start: Date | string; readonly end?: Date | string | null;
557
+ readonly allDay?: boolean; readonly color?: CalendarEventColor; readonly recurrence?: RecurrenceRule | string | null;
558
+ readonly seriesId?: string; readonly occurrenceDate?: IsoDate; readonly editable?: boolean; readonly pending?: boolean;
559
+ }
560
+ interface RecurrenceRule {
561
+ readonly frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'; readonly interval?: number; readonly weekdays?: readonly Weekday[];
562
+ readonly monthDay?: number; readonly weekdayPosition?: { readonly weekday: Weekday; readonly position: RecurrenceWeekPosition };
563
+ readonly count?: number | null; readonly until?: IsoDate | null; readonly exceptions?: readonly IsoDate[];
564
+ }
565
+ interface CalendarEventChange { readonly event: CalendarEvent; readonly kind: 'move' | 'resize'; readonly start: string; readonly end: string; readonly allDay: boolean }
566
+ type WeeklyAvailability = Readonly<Partial<Record<Weekday, readonly AvailabilityRange[]>>>; // Weekday 0 = domingo
567
+ interface AvailabilityRange { readonly start: IsoTime; readonly end: IsoTime }
568
+ interface BookedInterval { readonly date: IsoDate; readonly start: IsoTime; readonly end: IsoTime } // hm-slot-picker [booked]
569
+
570
+ // Visualizadores
571
+ interface LogEntry { readonly message: string; readonly level?: LogLevel; readonly timestamp?: Date | number | string | null; readonly source?: string }
572
+ type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
573
+ interface GalleryImage { readonly src: string; readonly alt: string; readonly thumbnail?: string; readonly caption?: string; readonly width?: number; readonly height?: number }
574
+
575
+ // Comércio e pagamento (valores em unidades da moeda, não centavos)
576
+ interface CartLine { readonly id: string; readonly name: string; readonly unitPrice: number; readonly quantity: number; readonly compareAtUnitPrice?: number | null; readonly variant?: string; readonly image?: string; readonly maxQuantity?: number | null; readonly sku?: string }
577
+ type PaymentMethodKind = 'card' | 'bank-account' | 'pix' | 'boleto' | 'wallet' | 'other';
578
+ interface PaymentMethod { readonly id: string; readonly kind: PaymentMethodKind; readonly brand?: CardBrand; readonly last4?: string; readonly expiry?: CardExpiry | null; readonly label?: string; readonly provider?: string; readonly isDefault?: boolean; readonly disabled?: boolean }
579
+ type CardTokenizer = (card: CardInput) => Promise<string>; // hm-payment-form [tokenize]: o provedor devolve o token
580
+ interface PaymentSubmission { readonly kind: PaymentMethodKind; readonly methodId: string | null; readonly card: CardSummary | null; readonly token: string | null; readonly installments: number; readonly billingAddress: PostalAddress | null } // nunca traz número completo nem CVC
581
+ ```
582
+
583
+ Textos: cada peça nova tem catálogo próprio em pt-BR/en/es (constantes `*_MESSAGES`, interface `*Messages`, por
584
+ exemplo `CART_MESSAGES`/`CartMessages`), escolhido pelo idioma ativo; o input parcial `texts` (o mesmo nome em todas as
585
+ peças — veja em `angular-api.md`) aceita `Partial<…Messages>`.